MediaFormat.java: Add KEY_MAX_WIDTH and KEY_MAX_HEIGHT

KEY_MAX_WIDTH and KEY_MAX_HEIGHT are optional video decoder
format keys.  Specify both to request seamless resolution-
change support from video decoders that support this feature.
You can check this via CodecCapabilities.isFeatureSupported.

The codecs use the MAX_WIDTH/HEIGHT values as hints for the
range of resolutions that needs to be supported.  Note,
however, that some codecs may require more memory just by
_preparing_ for larger maximum resolutions, whether or not
that resolution is actually used.

Change-Id: I00fe986ef894fec4bb39bceed081da0e88725d59
Signed-off-by: Lajos Molnar <lajos@google.com>
Related-to-bug: 7093648

1 files changed, 24 insertions, 0 deletions

diff --git a/media/java/android/media/MediaFormat.java b/media/java/android/media/MediaFormat.java
index 949a42c..01658c5 100644
--- a/media/java/android/media/MediaFormat.java
+++ b/media/java/android/media/MediaFormat.java
@@ -44,9 +44,19 @@ import java.util.Map;
  *         for encoders, readable in the output format of decoders</b></td></tr>
  * <tr><td>{@link #KEY_FRAME_RATE}</td><td>Integer or Float</td><td><b>encoder-only</b></td></tr>
  * <tr><td>{@link #KEY_I_FRAME_INTERVAL}</td><td>Integer</td><td><b>encoder-only</b></td></tr>
+ * <tr><td>{@link #KEY_MAX_WIDTH}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution width</td></tr>
+ * <tr><td>{@link #KEY_MAX_HEIGHT}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution height</td></tr>
  * <tr><td>{@link #KEY_REPEAT_PREVIOUS_FRAME_AFTER}</td><td>Long</td><td><b>video encoder in surface-mode only</b></td></tr>
  * <tr><td>{@link #KEY_PUSH_BLANK_BUFFERS_ON_STOP}</td><td>Integer(1)</td><td><b>video decoder rendering to a surface only</b></td></tr>
  * </table>
+ * Specify both {@link #KEY_MAX_WIDTH} and {@link #KEY_MAX_HEIGHT} to enable
+ * adaptive playback (seamless resolution change) for a video decoder that
+ * supports it ({@link MediaCodecInfo.CodecCapabilities#FEATURE_AdaptivePlayback}).
+ * The values are used as hints for the codec: they are the maximum expected
+ * resolution to prepare for.  Depending on codec support, preparing for larger
+ * maximum resolution may require more memory even if that resolution is never
+ * reached.  These fields have no effect for codecs that do not support adaptive
+ * playback.<br /><br />
  *
  * Audio formats have the following keys:
  * <table>
@@ -104,6 +114,20 @@ public final class MediaFormat {
      */
     public static final String KEY_HEIGHT = "height";
 
+    /**
+     * A key describing the maximum expected width of the content in a video
+     * decoder format, in case there are resolution changes in the video content.
+     * The associated value is an integer
+     */
+    public static final String KEY_MAX_WIDTH = "max-width";
+
+    /**
+     * A key describing the maximum expected height of the content in a video
+     * decoder format, in case there are resolution changes in the video content.
+     * The associated value is an integer
+     */
+    public static final String KEY_MAX_HEIGHT = "max-height";
+
     /** A key describing the maximum size in bytes of a buffer of data
      * described by this MediaFormat.
      * The associated value is an integer