From 269a560b372ec3c7ca62711ee8fa6f3b5ae79c04 Mon Sep 17 00:00:00 2001
From: Lajos Molnar <lajos@google.com>
Date: Wed, 25 May 2022 14:58:42 -0700
Subject: [PATCH] media: clarify that MediaFormat.KEY_LEVEL is required when
 specifying a profile

Also further clarify the meaning of level and profile.

Bug: 219899706
Change-Id: Ibf8e821a1c97173521163d7a3bb956d85194048d
---
 media/java/android/media/MediaFormat.java | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/media/java/android/media/MediaFormat.java b/media/java/android/media/MediaFormat.java
index 32fff1eb270d9..c2276e5205290 100644
--- a/media/java/android/media/MediaFormat.java
+++ b/media/java/android/media/MediaFormat.java
@@ -1069,11 +1069,20 @@ public final class MediaFormat {
 
     /**
      * A key describing the desired profile to be used by an encoder.
+     * <p>
      * The associated value is an integer.
      * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}.
      * This key is used as a hint, and is only supported for codecs
-     * that specify a profile. Note: Codecs are free to use all the available
-     * coding tools at the specified profile.
+     * that specify a profile. When configuring profile, encoder configuration
+     * may fail if other parameters are not compatible with the desired
+     * profile or if the desired profile is not supported, but it may also
+     * fail silently (where the encoder ends up using a different, compatible profile.)
+     * <p class="note">
+     * <strong>Note:</strong> Codecs are free to use all the available
+     * coding tools at the specified profile, but may ultimately choose to not do so.
+     * <p class="note">
+     * <strong>Note:</strong> When configuring video encoders, profile must be
+     * set together with {@link #KEY_LEVEL level}.
      *
      * @see MediaCodecInfo.CodecCapabilities#profileLevels
      */
@@ -1081,12 +1090,22 @@ public final class MediaFormat {
 
     /**
      * A key describing the desired profile to be used by an encoder.
+     * <p>
      * The associated value is an integer.
      * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}.
      * This key is used as a further hint when specifying a desired profile,
      * and is only supported for codecs that specify a level.
      * <p>
      * This key is ignored if the {@link #KEY_PROFILE profile} is not specified.
+     * Otherwise, the value should be a level compatible with the configured encoding
+     * parameters.
+     * <p class="note">
+     * <strong>Note:</strong> This key cannot be used to constrain the encoder's
+     * output to a maximum encoding level. Encoders are free to target a different
+     * level if the configured encoding parameters dictate it. Nevertheless,
+     * encoders shall use (and encode) a level sufficient to decode the generated
+     * bitstream, though they may exceed the (Video) Buffering Verifier limits for
+     * that encoded level.
      *
      * @see MediaCodecInfo.CodecCapabilities#profileLevels
      */