Merge "additional documentation for media codec info" into jb-mr2-dev

media/java/android/media/MediaCodecInfo.java

@@ -16,6 +16,31 @@
 
 package android.media;
 
+/**
+ * Provides information about a given media codec available on the device. You can
+ * iterate through all codecs available by querying {@link MediaCodecList}. For example,
+ * here's how to find an encoder that supports a given MIME type:
+ * <pre>
+ * private static MediaCodecInfo selectCodec(String mimeType) {
+ *     int numCodecs = MediaCodecList.getCodecCount();
+ *     for (int i = 0; i &lt; numCodecs; i++) {
+ *         MediaCodecInfo codecInfo = MediaCodecList.getCodecInfoAt(i);
+ *
+ *         if (!codecInfo.isEncoder()) {
+ *             continue;
+ *         }
+ *
+ *         String[] types = codecInfo.getSupportedTypes();
+ *         for (int j = 0; j &lt; types.length; j++) {
+ *             if (types[j].equalsIgnoreCase(mimeType)) {
+ *                 return codecInfo;
+ *             }
+ *         }
+ *     }
+ *     return null;
+ * }</pre>
+ *
+ */
 public final class MediaCodecInfo {
     private int mIndex;
 
@@ -45,9 +70,11 @@ public final class MediaCodecInfo {
     }
 
     /**
-     * Encapsulates the capabilities of a given codec component,
-     * i.e. what profile/level combinations it supports and what colorspaces
+     * Encapsulates the capabilities of a given codec component.
+     * For example, what profile/level combinations it supports and what colorspaces
      * it is capable of providing the decoded data in.
+     * <p>You can get an instance for a given {@link MediaCodecInfo} object with
+     * {@link MediaCodecInfo#getCapabilitiesForType getCapabilitiesForType()}, passing a MIME type.
      */
     public static final class CodecCapabilities {
         // Enumerates supported profile/level combinations as defined
@@ -114,6 +141,12 @@ public final class MediaCodecInfo {
         public int[] colorFormats;
     };
 
+    /**
+     * Encapsulates the profiles available for a codec component.
+     * <p>You can get a set of {@link MediaCodecInfo.CodecProfileLevel} objects for a given
+     * {@link MediaCodecInfo} object from the
+     * {@link MediaCodecInfo.CodecCapabilities#profileLevels} field.
+     */
     public static final class CodecProfileLevel {
         // from OMX_VIDEO_AVCPROFILETYPE
         public static final int AVCProfileBaseline = 0x01;
@@ -232,6 +265,7 @@ public final class MediaCodecInfo {
      * Enumerates the capabilities of the codec component. Since a single
      * component can support data of a variety of types, the type has to be
      * specified to yield a meaningful result.
+     * @param type The MIME type to query
      */
     public final CodecCapabilities getCapabilitiesForType(
             String type) {

media/java/android/media/MediaCodecList.java

@@ -19,9 +19,10 @@ package android.media;
 import android.media.MediaCodecInfo;
 
 /**
- * MediaCodecList class can be used to enumerate available codecs,
+ * Allows you to enumerate available codecs, each specified as a {@link MediaCodecInfo} object,
  * find a codec supporting a given format and query the capabilities
  * of a given codec.
+ * <p>See {@link MediaCodecInfo} for sample usage.
  */
 final public class MediaCodecList {
     /**