commit c06bb7f5b9c6be9d121e3f5b4ee7cd31c99f6879
author Scott Main <smain@google.com> Wed Jun 12 12:56:05 2013 -0700
committer Scott Main <smain@google.com> Fri Jun 14 11:56:15 2013 -0700
tree 20cb3d4378b1507c4c04fa1693e6e1b15c610ef8
parent 3b0205b7601a6fa3d7abf6dbc5a60223981103cc

additional documentation for media codec info

Change-Id: I3b4e5baccab6da2dfc8dff8d03872bb5b346a4ad

media/java/android/media/MediaCodecInfo.java

diff --git a/media/java/android/media/MediaCodecInfo.java b/media/java/android/media/MediaCodecInfo.java
index df87db3..aeed7d4 100644
--- a/media/java/android/media/MediaCodecInfo.java
+++ b/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 @@
     }
 
     /**
-     * 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 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 @@
      * 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

diff --git a/media/java/android/media/MediaCodecList.java b/media/java/android/media/MediaCodecList.java
index 2a60113..817ca31 100644
--- a/media/java/android/media/MediaCodecList.java
+++ b/media/java/android/media/MediaCodecList.java
@@ -19,9 +19,10 @@
 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 {
     /**