From afa6ceb5a0d809b630db43564d3ce7f7b821129c Mon Sep 17 00:00:00 2001 From: Lajos Molnar Date: Thu, 30 Jul 2015 10:14:16 -0700 Subject: media: Clarify MediaCodec and CodecCapabilities documentation Bug: 21932760 Bug: 22847191 Change-Id: Iacd24099a98c73fe4fb50226564690aa9b01c772 --- media/java/android/media/MediaCodec.java | 142 ++++++++++++++++++++------- media/java/android/media/MediaCodecInfo.java | 26 ++++- media/java/android/media/MediaCodecList.java | 14 +++ 3 files changed, 144 insertions(+), 38 deletions(-) diff --git a/media/java/android/media/MediaCodec.java b/media/java/android/media/MediaCodec.java index 3c459d83cb50..6c224e5c35e6 100644 --- a/media/java/android/media/MediaCodec.java +++ b/media/java/android/media/MediaCodec.java @@ -21,6 +21,7 @@ import android.annotation.NonNull; import android.annotation.Nullable; import android.graphics.ImageFormat; import android.graphics.Rect; +import android.graphics.SurfaceTexture; import android.media.MediaCodecInfo.CodecCapabilities; import android.os.Bundle; import android.os.Handler; @@ -32,6 +33,7 @@ import java.io.IOException; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.nio.ByteBuffer; +import java.nio.ByteOrder; import java.nio.ReadOnlyBufferException; import java.util.Arrays; import java.util.HashMap; @@ -228,8 +230,9 @@ import java.util.Map; data and submit it as a single codec-config buffer.

Android uses the following codec-specific data buffers. These are also required to be set in - the track format for proper {@link MediaMuxer} track configuration. Each parameter set and - codec-specific-data must start with a start code of {@code "\x00\x00\x00\x01"}. + the track format for proper {@link MediaMuxer} track configuration. Each parameter set and the + codec-specific-data sections marked with (*) must start with a start code of + {@code "\x00\x00\x00\x01"}.

@@ -237,28 +240,48 @@ import java.util.Map; + - + + + + + + + + + + + + + + - + + - - + + + - + + @@ -297,10 +320,10 @@ import java.util.Map; releaseOutputBuffer} methods to return the buffer to the codec.

While you are not required to resubmit/release buffers immediately to the codec, holding onto - input and/or output buffers may stall the codec, and this behavior is device dependent. E.g. it - is possible that a codec may hold off on generating output buffers until all outstanding buffers - have been released/resubmitted. Therefore, try to hold onto to available buffers as little as - possible. + input and/or output buffers may stall the codec, and this behavior is device dependent. + Specifically, it is possible that a codec may hold off on generating output buffers until + all outstanding buffers have been released/resubmitted. Therefore, try to + hold onto to available buffers as little as possible.

Depending on the API version, you can process data in three ways:

Format CSD buffer #0 CSD buffer #1CSD buffer #2
AACDecoder-specific information from ESDSDecoder-specific information from ESDS* Not UsedNot Used
VORBISIdentification headerSetup headerNot Used
OPUSIdentification headerPre-skip in nanosecs
+ (unsigned 64-bit {@linkplain ByteOrder#nativeOrder native-order} integer.)
+ This overrides the pre-skip value in the identification header.		Seek Pre-roll in nanosecs
+ (unsigned 64-bit {@linkplain ByteOrder#nativeOrder native-order} integer.)
MPEG-4Decoder-specific information from ESDSDecoder-specific information from ESDS*Not Used Not Used
H.264 AVCSPS (Sequence Parameter Sets)PPS (Picture Parameter Sets)SPS (Sequence Parameter Sets*)PPS (Picture Parameter Sets*)Not Used
H.265 HEVCVPS (Video Parameter Sets) +
- SPS (Sequence Parameter Sets) +
- PPS (Picture Parameter Sets)		VPS (Video Parameter Sets*) +
+ SPS (Sequence Parameter Sets*) +
+ PPS (Picture Parameter Sets*)		Not Used Not Used
@@ -346,7 +369,7 @@ import java.util.Map;

MediaCodec is typically used like this in asynchronous mode: 

- MediaCodec codec = MediaCodec.createCodecByName(name);
+ MediaCodec codec = MediaCodec.createByCodecName(name);
  MediaFormat mOutputFormat; // member variable
  codec.setCallback(new MediaCodec.Callback() {
    {@literal @Override}
@@ -403,7 +426,7 @@ import java.util.Map;
  

  MediaCodec is typically used like this in synchronous mode:
  
- MediaCodec codec = MediaCodec.createCodecByName(name);
+ MediaCodec codec = MediaCodec.createByCodecName(name);
  codec.configure(format, …);
  MediaFormat outputFormat = codec.getOutputFormat(); // option B
  codec.start();
@@ -442,7 +465,7 @@ import java.util.Map;
  between the size of the arrays and the number of input and output buffers used by the system,
  although the array size provides an upper bound.
  
- MediaCodec codec = MediaCodec.createCodecByName(name);
+ MediaCodec codec = MediaCodec.createByCodecName(name);
  codec.configure(format, …);
  codec.start();
  ByteBuffer[] inputBuffers = codec.getInputBuffers();
@@ -643,10 +666,10 @@ import java.util.Map;
  class. For API version numbers, see {@link android.os.Build.VERSION_CODES}.