Android Media Framework（三）OpenMAX API阅读与分析
必读：Android Media Framework - 开篇
这篇文章我们将聚焦Control API的功能与用法，为实现OMX Core、Component打下坚实的基础。
1、OMX_Core.h
OMX Core在OpenMAX IL架构中的位置位于IL Client与实际的OMX组件之间，OMX Core提供了两组API给IL Client使用，一组API用于管理OMX组件，另一组API用于操作/使用创建的OMX组件。
1.1
OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_Init(void);
OMX_Init：OMX_Init用来初始化OMX Core，在第一次使用OMX组件前它需要先被调用，并且只被调用一次；初始化可能包含以下几个步骤：- 分配并初始化使用OMX组件所需的内存和资源；
- 扫描系统中的所有可用OXM组件，并将它们加载到OMX Core中；
OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_Deinit(void);
OMX_Deinit：与OMX_Init功能相反，它用作于卸载OMX_Init加载的资源；
OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_ComponentNameEnum(
OMX_OUT OMX_STRING cComponentName,
OMX_IN OMX_U32 nNameLength,
OMX_IN OMX_U32 nIndex);
OMX_ComponentNameEnum：用于枚举OMX Core中可用的所有组件，该API包含三个参数，第一个参数cComponentName用于返回找到的组件名称（输出参数），第二个参数是字符串的长度（输入参数），第三个参数是遍历OMX Core组件列表的索引，通过递增索引并反复调用这个函数，就可以枚举出OMX Core中所有的组件名称，该API有两个作用：- 当需要查看 OMX Core 中有哪些可用的组件时，可以使用这个函数来获取所有组件的名称；
- 当需要通过名称来查找特定的组件时，可以使用这个函数来对所有组件进行遍历，直到找到与给定名称匹配的组件；
OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_GetHandle(
OMX_OUT OMX_HANDLETYPE* pHandle,
OMX_IN OMX_STRING cComponentName,
OMX_IN OMX_PTR pAppData,
OMX_IN OMX_CALLBACKTYPE* pCallBacks);
OMX_GetHandle：用于创建一个OMX组件，返回的句柄就是我们前面学过的OMX_COMPONENTTYPE，该函数需要传递四个参数：OMX_HANDLETYPE* pHandle：这是一个二级指针void**，用于接收创建的OMX_COMPONENTTYPE指针；OMX_STRING cComponentName：组件名称，根据该名称创建对应的组件；OMX_PTR pAppData：调用者（Application/IL Client）的指针;OMX_CALLBACKTYPE* pCallBacks：给OMX_COMPONENTTYPE注册的回调函数，用于回传消息；
OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_FreeHandle(
OMX_IN OMX_HANDLETYPE hComponent);
OMX_FreeHandle：销毁创建的OMX组件，传入参数为OMX_HANDLETYPE hComponent；
OMX_API OMX_ERRORTYPE OMX_APIENTRY OMX_SetupTunnel(
OMX_IN OMX_HANDLETYPE hOutput,
OMX_IN OMX_U32 nPortOutput,
OMX_IN OMX_HANDLETYPE hInput,
OMX_IN OMX_U32 nPortInput);
OMX_API OMX_ERRORTYPE OMX_GetContentPipe(
OMX_OUT OMX_HANDLETYPE *hPipe,
OMX_IN OMX_STRING szURI);
这两个API Android中没有用到，暂不了解。
OMX_API OMX_ERRORTYPE OMX_GetComponentsOfRole (
OMX_IN OMX_STRING role,
OMX_INOUT OMX_U32 *pNumComps,
OMX_INOUT OMX_U8 **compNames);
OMX_GetComponentsOfRole：用于获取在给定role（角色）下可以使用的所有OMX组件的列表，包含三个参数：OMX_STRING role：Role是用来描述OMX组件功能的字符串，每个OMX组件都拥有一个或多个角色，需要用role去指定OMX组件执行什么任务，role的名字规律"video_decoder.avc"、"audio_encoder.aac"，第一个字段表示音频/视频，下划线后表示编码/解码，后缀表示具体的编解码类型；OMX_U32 *pNumComps：输出参数，返回role对应的组件的数量；OMX_U8 **compNames：输出参数，返回role对应的所有组件的名称
OMX_API OMX_ERRORTYPE OMX_GetRolesOfComponent (
OMX_IN OMX_STRING compName,
OMX_INOUT OMX_U32 *pNumRoles,
OMX_OUT OMX_U8 **roles);
OMX_GetRolesOfComponent：获取一个组件名对应的所有的Role，功能和OMX_GetComponentsOfRole类似；
根据OMX_Init和OMX_ComponentNameEnum等API中的描述，我们大致可以猜到，OMX Core中需要维护一个列表（map），列表中的内容是一组一组的Role和Component Name。
1.2
在OpenMAX IL框架设计中，IL Client不能直接访问OMX组件的函数，它需要调用OMX Core提供的宏来间接操作OMX组件。要注意的是，OMX Core没有为OMX组件的所有函数都提供宏，换言之有些OMX组件函数不是给IL Client使用的。
首先来看定义的宏：
#define OMX_SendCommand( \
hComponent, \
Cmd, \
nParam, \
pCmdData) \
((OMX_COMPONENTTYPE*)(hComponent))->SendCommand( \
hComponent, \
Cmd, \
nParam, \
pCmdData)
OMX_SendCommand用于发送控制命令到组件，可用命令参考上文的枚举，该方法是非阻塞的，命令执行完成后需要发送callback通知IL Client。包含有四个参数：
hComponent：组件句柄；Cmd：要发送的命令类型；nParam：int类型的命令参数；pCmdData：无法使用int表示的命令参数；
#define OMX_GetParameter( \
hComponent, \
nParamIndex, \
pComponentParameterStructure) \
((OMX_COMPONENTTYPE*)(hComponent))->GetParameter( \
hComponent, \
nParamIndex, \
pComponentParameterStructure)
OMX_GetParameter用于从组件获取参数设置，该方法为阻塞调用：
nParamIndex：参数索引，用来指定获取什么参数；pComponentParameterStructure：指针，用于装载获取到的参数；
#define OMX_SetParameter( \
hComponent, \
nParamIndex, \
pComponentParameterStructure) \
((OMX_COMPONENTTYPE*)(hComponent))->SetParameter( \
hComponent, \
nParamIndex, \
pComponentParameterStructure)
OMX_SetParameter用于给组件设定参数，该方法为阻塞调用，参数功能与OMX_GetParameter类似。
#define OMX_GetConfig( \
hComponent, \
nConfigIndex, \
pComponentConfigStructure) \
((OMX_COMPONENTTYPE*)(hComponent))->GetConfig( \
hComponent, \
nConfigIndex, \
pComponentConfigStructure)
#define OMX_SetConfig( \
hComponent, \
nConfigIndex, \
pComponentConfigStructure) \
((OMX_COMPONENTTYPE*)(hComponent))->SetConfig( \
hComponent, \
nConfigIndex, \
pComponentConfigStructure)
OMX_GetConfig和OMX_SetConfig分别用于从组件获取配置、给组件设定配置，组件加载完成后可以
随时调用这两个方法，都是阻塞调用。不同于OMX_SetParameter设置的是组件的静态参数值，SetConfig设置的是运行时可更改的配置信息，例如视频的播放速度、音频的音量、视频的亮度等。
#define OMX_GetExtensionIndex( \
hComponent, \
cParameterName, \
pIndexType) \
((OMX_COMPONENTTYPE*)(hComponent))->GetExtensionIndex( \
hComponent, \
cParameterName, \
pIndexType)
OMX_GetExtensionIndex用于将OMX IL或厂商定义的扩展字符串转换为相应的结构体索引，该方法是阻塞的。许多音频和视频处理硬件具有特定的特性和特性，这些在OpenMAX IL标准中并未明确定义，为了使这些功能可以被利用，硬件厂商会提供特定的扩展；当应用程序需要访问这些特定的扩展功能时，就需要使用OMX_GetExtensionIndex来获取相关扩展的索引，然后使用这个索引去访问或者操作这些特定的扩展功能。
#define OMX_GetState( \
hComponent, \
pState) \
((OMX_COMPONENTTYPE*)(hComponent))->GetState( \
hComponent, \
pState)
OMX_GetState用于获取组件的当前状态。
#define OMX_UseBuffer( \
hComponent, \
ppBufferHdr, \
nPortIndex, \
pAppPrivate, \
nSizeBytes, \
pBuffer) \
((OMX_COMPONENTTYPE*)(hComponent))->UseBuffer( \
hComponent, \
ppBufferHdr, \
nPortIndex, \
pAppPrivate, \
nSizeBytes, \
pBuffer)
OMX_UseBuffer用于让组件使用由IL Client已经分配的buffer，或者使用tunneled组件已经提供的buffer。OMX_UseBuffer的实现应该分配出buffer header，并用参数填充它，最后通过ppBufferHdr返回。该方法是阻塞调用的，可以在LoadedToIdle状态下使用，也可在OMX_StateExecuting、OMX_StateIdle且端口被禁用的情况下使用。
关注公众号《青山渺渺》 获取更多音视频开发内容
