MediaCodec文档翻译

MediaCodec|文档翻译

　　classoverView

　mediacodec类可以用来调用系统底层的编码/解码软件。

　mediacodec一般是这么用的：

MediaCodec codec = MediaCodec.createDecoderByType(type);
 codec.configure(format, ...);
 codec.start();
 ByteBuffer[] inputBuffers = codec.getInputBuffers();
 ByteBuffer[] outputBuffers = codec.getOutputBuffers();
 for (;;) {
   int inputBufferIndex = codec.dequeueInputBuffer(timeoutUs);
   if (inputBufferIndex >= 0) {
     // fill inputBuffers[inputBufferIndex] with valid data
     ...
     codec.queueInputBuffer(inputBufferIndex, ...);
   }

   int outputBufferIndex = codec.dequeueOutputBuffer(timeoutUs);
   if (outputBufferIndex >= 0) {
     // outputBuffer is ready to be processed or rendered.
     ...
     codec.releaseOutputBuffer(outputBufferIndex, ...);
   } else if (outputBufferIndex == MediaCodec.INFO_OUTPUT_BUFFERS_CHANGED) {
     outputBuffers = codec.getOutputBuffers();
   } else if (outputBufferIndex == MediaCodec.INFO_OUTPUT_FORMAT_CHANGED) {
     // Subsequent data will conform to new format.
     MediaFormat format = codec.getOutputFormat();
     ...
   }
 }
 codec.stop();
 codec.release();
 codec = null;

//等会再逐一介绍上述代码每一句的作用

每一个Codec类都拥有input buffer和outputbuffer，这些buffer是通过API提供的函数按索引调用(Index)，这些buffer的格式是bytebuffer,实际上inputbuffer和outputbuffer都是bytebuffer的数组，用getInputBuffer和getOutputBuffer可以得到bytebuffer的调用。在成功调用Start()函数后，对象（原文是Client，在这里我理解为MediaCodec的实例化对象）并没有“拥有”input和output buffer,相应的，可以通过调用dequeueInputBuffer(long) 和dequeueOutputBuffer(MediaCodec.BufferInfo, long)把buffer的所有权从codec编解码器交换给对象。MediaCodec对象没有必要立刻把buffer传递给解码器或者释放到surface,上面的代码仅仅是一个简单的例子。

当MediaCodec对象有一个可用的input buffer时候，可以调用 queueInputBuffer(int, int, int, long, int)函数把buffer传递给解码器，当然，buffer里需要有数据。

解码器会相应的调用 dequeueOutputBuffer(MediaCodec.BufferInfo, long)返回一个output buffer,如果继续调用 releaseOutputBuffer(int, boolean) ，这个output buffer将被返回到解码器中，如果再 configure(MediaFormat, Surface, MediaCrypto, int)的时候传入了一个videoSurface(一般是SurfaceView).那么这个这个output buffer的内容将会显示在surface上。

不管是用于解码器的input buffer还是编码器的output buffer ,其中都包含了编码好的多媒体数据.对于视频格式的文件来说，buffer里包含的是一个短暂的时间片（比如一帧），对于音频格式的文件，可能是一个多帧的声音片段。不管哪种情况，buffer里的数据并不是任意字节边界的二进制数据，buffer里存储的不是数据流，而是一个元单元（access units）流。

很多媒体格式还需要多媒体文件头数据（这些数据一般是由一些包含set up data的buffer组成），或者编码器需要的特定数据。因此，最初传递给解码器的buffer必须是带有BUFFER_FLAG_CODEC_CONFIG下标的编码特定数据，一般这个下标是由queueInputBuffer(int, int, int, long, int)生成的。编码器需要的数据，包括媒体格式信息，都通过调用 configure(MediaFormat, Surface, MediaCrypto, int) (in ByteBuffer entries with keys "csd-0", "csd-1", 括号里这句不知道怎么翻译)，自动传递给了codec类，不需要对象自己把格式信息传给codec（也就是configure会自动传递带有BUFFER_FLAG_CODEC_CONFIG的buffer和媒体格式信息给编码器）。在输入数据的末尾，对象会通过queueInputBuffer(int, int, int, long, int)函数发送一个带有BUFFER_FLAG_END_OF_STREAM 下标的信号。为了解码与之前数据无关的数据(例如执行一个seek)，解码器需要调用flush()。在调用flush()后，对象里的inputbuffer或者outputbuffer都会清空，也就是说对象不再有任何buffer,但是数据的媒体格式信息不会改变，如果需要改变媒体格式信息，依次调用stop,configure,start.

format	如果为解码器，此处表示输入数据的格式；如果为编码器，此处表示输出数据的格式。
surface	指定一个surface，可用作decode的输出渲染。
crypto	如果需要给媒体数据加密，此处指定一个crypto类.
flags	如果正在配置的对象是用作编码器，此处加上`CONFIGURE_FLAG_ENCODE` 标签。

info	buffer的一些信息
timeoutUs	单位为微秒, 负数表示无穷大.

index	前面由调用 `dequeueInputBuffer(long)返回的index`
offset	The byte offset into the input buffer at which the data starts. 可以理解为有效数据开始的偏差，一般为0
size	输入的有效数据的大小
presentationTimeUs	这个buffer被渲染的时间（一般由extractor.getsampleTime获得）
flags	根据需要从 `BUFFER_FLAG_SYNC_FRAME`, `BUFFER_FLAG_CODEC_CONFIG` ， `BUFFER_FLAG_END_OF_STREAM选一个，或者0~`

index	The index of a client-owned input buffer previously returned in a call to `dequeueInputBuffer(long)`.
offset	The byte offset into the input buffer at which the data starts.
info	Metadata required to facilitate decryption, the object can be reused immediately after this call returns.
presentationTimeUs	The time at which this buffer should be rendered.
flags	A bitmask of flags `BUFFER_FLAG_SYNC_FRAME`, `BUFFER_FLAG_CODEC_CONFIG` or `BUFFER_FLAG_END_OF_STREAM`.

index	由codec对象拥有的，由 `dequeueOutputBuffer(MediaCodec.BufferInfo, long)返回的索引Index.`
render	如果有可用的显示surface，传递为true可表示显示。