Android 13 – Media框架（14）- OpenMax（三）

本文介绍: 上一节学习了 media.code c 服务中的部分内容，这一节我们将一起了解 OMX IL 层的 API 以及相关的结构体等内容。

上一节学习了 media.co dec 服务中的部分内容，这一节我们将一起了解 OMX IL 层的 API 以及相关的结构体等内容。

1、相关路径

以下是 Medi a 相关的头文件路径：
frameworks/native/headers/media_plugin/media/
cas 和 drm 是用于加密流解密使用，editor 里面有个 OMX_COLOR_Form atYUV420Plan ar 颜色空间的转换工具，这三个目录这里不做了解（不会），我们要重点关注的是 openmax 和 hardware 目录。

1.1 h ardwa re

frameworks/native/headers/media_plugin/media/hardware/
hardware 目录下放的是和硬件相关的一些头文件，Cry ptoAPI.h 大概是用于解密的，HDCPAPI.h 是用于HDMI加密的，这两个暂时不做了解；

OMXPluginBase.h 在前一节中已经做过了解了，libstagefrighthw.so 中的方法会创建一个 OMXPluginBase 对象；

VideoAPI.h 中声明有 media image (frame)，以及 Aspects of color 等相关的结构体，这里不做过多描述。

1.1.1 HardwareAPI.h

以下内容部分翻译自 HardwareAPI.h 中的注释：

struct EnableAndroidNativeBuffersParams：这个结构体用于把android native buffer 用作 graphic buffer 和 secure buffer
- graphic buffer usage：当 OMX node 通过 OMX_SetParameter 设定 OMX.google.android.index.enableAndroidNativeBuffers 配置时，这个功能将被打开（默认关闭）；
  当某个端口的 native buffer 使用被禁止时，该端口将正常被使用，端口使用的 buffer 会用 UseBuffer 来设定，这是当 CPU 需要访问 buffer 时将使用的模式；
  当 native buffer 被启用时，视频的 color format 信息将会使用 Android pi x el 格式，而不是使用 OMX 格式。启用 native buffer 可能会改变 component 接收 buffer 的方式，如果 store–meta data–mode 被使能，那么将会以 metadata的形式传输。此外，除非支持 OMX.google.android.index.useAndroidNativeBuffer2 扩展，否则应该使用 OMX_SetParameter（UseAndroidNativeBuffer ）来设定使用的 buffer。
- secure buffer usage：当 OMX node 通过 OMX_SetParameter 设定 OMX.google.android.index.allocateNativeHandle 配置时，这个功能将被打开（默认关闭）；
  当 native handle 在某个端口被禁用了，这个端口将会正常工作，并且预期调用 AllocateBuffer 来分配 buffer 并且返回 buffer 指针，这个模式会用作于 non-secure buffer 并且要组件分配 buffer 的情况；
  当 native handle 被使用时，组件需要分配一个 native_buffer_t 对象（可以通过binder传递），这个模式被用于 secure buffer，与之配合使用的有 nFilledLength、nAllocLength、nOffset 等参数。
- 注释：之所以这个结构体放在 Hardware API中，我的理解是无论 graphic buffer 还是 secure buffer 都是由硬件分配管理的，上面的翻译中描述了两种模式成功应用和失败应用的情况，至于上层如何使用，后续我们将在 ACodec 章节中来学习。
struct StoreMetaDataInBuffersParams：这个结构体用于在 video source（camera…）和 video encoder之间，video decoder 和 output buffer 之间传递数据，而避免数据的拷贝。 meta data 在 OMX client 和 OMX component之间传递时，buffer中存储的并不是真正的 video 数据，而是一些用于定位/解析真正数据的信息。启动 meta data 时，bStoreMetaData 需要设置为 OMX_TRUE，默认情况下将会启用 meta data mode。
当 bStoreMetaData 为 false 时，真正的 YUV 帧将会存储在 input/output buffer当中。
Metadata buffer 需要使用 UseBuffer 来注册到 OMX component 中。
- 当组件支援 OMX.google.android.index.storeANWBufferInMetadata 时，数据将会以 VideoNativeMetadata 的形式传递，并且会用 fence 来协同管理；
- 当组件支援 OMX.google.android.index.storeMetaDataInBuffers 时，数据将会以 VideoGrallocMetadata 的形式传递。
- 注释：之所以叫 meta data，指的是buffer中传递的不是真的数据，而是handle或者是物理地址，以及解析出buffer所需要的size、offset等信息，这些信息称为元信息，这个结构体一般会与上面的 grapgic buffer usage 搭配使用。
struct ConfigureVideoTunnelModeParams：用于 Android Tunnel Mode，网上讲 Tunnel Mode 的资料还比较少，具体如何实现不同的厂商可能有不同的方案，这里只翻译部分注释。
- describe：如果 Tunnel Mode 被打开，那么 video decoder 解出的帧将会直接送到 sink（池子）当中，nAudioHwSync 作为 HW SYNC ID 用来同步 audio hal 与 video 的输出，pSidebandWindow 需要绑定 codec 分配的 sideband window handle。

以上就是 HardwareAPI.h 中的部分内容，ACodec 并不会直接使用这些结构体，ACodec 回调用 IOmxNode 的接口，再由 OMXNodeInstance 解析参数，封装参数，最后传给 OMX component。

1.1.2 MetadataBufferType.h

这个文件中只定义了一个 enum MetadataBufferType，这里只对注释做一下翻译：

MetadataBufferType 定义了可以传递给 encoder 的 metadata buffer 的类型，这些类型主要是用于 libstagefright record框架使用的，这里的 record 可能指的是录屏或者是摄像头。Stagefright 框架是不需要知道关于 meta buffer的细节的，只要创建 meta buffer 和 video encoder 能够保持一致就行。

1.2 open max

1.2.1 OMX_Core.h

这个文件应该算是 OMX 的入口了，文件一开始的注释：OMX_Core 头文件定了application 和 component 公用的内容，我的理解就是 OpenMax AL 和 IL 层之间的接口。

我们直接拉到文件末尾，可以看到一组函数声明，有心的小伙伴会发现我们在上一节的 QComOMXPlugin 中见过它们，这些方法会被封装在 libOmxCore.so 中，具体的内容需要 vendor 来实现，这里对这几个方法描述进行翻译：

函数参数里的OMX_OUT 和 OMX_IN 用于记录当前的参数是返回参数还是输入参数。

OMX_Init：用来初始化 OMX core，这个方法执行时间应该小于 20 ms；
OMX_Deinit：对应于 OMX_Init，用于销毁 OMX core 中的内容，执行时间应该小于 20 ms；
OMX_ComponentNameEnum：枚举遍历系统中所有可用的编解码组件，第二个参数为一个字符指针，返回组件名称，名称类似于 OMX.qcom.video.decoder.h263；既然有遍历，那就会有一个容器来存储系统支援的所有组件信息，这个容器有各家vendor独立实现，实现不同会影响当前方法的实现；
OMX_GetHandle：根据给定的组件名称，将组件加载到内容当中（dlopen），调用组件的方法创建一个组件实例；（这里的意思是每个组件都是一个lib，每次要创建编解码实例都会dlopen，从而实现实例间互不影响，打开lib后会调用其中的方法返回示例，之后会直接使用这个实例，并且实例会被记录在 OMX core 当中）；
OMX_FreeHandle：释放 component Handle；
OMX_GetRolesOfComponent：获取组件的 role；这里的 role 指的是什么呢？个人理解是这样：多个不同的编解码组件可能会走同一套流程，并不是我们所想象的每个组件都会单独编译出一个 lib，虽然说流程相同，但是内部的一些配置可能会不一样，为了区分当前使用的是哪一个组件，就用 role 来区分。

再往上看，又有一组函数声明，这组函数的命名和 struct OMX_COMPONENTTYPE 中定义的函数指针是一一对应的，我们之前有提到创建 OMX 组件后，我们并不是直接使用组件，而是将其封装到 OMXNode 当中，最终由 OMXNode 调用组件的方法，以下这组函数声明就是对调用组件方法的封装，第一个参数 hComponent 指的就是 handle component（组件句柄/指针）：

OMX_GetComponentVersion：获取组件的信息，这是一个阻塞调用，耗时需要小于 5ms；
OMX_SendCommand：向组件发送一条命令，该调用是非阻塞的，组件需要先检查参数是否正确，然后才能将命令加入到组件线程中去执行，组件可能会调用 EventHandler callback 来返回结果，该函数的调用耗时需要小于 5ms；
- 从这里我们可以知道，omx 组件中应该会有一个 component 线程来专门执行上层下发的命令；
- 当命令是 OMX_CommandStateSet ，组件将会从 nParam 中获取新的状态，并且加入到命令队列中，从 executing 状态到 loaded 状态需要小于 500ms；
- 当命令是 OMX_CommandFlush，组件将会强制把指定 port 上所有不在处理状态的 buffer 全部按照接收的顺序 return，每个 port 执行 flush 应该小于 5ms；
- 当命令是 OMX_CommandPortDisable 或者是 OMX_CommandPortEnable，port 将会被关闭或者重启，耗时应该也小于 5ms；
OMX_GetParameter：获取当前组件的参数设置，它是阻塞调用，在 OMX_StateInvalid 状态下不能被调用，其他状态都能调用；它的第二个参数 nParamIndex 表示需要获取的参数类型，该方法执行时间应该小于 20ms；
OMX_SetParameter：类似 GetParameter；
OMX_GetConfig：从组件获取一个配置的结构体，这是一个阻塞调用，需要在 5ms 内完成；
OMX_SetConfig：给组件传递配置，需要与 GetConfig 搭配使用；
OMX_GetExtensionIndex：用于将特定的vendor 配置或者参数翻译成为 OMX 结构体索引；
OMX_GetState
OMX_UseBuffer：请求组件使用一个已经分配的buffer（来自于另一个组件或者来自于上层），并且分配出组件自己的 buffer header，该调用应该在 5ms 内完成；
OMX_AllocateBuffer：请求组件分配一个新的buffer 和一个 buffer header，并且将 buffer header 的指针返回，该调用应该在 5ms 内完成；
OMX_FreeBuffer：组件将会释放调用创建的 buffer header，如果 buffer 也是组件创建的，那么也会释放掉该 buffer；
OMX_EmptyThisBuffer：将一块填有数据的 buffer 送给组件的 input 端口，这块 buffer 被清空时将会调用 EmptyBufferDone 回调，将 buffer 返回给应用层，这是一个非阻塞调用。
OMX_FillThisBuffer：将一块空的 buffer 送到组件的 output 端口，组件将会填充该 buffer 并且调用 FillBufferDone 回传给应用层，同样的该函数也是非阻塞的；
OMX_UseEGLImage

解下来再看看其他结构体：

typedef enum OMX_COMMANDTYPE
{
    OMX_CommandStateSet,    /**< Change the component state */
    OMX_CommandFlush,       /**< Flush the data queue(s) of a component */
    OMX_CommandPortDisable, /**< Disable a port on a component. */
    OMX_CommandPortEnable,  /**< Enable a port on a component. */
    OMX_CommandMarkBuffer,  /**< Mark a component/buffer for observation */
    OMX_CommandKhronosExtensions = 0x6F000000, /**< Reserved region for introducing Khronos Standard Extensions */
    OMX_CommandVendorStartUnused = 0x7F000000, /**< Reserved region for introducing Vendor Extensions */
    OMX_CommandMax = 0X7FFFFFFF
} OMX_COMMANDTYPE;

command type 就是可以设置的命令类型，一般有状态设置，flush，端口的开启和关闭，vendor也可以自定义命令类型。

typedef enum OMX_STATETYPE

OMX_STATETYPE 指的是组件的状态，比较常见的有如下几种：

OMX_StateInvalid：组件发生异常；
OMX_StateLoaded：组件被创建但是还没有初始化完成；
OMX_StateIdle：组件初始化完成并且准备好开始；
OMX_StateExecuting：组件收到开始命令并且开始处理数据；
OMX_StatePause：组件收到暂停命令，这个用的很少

一些常见的flag：

OMX_BUFFERFLAG_EOS：EOS 表示输出端口将不会有数据再出来，所以在最后一块buffer上应该附上 EOS，上层给 decoder 写数据带上 eos 表示当前流结束；
OMX_BUFFERFLAG_STARTTIME：这个 flag 标记了起播时或者seek后第一帧应该从哪一帧开始显示渲染；比如说 seek 之后要从某个 pts 开始播放，但是刚好这一帧不是关键帧，那么需要从关键帧开始解码，从目标帧开始渲染。如果组件接收到 start time，它应该调用 SetConfig 去设置 OMX_ConfigTimeClientStartTime 。
OMX_BUFFERFLAG_DECODEONLY：组件只解码不渲染；
OMX_BUFFERFLAG_DATACORRUPT：表示当前buffer中的数据存在错误；
OMX_BUFFERFLAG_ENDOFFRAME：表示当前buffer标志着一帧数据的结束，默认情况下Android每次写入都是一帧数据，所以每次数据写给 component 都会带这个flag；
OMX_BUFFERFLAG_EXTRADATA：额外的数据需要加在数据流之前，某些格式需要加一些数据头；
OMX_BUFFERFLAG_CODECCONFIG：codec specific data (csd)，例如播放 h264需要的 SPS/PPS，播放AAC需要的AudioSpecificConfig，没有这些配置信息将无法解码播放。