atom.xml

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>xfdingustc&#39;s note</title>
  
  <link href="/atom.xml" rel="self"/>
  
  <link href="http://yoursite.com/"/>
  <updated>2017-04-06T03:29:12.595Z</updated>
  <id>http://yoursite.com/</id>
  
  <author>
    <name>xfdingustc</name>
    
  </author>
  
  <generator uri="http://hexo.io/">Hexo</generator>
  
  <entry>
    <title>OpenMax标准协议 第二章 OpenMAX IL 介绍和框架</title>
    <link href="http://yoursite.com/2017/04/01/chapter2/"/>
    <id>http://yoursite.com/2017/04/01/chapter2/</id>
    <published>2017-04-01T03:20:10.000Z</published>
    <updated>2017-04-06T03:29:12.595Z</updated>
    
    <content type="html"><![CDATA[<p>#OpenMAX IL 介绍和框架<br>本章介绍了OpenMAX的特点和框架</p>
<p>##2.1  OpenMAX IL 简介<br>OpenMAX IL层API定义了一个用于在系统提供的软件组件的接入层软件接口。目的是让拥有不同方法的组件提供一个标准化的接口和命令集， 来构建和销毁组件。</p>
<p>###2.1.1 架构概述<br>如果一个系统，需要四种多媒体处理模块，记为F1，F2，F3和F4。这些模块可能来自不同的公司或部门。每一个处理模块可能都有不同的初始化/销毁，配置和数据传输接口。OpenMAX IL的API可以将这些不同的接口或模块封装为标准的组件。</p>
<p>该API包括一个可以让来自不同的供应商/组织之间可以彼此交换数据的相互兼容组件的标准协议。</p>
<p>OpenMAX IL API的上层软件为IL客户端实例，可以是一个多媒体框架或是一个应用程序。IL客户端与一个称之为核心（Core）的集中式IL实例交互。 IL客户端使用OpenMAX Core进行加载和卸载组件，建立两个OpenMAX组件之间的直接通信，并且访问组件的功能方法。</p>
<p>IL客户端总是通过IL Core与组件进行通信。在大多数情况下，这种通信是通过调用IL Core的一些宏方法，这些宏可以被直接翻译为一些组件的方法。特殊情况（当IL客户端调用一个实际的核心功能）包括组件的创建，销毁以及两个组件管道的连接。</p>
<p>组件内嵌了多媒体处理功能。虽然本规范明确规定了OpenMAX Core的功能，组件供应商定义了组件的功能。组件可以操作四种类型的数据：音频，视频，图像，和其他（例如，用于同步的时间数据）。</p>
<p>一个OpenMAX组件提供了通过其组件句柄的一系列标准组件函数接口。这些函数允许客户端获取和设置组件和端口的配置参数，获取和设置组件的状态，发送命令给组件，接受事件通知，分配buffer，与单一组件端口建立通信，并连接两个组件端口之间的通信。</p>
<p>每一个OpenMAX组件应该至少有一个端口保证OpenMAX一致性。虽然供应商可能会提供一个兼容OpenMAX的组件，它没有端口。 大多数一致性测试依赖至少一个端口。OpenMAX所定义端口类型可以根据所传输的数据类型分为四类：音频、视频、图像和其他。每一个端口可以定义为为输入或者输出端口，这取决于它是否消耗或生产buffer。在一个含有四个多媒体处理功能的模块F1，F2，F3，F4的系统中，系统需要为每一个功能提供OpenMAX标准接口。开发人员可以轻易的任意组合这些功能。功能的分离是基于端口的划分。图2-1显示了这些功能的可能组合。</p>
<p><img src="img/2_1.png" alt=""></p>
<p><strong>表 2-1. OpenMAX实现的几种形式</strong></p>
<p>###2.1.2 名词解释<br>本小节介绍了OpenMax IL 中所用的字母缩写和关键词定义</p>
<p>####2.1.2.1  字母缩写<br>表2-1 列举了OpenMAX IL中首字母缩写的含义.</p>
<table>
<thead>
<tr>
<th>首字母缩写</th>
<th>含义</th>
</tr>
</thead>
<tbody>
<tr>
<td>IPC</td>
<td>进程间通信</td>
</tr>
<tr>
<td>OMX</td>
<td>OpenMAX功能和结构的名称前缀。例如，一个组件可以处于OMX_StateExecuting状态。</td>
</tr>
</tbody>
</table>
<p><strong>表 2-1. 首字母缩写</strong></p>
<p>####2.1.2.2  关键词定义<br>表 2-2 列举了OpenMAX IL中关键词的定义.</p>
<table>
<thead>
<tr>
<th>关键词</th>
<th>含义</th>
</tr>
</thead>
<tbody>
<tr>
<td>Accelerated component</td>
<td>OpenMAX组件封装了一部分在加速器中运行的功能。加速组件具有某些特殊的特性，如能够支持某些类型的管道(tunnel)。</td>
</tr>
<tr>
<td>Accelerator</td>
<td>硬件加速功能处理器。这种硬件模块也可称为硬件加速器。注意，加速器也可以不是硬件而是运行在另一个处理器上的软件模块。</td>
</tr>
<tr>
<td>AMR</td>
<td>自适应多媒体检索的缩写，是一种从3GGP组织提出的自适应码率编解码算法。</td>
</tr>
<tr>
<td>Host processor</td>
<td>多核系统中控制多媒体加速的处理器，通常运行高级操作系统。</td>
</tr>
<tr>
<td>IL client</td>
<td>调用OpenMAX核心（Core）或组件(component)方法的软件层。IL客户端可能是低于GUI的软件层，如Gstreamer，也可能在GUI下面几层。在此文档中，应用是指任何调用OpenMAX方法的软件模块。</td>
</tr>
<tr>
<td>Main memory</td>
<td>CPU和加速器共享的外部存储器。</td>
</tr>
<tr>
<td>OpenMAX component</td>
<td>封装目标系统所需功能的组件。OpenMAX封装了提供功能的标准接口。</td>
</tr>
<tr>
<td>OpenMAX core</td>
<td>与系统平台相关的代码，提供了找到并加载OpenMAX组件到内存的必要功能。当应用不再需要此OpenMAX组件时，Core也负责销毁内存中的组件。总的来说，加载OpenMAX组件到内存后，Core将不参与组件和应用程序之间的通信</td>
</tr>
<tr>
<td>Resource manager</td>
<td>管理系统中硬件资源的软件模块。</td>
</tr>
<tr>
<td>RTP</td>
<td>实时协议的缩写，它是用于传输实时数据的因特网标准协议，包括音频和视频。</td>
</tr>
<tr>
<td>Synchronization</td>
<td>组件之间相互控制的机制。</td>
</tr>
<tr>
<td>Tunnels/Tunneling</td>
<td>两个OpenMAX组件之间标准数据通路。</td>
</tr>
</tbody>
</table>
<p><strong>表 2-2. 关键词定义</strong></p>
<p>###2.1.3 系统组件<br>图2-2显示了使用OpenMAX进行通信的各种类型。每个组件可以有任意数量的端口用于数据通信。具有单个输出端口的组件称为源组件(Source component)。具有单个输入端口的组件称为接收器组件(sink component)。完全运行在主处理器上的组件称为主组件。在松耦合的加速器上运行的组件称为加速器组件。OpenMAX可能直接与应用程序或异构的多媒体框架集成。</p>
<p>下面描述了三种类型的通信。非通道通信(Non-tunneled)指的是IL客户端和组件之间的数据Buffer交换机制。通道(Tunneling)指的是组件之间直接交换数据Buffer的标准机制。专有通信(Proprietary）指的是两个组件之间直接信息数据通信，也可以当通道请求（tunneling request）时，作为一个两个组件通道的替代方案。</p>
<p><img src="img/2_2.png" alt=""></p>
<p><strong>表 2-2. OpenMAX IL 系统组件</strong></p>
<p>####2.1.3.1  组件Profiles<br>OpenMAX组件功能分为两个profile：base profile和interop profile。</p>
<p>Base profile 应该支持非管道（non-tunneled）通信， 可能支持专有通信（proprietary），不支持管道（tunneled）通信。</p>
<p>Interop profile是base profile的一个超集，它应该支持管道（tunneled）和非管道（non-tunneled）通信，可能支持专有通信。</p>
<p>Interop profile和base profile的主要区别是是否支持管道（tunneled）通信。定义base profile的意义在于简化OpenMAX的实现难度，因为并不需要实现tunneled 通信</p>
<p>###2.1.4 组件状态<br>每一个OpenMAX组件的运行可以视为一系列状态的转移，如图2-3。每一个组件的初始状态为unloaded。组件可以通过调用OpenMAX Core的接口进行装载。其他的状态转移可以通过直接和组件进行通信来完成。</p>
<p>当使用不正确的数据进行状态转移的时候，组件可以进入非法（invalide）状态。例如，如果回调函数的指针指向非法地址的时候，组件可能会超时并且向IL客户端发出错误警告。IL客户端检测到非法状态时， 应该停止运行，释放，卸载并且重新加载这个组件。图2-3描绘了所有的状态均可以跳转到非法状态，但非法状态只能跳转到unload状态，并且重新加载组件。</p>
<p><img src="img/2_3.png" alt=""></p>
<p><strong>表 2-3. 组件状态</strong></p>
<p>由于需要获得所需要的资源， 进入IDLE状态可能会失败。当从LOADED向IDLE转移失败时， IL客户端可以重试或者转入等待资源（Wait for resource）状态。当进入等待资源（wait for resource）状态是， 组件会向资源管理器注册，当资源可以可以获得时得到提醒。资源管理器随后将组件转至IDLE状态。IL客户端发送控制命令进行除了非法（invalide）状态以外的所以其他状态转移。</p>
<p>IDLE状态表明组件已经获得所有所需资源，但此时并没有处理数据。EXECUTING状态表明组件正在接受数据Buffer，进行处理，并且会发出响应的回调（见第3节）。PAUSE状态保持了数据buffer执行的上下文，但并不处理或交换数据或。从PAUSED到EXECUTING的状态转移可以当组件由挂起到继续时能够处理buffer。</p>
<p>从EXECLUTING到PAUSED或者IDLE的转移可能会导致处理过的buffer上下文丢失，这时候需要重新开始一个新的流。IDLE到LOADED的转可能会导致运行的资源例如通信Buffer的丢失。</p>
<p>###2.1.5 组件架构<br>表2-4描述了组件的架构。注意，该组件只有一个入口（通过一个拥有一系列标准方法接口的句柄），但可能会有多个回调，取决于组件有多少个端口（port）。每个组件会调用指定的IL客户端的事件处理程序（event handler）。每个端口（port）会调用（或回调）制定的外部方法。每个端口（port）会和一个指向buffer头的队列关联。这些buffer头指向真正的buffer。命令函数（command functions）也有一个命令队列。所有的参数或者配置函数需要提供一个指定的索引并包括一个参数或配置的结构，如图2-4。</p>
<p><img src="img/2_4.png" alt=""></p>
<p><strong>图 2-4. OpenMAX IL API 组件架构</strong></p>
<p>端口必须支持向IL客户端的回调。当组件是interop profile的时候，必须支持和其他组件之间的通信。</p>
<p>###2.1.6 通信行为<br>一旦OpenMAX core获得了组件的句柄，便可以开始对组件进行配置工作。当端口的数量被确定后，组件数据通信的方法便可以调用，并且是不可以阻塞的。<br>每一个端口会指定一个特定的数据格式，并且组件会进入合适的状态。数据通信是和组件的端口（port）绑定的。IL客户端总是会调用输入端口<code>OMX_EmptyThisBuffer</code>接口（具体信息可以看3.2.2.17小节），调用输出端口（port）的<code>OMX_FillThisBuffer</code>（具体信息可以看3.2.2.18小节）。如果是同步执行，在返回之前，回调用回调函数<code>OMX_EmptyBufferDone</code> 或 <code>OMX_FillBufferDone</code>。 图2-5表述了同步执行和异步执行的对比行为。注意， IL客户端不应该假设返回和回调的先后顺序， 必须对同步和异步的OpenMAX组件都进行异构集成。</p>
<p><img src="img/2_5.png" alt=""></p>
<p><strong>图 2-5. 异步对比同步操作</strong></p>
<p>与组件的数据通信总是指向特定的组件端口。每一个端口（port）有一个分配供使用的buffer，最小数量由组件制定。端口将buffer头与每一块buffer相关联。buffer头拥有buffer数据的引用，并且提供响应的元数据（metadata）。每个组件端口应该既可以分配自己的buffer也可以使用分配好的buffer，往往某一种方案会比其他的效率高。</p>
<p>###2.1.7 管道（tunneled） buffer的分配和共享<br>本小结描述了管道（tunnel）组件的buffer分配和共享。对于给定的管道，会有一个端口提供buffer并且将buffer转递给接受的端口。最简单的情况，提供者同时会分配这些buffer。然而，在适当的情况下，管道（tunnel）组件会选择复用buffer，以免多次内存拷贝。这种做法被称为buffer共享</p>
<p>两个端口之间的管道表示了两个端口之间的依赖关系。buffer共享扩展了这个依赖关系，使得共享同一组buffer的所有端口形成隐式依赖链。该依赖链中的一个端口分配所有的共享buffer。</p>
<p>共享buffer是在组件内部实现的，并且对其他组件透明。接受端口并不知道提供者是分配还是复用了这些buffer。此外，输出也不知道输入是否复用了这些buffer。</p>
<p>严格的说，一个组件只需要遵守他所需要的外部语义，并且实现buffer共享。更具体的说，外部语义要求一个组件能够做到如下：</p>
<ul>
<li>在所有输出端口（Provide buffer）上提供buffer。</li>
<li>精确地在其端口上传递buffer要求。</li>
<li>从一个输出端口向一个输入端口通过调用<code>OMX_EmptyThisBuffer</code>转递数据</li>
<li>从一个输入端口向一个输出端口通过调用<code>OMX_FillThisBuffer</code>返回一个buffer</li>
</ul>
<p>如果一个组件使用共享buffer, 它需要实现如下功能：</p>
<ul>
<li>在某些输出端口上提供可复用的buffer</li>
<li>当端口上有buffer通信的需求时可以共享端口。</li>
<li>调用<code>OMX_EmptyThisBuffer</code>和其对应的回调函数<code>OMX_EmptyBufferDone</code>之间， 内部会从输出端口到另一个输出端口传递一个buffer</li>
</ul>
<p>OpenMAX虽然没有明确要求组件支持共享, 但定义了外部构件语义需要兼容共享方式。本节讨论在共享buffer的上下文中实现这些语义。如果没有组件共享buffer，则实现简化为一组简单的步骤和过称。</p>
<p>####2.1.7.1  相关术语<br>本节描述了tunneled buffer的分配和共享。图2-6描绘了概念。</p>
<p><img src="img/2_6.png" alt=""></p>
<p><strong>图 2-6. Buffer分配和共享关系的例子</strong></p>
<p>在一对管道连接的端口中，端口会调用他的邻居端口<code>UseBuffer</code>接口告知自己为输出端口。输出端口并不一定需要分配内存，它可以复用同组件下另一端口的buffer。在图2-6中，端口a和c描绘了输出端口。</p>
<p>从邻居端口接收到<code>UseBuffer</code>调用的端口是一个输出端口。图2-6中的端口b和d描绘了出入端口。</p>
<p>一个端口的管道端口是指其共享管道的邻居端口。例如，在图2-6中端口b是端口a的管道端口。同理，a也是b的管道端口。</p>
<p>一个分配器端口（allocator port）是一个输出端口，而且可有分配自己的buffer。图2-6中的端口a是唯一的分配器端口。</p>
<p>共享端口（sharing port）是可以复用同一组件中其他端口buffer的端口。例如，图2-6中端口c就是共享端口。</p>
<p>一个管道组件指的是至少有一个管道的组件。</p>
<p>端口buffer的需求包括了buffer的数量和每块buffer的大小。buffer所需的最大值是指所需数量的最大值和所需大小的最大值。一个端口通过其管道端口调用<code>OMX_GetParameter</code>接口，并传入结构体<code>OMX_PORTDEFINITIONTYPE</code>参数来获得buffer的需求。注意，一个端口可能从其共享buffer的端口而不是接受<code>OMX_GetParameter</code>接口来确定其buffer的需求，因为他们隶属于同一个组件。</p>
<p>####2.1.7.2  IL客户端组建设置<br>为了配置管道组件，IL客户端需要按顺序进行下面的操作：</p>
<ol>
<li>加载所有的管道组件并配置这些组件的管道。</li>
<li>将所有的管道组件的状态由loaded转为idle。</li>
</ol>
<p>如果IL客户端没有按此进行操作，一个管道组件可能由于组件间的依赖关系而永远无法转移到idle状态。</p>
<p>####2.1.7.3  共享时组件状态由loaded到idle的转移<br>在<code>OMX_SetupTunnel</code>调用时，管道的两个端口会确立哪个端口（输入或输出）是buffer提供者。因此，当一个组件被要求从loaded转移到idle时，它会知道它所有提供者和接受者端口的角色。</p>
<p>当命令组件由loaded转移到idle的时候，它需要按顺序进行下面的操作：</p>
<ul>
<li><p>1.组件决定那种buffer共享它需要实现。如果有，需要遵循下列规则：</p>
<ul>
<li>a) 它的一个输入端口到一个或多个输出端口、一个输出端口到一个输入端口。</li>
<li>b) 只有提供者端口可以复用其他端口的buffer。</li>
<li>c) 一个组件在多个输出端口上共享buffer需要输出的端口是只读的，如图2-7所示。</li>
</ul>
</li>
</ul>
<p><img src="img/2_7.png" alt=""></p>
<p><strong>图 2-7. 可能的共享关系</strong></p>
<ul>
<li>2.组件确定哪个是其供应端口和分配器端口（如果有有的话）。如果不从同组件的非供应端口复用buffer是，一个供应端口也是一个分配端口（即，不是一个分享端口）。在图2-8中，供应端口是有箭头指向外面的端口，非供应端口是有箭头指向它的端口。端口上的箭头表明了共享关系。端口旁边的正方形（buffer）表明了这是一个分配器端口。</li>
</ul>
<p><img src="img/2_8.png" alt=""></p>
<p><strong>图 2-8. 确定分配器</strong></p>
<ul>
<li>3.组件在每个分配器端口上分配buffer的策略如下：<ul>
<li>a) 每个复用分配器端口buffer的端口，分配器端口会确定其共享端口的buffer需求。见下面的条例A。</li>
<li>b) 分配器端口通过调用<code>OMX_GetParameter</code>决定其管道端口buffer要求。参见条例B。</li>
<li>c) 分配器端口根据自己的最大需求，管道端口的要求，和所有的共享端口的要求分配buffer。</li>
<li>d) 分配器端口通过调用<code>OMX_SetParameter</code>的<code>OMX_IndexParamPortDefinition</code>设置合适的<code>nBufferCountActual</code>值，来通知非供应端口实际的buffer数量。见下面的条例E。</li>
<li>e) 分配器端口和每个复用其buffer的共享端口共享buffer。见条例D。</li>
<li>f) 每个分配的buffer，分配器端口调用其管道端口的<code>OMX_UseBuffer</code>接口。参见条例C。</li>
</ul>
</li>
</ul>
<p>组件还应遵循下列条例：</p>
<ul>
<li>A. 一个共享端口要确定其需求，共享端口应先调用其管道端口的<code>OMX_GetParameter</code>来查询需求，然后返回自己和其管道端口的最大要求。</li>
<li>B. 当一个非供应端口接受到<code>OMX_GetParameter</code>调用来查询自己的buffer需求是，它需要首先确定所有复用自己buffer的端口的需求（见条例A），然后返回自己和其他这些端口的最大值。</li>
<li>C. 当一个非供应端口接受到来自其管道端口的<code>OMX_GetParameter</code>调用，它需要把这些buffer和组件内所有和它复用buffer的端口共享。</li>
<li>D. 当端口A和组件内复用其buffer的端口B共享一个buffer时，端口B需要调用 <code>OMX_UseBuffer</code>并且将buffer传递给他的管道端口。</li>
<li>E. 当非供应端口接受到其管道端口的<code>OMX_SetParameter</code> 的<code>OMX_IndexParamPortDefinition</code>调用时，供应端口应该将值<code>nBufferCountActual</code>传递给所有复用其buffer的端口。同理，每一个通过这种方式收到 <code>nBufferCountActual</code>值的供应端口，需要通过调用传递<code>OMX_SetParameter</code> 的<code>OMX_IndexParamPortDefinition</code>的接口将<code>nBufferCount</code> 值给他的管道端口， buffer的实际数量以这种方式在整个依赖链中传播。</li>
</ul>
<p>当一个组件获得所需的所有buffer，便可以由loaded状态转为idle状态。</p>
<p>在实践中，可以有如下的直接映射：</p>
<ul>
<li>步骤1~3对应loaded向idle状态的转变</li>
<li>条例A对应一个共享端口的buffer需求的子函数</li>
<li>条例B对应<code>OMX_GetParameter</code>的实现</li>
<li>条例C对应<code>OMX_UseBuffer</code>的实现</li>
<li>条例D对应一个端口向另一个端口分享buffer的子函数</li>
</ul>
<p>为了搞清楚合理分配buffer的这些步骤和条例，可以参考图2-9.注意这个例子是用于实践上面步骤和条例的，实际的用例会负责的多。</p>
<p><img src="img/2_9.png" alt=""></p>
<p><strong>图 2-9. Buffer分配的例子</strong></p>
<p>下面集中讨论组件3如何到idle状态的，其他的组件类似。</p>
<p>当IL客户端命令组件3从loaded向idle转移时，它需要遵循下面的步骤：</p>
<ol>
<li>组件3注意到它可以重用端口d的buffer，因为端口e是一个供应者端口。组件3建立了端口d到端口e的共享关系。</li>
<li>既然端口d是一个供应者端口并且不复用buffer，那么端口d是一个分配者端口。</li>
<li>端口3分配并部署端口d的buffer:<ul>
<li>a) 既然端口e复用端口d的buffer，组件3确定端口e的需求。根据条例A， 端口e调用端口f的<code>OMX_GetParameter</code>确定f的需求，并将自己的和f的最大值报告出去。</li>
<li>b) 端口d调用端口c的<code>OMX_GetParameter</code>接口确定他的buffer需求。根据条例B，端口C需要确定端口b的buffer需求。更具提条例A，端口b返回自己和a的最大需求。端口c得到这个需求在和自己的需求比较返回最大值。</li>
<li>c) 端口d根据自己的需求和端口c，e返回的最大值分配buffer， 分配的buffer是根据端口a,b,c,d,e,f需求的最大值确定的，所有的端口都复用端口d的buffer。</li>
<li>d) 既然端口e复用端口d的buffer，组件3用端口e分享这些buffer。根据条例D，端口e调用端口f的<code>OMX_UseBuffer</code>接口以分享这些buffer。</li>
<li>e) 对于每块分配的buffer，端口d调用端口c的 <code>OMX_UseBuffer</code>。根据提条例C，端口C和B分享这些buffer。而端口b根据条例D调用端口a<code>OMX_UseBuffer</code></li>
</ul>
</li>
</ol>
<p>至此，所有组件的所有端口都有自己的buffer，所有的组件都可以转移到idle状态。</p>
<p>####2.1.7.4  使用共享buffer的协议<br>当一个输入端口收到<code>OMX_EmptyThisBuffer</code>调用得到一块共享buffer时，输入端口可以通过遵循下面的准则复用这块buffer到其共享端口：</p>
<ul>
<li>输出端口要在其管道端口的返回相应的回调函数<code>OMX_EmptyBufferDone</code>前，调用其管道端口的<code>OMX_EmptyThisBuffer</code>方法。</li>
<li>输入端口不能在所有的与其共享buffer的输出端口返回<code>OMX_EmptyBufferDone</code>之前返回<code>OMX_EmptyBufferDone</code>。</li>
</ul>
<p>####2.1.7.5  非共享情况下组件状态由loaded到idle的转移<br>如果一个组件没有共享buffer，和共享buffer的情况相比起来，组件的实现的步骤和准则会简单一些：</p>
<p>一个非共享组件要从loaded转移到idle状态时，它需要按下面的顺序进行操作：</p>
<ol>
<li>组件确定那些buffer共享需要实现。在这情况下，没有共享需要实现。</li>
<li>组件确定那些是供应端口，如果有，他们都是分配者端口。所有的供应端口都是分配者端口。</li>
<li>组件按照下面准则为所有的分配者端口分配buffer：<ul>
<li>a. 由于没有buffer共享，组件不需要获取共享端口的需求。</li>
<li>b. 分配器通过调用<code>OMX_GetParameter</code>来确定其管道端口的buffer需求。</li>
<li>c. 分配器端口根据自身和其管道端口对buffer需求的最大值来分配buffer。</li>
<li>d. 由于没有共享，没有buffer需要转递到共享端口。</li>
<li>e. 对每一块分配出来的buffer， 分配器端口调用其管道端口的<code>OMX_UseBuffer</code></li>
</ul>
</li>
</ol>
<p>所有共享组件的准则不适用与非共享组件。</p>
<p>###2.1.8 端口重连接<br>端口的重连接可以使一个管道组件被另一个管道组件替换而不需要卸载周围的组件。图2-10，组件B1被组件B2替换。要做到这一点，组件A的输出端口和组件B的输入端口首先应该用disable的命令禁用。一旦所有所有分配的buffer回到他们的拥有者并且释放，组件A的输出端口便可以连接到组件B2.组件B1输出端口和组件C的输入端口应该给予同样的禁用命令。所有分配buffer回到他们的拥有者并被释放后，组件C的输入端口可以重新连接到组件B2的输出端口。然后，可以给所有的端口发启用命令。</p>
<p><img src="img/2_10.png" alt=""></p>
<p><strong>图 2-10. 端口重连接</strong></p>
<p>在某些情况下，例如音频，将一个组件重新连接到另一个组件，老的组件淡出新的组件淡入也是可以的。图2-11展示了这是如何工作的。步骤1，组件A发送数据给组件B1。步骤2，IL客户端首先建立组件A和B2之间的管道，再建立B2和C之间的管道，然后启用两个管道上的所有端口。组件C可能将B1和B2通过不同的增益进行混音。步骤3，组件B1和组件A，C连接的端口都被禁用，B1的资源也会被释放。</p>
<p><img src="img/2_11.png" alt=""></p>
<p><strong>图 2-11. 组件重连接</strong></p>
<p>###2.1.9 队列和清空<br>一个单独的命令队列能够在使用非管道通信时让组件将没有处理的buffer清空并返回给IL客户端，或在使用管道通信是返回给管道端口。图2-12，假设端口有一个输出端口，它使用了IL客户端分配的buffer。在这个例子中，客户端在发送清空命令之前发送了一串共5块buffer给组件。处理清空命令时，组件按照原先的顺序返回每一个未处理的buffer，并触发事件处理程序通知IL客户端。有两块buffer已经在收到清空命令之前被处理了。组件返回剩下的三块buffer并产生一个事件。IL客户端应该等待此时间然后再去尝试释放这个组件。</p>
<p><img src="img/2_12.png" alt=""></p>
<p><strong>图 2-12. 清空队列</strong></p>
<p>###2.1.10  标记buffer<br>当遇到标记buffer是，IL客户端还可以触发一个事件。一块buffer可以在其头部被标记。标记在OpenMAX组件的输入端口和输出端口直接内部传递。当遇到这块标记buffer是，组件可以发送一个时间给IL客户端。图2-13显示了这是怎么工作的。</p>
<p><img src="img/2_13.png" alt=""></p>
<p><strong>图 2-13. 标记buffer</strong><br>IL客户端发送一个命令来标记buffer。组件的输出端口发送的下一个buffer被标记成B1。组件B处理buffer B1后提供了加入此标记的buffer B2.当组件C从输入端口中收到这个标记过的buffer B2，组件处理这块buffer出发事件处理程序。</p>
<p>###2.1.11  时间和回调<br>组件发送给客户端一共有六种事件：</p>
<ul>
<li>任何时间都可能遇到错误时间</li>
<li>命令成功处理后会触发一个命令完成通知时间</li>
<li>组件检测到一块标记的buffer时会触发标记buffer事件</li>
<li>当组件改变其端口设置时会触发端口设置改变通知事件</li>
<li>码流结束时（EOS）会触发buffer标志事件。</li>
<li>组件获得正在等待的资源时会触发资源获得事件。</li>
</ul>
<p>端口标记buffer的处理回调指示了buffer的可用性或表明buffer是需要的。</p>
<p>###2.1.12  Buffer载荷(Payload)<br>端口的配置用于确定传输到组件端口上的数据格式，但配置并没有定义数据怎么样存储在buffer中的。</p>
<p>通常有三种情况描述了数据如何填充buffer，每一种都有其优点。</p>
<p>在所有的情况下，buffer中有效的数据范围和位置通过buffer头部中的参数<code>pBuffer</code>, <code>nOffset</code> 和<code>nFilledLength</code>来定义。参数<code>pBuffer</code>指向了buffer的起始地址。参数<code>nOffset</code>指示了buffer的起始位置和有效数据开始之间的字节数。参数<code>nFilledLength</code>指定了buffer中连续有效数据的字节数。因此buffer中的有效数据位于<code>pBuffer</code> + <code>nOffset</code> 和 <code>pBuffer</code> + <code>nOffset</code> + <code>nFilledLength</code>之间。</p>
<p>下面的案例代表了在编解码时输入或输出到一个组件的压缩过的数据。在所有的情况中，buffer仅为数据提供传输机制，而对内容没有特别的要求。对内容的要求有端口配置参数定义。</p>
<p>buffer的阴影部分表示数据，白色部分表示没有数据。</p>
<p>情况1：每块buffer全部或部分填充。在含有压缩数据帧的时候，帧由f1到fn表示。</p>
<p><img src="img/2_13_1.png" alt=""></p>
<p>情况1的优点在于解码回放的时候。buffer可以容纳多个帧以减少解码时候的所需的buffer数量。但这种情况下，解码器需要在解码帧的时候解析数据。它也要求解码器组件有一个帧生成buffer，用于放置被解析的数据或维护下一个buffer才能来的完成的部分帧。</p>
<p>情况2：每一块buffer都被完整的压缩数据帧填充。</p>
<p><img src="img/2_13_2.png" alt=""></p>
<p>情况2不同与情况1，它需要压缩的数据首先被解析一遍以保证只有完整的帧被放在buffer中。案例2 也需要解码组件解析数据，但可能不需要额外的工作buffer用于解析帧。</p>
<p>情况3：每一块buffer仅被一个压缩数据帧填充。</p>
<p><img src="img/2_13_3.png" alt=""></p>
<p>案例3的好处是解码组件并不需要解析数据。解析的工作在源组件中完成。但对于这种方式，数据传输是瓶颈。数据传输一次只能传递一帧。基于这种时间，每一帧传输的消耗可能比从buffer中解析帧有更大的消耗。</p>
<p>一个编码器或解码器至少要支持第一种情况。根据定义，编解码其可以支持情况1，那么他可以支持情况2和3，但只有但压缩格式允许帧边界的字节对其。情况2或3的可能没有意义，例如，在RTP-payload格式，bandwidth-efficient模式的AMR的配置中。这种格式定义并不是字节对其，并不适合这些情况定义的字节对齐的帧边界。</p>
<p>当为解码器的输入或者编码器的输出用压缩数据填充一块buffer的时候，只有当帧不是字节对齐时才会遇到限制填充完整帧的问题。在格式的协议之外必须加入额外的填充。之后填充会被删除，因为数据无法被附加。这需要拥有标准规范以外的填充位的知识。同样，如果填充不到位，无法保证标准符合端口配置的标准规范，完整的帧无法被放入buffer中。在这两种情况下，必须知道如果处理这种情况，而且每个组件是不同的。</p>
<p>为了保证通用性，buffer中存储的内容不能假设或要求是完整的若干帧，但对未压缩的数据格式，至少有一个完整数据单元会存在与一个buffer中。压缩数据格式不限制每个buffer中传递的内容量。</p>
<p>###2.1.13  Buffer标记和时间戳<br>buffer标记与buffer包含的数据的某些属性关联。buffer的时间戳以微秒为单位，表示数据被显示的时间。一旦一个时间戳和一块buffer关联，没有组件应该修改这个用于速率控制或同步的时间戳。同步是在时钟组件中实现的。</p>
<p>buffer元数据（即标记和时间戳）适用于buffer中的第一个逻辑单元。因此，buffer中存在多个逻辑单元是，元数据适用于起始边界在buffer中的逻辑单元。除非另有规定（例如，一个标记的定义），一个组件收到有标记或者时间戳的逻辑单元应该将这个元数据拷贝到输入产生的逻辑输出单元中。</p>
<p>###2.1.14  同步<br>同步是靠启用时钟组件上的同步端口来实现的。这些端口和时钟组件被定义在其他（other）域，但操作协议和方法和数据端口一致。时钟组件维护了一个媒体时钟，基于音视频参考时钟，用于跟踪媒体流中的位置。时钟组件通过同步端口发送包含时间信息buffer到客户端组件（由媒体时间更新，包含了媒体时钟的当前位置，缩放和状态）。客户端组件可以通过要求时钟组件发送时间戳来给一个操作确定执行的时间（例如，视频帧的显示）。在这个例子中，客户端组件当收到请求执行时执行操作。图2-14展示了时间和数据buffer流程的一个例子。</p>
<p><img src="img/2_14.png" alt=""></p>
<p><strong>图 2-14. 时间和数据buffer的流程</strong></p>
<p>###2.1.15  速率控制<br>时钟组件还通过暴露一组控制媒体时钟的配置实现了所有的速率控制。IL客户端可能会改变媒体时钟的缩放因子来实现播放，快进，快退，暂停和慢动作特技。IL客户端可以通过改变媒体时钟的状态开始或停止时钟。时钟组件通过向所有的同步端口发送新的缩放或状态的媒体时间更新消息来改变使他所有的客户端组件知道媒体时钟缩放和状态的变化。虽然组件无法改变buffer的时间戳来响应缩放，但他可以响应的改变他的处理流程。例如，音频组件可以在特技播放时调整音调或完全停止输出。</p>
<p>###2.1.16  组件注册<br>通常组件是如何注册到核心是核心自己来定义的。</p>
<p>然而，如果核心支持与组件的静态连接，那么他将支持一个标准的在编译时的组件注册机制，如第3节所述。因此，供应商可以提供组件所有核心支持的合适静态连接的组件，这是通过将组件信息放入数据结构中，这是核心和组件的联系。</p>
<p>一个组件可以使用这个机制静态注册，但他的大部分代码是动态加载的。</p>
<p>###2.1.17  资源管理器<br>这一小节讨论OpenMAX IL API中的资源管理器的角色。</p>
<p>####2.1.17.1  资源管理的需求<br>当组件由于资源不足而不发进入idle状态时，IL客户端不知道缺乏那些资源或是那些组件正在使用这个组员。因此，IL客户端无法关掉所有的组件强制释放音频流（例如），除非知道IL组件是怎么具体实现的。这两种情况都不是可行的选择。这些情况需要IL的资源管理。</p>
<p>OpenMAX的一个目的是提供给上层一个硬件无关的软件层。硬件无关的目标可以通过实现指定资源管理的下列要求来实现：</p>
<ul>
<li>IL客户端（例如，通常是一个软件系统的多媒体插件）不需要知道IL实现的细节或组件使用的资源。例如，IL客户端可能不知道组件是否是硬件加速的。</li>
<li>在资源冲突的情况下，IL客户端可以信赖组件在不同硬件平台上的实现是同一的行为。</li>
<li>一个IL客户端不应该和硬件供应商的资源管理器直接连接，有下面两个原因。<ul>
<li>这种方法违背了硬件无关性的目标。</li>
<li>这种方法增加了IL客户端相当大的工作，因为影响了IL客户端在多个硬件平台上的可复用性。</li>
</ul>
</li>
</ul>
<p>虽然资源管理没有在OpenMAX IL API的1.0版本中彻底解决，“钩子（hook）”资源管理器已经放在了相应的位置包括行为的准则，组件的优先级，资源管理相关的组建状态。这些“钩子”作为后续版本OpenMAX IL API的基础。</p>
<p>在进一步讨论之前，资源管理和策略的术语有必要阐述一下：</p>
<ul>
<li>资源管理负责管理组件对有限资源的访问。资源管理器将知道有多少特定的资源可用，那些组件使用当前资源，以及组件使用的资源有多少。资源管理器将推荐策略，组件可以根据资源可用性和冲突抢占或继续。</li>
<li>策略负责管理组件链或流。策略管理器根据资源管理、系统配置、应用程序请求或其他因素来确定是否允许运行或继续</li>
</ul>
<p>####2.1.17.2  架构假设<br>下面的讨论提出了两个关于OpenMAX IL的架构假设:</p>
<ul>
<li>假设1：一个框架包含客户端和OpenMAX IL之间的策略管理器</li>
<li>假设2：一个系统可以有一个或多个硬件平台，有不同的OpenMAX组件，并被硬件特定的资源管理器管理</li>
</ul>
<p>这些假设如上层架构图图2-15所示。如果一个系统没有架构（即，用户程序接口直接与IL连接），OpenMAX IL API协议没有规定资源管理是如何进行的。假设2规定系统有一个同一集中的资源管理器。</p>
<p><img src="img/2_15.png" alt=""></p>
<p><strong>Figure 2-15. 架构假设</strong></p>
<p>为保证资源冲突是组件的行为是一直的，组件优先级和行为准则的基本定义是必要的。</p>
<p>####2.1.17.3  组件优先级</p>
<p>每一个IL组件有一个优先级值（一个OMX_32整型数），由IL客户端设置。优先级的实际范围可以留给平台，但优先级的顺序是重要的，并且在IL的实现中要一致：递减的优先级顺序。即0是最高优先级。下面的准则也适用：当相同优先级组件进行比较时，最近获得资源的组件应该有更高的优先级。</p>
<p>####2.1.17.4  行为准则<br>IL层定义了下面的行为准则：</p>
<ul>
<li>错误<code>OMX_ErrorInsufficientResources</code>仅当组件试图进入idle状态但没有足够资源或是资源无法被低优先级的组件释放时调用。</li>
<li>组件不知道当他试图进入idle状态时会发生资源抢占，资源需要被低优先级的组件释放。</li>
<li>当一个组件已经被抢占，当从Executing或pause状态转移到idle时，发出<code>OMX_ErrorResourcesPreempted</code>错误，如果从idle转移到loaded状态时，发出 <code>OMX_ErrorResourcesLost</code> 错误给IL客户端，</li>
<li>如果IL客户端想知道什么时候和流相关的组件可以被启动或继续，IL客户端则应该要求当资源可用时被通知。这是通过将组件转移到<code>OMX_StateWaitForResources</code>状态。当资源可用时，组件自动进入idle状态。当客户端收到组件进入idle状态的通知是，它会尝试将其他的链上的组件也转移到idle状态。这种向idle状态的资源的自动转移可以确保当多个IL客户端等待同一个资源时，IL客户端可以当资源可用时立即开始或恢复。如果组件自动转移到loaded状态，其他的IL客户端可以首先获得资源。这些行为准则可以覆盖IL客户端和组件之间的交互。</li>
</ul>
<p>####2.1.17.5  硬件厂商资源管理器<br>要实现行为准则，需要在IL层下拥有一个硬件厂商的资源管理器，并执行下面的功能：</p>
<ul>
<li>实现并管理等待队列。</li>
<li>跟踪可用资源。</li>
<li>跟踪每一个拥有资源的组件和被使用的资源。</li>
<li>当一个高优先级组件请求资源时，通知一个或多个组件让他们放弃他们的资源。</li>
<li>当资源可用时通知等待资源高优先级的组件。</li>
</ul>
<p>组件和硬件资源管理器之间的实际交互是基于特定厂商并超出了本文档的范围。第三节提供了优先级和资源管理相关参数结构和用例的更多细节。</p>
]]></content>
    
    <summary type="html">
    
      &lt;p&gt;#OpenMAX IL 介绍和框架&lt;br&gt;本章介绍了OpenMAX的特点和框架&lt;/p&gt;
&lt;p&gt;##2.1  OpenMAX IL 简介&lt;br&gt;OpenMAX IL层API定义了一个用于在系统提供的软件组件的接入层软件接口。目的是让拥有不同方法的组件提供一个标准化的接口和命令
    
    </summary>
    
    
  </entry>
  
  <entry>
    <title>OpenMax标准协议 第三章 OpenMAX IL控制API</title>
    <link href="http://yoursite.com/2017/04/01/chapter3/"/>
    <id>http://yoursite.com/2017/04/01/chapter3/</id>
    <published>2017-04-01T03:20:10.000Z</published>
    <updated>2017-04-06T03:28:50.667Z</updated>
    
    <content type="html"><![CDATA[<p>#3 OpenMAX IL控制API<br>OpenMAX IL API允许IL客户端控制音频、视频、图像领域上的组件。“其他”领域还包括额外的一些功能，例如音视频同步。OpenMAX IL API的使用者往往是一个多媒体框架。在本文档的其他部分，OpenMAX IL API的使用者指的就是IL客户端。</p>
<p>OpenMAX IL API定义了一组头文件，他们的名称是：</p>
<ul>
<li><code>OMX_Types.h</code>: OpenMAX IL使用的数据类型</li>
<li><code>OMX_Core.h</code>: OpenMAX IL 核心 API</li>
<li><code>OMX_Component.h</code>: OpenMAX 组件 API</li>
<li><code>OMX_Audio.h</code>: OpenMAX 音频数据结构</li>
<li><code>OMX_IVCommon.h</code>: OpenMAX 视频和图像通用的数据结构</li>
<li><code>OMX_Video.h</code>: OpenMAX 视频数据结构</li>
<li><code>OMX_Image.h</code>: OpenMAX 图像据结构</li>
<li><code>OMX_Other.h</code>: OpenMAX 其他的数据结构 (包括音视频同步)</li>
<li><code>OMX_Index.h</code>: OpenMAX定义的数据结构的索引</li>
</ul>
<p>本节介绍了如果配置OpenMAX Core和OpenMAX组件的操作。</p>
<p>首先介绍了OpenMAX的数据类型。其次，阐述了OpenMAX Core的方法。组件的实现的方法在第3.3节中讨论。最后，第3.4节介绍了一些操作的调用顺序，包括组件的初始化，普通数据流，数据管道的建立，数据管道中数据流。这些时序图介绍了IL客户端，IL Core和OpenMAX组件之间的交互。</p>
<p>下面约定用于记录接口方法参数：</p>
<ul>
<li>&lt;参数名&gt; [输入] 指定一个输入参数，由函数调用者设置并被函数读取。</li>
<li>&lt;参数名&gt; [输出] 指定一个输出参数，由函数本身设置并返回给调用者。当函数返回时，调用者读取通过引用传递的参数的新值。</li>
<li>&lt;参数名&gt; [输入输出] 指定一个输入/输出参数，由函数调用者设置。函数改变这个参数的值并返回给调用者。</li>
</ul>
<p>参数的分类可以在OpenMAX的头文件中找到，里面定义了空的宏： <code>OMX_IN</code>, <code>OMX_OUT</code> 和 <code>OMX_INOUT</code>。<code>OMX_IN</code>对应 &lt;参数名&gt; [输入]， <code>OMX_OUT</code>对应&lt;参数名&gt; [输出]， <code>OMX_INOUT</code> 对应&lt;参数名&gt; [输入输出]</p>
<p>##3.1  OpenMAX 类型</p>
<p>###3.1.1 枚举<br><code>OMX_Core.h</code>中定义了5个32位整型枚举数</p>
<ul>
<li><code>OMX_ERRORTYPE</code> 为每一个OpenMAX IL API方法的返回值（见3.1.1.3小节）</li>
<li><code>OMX_COMMANDTYPE</code> 包含了所有IL客户端发往组件的命令（见小节3.1.1.1）</li>
<li><code>OMX_EVENTTYPE</code> 包括了OpenMAX组件产生并传递给IL客户端的消息（见3.1.1.4节）。</li>
<li><code>OMX_BUFFERSUPPLIERTYPE</code> 包括了管道端口中所有可能的buffer供应者。3.1.1.5小节可以看到这个枚举类型用法的描述。</li>
<li><code>OMX_STATETYPE</code>, 在3.1.1.2中描述。</li>
</ul>
<p>图 3-1 显示了<code>OMX_Core.h</code>定义的枚举类型</p>
<p><img src="img/3_1.png" alt=""></p>
<p><strong>图 3-1. OMX_Core.h中定义的枚举类型</strong></p>
<p>####3.1.1.1  OMX_COMMANDTYPE<br>表3-1展示了IL客户端可以向OpenMAX组件发送的消息类型。由于消息是非阻塞的，当消息处理完毕后， OpenMAX组件会生成一个消息完成回调。<br>回调是在一个专门的结构中定义，见3.1.2.7小节。</p>
<table>
<thead>
<tr>
<th>字段名称</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td>OMX_CommandStateSet</td>
<td>切换组件状态</td>
</tr>
<tr>
<td>OMX_CommandFlush</td>
<td>清空组件上一个端口的buffer队列</td>
</tr>
<tr>
<td>OMX_CommandPortDisable</td>
<td>禁用组件上一个端口</td>
</tr>
<tr>
<td>OMX_CommandPortEnable</td>
<td>启用组件上一个端口</td>
</tr>
<tr>
<td>OMX_CommandMarkBuffer</td>
<td>标记一块buffer并指定接受标记时间的组件</td>
</tr>
</tbody>
</table>
<p>表 3-2 描述了每一个命令需要的参数。</p>
<table>
<thead>
<tr>
<th>命令代码</th>
<th>参数</th>
<th>数据</th>
</tr>
</thead>
<tbody>
<tr>
<td>OMX_CommandStateSet</td>
<td>OMX_STATETYPE – 要转移的状态</td>
<td>无</td>
</tr>
<tr>
<td>OMX_CommandFlush</td>
<td>OMX_U32 – 目标端口ID</td>
<td>无</td>
</tr>
<tr>
<td>OMX_CommandPortDisable</td>
<td>OMX_U32 – 目标端口ID</td>
<td>无</td>
</tr>
<tr>
<td>OMX_CommandPortEnable</td>
<td>OMX_U32 – 目标端口ID</td>
<td>无</td>
</tr>
<tr>
<td>OMX_CommandMarkBuffer</td>
<td>OMX_U32 – 目标端口ID</td>
<td>OMX_MARKTYPE* - 标记数据和目标组件</td>
</tr>
</tbody>
</table>
<p><strong>表 3-2. 命令语法</strong></p>
<p>####3.1.1.2  OMX_STATETYPE<br>表3-2展示了IL客户端调用了一系列<code>OMX_SendCommand</code>(<code>OMX_StateSet</code>, &lt;状态&gt;)后的状态转移，新的状态当参数传递给组件。尖括号包围的转移名表示转换不是由IL客户端命令触发的，而是由一系列组件内部事件的结果。</p>
<p><img src="img/3_2.png" alt=""></p>
<p><strong>图 3-2. OpenMAX 组件状态转移</strong></p>
<p>这个小节描述了组件的状态。IL客户端通过调用<code>OMX_SendCommand</code>发送<code>OMX_CommandStateSet</code>命令来切换组件状态。</p>
<p>表 3-3 展示了OpenMAX组件的状态</p>
<table>
<thead>
<tr>
<th>字段名</th>
<th>描述</th>
<th>是否获取资源</th>
<th>buffer位置</th>
</tr>
</thead>
<tbody>
<tr>
<td>OMX_StateInvalid</td>
<td>组件已损坏或遇到无法回复的错误</td>
<td>未知</td>
<td>未知</td>
</tr>
<tr>
<td>OMX_StateLoaded</td>
<td>组件已加载但没有获得资源</td>
<td>否</td>
<td>无</td>
</tr>
<tr>
<td>OMX_StateIdle</td>
<td>组件已获得资源但没有转递任何buffer或开始处理数据</td>
<td>是</td>
<td>只有供应者</td>
</tr>
<tr>
<td>OMX_StateExecuting</td>
<td>组件以开始转递buffer并处理数据</td>
<td>是</td>
<td>供应者和非供应者</td>
</tr>
<tr>
<td>OMX_StatePause</td>
<td>组件暂停处理数据但可能会从暂停点恢复</td>
<td>是</td>
<td>供应者和非供应者</td>
</tr>
<tr>
<td>OMX_StateWaitForResources</td>
<td>组件在等待可用资源</td>
<td>否</td>
<td>无</td>
</tr>
</tbody>
</table>
<p><strong>表 3-3. OpenMAX 组件状态</strong></p>
<p>######3.1.1.2.1  OMX_StateLoaded<br>在调用<code>OMX_GetHandle</code>创建组件之后，分配资源之前，组件处于<code>OMX_StateLoaded</code>状态。在这个状态，IL客户端可以通过<code>OMX_SetParameter</code>改变组件参数，创建组件端口上的数据通道，或者切换组件状态至<code>OMX_StateIdle</code>或<code>OMX_StateWaitForResources</code>。</p>
<p>IL客户端可以选择一个处于<code>OMX_StateLoaded</code>的组件转移到<code>OMX_StateWaitForResources</code>状态，例如，组件未能获得切换到<code>OMX_StateIdle</code>状态的资源。</p>
<h6 id="3-1-1-2-1-1-OMX-StateLoaded-到-OMX-StateIdle"><a href="#3-1-1-2-1-1-OMX-StateLoaded-到-OMX-StateIdle" class="headerlink" title="3.1.1.2.1.1  OMX_StateLoaded 到 OMX_StateIdle"></a>3.1.1.2.1.1  OMX_StateLoaded 到 OMX_StateIdle</h6><p>如果IL客户端请求状态由<code>OMX_StateLoaded</code>切换到<code>OMX_StateIdle</code>，组件必须在完成状态切换前获得所有的资源，包换buffer。此外，在状态切换完成之前，buffer的提供者（在非管道模式时为IL客户端），必须保证非提供者拥有他所有的buffer。如果一个端口连接到IL客户端，IL客户端可以自己分配buffer并通过调用端口上的<code>OMX_UseBuffer</code>方法转递给端口，或者调用端口上<code>OMX_AllocateBuffer</code>命令让端口直接分配。</p>
<p>当端口出于管道状态，供应端口要么自己分配buffer，要么当端口实现了buffer共享时，复用同组件上的其他端口上的buffer。管道供应端口则通过调用非供应者的<code>OMX_UseBuffer</code> 将buffer转递给非供应者。</p>
<p>端口上的buffer数量由端口的定义（见<code>OMX_IndexParamPortDefinition</code>）确定，默认是最小值（见同一个数据结构）。但在提供者可以调用<code>OMX_UseBuffer</code> 和<code>OMX_AllocateBuffer</code>之前可以通过调用 <code>OMX_SetParameter</code>修改此值。</p>
<p>#####3.1.1.2.2  OMX_StateIdle<br>在<code>OMX_StateIdle</code>状态时，组件已经可以被使用，这意味着所有必要的资源已经分配。但是，提供者仍然保留着buffer，并没有发生buffer交换或处理。因此，如果这个状态由<code>OMX_StateExecuting</code>或<code>OMX_StatePause</code>转移而来，组件必须归还他正在处理的所有buffer给他的提供者。IL客户端可能会转移到除了<code>OMX_StateInvalid</code>和<code>OMX_StateWaitForResources</code>任何其他状态。</p>
<p>######3.1.1.2.2.1  OMX_StateIdle 到 OMX_StateLoaded<br>在从<code>OMX_StateIdle</code> 到 <code>OMX_StateLoaded</code>的转移过程中，每一个buffer提供者必须为非提供者端口上的每一块buffer调用<code>OMX_FreeBuffer</code>方法。如果提供者分配了buffer，他必须在调用<code>OMX_FreeBuffer</code>之前释放buffer。如果非供应端口分配了buffer，他必须收到<code>OMX_FreeBuffer</code>调用时释放内存。此外，非供应端口总是必须收到<code>OMX_FreeBuffer</code>调用时释放buffer头。当所有的buffer被移出组件时，状态转移完成。组件通过一个回调时间表示调用<code>OMX_SendCommand</code>完成。</p>
<p>######3.1.1.2.2.2  OMX_StateIdle 到 OMX_StateExecuting<br>如果IL客户端请求将状态由<code>OMX_StateIdle</code>切换至<code>OMX_StateExecuting</code>，组件应该开始转移并处理数据。和IL客户端通信的端口，IL客户端会通过<code>OMX_EmptyThisBuffer</code>和<code>OMX_FillThisBuffer</code>初始化数据传输。在管道端口中，任何输入端口也是供应端口，应该把它的空buffer通过调用<code>OMX_FillThisBuffer</code>转移给他的管道输出端口。</p>
<p>#####3.1.1.2.3  OMX_StateExecuting<br>在这个状态中，OpenMAX组件传输并处理数据。组件应该接受其输入端口的<code>OMX_EmptyThisBuffer</code> 调用和输出端口的<code>OMX_EmptyThisBuffer</code>。任何与IL端口通信的端口应该调用回调函数<code>EmptyBufferDone</code>和<code>FillBufferDone</code>返回空或满的buffer给IL客户端。管道端口应该调用<code>OMX_FillThisBuffer</code>或<code>OMX_EmptyThisBuffer</code>返回空或满的buffer给管道端口的另一段。IL客户端可以将组件从<code>OMX_StateIdle</code>或<code>OMX_StatePaused</code>转移至<code>OMX_StateExecuting</code>。</p>
<p>######3.1.1.2.3.1  OMX_StateExecuting 到 OMX_StateIdle<br>如果IL客户端请求状态由<code>OMX_StateExecuting</code>转移到<code>OMX_StateIdle</code>，组件应该在转移完成之前归换所有的buffer给他的提供者，并且接受所有自身提供者端口上的buffer。任何与IL客户端通信的端口应该通过<code>OMX_EmptyBufferDone</code>和<code>OMX_FillBufferDone</code>返回自己持有的buffer，这些buffer本来是分别给输入或输出端口使用的。任何管道端口应该通过<code>OMX_EmptyBufferDone</code>和<code>OMX_FillBufferDone</code>返回自己持有的buffer给管道另一端的端口。同理，非供应管道端口应该等待他的管道端口返回所有的buffer。</p>
<p>#####3.1.1.2.4  OMX_StatePause<br>在这个状态下，OpenMAX组件不传输或者处理数据，但buffer也不会返回给供应者。<code>OMX_StatePause</code>转移到<code>OMX_StateExecuting</code>，执行可以继续并且可能不会丢失数据。组件在自己的输入端口上可能继续接受数据，但这些buffer仅仅存放到队列中但不会进一步处理。 IL客户端可能将组将由<code>OMX_StatePause</code>转移至<code>OMX_StateIdle</code>或<code>OMX_StateExecuting</code>。在<code>OMX_StatePause</code>向<code>OMX_StateIdle</code>转移时,组件应该想他的供应者归还所有的buffer，方式描述参见3.1.1.2.3.1小节。</p>
<p>#####3.1.1.2.5  OMX_StateWaitForResources<br>在这个状态中，组件等待一个或多个需要的资源。这个状态和资源管理器有关。假设系统有一个或多个硬件特有的资源管理器来管理资源。OpenMAX组件和资源管理器之间的交互不再本标准讨论范围内。</p>
<p>如果处于<code>OMX_StateLoaded</code>状态的组件由于非buffer资源不足而无法切换至<code>OMX_StateIdle</code>状态是，IL客户端如果希望知道什么时候资源变得可用，那么可以将组件至于<code>OMX_StateWaitForResources</code>状态。IL客户端可以通过由<code>OMX_StateWaitForResources</code>状态转移至 <code>OMX_StateLoaded</code>命令组件停止等待资源。如果在<code>OMX_StateWaitForResources</code>状态的组件得到了所有等待的资源，它应该开始转移至<code>OMX_StateIdle</code>。</p>
<p>######3.1.1.2.5.1  OMX_StateWaitForResources 到 OMX_StateIdle<br>当组件开始从<code>OMX_StateWaitForResources</code>向<code>OMX_StateIdle</code>转移，它应该通过事件<code>OMX_EventResourcesAcquired</code>向IL客户端进行通知。当IL客户端收到<code>OMX_EventResourcesAcquired</code>时间，它应该调用<code>OMX_UseBuffer</code> 和<code>OMX_AllocateBuffer</code>，和从<code>OMX_StateLoaded</code>向 <code>OMX_StateIdle</code>一样，同理，除非组件获得了所有的资源，包括buffer，他不能完成到<code>OMX_StateIdle</code>的状态转移。</p>
<p>#####3.1.1.2.6  OMX_StateInvalid<br>在这个状态时，组件发现内部损坏或遇到无法恢复的错误。当它检测到这个情况是，组件将自己转移到<code>OMX_StateInvalid</code>并通知IL客户端产生一个值为<code>OMX_ErrorInvalidState</code>的<code>OMX_ErrorEvent</code>事件。 但客户端收到这个时间。它应该释放组件关联的所有资源并且最后调用<code>OMX_FreeHandle</code>释放组件关联的句柄。</p>
<p>位于<code>OMX_StateInvalid</code>状态的组件应该除了 <code>OMX_GetState</code>, <code>OMX_FreeBuffer</code>, 或<code>OMX_ComponentDeinit</code>方法调用外，其他的调用都失败并返回<code>OMX_ErrorStateInvalid</code>错误信息。IL组件应该同样明确的通过<code>OMX_SendCommand</code>将组件转移到<code>OMX_StateInvalid</code>状态。组件可以从任意状态转移到<code>OMX_StateInvalid</code>。</p>
<p>####3.1.1.3  OMX_ERRORTYPE<br>表3-4描述了枚举类型<code>OMX_ERRORTYPE</code>，它定义了每一个OpenMAX IL API返回的OpenMAX的标准错误。这些错误可以覆盖大多数的普通错误。但是硬件厂商可以根据下面的原则自由的加入额外的错误类型：</p>
<ul>
<li>厂商的错误消息范围是0x90000000到0x9000FFFF。</li>
<li>厂商错误消息应该定义在和组件一起提供的头文件中。未定义的错误消息是不允许的。</li>
</ul>
<table>
<thead>
<tr>
<th>字段名称</th>
<th style="text-align:center">值</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td>OMX_ErrorNone</td>
<td style="text-align:center">0</td>
<td>函数返回正确</td>
</tr>
<tr>
<td>OMX_ErrorInsufficientResources</td>
<td style="text-align:center">0x80001000</td>
<td>执行请求操作没有足够的资源</td>
</tr>
<tr>
<td>OMX_ErrorUndefined</td>
<td style="text-align:center">0x80001001</td>
<td>未知原因的错误</td>
</tr>
<tr>
<td>OMX_ErrorInvalidComponentName</td>
<td style="text-align:center">0x80001002</td>
<td>组件名错误</td>
</tr>
<tr>
<td>OMX_ErrorComponentNotFound</td>
<td style="text-align:center">0x80001003</td>
<td>没有找到指定名称的组件</td>
</tr>
<tr>
<td>OMX_ErrorInvalidComponent</td>
<td style="text-align:center">0x80001004</td>
<td>指定组件没有<code>OMX_ComponentInit</code>入口，或者组件没有完成<code>OMX_ComponentInit</code>调用</td>
</tr>
<tr>
<td>OMX_ErrorBadParameter</td>
<td style="text-align:center">0x80001005</td>
<td>一个或多个参数非法</td>
</tr>
<tr>
<td>OMX_ErrorNotImplemented</td>
<td style="text-align:center">0x80001006</td>
<td>请求功能未实现</td>
</tr>
<tr>
<td>OMX_ErrorUnderflow</td>
<td style="text-align:center">0x80001007</td>
<td>下一个buffer准备好之前目前的buffer已空</td>
</tr>
<tr>
<td>OMX_ErrorOverflow</td>
<td style="text-align:center">0x80001008</td>
<td>需要buffer的时候不可用</td>
</tr>
<tr>
<td>OMX_ErrorHardware</td>
<td style="text-align:center">0x80001009</td>
<td>硬件响应错误</td>
</tr>
<tr>
<td>OMX_ErrorInvalidState</td>
<td style="text-align:center">0x8000100A</td>
<td>组件处于<code>OMX_StateInvalid</code>状态</td>
</tr>
<tr>
<td>OMX_ErrorStreamCorrupt</td>
<td style="text-align:center">0x8000100B</td>
<td>发现流损坏</td>
</tr>
<tr>
<td>OMX_ErrorPortsNotCompatible</td>
<td style="text-align:center">0x8000100C</td>
<td>建立管道的端口不兼容</td>
</tr>
<tr>
<td>OMX_ErrorResourcesLost</td>
<td style="text-align:center">0x8000100D</td>
<td>处于<code>OMX_StateIdle</code> 状态的组件丢失了分配的资源， 导致组件回到<code>OMX_StateLoaded</code>状态</td>
</tr>
<tr>
<td>OMX_ErrorNoMore</td>
<td style="text-align:center">0x8000100E</td>
<td>没有更多的索引可以枚举。</td>
</tr>
<tr>
<td>OMX_ErrorVersionMismatch</td>
<td style="text-align:center">0x8000100F</td>
<td>组件检测到版本不匹配。</td>
</tr>
<tr>
<td>OMX_ErrorNotReady</td>
<td style="text-align:center">0x80001010</td>
<td>组件此时没有准备好返回数据。</td>
</tr>
<tr>
<td>OMX_ErrorTimeout</td>
<td style="text-align:center">0x80001011</td>
<td>发生超时.</td>
</tr>
<tr>
<td>OMX_ErrorSameState</td>
<td style="text-align:center">0x80001012</td>
<td>组件试图切换至当前正处于的状态</td>
</tr>
<tr>
<td>OMX_ErrorResourcesPreempted</td>
<td style="text-align:center">0x80001013</td>
<td>处于 <code>OMX_StateExecuting</code>或 <code>OMX_Pause</code>状态的组件所分配的资源被抢占，导致组件回到<code>OMX_StateIdle</code>状态</td>
</tr>
<tr>
<td>OMX_ErrorPortUnresponsiveDuringAllocation</td>
<td style="text-align:center">0x80001014</td>
<td>非供应端口认为等待供应端口调用<code>OMX_UseBuffer</code>来分配buffer时间过长。非供应端口在loaded向idle进行状态切换时或启用某一端口时通过<code>EventHandler</code>回调发送此错误给IL客户端</td>
</tr>
<tr>
<td>OMX_ErrorPortUnresponsiveDuringDeallocation</td>
<td style="text-align:center">0x80001015</td>
<td>非供应端口认为等待供应端口调用<code>OMX_FreeBuffer</code>来释放buffer时间过长。非供应端口在idle向loaded进行状态切换时或禁用某一端口时通过<code>EventHandler</code>回调发送此错误给IL客户端</td>
</tr>
<tr>
<td>OMX_ErrorPortUnresponsiveDuringStop</td>
<td style="text-align:center">0x80001016</td>
<td>供应端口认为等待非供应端口调用<code>EmptyThisBuffer</code>或<code>FillThisBuffer</code>返回时间过长。供应端口在idle向loaded进行状态切换时或禁用某一端口时通过<code>EventHandler</code>回调发送此错误给IL客户端</td>
</tr>
<tr>
<td>OMX_ErrorIncorrectStateTransition</td>
<td style="text-align:center">0x80001017</td>
<td>试图进行不允许的状态转移</td>
</tr>
<tr>
<td>OMX_ErrorIncorrectStateOperation</td>
<td style="text-align:center">0x80001018</td>
<td>试图调用的命令和方法在当前状态是不支持的</td>
</tr>
<tr>
<td>OMX_ErrorUnsupportedSetting</td>
<td style="text-align:center">0x80001019</td>
<td>一个或多个参数或配置结构不正确</td>
</tr>
<tr>
<td>OMX_ErrorUnsupportedIndex</td>
<td style="text-align:center">0x8000101A</td>
<td>给出的索引参数或配置不支持</td>
</tr>
<tr>
<td>OMX_ErrorBadPortIndex</td>
<td style="text-align:center">0x8000101B</td>
<td>给出得端口索引不正确</td>
</tr>
<tr>
<td>OMX_ErrorPortUnpopulated</td>
<td style="text-align:center">0x8000101C</td>
<td>端口丢失了一个或多个buffer</td>
</tr>
</tbody>
</table>
<p><strong>Table 3-4. OpenMAX 错误代码</strong></p>
<p>####3.1.1.4  OMX_EVENTTYPE<br>枚举类型<code>OMX_EVENTTYPE</code>如表3-5所示，它包括了OpenMAX组件产生的事件类型。3.1.2.7小节描述了OpenMAX组件产生事件并通过回调传送给IL客户端。与事件关联的参数也一并通过回调传递。</p>
<table>
<thead>
<tr>
<th>字段名</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>OMX_EventCmdComplete</td>
<td>组件完成命令执行。</td>
</tr>
<tr>
<td>OMX_EventError</td>
<td>组件检测到错误。</td>
</tr>
<tr>
<td>OMX_EventMark</td>
<td>一个标记的buffer到达目标组件，IL客户端收到此带有指向私有数据指针的事件。</td>
</tr>
<tr>
<td>OMX_EventPortSettingsChanged</td>
<td>组件改变了端口设置。例如，组件根据比特流的解析相应的改变了端口设置。</td>
</tr>
<tr>
<td>OMX_EventBufferFlag</td>
<td>组件检测到码流结束（EOS）时发送的事件。</td>
</tr>
<tr>
<td>OMX_EventResourcesAcquired</td>
<td>组件得到资源并将从<code>OMX_StateWaitForResources</code>切换到<code>OMX_StateIdle</code></td>
</tr>
</tbody>
</table>
<p><strong>表 3-5. OpenMAX 事件类型</strong></p>
<p>#####3.1.1.4.1  OMX_EventCmdComplete<br>组件完成命令执行后会立刻产生<code>OMX_EventCmdComplete</code>事件传递给IL客户端。如果是组件状态改变，新状态会作为事件的参数。组件转移到<code>OMX_StateInvalid</code>不会产生此事件。</p>
<p>#####3.1.1.4.2  OMX_EventError<br>组件检测到下面的情况的错误时会产生｀OMX_EventError｀事件，错误事件类型会放在事件参数中，并使用<code>OMX_ERRORTYPE</code>中定义的值。组件应该通过<code>OMX_EventError</code>发送下面的错误：</p>
<ul>
<li>组件转移到<code>OMX_StateInvalid</code>状态时会发送<code>OMX_ErrorInvalidState</code>错误。</li>
<li>组件由于资源不足时从<code>OMX_StateExecuting</code> 或 <code>OMX_StatePause</code> 切换到 <code>OMX_StateIdle</code>时会发送<code>OMX_ErrorResourcesPreempted</code>错误。</li>
<li>组件由于资源丢失而从<code>OMX_StateIdle</code> 切换到 <code>OMX_StateLoaded</code>时会发送<code>OMX_ErrorResourcesLost</code>错误。</li>
</ul>
<p>#####3.1.1.4.3  OMX_EventMark<br>组件受到一块标记过的buffer时会产生<code>OMX_EventMark</code>事件。组件收到buffer时，他应该比较自身指针和buffer中<code>pMarkTargetComponent</code>字段。如果指针相等，组件处理完buffer后应该立即发送一个包含<code>pMarkData</code>参数的标记事件。IL客户端可以使用使用此标记事件来计算组件链上的传输延时，或通知组件一个快特殊的buffer已经到达目的地。</p>
<p>#####3.1.1.4.4  OMX_EventPortSettingsChanged<br>组件改变端口设置时会立刻产生<code>OMX_EventPortSettingsChanged</code>事件。例如，视频解码器可能不知道输出视频的帧大小和帧率，因为这些参数在输入比特流中编码。一旦这些组件被解析了，组件改变输出组件上的配置结构并且传递<code>OMX_EventPortSettingsChanged</code>事件给IL客户端。</p>
<p>#####3.1.1.4.5  OMX_EventBufferFlag<br>当一个输出端口发出一个在字段<code>nFlags</code>带有<code>OMX_BUFFERFLAG_EOS</code>标识的buffer时，组件产生<code>OMX_EventBufferFlag</code>事件。事件处理程序中的<code>nData1</code>字段指示了输出端口的索引， <code>nData2</code>字段指示了包含码流结束（EOS）标志的不可变的｀nFlags｀字段。如果组件不再传递流（例如，组件时一个视频或视频sink），组件处理完带有<code>OMX_BUFFERFLAG_EOS</code>的buffer后，应该为此流发送一个<code>OMX_EventBufferFlag</code>事件。事件处理程序的<code>nData1</code>字段指定了接受buffer的输入端口，｀nData2｀字段指定了含有EOS标志的不可变的<code>nFlags</code>字段。</p>
<p>#####3.1.1.4.6  OMX_EventResourcesAcquired<br>组件处于<code>OMX_StateWaitForResources</code>状态时，资源管理器检测到所需资源可用时，组件产生<code>OMX_EventResourcesAcquired</code>事件。组件收到这个事件时，它便可以转移状态到<code>OMX_StateIdle</code>，并且会所有端口上的buffer分配。</p>
<p>####3.1.1.5  OMX_BUFFERSUPPLIERTYPE<br>表3-6中的枚举类型｀OMX_BUFFERSUPPLIERTYPE｀指明了管道端口中的供应端口。一个供应端口要么自己分配buffer，要么复用同一组件下的另一个端口的buffer。</p>
<table>
<thead>
<tr>
<th>字段名称</th>
<th>值</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>OMX_BufferSupplyUnspecified</td>
<td>0x0</td>
<td>提供buffer的端口未指定，或没有优先的提供者。</td>
</tr>
<tr>
<td>OMX_BufferSupplyInput</td>
<td></td>
<td>输入端口提供buffer。</td>
</tr>
<tr>
<td>OMX_BufferSupplyOutput</td>
<td></td>
<td>输出端口提供buffer。</td>
</tr>
</tbody>
</table>
<p><strong>表 3-6. OpenMAX管道建立时Buffer提供类型</strong></p>
<p>###3.1.2 结构<br>本小节讨论了OpenMAX core中定义的数据结构。每个OpenMAX组件的钱两个字段指明了结构的大小和小节3.1.2.4中定义的版本号<code>OMX_VERSIONTYPE</code>。分配OpenMAX结构的实例负责填充着两个值。</p>
<p>####3.1.2.1  OMX_COMPONENTREGISTERTYPE<br>`OMX_COMPONENTREGISTERTYPE｀结构用于组件静态链接到core中时。Core使用此结构加载和运行特定的组件初始化方法。</p>
<p><code>OMX_COMPONENTREGISTERTYPE</code>定义如下.</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div></pre></td><td class="code"><pre><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct</span> OMX_COMPONENTREGISTERTYPE</div><div class="line">&#123;</div><div class="line">  <span class="keyword">const</span> <span class="keyword">char</span> * pName;</div><div class="line">  OMX_COMPONENTINITTYPE pInitialize;</div><div class="line">&#125; OMX_COMPONENTREGISTERTYPE;</div></pre></td></tr></table></figure>
<p>####3.1.2.2  OMX_COMPONENTINITTYPE Type Definition<br><code>OMX_COMPONENTINITTYPE</code>类型定义了组件初始化入口的程序指针。定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div></pre></td><td class="code"><pre><div class="line"><span class="function"><span class="keyword">typedef</span> <span class="title">OMX_ERRORTYPE</span> <span class="params">(* OMX_COMPONENTINITTYPE)</span><span class="params">(OMX_IN OMX_HANDLETYPE hComponent)</span></span>;</div></pre></td></tr></table></figure>
<p>#####3.1.2.2.1  pName<br><code>pName</code>包含了组件的名称，最大不超过128个字节（包括‘\0’）</p>
<p>#####3.1.2.2.2  pInitialize<br><code>pInitialize</code>包括了组件初始化函数的指针。</p>
<p>####3.1.2.3  OMX_ComponentRegistered[]<br>任何静态链接组件的core应该在<code>OMX_COMPONENTREGISTERTYPE</code>字段中声明它所有注册的全局组件列表。</p>
<p>####3.1.2.4  OMX_VERSIONTYPE<br><code>OMX_VERSIONTYPE</code>类型指示了组件或结构的版本。每个结构使用<code>OMX_VERSIONTYPE</code>字段指定了结构的OpenMAX版本。对OpenMAX IL 1.0版本，协议版本时1.0.0.0。组件结构也包含了一个厂商特定的组件版本号的<code>OMX_VERSIONTYPE</code>字段。</p>
<p><code>OMX_VERSIONTYPE</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div><div class="line">11</div></pre></td><td class="code"><pre><div class="line"><span class="keyword">typedef</span> <span class="keyword">union</span> OMX_VERSIONTYPE</div><div class="line">&#123;</div><div class="line">  <span class="keyword">struct</span></div><div class="line">  &#123;</div><div class="line">    OMX_U8 nVersionMajor;</div><div class="line">    OMX_U8 nVersionMinor;</div><div class="line">    OMX_U8 nRevision;</div><div class="line">    OMX_U8 nStep;</div><div class="line">  &#125; ;</div><div class="line">  OMX_U32 nVersion;</div><div class="line">&#125; OMX_VERSIONTYPE;</div></pre></td></tr></table></figure>
<p>#####3.1.2.4.1  nVersionMajor<br><code>nVersionMajor</code> 标识主要版本号.</p>
<p>#####3.1.2.4.2  nVersionMinor<br><code>nVersionMinor</code> 标识次要版本号.</p>
<p>#####3.1.2.4.3  nRevision<br><code>nRevision</code> 标识修订号.</p>
<p>#####3.1.2.4.4  nStep<br><code>nStep</code> 步骤号。</p>
<p>####3.1.2.5  OMX_PRIORITYMGMTTYPE<br><code>OMX_PRIORITYMGMTTYPE</code>类型指示了组件组的被指定的优先级。组件组指的是与一个相同的功能关联的相互依赖的一组组件。组里的所有组件使用相同的组ID和优先级。如果组里的一个组件丢失了资源并停止运行，他们所共同提供的功能也会结束。这种情况下，同一组的所有其他组件应该转移到<code>OMX_StateLoaded</code>。组件仅有一个特定的<code>nGroupID</code>的行为时原子的。</p>
<p><code>OMX_PRIORITYMGMTTYPE</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct</span> OMX_PRIORITYMGMTTYPE &#123;</div><div class="line">  OMX_U32 nSize;</div><div class="line">  OMX_VERSIONTYPE nVersion;</div><div class="line">  OMX_U32 nGroupPriority;</div><div class="line">  OMX_U32 nGroupID;</div><div class="line">&#125; OMX_PRIORITYMGMTTYPE;</div></pre></td></tr></table></figure>
<p>#####3.1.2.5.1  nGroupPriority<br>｀nGroupPriority｀的值为组件组的优先级。如果组件被指定了这个类型的参数，那么组件所在的组的组件优先级也是这个值。根据定义，0代表了组件组的最高优先级。</p>
<p>指定组件组的具体机制不再本文档讨论范围。</p>
<p>#####3.1.2.5.2  nGroupID<br>｀nGroupID｀的值是同一个组件组里所有组件的唯一ID。</p>
<p>####3.1.2.6  OMX_BUFFERHEADERTYPE<br>在一个单一端口的上下文中，每一个数据buffer拥有一个相关联的头，包括了buffer的元信息。IL客户端与每一个与之通信的端口共享buffer头。同理，每一个管道两头的两个端口共享buffer头。另外，如果一个buffer传输到多个端口将buffer头分到每一个端口上去。buffer头的定义如下。</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div><div class="line">11</div><div class="line">12</div><div class="line">13</div><div class="line">14</div><div class="line">15</div><div class="line">16</div><div class="line">17</div><div class="line">18</div><div class="line">19</div><div class="line">20</div></pre></td><td class="code"><pre><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct</span> OMX_BUFFERHEADERTYPE</div><div class="line">&#123;</div><div class="line">  OMX_U32 nSize;</div><div class="line">  OMX_VERSIONTYPE nVersion;</div><div class="line">  OMX_U8* pBuffer;</div><div class="line">  OMX_U32 nAllocLen;</div><div class="line">  OMX_U32 nFilledLen;</div><div class="line">  OMX_U32 nOffset;</div><div class="line">  OMX_PTR pAppPrivate;</div><div class="line">  OMX_PTR pPlatformPrivate;</div><div class="line">  OMX_U32 nOutputPortPrivate;</div><div class="line">  OMX_U32 nInputPortPrivate;</div><div class="line">  OMX_HANDLETYPE hMarkTargetComponent;</div><div class="line">  OMX_PTR pMarkData;</div><div class="line">  OMX_U32 nTickCount;</div><div class="line">  OMX_TICKS nTimeStamp;</div><div class="line">  OMX_U32 nFlags;</div><div class="line">  OMX_U32 nOutputPortIndex;</div><div class="line">  OMX_U32 nInputPortIndex;</div><div class="line">&#125; OMX_BUFFERHEADERTYPE;</div></pre></td></tr></table></figure>
<p>#####3.1.2.6.1  pBuffer<br><code>pBuffer</code>为buffer中数据存储的真实指针，但并不一定时是有效数据的起始位置。更多信息参考3.1.2.6.4描述的<code>nOffset</code>。</p>
<p>#####3.1.2.6.2  nAllocLen<br><code>nAllocLen</code>为buffer中分配的总大小，包括有效的和未用的字节。</p>
<p>#####3.1.2.6.3  nFilledLen<br><code>nFilledLen</code>为buffer中有效数据的总大小，从<code>pBuffer</code>和<code>nOffset</code>指定的位置开始。</p>
<p>#####3.1.2.6.4  nOffset<br><code>nOffset</code>为从buffer开始计算的有效数据的偏移位置。有效数据的指针可以从<code>nOffset</code>和<code>pBuffer</code>相加得到。</p>
<p>#####3.1.2.6.5  pAppPrivate<br><code>pAppPrivate</code>为指向IL客户端私有结构的指针。</p>
<p>#####3.1.2.6.6  pPlatformPrivate<br><code>pPlatformPrivate</code>为指向平台私有结构的指针。分配buffer头结构的core使用这个指针。</p>
<p>#####3.1.2.6.7  pOutputPortPrivate<br><code>pOutputPortPrivate</code>为使用buffer的输出端口的私有指针。如果buffer头用于输入端口与IL客户端之间的通信，buffer的<code>pOutputPortPrivate</code>则不用定义。</p>
<p>#####3.1.2.6.8  pInputPortPrivate<br><code>pInputPortPrivate</code>为使用buffer的输入端口的私有指针。如果buffer头用于输出端口与IL客户端之间的通信，buffer的<code>pInputPortPrivate</code>则不用定义。</p>
<p>#####3.1.2.6.9  hMarkTargetComponent<br><code>hMarkTargetComponent</code>为处理buffer时需要发出｀OMX_EventMark｀消息的组件的句柄。一个空的句柄表面buffer没有携带任何标记。<code>OMX_CommandMarkBuffer</code>命令将次句柄传递给标记的组件。标记的组件，将此句柄复制到标记的buffer中。每个处理此buffer的组件应该使用这个句柄和自己向比较，如果相同，则发出标记消息。组件应该在输入buffer和相应的输出buffer中传递这个字段。</p>
<p>#####3.1.2.6.10  pMarkData<br><code>pMarkData</code>指针指向IL客户端特定的数据，与<code>OMX_EventMark</code>发出的消息标志相关联。当收到这个标记时，IL客户端可以使用这个数据来和其他的标记相区别。命令<code>OMX_CommandMarkBuffer</code>提供此指针来标记组件。标记的组件，将此句柄复制到标记的buffer中。组件应该在输入buffer和相应的输出buffer中传递这个字段。</p>
<p>#####3.1.2.6.11  nTickCount<br><code>nTickCount</code>为一个组件和IL客户端可以更新的计时器，为可选条目，不是所有的组件会更新它。｀nTickCount｀的值以微秒为单位。由于这个值是一个任意起始点的相对值，它不能用于确定绝对时间。</p>
<p>#####3.1.2.6.12  nTimeStamp<br><code>nTimeStamp</code>为buffer中第一个逻辑单元的时间戳。Buffer中后续数据的时间戳可以通过buffer的持续时间和此时间戳相加得到。组件应该在输入buffer和相应的输出buffer中传递这个字段。</p>
<p>#####3.1.2.6.13  nFlags<br><code>nFlags</code>字段包含了buffer的特定的标志，例如EOS标志。组件应该在输入buffer和相应的输出buffer中传递这个字段。标志的列表如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_BUFFERFLAG_EOS 0x00000001</span></div><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_BUFFERFLAG_STARTTIME 0x00000002</span></div><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_BUFFERFLAG_DECODEONLY 0x00000004</span></div><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_BUFFERFLAG_DATACORRUPT 0x00000008</span></div><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_BUFFERFLAG_ENDOFFRAME 0x00000010</span></div></pre></td></tr></table></figure>
<p>######3.1.2.6.13.1  OMX_BUFFERFLAG_EOS<br>如果组件的输出端口没有更多的数据发出，则会设置EOS。因此，一个输出端口应该在最后一个发出的buffer上设置EOS，输出端口什么时候停止发送数据由具体的实现决定。</p>
<p>######3.1.2.6.13.2  OMX_BUFFERFLAG_STARTTIME<br>流的源（例如，分离器组件）设置包含流的起始时间戳的buffer<code>OMX_BUFFERFLAG_STARTTIME</code>标志。起始时间戳对应了起始或跳转操作后第一帧数据显示时间。</p>
<p>流的第一个时间戳不一定是起始时间。例如，在搜索一个特定视频帧的情况下，目标帧可能是一个帧间帧。因此，流的第一帧应该是在目标帧之前的帧内帧。在目标帧所依赖的帧重建完毕后，才能发生目标帧的起始时间。</p>
<p><code>OMX_BUFFERFLAG_STARTTIME</code>标志直接和buffer的时间戳向关联。因此，buffer数据和<code>OMX_BUFFERFLAG_STARTTIME</code>标志的关系和传输和时间戳完全一致。</p>
<p>时钟组件收到一个带有<code>STARTTIME</code>标志的buffer应该在它的同步端口上使用<code>OMX_ConfigTimeClientStartTime</code>调用<code>OMX_SetConfig</code>来传递buffer的时间戳。</p>
<p>######3.1.2.6.13.3  OMX_BUFFERFLAG_DECODEONLY<br>流的源头（例如，一个分离器组件）设置一个只解码不显示的buffer<code>OMX_BUFFERFLAG_DECODEONLY</code> 标志。这个标志用于，源跳转到一个帧间帧时，需要首先解出目标所依赖的帧。在这个例子中，源需要将目标所依赖的帧发出但标记他们只能被解码。</p>
<p><code>OMX_BUFFERFLAG_DECODEONLY</code>标记和buffer数据相关联，传输的行为和时间戳完全一致。显示数据的组件应该忽略所有设置了<code>OMX_BUFFERFLAG_DECODEONLY</code>标志的buffer。</p>
<p>######3.1.2.6.13.4  OMX_BUFFERFLAG_DATACORRUPT<br>当IL客户端识别buffer相关的数据损坏时设置<code>OMX_BUFFERFLAG_DATACORRUPT</code>标志位。</p>
<p>######3.1.2.6.13.5  OMX_BUFFERFLAG_ENDOFFRAME<br><code>OMX_BUFFERFLAG_ENDOFFRAME</code>是一个可选的标志位，buffer playload中包含帧结束的最后一个字节时由输出端口设置。任何一个在输出端口上实现了设置<code>OMX_BUFFERFLAG_ENDOFFRAME</code>标志的组件应该为输出端口发出的每一个包含EOF的buffer设置这个标志。没有buffer payload可以包含两个独立的帧。</p>
<p>这些限制保证了从输出端口接受到数据的输入端口能够不通过额外的处理检测到EOF。也保证了如果输出端口支持这个标志的话，输入端口能轻易的通过标志位的有或无检测第一帧是否传输完。</p>
<p>####3.1.2.6.14  nOutputPortIndex<br><code>nOutputPortIndex</code>包含了使用buffer的输出端口的索引。如果一个buffer头用于和IL端口上的输入端口通信的话，此值不用定义。</p>
<p>#####3.1.2.6.15  nInputPortIndex<br><code>nInputPortIndex</code>包含了使用buffer的输入端口的索引。如果buffer头用于和IL客户端通信的输出端口，此值不用定义。</p>
<p>####3.1.2.7  OMX_PORT_PARAM_TYPE<br>组件用<code>OMX_PORT_PARAM_TYPE</code>结构来定义特定域上的端口数量和起始端口索引。</p>
<p><code>OMX_PORT_PARAM_TYPE</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct</span> OMX_PORT_PARAM_TYPE &#123;</div><div class="line">  OMX_U32 nSize;</div><div class="line">  OMX_VERSIONTYPE nVersion;</div><div class="line">  OMX_U32 nPorts;</div><div class="line">  OMX_U32 nStartPortNumber;</div><div class="line">&#125; OMX_PORT_PARAM_TYPE;</div></pre></td></tr></table></figure>
<p>#####3.1.2.7.1  nPorts<br><code>nPorts</code>为组件给定端口域（音频，视频，图像或其他）上的端口数。</p>
<p>#####3.1.2.7.2  nStartPortNumber<br><code>nStartPortNumber</code>为组件给定端口域（音频，视频，图像或其他）上的端口索引。给定域的后续端口按顺序编号从<code>nStartNumber</code>开始。</p>
<p>#####3.1.2.8  OMX_CALLBACKTYPE<br>OpenMAX IL包含了一个回调机制，允许组件可以和IL客户端进行下面的通信：</p>
<ul>
<li>IL客户端发出的异步命令成功，失败或产生错误。命令包括通过<code>OMX_SendCommand</code>和IL客户端发出的<code>EmptyThisBuffer</code>和<code>FillThisBuffer</code>。</li>
<li>和命令无关的错误发生。例如，组件进入了无法回复的错误并且转移到<code>OMX_StateInvalid</code>状态。</li>
</ul>
<p>为了实现回调，OpenMAX IL定义了3个回调函数：一个通用的事件处理程序和两个和数据流相关的回调（<code>EmptyBufferDone</code>和<code>FillBufferDone</code>）</p>
<p>IL客户端负责用回调函数入口填充<code>OMX_CALLBACKTYPE</code>结构并在初始化的时候传递给OpenMAX core，通常在函数<code>OMX_GetHandle</code>中。</p>
<p><code>OMX_CALLBACKTYPE</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div><div class="line">11</div><div class="line">12</div><div class="line">13</div><div class="line">14</div><div class="line">15</div><div class="line">16</div><div class="line">17</div><div class="line">18</div></pre></td><td class="code"><pre><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct</span> OMX_CALLBACKTYPE</div><div class="line">&#123;</div><div class="line">  OMX_ERRORTYPE (*EventHandler)(</div><div class="line">  	OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_PTR pAppData,</div><div class="line">    OMX_IN OMX_EVENTTYPE eEvent,</div><div class="line">    OMX_IN OMX_U32 nData1,</div><div class="line">    OMX_IN OMX_U32 nData2,</div><div class="line">    OMX_IN OMX_PTR pEventData);</div><div class="line">  OMX_ERRORTYPE (*EmptyBufferDone)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_PTR pAppData,</div><div class="line">    OMX_IN OMX_BUFFERHEADERTYPE* pBuffer);</div><div class="line">  OMX_ERRORTYPE (*FillBufferDone)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_PTR pAppData,</div><div class="line">    OMX_IN OMX_BUFFERHEADERTYPE* pBuffer);</div><div class="line">&#125; OMX_CALLBACKTYPE;</div></pre></td></tr></table></figure>
<p>#####3.1.2.8.1  EventHandler<br>组件使用事件处理函数方法来通知IL客户端什么时候一个所感兴趣的事件在组件内部发生了。枚举类型<code>OMX_EVENTTYPE</code>定义了OpenMAX IL事件的集合，可以参看每中事件的定义。<code>nData1</code>携带了完成事件的<code>OMX_COMMANDTYPE</code> 值或是<code>OMX_ERRORTYPE</code>的错误类型。<code>nData2</code>携带了更多的事件参数，例如，<code>OMX_STATETYPE</code>。<code>pEventData</code>包含了事件具体的数据。<code>pEventData</code>指针可能包含了额外的与时间有关的数据（例如，标记特定数据）。事件处理函数的调用是阻塞的，所有IL客户端应该在5个毫秒内完成响应，以免长时间阻塞住组件。</p>
<p>方法<code>EventHandler</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE(* OMX_CALLBACKTYPE::EventHandler)(</div><div class="line">  OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">  OMX_IN OMX_PTR pAppData,</div><div class="line">  OMX_IN OMX_EVENTTYPE eEvent,</div><div class="line">  OMX_IN OMX_U32 nData1,</div><div class="line">  OMX_IN OMX_U32 nData2,</div><div class="line">  OMX_IN OMX_PTR pEventData)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em></td>
<td>调用此函数的组件句柄。</td>
</tr>
<tr>
<td>̛<em>eEvent</em></td>
<td>组件和IL客户端通信的事件。</td>
</tr>
<tr>
<td><em>nData1</em></td>
<td>第一个事件特定的整型参数。表3-7描述了在每个事件上下文中的意义。</td>
</tr>
<tr>
<td><em>nData2</em></td>
<td>第二个事件特定的整型参数。表3-7描述了在每个事件上下文中的意义。如果没有用，默认值为0.</td>
</tr>
<tr>
<td><em>pEventData</em></td>
<td>指向事件特定数据的指针。表3-7描述了在每个事件上下文中的意义。</td>
</tr>
</tbody>
</table>
<p><strong>表 3-7 每一种事件所用的参数列表</strong></p>
<table>
<thead>
<tr>
<th>eEvent</th>
<th>nData1</th>
<th>nData2</th>
<th>pEventData</th>
</tr>
</thead>
<tbody>
<tr>
<td>OMX_EventCmdComplete</td>
<td>OMX_CommandStateSet</td>
<td>状态切换完成</td>
<td>无</td>
</tr>
<tr>
<td></td>
<td>OMX_CommandFlush</td>
<td>端口索引</td>
<td>无</td>
</tr>
<tr>
<td></td>
<td>OMX_CommandPortDisable</td>
<td>端口索引</td>
<td>无</td>
</tr>
<tr>
<td></td>
<td>OMX_CommandPortEnable</td>
<td>端口索引</td>
<td>无</td>
</tr>
<tr>
<td></td>
<td>OMX_CommandMarkBuffer</td>
<td>端口索引</td>
<td>无</td>
</tr>
<tr>
<td>OMX_EventError</td>
<td>错误代码</td>
<td>0</td>
<td>无</td>
</tr>
<tr>
<td>OMX_EventMark</td>
<td>0</td>
<td>0</td>
<td>标记相连的数据（如果有的话）</td>
</tr>
<tr>
<td>OMX_EventPortSettingsChanged</td>
<td>端口索引</td>
<td>0</td>
<td>无</td>
</tr>
<tr>
<td>OMX_EventBufferFlag</td>
<td>端口索引</td>
<td><code>nFlags</code>不可变</td>
<td>无</td>
</tr>
<tr>
<td>OMX_EventResourcesAcquired</td>
<td>0</td>
<td>0</td>
<td>无</td>
</tr>
</tbody>
</table>
<p><strong>表 3-7. 事件参数用法</strong></p>
<p>#####3.1.2.8.2  EmptyBufferDone<br>组件使用回调<code>EmptyBufferDone</code>从一个输入端口返回传递一个buffer给IL客户端。组件设置buffer头中的<code>nOffset</code>和<code>nFilledLength</code>值来反应buffer中被消耗的部位。例如，如果完全被消耗，则<code>nFilledLength</code>设置为0。</p>
<p>为了加快执行组件和IL客户端之间的数据流动，组件在下面情况下使用<code>EmptyBufferDone</code>方法把输入buffer返回给IL客户端：</p>
<ul>
<li>IL客户端命令状态由<code>OMX_StateExecuting</code>或<code>OMX_StatePause</code>转移到<code>OMX_StateIdle</code> 或<code>OMX_StateInvalid</code>。</li>
<li>IL客户端清空或禁用端口。</li>
</ul>
<p><code>EmptyBufferDone</code>为阻塞方法，应该在5毫秒以内返回。因此， IL客户端在调用期间可能不选择填充缓冲区，而在调用之外排队处理。</p>
<p>方法<code>EmptyBufferDone</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE(* OMX_CALLBACKTYPE::EmptyBufferDone)(</div><div class="line">  OMX_OUT OMX_HANDLETYPE hComponent,</div><div class="line">  OMX_OUT OMX_PTR pAppData,</div><div class="line">  OMX_OUT OMX_BUFFERHEADERTYPE* pBuffer)</div></pre></td></tr></table></figure>
<p>The parameters are as follows.</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em></td>
<td>调用此函数的组件句柄。</td>
</tr>
<tr>
<td><em>pAppData</em></td>
<td>指向IL客户端定义数据的指针。</td>
</tr>
<tr>
<td><em>pBuffer</em></td>
<td>指向消耗或返回的<code>OMX_BUFFERHEADERTYPE</code>结构类型的指针。</td>
</tr>
</tbody>
</table>
<p>#####3.1.2.8.3  FillBufferDone<br>组件使用回调<code>FillBufferDone</code>从输出端口返回数据给IL客户端。组件设置buffer头中的<code>nOffset</code>和<code>nFilledLength</code>值来反应buffer中被填充的部位。例如，如果没有数据，则<code>nFilledLength</code>设置为0。</p>
<p>为了加快执行组件和IL客户端之间的数据流动，组件在下面情况下使用此方法把输出buffer返回给IL客户端：</p>
<ul>
<li>IL客户端命令状态由<code>OMX_StateExecuting</code>或<code>OMX_StatePause</code>转移到<code>OMX_StateIdle</code> 或<code>OMX_StateInvalid</code>。</li>
<li>IL客户端清空或禁用端口。</li>
</ul>
<p><code>FillBufferDone</code>为阻塞方法，应该在5毫秒以内返回。因此， IL客户端在调用期间可能不选择填充缓冲区，而在调用之外排队处理。</p>
<p><code>FillBufferDone</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE(* OMX_CALLBACKTYPE::FillBufferDone)(</div><div class="line">  OMX_OUT OMX_HANDLETYPE hComponent,</div><div class="line">  OMX_OUT OMX_PTR pAppData,</div><div class="line">  OMX_OUT OMX_BUFFERHEADERTYPE* pBuffer)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em></td>
<td>访问组件的句柄。此句柄为方法<code>GetHandle</code>返回的组件句柄。</td>
</tr>
<tr>
<td><em>pAppData</em></td>
<td>指向IL客户端定义数据的指针。</td>
</tr>
<tr>
<td><em>pBuffer</em></td>
<td>指向填充或返回的<code>OMX_BUFFERHEADERTYPE</code>结构类型的指针。</td>
</tr>
</tbody>
</table>
<p>####3.1.2.9  OMX_PARAM_BUFFERSUPPLIERTYPE<br><code>OMX_PARAM_BUFFERSUPPLIERTYPE</code>结构用于传输buffer提供者的设置或偏好。</p>
<p><code>OMX_PARAM_BUFFERSUPPLIERTYPE</code> 定义如下.</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct</span> OMX_PARAM_BUFFERSUPPLIERTYPE &#123;</div><div class="line">  OMX_U32 nSize;</div><div class="line">  OMX_VERSIONTYPE nVersion;</div><div class="line">  OMX_U32 nPortIndex;</div><div class="line">  OMX_BUFFERSUPPLIERTYPE eBufferSupplier;</div><div class="line">&#125; OMX_PARAM_BUFFERSUPPLIERTYPE;</div></pre></td></tr></table></figure>
<p>#####3.1.2.9.1  nPortIndex<br><code>nPortIndex</code>为结构适用的组件端口</p>
<p>#####3.1.2.9.2  eBufferSupplier<br><code>eBufferSupplier</code>字段包括了buffer提供者的索引，如果是一个输入或输出端口。</p>
<p>####3.1.2.10  OMX_TUNNELSETUPTYPE<br>当IL客户端调用<code>OMX_SetupTunnel</code>来连接端口时，方法<code>ComponentTunnelRequest</code>使用<code>OMX_TUNNELSETUPTYPE</code>结构体来在两个端口之间传输数据。</p>
<p><code>OMX_TUNNELSETUPTYPE</code> 定义如下.</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div></pre></td><td class="code"><pre><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct</span> OMX_TUNNELSETUPTYPE</div><div class="line">&#123;</div><div class="line">  OMX_U32 nTunnelFlags;</div><div class="line">  OMX_BUFFERSUPPLIERTYPE eSupplier;</div><div class="line">&#125; OMX_TUNNELSETUPTYPE;</div></pre></td></tr></table></figure>
<p>#####3.1.2.10.1  nTunnelFlags<br><code>nTunnelFlags</code>整型参数包括了接受此结构的端口所适用的一个或多个比特标志，这些标志包括：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_PORTTUNNELFLAG_READONLY 0x00000001</span></div></pre></td></tr></table></figure>
<p>如果标志设置为只读，接受到结构体的输入端口不能改变管道上buffer的内容。</p>
<p>#####3.1.2.10.2  eSupplier<br><code>eSupplier</code>定义了是输出还是输入端口提供buffer。3.4.1.2小节描述了建立管道的具体调用步骤。</p>
<p>####3.1.2.11  OMX_PARAM_PORTDEFINITIONTYPE<br><code>OMX_PARAM_PORTDEFINITIONTYPE</code>结构提包含了组件中每个端口的一些通用的字段。一些字段在每个域上都是通用的而其他的字段是每个域特有的。IL客户端使用这个结构体来获取每个端口的通用信息。</p>
<p><code>OMX_PARAM_PORTDEFINITIONTYPE</code> 定义如下.</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div><div class="line">11</div><div class="line">12</div><div class="line">13</div><div class="line">14</div><div class="line">15</div><div class="line">16</div><div class="line">17</div></pre></td><td class="code"><pre><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct</span> OMX_PARAM_PORTDEFINITIONTYPE &#123;</div><div class="line">  OMX_U32 nSize;</div><div class="line">  OMX_VERSIONTYPE nVersion;</div><div class="line">  OMX_U32 nPortIndex;</div><div class="line">  OMX_DIRTYPE eDir;</div><div class="line">  OMX_U32 nBufferCountActual;</div><div class="line">  OMX_U32 nBufferCountMin;</div><div class="line">  OMX_U32 nBufferSize;</div><div class="line">  OMX_BOOL bEnabled;</div><div class="line">  OMX_BOOL bPopulated;</div><div class="line">  <span class="keyword">union</span> &#123;</div><div class="line">    OMX_AUDIO_PORTDEFINITIONTYPE audio;</div><div class="line">    OMX_VIDEO_PORTDEFINITIONTYPE video;</div><div class="line">    OMX_IMAGE_PORTDEFINITIONTYPE image;</div><div class="line">    OMX_OTHER_PORTDEFINITIONTYPE other;</div><div class="line">  &#125; format;</div><div class="line">&#125; OMX_PARAM_PORTDEFINITIONTYPE;</div></pre></td></tr></table></figure>
<p>#####3.1.2.11.1  nPortIndex<br><code>nPortIndex</code> 是一个标识端口的只读字段。他的值为一个组件上唯一的32比特的数。 同一个组件上的两个不同的端口不能拥有相同的端口号。而不同组件上的端口可以有相同的端口号。</p>
<p>#####3.1.2.11.2  eDir<br><code>eDir</code>是一个指明端口方向（<code>OMX_DirInput</code>或<code>OMX_DirOutput</code>）的只读域。</p>
<p>#####3.1.2.11.3  nBufferCountActual<br><code>nBufferCountActual</code> 表明了端口在poplated之前（如字段bPopulated所示）所需要的buffer的数量。组件应该为这个字段设置一个不小于<code>nBufferCountMin</code>的缺省值。</p>
<p>#####3.1.2.11.4  nBufferCountMin<br><code>nBufferCountMin</code> 是一个指定了端口所需最少buffer数的只读字段。组件应定义一个非零的缺省值。</p>
<p>#####3.1.2.11.5  nBufferSize<br><code>nBufferSize</code> 是一个指定了端口所需分配的buffer的最小buffer字节数的只读字段。</p>
<p>#####3.1.2.11.6  bEnabled<br><code>bEnabled</code>为指定了端口是否启用的只读布尔型端口。默认值为<code>OMX_TRUE</code>，并可以通过<code>OMX_SendCommand</code>方法发送<code>OMX_CommandPortEnable</code>和<code>OMX_CommandPortDisable</code>来启用/禁用。</p>
<p>端口被禁用是不可以被populated。</p>
<p>#####3.1.2.11.7  bPopulated<br><code>bPopulated</code>为一个指示端口是否populated的只读bool型字段。当端口上所有<code>nBufferCountActual</code>指明的数量<code>nBufferSize</code>指明的大小的buffer被分配的时候，端口才是populated的。一个populated的端口应该被启用。启用的端口应该通过转移到<code>OMX_StateIdle</code>状态populated和切换到<code>OMX_StateLoaded</code>来unpopulated。</p>
<p>#####3.1.2.11.8  eDomain<br><code>eDomain</code>为指定端口域的只读字段。决定了共同体中的内容，见小节3.1.2.11.9的解释。</p>
<p>#####3.1.2.11.9  format<br><code>format</code>字段为一个域参数的共同体。具体信息可以见第4章。</p>
<p>###3.1.3 OMX_PORTDOMAINTYPE<br>表3-8枚举了<code>OMX_PARAM_PORTDEFINITIONTYPE</code>结构体中使用的字段，用于定义端口的作用域。</p>
<table>
<thead>
<tr>
<th>字段名称</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>OMX_PortDomainAudio</td>
<td>指定了字段格式类型为<code>OMX_AUDIO_PORTDEFINITIONTYPE</code></td>
</tr>
<tr>
<td>OMX_PortDomainVideo</td>
<td>指定了字段格式类型为<code>OMX_VIDEO_PORTDEFINITIONTYPE</code></td>
</tr>
<tr>
<td>OMX_PortDomainImage</td>
<td>指定了字段格式类型为<code>OMX_IMAGE_PORTDEFINITIONTYPE</code></td>
</tr>
<tr>
<td>OMX_PortDomainOther</td>
<td>指定了字段格式类型为<code>OMX_OTHER_PORTDEFINITIONTYPE</code></td>
</tr>
</tbody>
</table>
<p><strong>表 3-8. 端口域名称                                  </strong></p>
<p>###3.1.4 OMX_HANDLETYPE<br><code>OMX_HANDLETYPE</code>结构体定义了IL客户端可见的组件句柄。组件句柄用于访问所有组件的方法。组件句柄也包含了组件私有数据域的指针。OpenMAX core在加载组件的过程中分配并初始化组件。组件加载完毕后，IL客户端可以安全的访问所有组件的公有方法，虽然某些方法会由于状态不对而返回错误。</p>
<p>##3.2  OpenMAX Core 方法/宏<br>OpenMAX core实现了IL客户端使用组件的主要接口。为了效率，OpenMAX IL定义了一系列的宏来完成对组件方法一对一的映射。一些宏和方法建议函数在5毫秒或20号码内返回，这取决与函数。5毫秒的超时被标准认为是不需要buffer处理的命令的合理的响应事件。标准认为需要处理buffer的命令处理的合理超时时间为20号码。这里的假设是最长的buffer处理应该低于30号码，对应域每秒30帧视频。这些超时的主要目的是为了使组件集成者可以通过一致性测试很容易的得到组件的响应延时。</p>
<p>这些宏包含下面的内容：</p>
<ul>
<li>获取组件信息（版本，能力）</li>
<li>在初始化时设置/获取组件参数。</li>
<li>在运行是设置/获取组件参数。</li>
<li>分配/释放buffer。</li>
<li>发送给OpenMAX组件端口一个充满数据的buffer。</li>
<li>发送给OpenMAX组件端口一个空的buffer。</li>
<li>发送命令给组件。</li>
<li>获得组件的实际状态。</li>
<li>获取OpenMAX组件专有参数的引用。</li>
</ul>
<p>OpenMAX Core也实现了下面的方法：</p>
<ul>
<li>初始化/析构整个OpenMAX IL core。</li>
<li>获得一个OpenMAX组件句柄</li>
<li>释放一个OpenMAX组件句柄</li>
<li>运行时探测系统上所有可用的OpenMAX组件。</li>
<li>在OpenMAX组件之间建立数据管道。</li>
</ul>
<p>当一个方法执行的时间限制被指定时，它并不打算是组件标准一致性的硬性规定。但如果不遵守这个限制，组件文档中应该标明。</p>
<p>###3.2.1 方法的返回值<br>表3-9列举了每一个方法的所有可能的返回错误值。致命错误指的是组件无法恢复。发生致命错误时组件应该转移到<code>OMX_StateInvalid</code>状态。除了最后两列，左右的列对应着调用组件方法的错误返回。最后两列为内部错误时发出的异步错误。</p>
<p><img src="img/t3_9.png" alt=""></p>
<p>###3.2.2 宏<br>本小节描述了OpenMAX Core中的宏</p>
<p>表3-10定义了在每一种状态下哪一个宏应该被调用。</p>
<p><img src="img/t3_10.png" alt=""></p>
<p>表3-10. 合法的组件调用</p>
<p>####3.2.2.1  OMX_GetComponentVersion<br>宏<code>OMX_StateInvalid</code>查询组件并返回具体信息。这是一个阻塞调用。组件应该在5毫秒内返回这个调用。</p>
<p>The macro 定义如下.</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div><div class="line">11</div><div class="line">12</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_GetComponentVersion (</span></div><div class="line">  hComponent,</div><div class="line">  pComponentName,</div><div class="line">  pComponentVersion,</div><div class="line">  pSpecVersion,</div><div class="line">  pComponentUUID )</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent)-&gt;GetComponentVersion( \</div><div class="line">    hComponent, \</div><div class="line">    pComponentName, \</div><div class="line">    pComponentVersion, \</div><div class="line">    pSpecVersion, \</div><div class="line">    pComponentUUID)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>输入</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行命令的组件句柄。</td>
</tr>
<tr>
<td><em>pComponentName</em> [输出]</td>
<td>组件名字符串的指针。组件名必须是小于127字节加结尾即最大长度为128字节的字符串。例如，一个合法的组件名可以是”OMX.&lt;厂商名&gt;.AUDIO.DSP.MIXER\0”。名字由厂商指定，但需要以”OMX.”开始加上厂商指定的字符串。</td>
</tr>
<tr>
<td><em>pComponentVersion</em> [输出]</td>
<td>组件所填充的OpenMAX版本结构体的指针。组件会填入版本值。注意组件的版本和在所有结构中的OpenMAX协议的版本不是一样的。厂商组件自行定义组件的版本来确定这个值。</td>
</tr>
<tr>
<td><em>pSpecVersion</em> [输出]</td>
<td>组件所填充的OpenMAX版本结构体的执政。<code>SpecVersion</code>是组件对应的协议的版本。注意这个版本和结构体的版本可能一样也可能不一样。例如，如果组件是根据2.0版本的协议实现的，但创建IL的客户端是由1.0版本的协议建立的，两者是不同的。</td>
</tr>
<tr>
<td><em>pComponentUUID</em> [输出]</td>
<td>组件通用唯一识别码（UUID）的指针，由组件填入。UUID是一个唯一的识别码，由组件在运行期间设置，并且每个组件实例都是唯一的。</td>
</tr>
</tbody>
</table>
<p>#####3.2.2.1.1  先决条件2<br>这种方法没有先决条件。</p>
<p>#####3.2.2.1.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* detect mismatch between IL client's and component's spec version */</span></div><div class="line">OMX_GetComponentVersion(</div><div class="line">  hComp,</div><div class="line">  &amp;CompName,</div><div class="line">  &amp;CompVersion,</div><div class="line">  &amp;CompSpecVersion,</div><div class="line">  &amp;CompUUID);</div><div class="line">  <span class="keyword">if</span> (CompSpecVersion != IlClientVersion)&#123;</div><div class="line">    <span class="built_in">printf</span>(<span class="string">"ERROR: version mismatch\n"</span>);</div><div class="line">  &#125;</div></pre></td></tr></table></figure>
<p>####3.2.2.2  OMX_SendCommand<br>宏<code>OMX_SendCommand</code>会调用组件上的一个命令。这是一个非阻塞的调用，有效的命令参数应该在最小5毫秒内返回。通常来说，组件并不在此调用的上下文中执行命令，但如果方案中没有多线程的话可能会选择在上下文中执行。在这两种情况下，组件使用事件回调来通知IL客户端命令执行完毕的结果。如果组件成功执行命令，组件会生成<code>OMX_EventCmdComplete</code>回调。如果组件执行命令失败，则生成<code>OMX_EventError</code>并将适当的错误以参数传回。</p>
<p>组件可能选择将命令传入队列以便后续执行。唯一的限制就是完成的顺序应该和请求的顺序一致。</p>
<p>宏定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_SendCommand (</span></div><div class="line">  hComponent,</div><div class="line">  Cmd,</div><div class="line">  nParam,</div><div class="line">  pCmdData)</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent)-&gt;SendCommand( \</div><div class="line">    hComponent, \</div><div class="line">    Cmd, \</div><div class="line">    nParam,</div><div class="line">    pCmdData)</div></pre></td></tr></table></figure>
<p>参数如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行命令的组件句柄</td>
</tr>
<tr>
<td><em>Cmd</em> [输入]</td>
<td>待组件执行的命令</td>
</tr>
<tr>
<td><em>nParam</em> [输入]</td>
<td>待执行命令的整型参数</td>
</tr>
<tr>
<td><em>pCmdData</em>[输入]</td>
<td>一个指针，包含具体实现的无法用数值型参数来描述的数据</td>
</tr>
</tbody>
</table>
<p>3.3.6小节描述了每个组件实现的对应的方法。</p>
<p>####3.2.2.3  OMX_CommandStateSet<br>IL客户端调用此命令来请求组件切换到<code>nParam</code>指定的状态中。只有合法的状态转移并且所有先决条件都已满足，组件才可以完成老状态到新状态之间的成功切换。更多信息参见3.1.1.2小节。</p>
<p>如果组件成功转移到新的状态，他会通过事件<code>OMX_EventCmdComplete</code> 来通知IL客户端，<code>nData1</code>中存放<code>OMX_CommandStateSet</code>，<code>nData2</code>放入新的状态。如果转移失败，组件应该通过事件<code>OMX_EventError</code>通知IL客户端错误。相关错误包括但不限于以下内容：</p>
<ul>
<li><code>OMX_ErrorSameState</code>: 组件已经在此状态</li>
<li><code>OMX_ErrorIncorrectStateTransition</code>: 转移请求非法</li>
<li><code>OMX_ErrorInsufficientResources</code>: 组件获取转移所需的资源失败</li>
</ul>
<p>####3.2.2.4  OMX_CommandFlush<br>IL调用此命令来清空组件上一个或多个组件。<code>nParam</code>指定了待刷新端口的缩影。如果值为-1，则应该清空所有端口。</p>
<p>当IL客户端清空一个非供应端口时，端口应该返回所有拥有的buffer给供应端口。如果供应端口为IL客户端，被清空的组件使用<code>EmptyBufferDone</code> 和<code>FillBufferDone</code>（分别对应输入或输入端口）返回buffer。如果供应端口为一个管道端口，被清空的端口使用使用<code>EmptyThisBuffer</code> 和<code>FillThisBuffer</code>（分别对应输入或输入端口）返回buffer。</p>
<p>对于每个组件成功清空的端口，组件应该发送一个<code>OMX_EventCmdComplete</code>事件， <code>nData1</code>中放入<code>OMX_CommandFlush</code>，<code>nData2</code>中放入独立的端口索引，即使<code>nParam</code>使用的是-1。如果清空失败，组件应该使用<code>OMX_EventError</code>事件来通知IL客户端错误。</p>
<p>####3.2.2.5  OMX_CommandPortDisable<br>命令<code>OMX_CommandPortDisable</code>禁用一个端口。<code>nParam</code>指定了禁用端口的索引。如果<code>nParam</code>值为-1，组件应该禁用所有的端口。一个被禁用的端口没有buffer也不连接到IL客户端或是通过管道连接到其他端口。一个被禁用的端口从<code>OMX_StateLoaded</code>或<code>OMX_StateWaitForResources</code> 转移到<code>OMX_StateIdle</code>是不分配buffer。IL客户端可以通过<code>OMX_SetParameter</code>改变一个禁用端口的设置或是忽略状态来建立一个管道。因此命令<code>OMX_CommandPortDisable</code>配合<code>OMX_CommandPortEnable</code>，可以用于动态的改变端口配置或重新连接管道。</p>
<p>端口收到<code>OMX_CommandPortDisable</code>必须立刻清除端口定义结构体上的<code>bEnabled</code>字段。如过IL客户端禁用的端口是一个非供应端口，IL客户端应该通过<code>OMX_EmptyThisBuffer</code>/<code>OMX_FillThisBuffer</code>（管道） 或<code>EmptyBufferDone</code>/<code>FillBufferDone</code>（非管道）返回所有的拥有的buffer。然后，IL客户端应该等待供应端口通过<code>OMX_FreeBuffer</code>释放buffer来完成禁用命令。如果被禁用的端口是一个供应端口，分配了buffer， IL客户端应该等待非供应端口通过<code>OMX_EmptyThisBuffer</code>或<code>OMX_FillThisBuffer</code>返回buffer。然后，IL客户端应该等待供应端口通过<code>OMX_FreeBuffer</code>释放buffer来完成禁用命令。</p>
<p>对于每一个组件成功禁用的端口，组件应该发送<code>OMX_EventCmdComplete</code>事件，<code>nData1</code>中放入<code>OMX_CommandPortDisable</code>，<code>nData2</code>中放入独立的端口索引，<code>nParam</code>使用的是-1。如果禁用失败，组件应该使用<code>OMX_EventError</code>事件来通知IL客户端错误。</p>
<p>####3.2.2.6  OMX_CommandPortEnable<br><code>OMX_CommandPortEnable</code>命令启用一个端口。<code>nParam</code>指定了启用端口的索引。如果<code>nParam</code>值为-1，组件应该启用所有的端口。启用端口应该遵循组件状态的所有要求。因此，端口应该：</p>
<ul>
<li>组件如果在<code>OMX_StateLoaded</code>或<code>OMX_StateWaitForResources</code>应该没有buffer分配，而在其他状态应该所有buffer都已分配</li>
<li>从 <code>OMX_StateLoaded</code>或<code>OMX_WaitForResources</code>转移到<code>OMX_IdleState</code>时分配buffer。</li>
<li>在<code>OMX_StateExecuting</code>状态时传输buffer到数据流</li>
<li>除了 <code>OMX_StateLoaded</code>以外所有其他状态不允许通过<code>OMX_SetParameter</code>改变参数。</li>
</ul>
<p>命令<code>OMX_CommandPortEnable</code>配合<code>OMX_CommandPortDisable</code>，可以用于动态的改变端口配置或重新连接管道。</p>
<p>端口收到<code>OMX_CommandPortEnable</code>后必须立刻设置端口定义结构体中的<code>bEnabled</code>字段。如果IL客户端在组件为除<code>OMX_StateLoaded</code>或 <code>OMX_WaitForResources</code>以外的任何状态启用端口，端口应该通过和<code>OMX_StateLoaded</code>到<code>OMX_StateIdle</code>相同的调用顺序分配buffer。如果IL客户端当组件为<code>OMX_Executing</code>时启用，那么端口应该开始传输buffer。</p>
<p>针对每一个组件成功启用的端口，组件应该发送<code>OMX_EventCmdComplete</code>事件，<code>nData1</code>中放入<code>OMX_CommandPortEnable</code>，<code>nData2</code>放入独立的端口索引，即使使用<code>nParam</code>为-1来启用。如果端口启用操作失败，组件应该通过<code>OMX_EventError</code>事件通知IL客户端。</p>
<p>####3.2.2.7  OMX_CommandMarkBuffer<br>命令<code>OMX_CommandMarkBuffer</code>指示给定的端口标记buffer。<code>nParam</code>持有进行标记的端口索引。<code>OMX_SendCommand</code>的<code>pCmdData</code>参数指向<code>OMX_MARKTYPE</code>结构体。结构体中<code>pMarkTargetComponent</code>字段持有目标组件的指针，当处理完标记的buffer后会发送事件给目标组件。<code>pMarkData</code>字段持有一个指针，指向与标记相关的应用程序特定的数据， 用来给应用程序在一个标记事件中唯一标识这个标记（标识数据的名称）。</p>
<p>当指示标记一个buffer时，组件将在接受到标记命令后标记接受的下一个buffer。源组件是一个特殊情况，它将标记加到其输出buffer队列的下一个buffer。非源组件的情况下，nParam中的端口索引值持有了标记下一个buffer的输入端口的索引。源组件的情况下，nParam中的端口索引值持有了标记下一个buffer的输出端口的索引。</p>
<p>在下列情况下， 多个标记可能会竞争同一个buffer：</p>
<ul>
<li>组件连续收到两个或更多标记命令，两次标记之间没有buffer.</li>
<li>两个或多个输入buffer，每个都有一个标记，合并成一个输出buffer，（例如，在一个mixer中）</li>
<li>组件收到一个标记命令但下一个buffer已经被标记。</li>
</ul>
<p>如果多个标记竞争同一个buffer，组件使用第一个收到的标记来标记buffer，并且按收到标记的顺序将剩余的标记应用到后续的buffer中。如果后面没有buffer，组件可以把剩余的标记应用到一个或多个空的buffer中去。</p>
<p>组件成功标记buffer的每一个端口，组件应该发送<code>OMX_EventCmdComplete</code>事件，<code>nData1</code>中放置<code>OMX_CommandPortMarkBuffer</code>，<code>nData2</code>放置独立的端口索引。如果标记操作失败，组件应该通过<code>OMX_EventError</code>事件通知IL客户端。</p>
<p>buffer头包含了<code>pMarkTargetComponent</code>和<code>pMarkData</code>字段，意义和<code>OMX_MARKTYPE</code>中的字段相同。组件通过从标记命令拷贝<code>pMarkTargetComponent</code>和<code>pMarkData</code>字段来标记buffer。默认情况下这两个字段是空的（例如，标记buffer之前）。一个组件根据buffer标志位和时间戳简历的元数据规则来从输入buffer向输出buffer传播标记。目标组件不传播标记，而是将两个字段清楚为NULL。</p>
<p>但组件收到buffer，他应该自身指针和pMarkTargetComponent。如果指针匹配，buffer离开组件或成功处理而不需要离开组件后，组件应该立马发送标记事件，包含了pMarkData作为参数。</p>
<p>#####3.2.2.7.1  先决条件<br>这种方法没有先决条件。</p>
<p>#####3.2.2.7.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* disable every audio port of a component*/</span></div><div class="line">OMX_GetParameter(hComp, OMX_IndexParamAudioInit, &amp;oParam);</div><div class="line"><span class="keyword">for</span> (i=<span class="number">0</span>;i&lt;oParam.nPorts;i++) &#123;</div><div class="line">  OMX_SendCommand(</div><div class="line">    hComp,</div><div class="line">    OMX_CommandPortDisable,</div><div class="line">    Param.nStartPortNumber + i,</div><div class="line">    <span class="number">0</span>);</div><div class="line">&#125;</div></pre></td></tr></table></figure>
<p>####3.2.2.8  OMX_GetParameter<br>宏<code>OMX_GetParameter</code>取得组件的一个参数。参数<code>nParamIndex</code>指示了请求组件的哪一个结构体。调用者在调用此宏之前应该提供结构体的内存并填充<code>nSize</code>和<code>nVersion</code>字段。如果参数是来自一个端口，调用者也应该在调用此宏之前在<code>nPortIndex</code>字段中提供一个有效的端口号。所有组件应该支持每个参数的一组默认值，这样调用者可以得到有效值的结构体。</p>
<p>这个调用为一个阻塞调用。组件应该在20毫秒以内返回这个调用。</p>
<p>宏OMX_GetParameter定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_GetParameter (</span></div><div class="line">  hComponent,</div><div class="line">  nParamIndex,</div><div class="line">  ComponentParameterStructure)</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent)-&gt;GetParameter( \</div><div class="line">    hComponent, \</div><div class="line">    nParamIndex, \</div><div class="line">    ComponentParameterStructure)</div></pre></td></tr></table></figure>
<p>参数描述如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>nParamIndex</em> [输入]</td>
<td>填充的结构体索引。 这个值来自<code>OMX_INDEXTYPE</code>结构体</td>
</tr>
<tr>
<td><em>ComponentParameterStructure</em> [输入,输出]</td>
<td>指向IL客户端分配的结构体的指针，由组件填充</td>
</tr>
</tbody>
</table>
<p>3.3.7小节描述了每个组件实现的相应的方法。</p>
<p>#####3.2.2.8.1  先决条件<br>这个宏可以当组件在除<code>OMX_StateInvalid</code>外的任何状态时被调用。</p>
<p>#####3.2.2.8.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* disable every audio port of a component*/</span></div><div class="line">OMX_GetParameter(hComp, OMX_IndexParamAudioInit, &amp;oParam);</div><div class="line"><span class="keyword">for</span> (i=<span class="number">0</span>;i&lt;oParam.nPorts;i++) &#123;</div><div class="line">  OMX_SendCommand(</div><div class="line">    hComp,</div><div class="line">    OMX_CommandPortDisable,</div><div class="line">    oParam.nStartPortNumber + i,</div><div class="line">    <span class="number">0</span>);</div><div class="line">&#125;</div></pre></td></tr></table></figure>
<p>####3.2.2.9  OMX_SetParameter<br>宏<code>OMX_SetParameter</code>将发送一个参数结构体给组件。参数<code>nParamIndex</code>指示了传递给组件的是哪一个结构体。</p>
<p>调用者应该提供正确的结构体的内存，并在调用宏之前填充结构体中<code>nSize</code>和<code>nVersion</code>字段。调用者可以在调用之后可以自由的处理该结构，因为组件需要拷贝它需要保留的任何数据。</p>
<p>一些参数结构体包含了只读字段。<code>OMX_SetParameter</code>方法将保留只读字段，并且调用者试图改变只读字段时也不会产生错误。</p>
<p>此调用为阻塞调用。组件应该在20毫秒以内返回。</p>
<p>宏<code>OMX_SetParameter</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_SetParameter (</span></div><div class="line">  hComponent,</div><div class="line">  nParamIndex,</div><div class="line">  ComponentParameterStructure)</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent)-&gt;SetParameter( \</div><div class="line">    hComponent, \</div><div class="line">    nParamIndex, \</div><div class="line">    ComponentParameterStructure)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>nIndex</em> [输入]</td>
<td>发送的结构体缩影。这个值来自<code>OMX_INDEXTYPE</code>枚举类型</td>
</tr>
<tr>
<td><em>ComponentParameterStructure</em> [输入]</td>
<td>指向IL客户端分配的结构体的指针，组件用于初始化</td>
</tr>
</tbody>
</table>
<p>3.3.8小节描述了每个组件实现的相应方法。</p>
<p>#####3.2.2.9.1  先决条件<br>宏<code>OMX_SetParameter</code>仅当组件在<code>OMX_StateLoaded</code>或组件被禁用时被调用。</p>
<p>#####3.2.2.9.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* force a port to be the supplier */</span></div><div class="line">OMX_GetParameter(hComp, OMX_IndexParamPortDefinition, &amp;oPortDef);</div><div class="line"><span class="keyword">if</span> (oPortDef.eDir == OMX_DirInput)&#123;</div><div class="line">  oSupplier.eBufferSupplier = OMX_BufferSupplyInput;</div><div class="line">&#125; <span class="keyword">else</span> &#123;</div><div class="line">  oSupplier.eBufferSupplier = OMX_BufferSupplyOutput;</div><div class="line">&#125;</div><div class="line">oSupplier.nPortIndex = nPortIndex;</div><div class="line">OMX_SetParameter(hComp, OMX_IndexParamCompBufferSupplier, &amp;oSupplier);</div></pre></td></tr></table></figure>
<p>####3.2.2.10  OMX_GetConfig<br>宏<code>OMX_GetConfig</code>将从一个组件获得一个配置结构体。此红可以在组件被加载后任何事件被调用。参数<code>nParamIndex</code>指示了组件的哪一个结构体被请求。调用者应该在调用这个宏之前提供此结构体的内存并填充<code>nSize</code>和<code>nVersion</code>字段。如果是配置一个端口，调用者也应该在调用之前在<code>nPortIndex</code>字段提供一个有效的端口号。所有的组件应该支持每个配置的默认值，这样调用者可以获得填充正确值的结构体。</p>
<p>此调用为一个阻塞调用。组件应该在5毫秒内返回。</p>
<p>宏<code>OMX_GetConfig</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_GetConfig (</span></div><div class="line">  hComponent,</div><div class="line">  nConfigIndex,</div><div class="line">  ComponentConfigStructure)</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent)-&gt;GetConfig( \</div><div class="line">    hComponent, \</div><div class="line">    nConfigIndex, \</div><div class="line">    ComponentConfigStructure)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em>[输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>nIndex</em>[输入]</td>
<td>需要填充的结构体索引。此值来自OMX_INDEXTYPE枚举类型</td>
</tr>
<tr>
<td><em>ComponentConfigStructure</em>[输入,输出]</td>
<td>指向IL客户端分配的结构体指针，由组件填充</td>
</tr>
</tbody>
</table>
<p>3.3.9小节描述了每个组件实现的相应方法。</p>
<p>#####3.2.2.10.1  先决条件<br>此宏可以当组件在除了<code>OMX_StateInvalid</code>外的任意状态被调用。</p>
<p>#####3.2.2.10.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* Wait until a certain playback position */</span></div><div class="line"><span class="keyword">do</span> &#123;</div><div class="line">  OMX_GetConfig(hClockComp, OMX_IndexConfigTimeCurrentMediaTime,</div><div class="line">    oMediaTime);</div><div class="line">&#125; <span class="keyword">while</span> (oMediaStamp.nTimestamp &lt; nTargetTimeStamp);</div></pre></td></tr></table></figure>
<p>####3.2.2.11  OMX_SetConfig<br>宏<code>OMX_SetConfig</code>将给组件一个配置值。组件加载完后，这个宏可以在任何时间被调用。</p>
<p>调用者应该在调用宏之前提供正确的结构体的内存，并填充结构体中<code>nSize</code>和<code>nVersion</code>字段。调用者可以在调用之后可以自由的处理该结构，因为组件需要拷贝它需要保留的任何数据。</p>
<p>一些配置结构体包含了只读字段。<code>OMX_SetConfig</code>方法将保留只读字段，并且调用者试图改变只读字段时也不会产生错误。</p>
<p>这个调用为一个阻塞调用。组件应该在5毫秒以内返回这个调用。</p>
<p>宏<code>OMX_SetConfig</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_SetConfig (</span></div><div class="line">  hComponent,</div><div class="line">  nConfigIndex,</div><div class="line">  ComponentConfigStructure )</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent)-&gt;SetConfig( \</div><div class="line">    hComponent, \</div><div class="line">    nConfigIndex, \</div><div class="line">    ComponentConfigStructure)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>nIndex</em> [输入]</td>
<td>发送的结构体索引。此值来自OMX_INDEXTYPE枚举类型</td>
</tr>
<tr>
<td><em>ComponentConfigStructure</em> [输入]</td>
<td>指向IL客户端分配的结构体的指针，组件用于初始化</td>
</tr>
</tbody>
</table>
<p>3.3.10小节描述了每个组件实现的相应方法。</p>
<p>#####3.2.2.11.1  先决条件<br>此宏可以当组件在除了<code>OMX_StateInvalid</code>外的任意状态被调用。</p>
<p>#####3.2.2.11.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* Change the time scale of the clock component*/</span></div><div class="line">oScale.xScale = <span class="number">0x00020000</span>; <span class="comment">/*2x*/</span></div><div class="line">OMX_SetConfig(hClockComp, OMX_IndexConfigTimeScale, (OMX_PTR)&amp;oScale);</div></pre></td></tr></table></figure>
<p>####3.2.2.12  OMX_GetExtensionIndex<br>宏<code>OMX_GetExtensionIndex</code>将调用组件从一个标准OpenMAX或厂商扩展的配置或参数翻译为OpenMAX结构体索引。厂商不需要在那些已经在OMX_INDEXTYPE中定义的索引支持这个命令，从而可以降低内存占用。组件可以支持<code>OMX_INDEXTYPE</code>中没有的任何标准OpenMAX或厂商扩展的索引。</p>
<p>这个调用为一个阻塞调用。组件应该在5毫秒以内返回这个调用。</p>
<p>宏<code>OMX_GetExtensionIndex</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_GetExtensionIndex (</span></div><div class="line">  hComponent,</div><div class="line">  cParameterName,</div><div class="line">  pIndexType )</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent)-&gt;GetExtensionIndex( \</div><div class="line">    hComponent, \</div><div class="line">    cParameterName, \</div><div class="line">    pIndexType)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>cParameterName</em>[输入]</td>
<td>一个OMX_STRING值，小于128个字符（包括了结尾的null字节）。组件将把这个字符串翻译为一个配置索引</td>
</tr>
<tr>
<td><em>pIndexType</em> [输出]</td>
<td>指向OMX_INDEXTYPE结构体的指针，用于接受索引值</td>
</tr>
</tbody>
</table>
<p>3.3.11小节描述了每个组件实现的相应方法。</p>
<p>#####3.2.2.12.1  先决条件<br>此宏可以当组件在除了<code>OMX_StateInvalid</code>外的任意状态被调用。</p>
<p>#####3.2.2.12.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* Set the vendor-specific filename parameter on a reader */</span></div><div class="line">OMX_GetExtensionIndex(</div><div class="line">  hFileReaderComp,</div><div class="line">  <span class="string">"OMX.CompanyXYZ.index.param.filename"</span>,</div><div class="line">  &amp;eIndexParamFilename);</div><div class="line">OMX_SetParameter(hComp, eIndexParamFilename, &amp;oFileName);</div></pre></td></tr></table></figure>
<p>####3.2.2.13  OMX_GetState<br>宏<code>OMX_GetState</code>将调用组件来获得组件的当前状态并将组件值放入<code>pState</code>指向的地址。组件应该在5毫秒内返回。</p>
<p>宏<code>OMX_GetState</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_GetState (</span></div><div class="line">  hComponent,</div><div class="line">  pState )</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent)-&gt;GetState( \</div><div class="line">    hComponent, \</div><div class="line">    pState)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>定义</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>pState</em>[输出]</td>
<td>指向接受状态的指针。返回的值应该是<code>OMX_STATETYPE</code>成员之一。</td>
</tr>
</tbody>
</table>
<p>3.3.12小节描述了每个组件实现的相应方法。</p>
<p>#####3.2.2.13.1  先决条件<br>这种方法没有先决条件。</p>
<p>#####3.2.2.13.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line">OMX_SendCommand(hComp, OMX_CommandStateSet, OMX_StateIdle, <span class="number">0</span>);</div><div class="line"><span class="keyword">do</span> &#123;</div><div class="line">  OMX_GetState(hComp, &amp;eState);</div><div class="line">&#125; <span class="keyword">while</span> (OMX_StateIdle != eState);</div></pre></td></tr></table></figure>
<p>####3.2.2.14  OMX_UseBuffer<br>宏<code>OMX_UseBuffer</code>请求组件使用IL客户端已经分配好或一个管道的组件提供的buffer。<code>OMX_UseBuffer</code>的实现应该分配buffer头，填充给定的参数，并通过输出参数ppBufferHdr传递回来。</p>
<p>宏<code>OMX_UseBuffer</code>应该在下面的情况下执行：</p>
<ul>
<li>当组件在<code>OMX_StateLoaded</code>并已经发送了转移到<code>OMX_StateIdle</code>的请求。</li>
<li>当组件在<code>OMX_StateWaitForResources</code>状态，所需求资源可用，并组件已经准备转移到<code>OMX_StateIdle</code>状态。</li>
<li>当组件处于<code>OMX_StateExecuting</code>, <code>OMX_StatePause</code>, 或<code>OMX_StateIdle</code>在禁用的端口上</li>
</ul>
<p>这个调用为一个阻塞调用。组件应该在20毫秒以内返回这个调用。</p>
<p>宏<code>OMX_UseBuffer</code>定义如下：<br><figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div><div class="line">11</div><div class="line">12</div><div class="line">13</div><div class="line">14</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_UseBuffer(\</span></div><div class="line">  hComponent,\</div><div class="line">  ppBufferHdr,\</div><div class="line">  nPortIndex,\</div><div class="line">  pAppPrivate,\</div><div class="line">  nSizeBytes,\</div><div class="line">  pBuffer)\</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent-&gt;UseBuffer(\</div><div class="line">    hComponent,\</div><div class="line">    ppBufferHdr,\</div><div class="line">    nPortIndex,\</div><div class="line">    pAppPrivate,\</div><div class="line">    nSizeBytes,\</div><div class="line">    pBuffer)</div></pre></td></tr></table></figure></p>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>ppBufferHdr</em> [输出]</td>
<td>指向一个OMX_BUFFERHEADERTYPE结构体的指针的指针，用于接受buffer头的指针。</td>
</tr>
<tr>
<td><em>nPortIndex</em> [输入]</td>
<td>指定buffer的端口索引。这个索引与拥有端口的组件相对应。</td>
</tr>
<tr>
<td><em>pAppPrivate</em> [输入]</td>
<td>指针，指向和具体实现内存空间，由buffer提供者负责。</td>
</tr>
<tr>
<td><em>nSizeBytes</em> [输入]</td>
<td>buffer大小，由字节标识</td>
</tr>
<tr>
<td><em>pBuffer</em> [输入]</td>
<td>指向使用的内存buffer空间的指针</td>
</tr>
</tbody>
</table>
<p>3.3.14小节描述了每个组件实现的相应方法。</p>
<p>#####3.2.2.14.1  先决条件<br>组件应该处于<code>OMX_StateLoaded</code>或<code>OMX_StateWaitForResources</code>状态，或调用的端口被禁用。</p>
<p>#####3.2.2.14.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div><div class="line">11</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* supplier port allocates buffers and pass them to non-supplier */</span></div><div class="line"><span class="keyword">for</span> (i=<span class="number">0</span>;i&lt;pPort-&gt;nBufferCount;i++)</div><div class="line">&#123;</div><div class="line">  pPort-&gt;pBuffer[i] = <span class="built_in">malloc</span>(pPort-&gt;nBufferSize);</div><div class="line">  OMX_UseBuffer(pPort-&gt;hTunnelComponent,</div><div class="line">                &amp;pPort-&gt;pBufferHdr[i],</div><div class="line">                pPort-&gt;nTunnelPort,</div><div class="line">                pPort,</div><div class="line">                pPort-&gt;nBufferSize,</div><div class="line">                pPort-&gt;pBuffer[j]);</div><div class="line">&#125;</div></pre></td></tr></table></figure>
<p>####3.2.2.15  OMX_AllocateBuffer<br>宏OMX_AllocateBuffer将请求组件分配一块新的buffer和buffer头。组件将分配buffer和buffer头并返回buffer头的指针。这个调用为阻塞调用，并且应该在下列条件下进行：</p>
<ul>
<li>组件处于<code>OMX_StateLoaded</code>状态并且已经发送了转移至<code>OMX_StateIdle</code>的请求。</li>
<li>组件处于<code>OMX_StateWaitForResources</code>状态，所需资源可用，并且组件已准备进入<code>OMX_StateIdle</code>状态</li>
<li>当组件处于<code>OMX_StateExecuting</code>, <code>OMX_StatePause</code>, 或<code>the OMX_StateIdle</code>状态时禁用端口。</li>
</ul>
<p>宏<code>OMX_AllocateBuffer</code>在只和IL客户端的通信的特定端口分配buffer。这个宏不能用于管道端口上的分配buffer。在配置管道端口之前buffer分配会导致组件在端口上调用<code>OMX_SetupTunne</code>l失败。</p>
<p>组件应该在5毫秒以内返回这个调用。</p>
<p>宏<code>OMX_AllocateBuffer</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div><div class="line">11</div><div class="line">12</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_AllocateBuffer (</span></div><div class="line">  hComponent,</div><div class="line">  pBuffer,</div><div class="line">  nPortIndex,</div><div class="line">  pAppPrivate,</div><div class="line">  nSizeBytes )</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent)-&gt;AllocateBuffer( \</div><div class="line">      hComponent, \</div><div class="line">      pBuffer, \</div><div class="line">      nPortIndex, \</div><div class="line">      pAppPrivate, \</div><div class="line">      nSizeBytes)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>ppBufferHdr</em> [输出]</td>
<td>指向<code>OMX_BUFFERHEADERTYPE</code>结构体指针的指针，用于接受指向buffer头的指针</td>
</tr>
<tr>
<td><em>nPortIndex</em> [输入]</td>
<td>选择组件上使用buffer的端口。端口可以通过<code>nPortIndex</code>值在组件端口定义的数组中找到。</td>
</tr>
<tr>
<td><em>pAppPrivate</em> [输入]</td>
<td>初始化buffer头结构体中<code>pAppPrivate</code>成员</td>
</tr>
<tr>
<td><em>nSizeBytes</em> [输入]</td>
<td>分配buffer的大小</td>
</tr>
</tbody>
</table>
<p>3.3.15小节描述了每个组件实现的相应方法。</p>
<p>#####3.2.2.15.1  先决条件<br>组件应该处于<code>OMX_StateLoaded</code>或<code>OMX_StateWaitForResources</code>状态，或调用的端口被禁用。</p>
<p>#####3.2.2.15.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* IL client asks component to allocate buffers */</span></div><div class="line"><span class="keyword">for</span> (i=<span class="number">0</span>;i&lt;pClient-&gt;nBufferCount;i++)</div><div class="line">&#123;</div><div class="line">  OMX_AllocateBuffer(hComp,</div><div class="line">      &amp;pClient-&gt;pBufferHdr[i],</div><div class="line">      pClient-&gt;nPortIndex,</div><div class="line">      pClient,</div><div class="line">      pClient-&gt;nBufferSize);</div><div class="line">&#125;</div></pre></td></tr></table></figure>
<p>####3.2.2.16  OMX_FreeBuffer<br>宏<code>OMX_FreeBuffer</code>将从一个组件中释放一块buffer和buffer头。如果组件只分配buffer，则只释放buffer头。如果组件分配buffer和buffer头，则应该释放buffer和buffer头。因此，组件应该记录哪些buffer是自己分配的，以便执行响应的释放。</p>
<p>这个调用应该在下面的情况下执行：</p>
<ul>
<li>当组件在<code>OMX_StateIdle</code>且IL客户端已发送了一个向OMX_StateLoaded转移的请求（例如，在组件停止时）。</li>
<li>当组件在<code>OMX_StateExecuting</code>, <code>OMX_StatePause</code>, 或<code>OMX_StateIdle</code>状态时禁用端口。</li>
</ul>
<p>这个方法可以在任何事件被调用，但如果调用没有按上面描述的规则执行，则可能端口发送<code>OMX_ErrorPortUnpopulated</code>错误。在管道中，这个方法由供应端口调用，用于释放供应端口管道上的buffer头。</p>
<p>这个调用为一个阻塞调用。组件应该在20毫秒以内返回这个调用。</p>
<p>宏OMX_FreeBuffer定义如下。</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_FreeBuffer (</span></div><div class="line">    hComponent,</div><div class="line">    nPortIndex,</div><div class="line">    pBuffer )</div><div class="line">    ((OMX_COMPONENTTYPE*)hComponent)-&gt;FreeBuffer( \</div><div class="line">        hComponent, \</div><div class="line">        nPortIndex,</div><div class="line">        pBuffer)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>nPortIndex</em> [输入]</td>
<td>使用特定buffer的端口索引</td>
</tr>
<tr>
<td><em>pBuffer</em> [输入]</td>
<td>指向OMX_BUFFERHEADERTYPE结构体的指针，用于提供或接受buffer头的指针。</td>
</tr>
</tbody>
</table>
<p>3.3.16小节描述了每个组件实现的相应方法。</p>
<p>#####3.2.2.16.1  先决条件<br>组件应处于<code>OMX_StateIdle</code>状态或端口被禁用。</p>
<p>#####3.2.2.16.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* supplier port frees buffers */</span></div><div class="line"><span class="keyword">for</span> (i=<span class="number">0</span>;i&lt;pPort-&gt;nBufferCount;i++)</div><div class="line">&#123;</div><div class="line">  <span class="built_in">free</span>(pPort-&gt;pBuffer[i]);</div><div class="line">  pPort-&gt;pBuffer[i] = <span class="number">0</span>;</div><div class="line">  OMX_FreeBuffer(pPort-&gt;hTunnelComponent,</div><div class="line">      pPort-&gt;nTunnelPort,</div><div class="line">      pPort-&gt;pBufferHdr[i]);</div><div class="line">  pPort-&gt;pBufferHdr[j] = <span class="number">0</span>;</div><div class="line">&#125;</div></pre></td></tr></table></figure>
<p>####3.2.2.17  OMX_EmptyThisBuffer<br>宏<code>OMX_EmptyThisBuffer</code>会发送一块满的buffer给组件的一个输入端口。当buffer含有数据，buffer头中<code>nFilledLength</code>字段的值应该不为0。如果buffer不含有数据，<code>nFilledLength</code>的值为0x0。当组件在<code>OMX_StateExecuting</code>或<code>OMX_StatePaused</code>状态，或者正在向<code>OMX_StateExecuting</code>状态转移时，调用宏<code>OMX_EmptyThisBuffer</code>来传递包含数据的buffer。</p>
<p>当端口没有管道时，发送给<code>OMX_EmptyThisBuffer</code>的buffer一旦被清空就通过回调<code>EmptyBufferDone</code>返回给IL客户端。</p>
<p>当端口有管道时，只要组件处于<code>OMX_StateExecuting</code>状态，发送给<code>OMX_EmptyThisBuffer</code>的buffer一旦被清空会发送给管道端口。buffer使用<code>OMX_EmptyThisBuffer</code>返回给提供buffer的输出端口，不管管道是否被清空或者禁用。buffer也会返回给提供的输入端口，当调用<code>OMX_FillThisBuffer</code>的组件正从<code>OMX_StateExecuting</code>或<code>OMX_StatePaused</code>状态转移到<code>OMX_StateIdle</code>状态。</p>
<p>这个调用为一个非阻塞调用，因为组件将buffer放入队列并立马返回。buffer会在后面合适的时间被填充。如果buffer头中的参数<code>nInputPortIndex</code>没有指定一个特定的输出端口，组件会返回<code>OMX_ErrorBadPortIndex</code>。组件应该在5毫秒以内返回这个调用。</p>
<p>宏<code>OMX_EmptyThisBuffer</code>定义如下：<br><figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_EmptyThisBuffer (</span></div><div class="line">    hComponent,</div><div class="line">    pBuffer )</div><div class="line">    ((OMX_COMPONENTTYPE*)hComponent)-&gt;EmptyThisBuffer( \</div><div class="line">        hComponent, \</div><div class="line">        pBuffer)</div></pre></td></tr></table></figure></p>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>pBuffer</em> [输入]</td>
<td>指向OMX_BUFFERHEADERTYPE结构体的指针，用于提供或接受buffer头的指针。buffer头应该指定接受buffer的输入端口的索引。</td>
</tr>
</tbody>
</table>
<p>3.3.17小节描述了每个组件实现的相应方法。</p>
<p>#####3.2.2.17.1  先决条件<br>组件必须处于如表3-10所示的合适状态。</p>
<p>#####3.2.2.17.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* deliver full buffer */</span></div><div class="line"><span class="keyword">if</span> (pPort-&gt;hTunnelComponent)</div><div class="line">  OMX_EmptyThisBuffer(pPort-&gt;hTunnelComponent, pBuffer);</div><div class="line"><span class="keyword">else</span></div><div class="line">  pCallbacks-&gt;FillBufferDone(hComp, pBuffer,</div><div class="line">      pPort-&gt;pCallbackAppData);</div></pre></td></tr></table></figure>
<p>####3.2.2.18  OMX_FillThisBuffer<br>宏<code>OMX_FillThisBuffer</code>会给组件的输出端口发送一个空buffer。当组件正处于<code>OMX_StatePaused</code>或<code>OMX_StateExecuting</code>状态，或者正在向<code>OMX_StateExecuting</code>状态转移时调用宏<code>OMX_FillThisBuffer</code>用来传递一块不含数据的buffer。</p>
<p>当端口没有管道时，发送给<code>OMX_FillThisBuffer</code>的buffer一旦被填充通过回调<code>FillBufferDone</code>返回给IL客户端。</p>
<p>当端口有管道时，只要组件处于<code>OMX_StateExecuting</code>状态，发送给<code>OMX_FillThisBuffer</code>的buffer一旦被填充会发送给管道端口。buffer使用<code>OMX_FillThisBuffer</code>返回给提供buffer的输出端口，不管管道是否被清空或者禁用。buffer也会返回给提供的输出端口，当调用<code>OMX_FillThisBuffer</code>的组件正从<code>OMX_StateExecuting</code>或<code>OMX_StatePaused</code>状态转移到<code>OMX_StateIdle</code>状态。</p>
<p>这个调用为一个非阻塞调用，因为组件将buffer放入队列并立马返回。buffer会在后面合适的时间被填充。如果buffer头中的参数<code>nOutputPortIndex</code>没有指定一个特定的输出端口，组件会返回<code>OMX_ErrorBadPortIndex</code>。组件应该在5毫秒以内返回这个调用。</p>
<p>宏<code>OMX_FillThisBuffer</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line"><span class="meta">#<span class="meta-keyword">define</span> OMX_FillThisBuffer (</span></div><div class="line">  hComponent,</div><div class="line">  pBuffer )</div><div class="line">  ((OMX_COMPONENTTYPE*)hComponent)-&gt;FillThisBuffer( \</div><div class="line">      hComponent, \</div><div class="line">      pBuffer)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>pBuffer</em> [输入]</td>
<td>指向OMX_BUFFERHEADERTYPE结构体的指针，用于提供或接受buffer头的指针。buffer头应该指定接受buffer的输入端口的索引。</td>
</tr>
</tbody>
</table>
<p>3.3.18小节描述了每个组件实现的相应方法。</p>
<p>#####3.2.2.18.1  先决条件<br>组件必须处于如表3-10所示的合适状态。</p>
<p>#####3.2.2.18.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div><div class="line">11</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* On a port enable, if tunneling and an input and not supplier */</span></div><div class="line"><span class="comment">/* then give buffers to supplier port */</span></div><div class="line"><span class="keyword">if</span> (pPort-&gt;hTunnelComponent &amp;&amp;</div><div class="line">    (pPort-&gt;oPortDef.eDir == OMX_DirInput) &amp;&amp;</div><div class="line">    (pPort-&gt;eSupplierSetting == OMX_BufferSupplyInput) )</div><div class="line">&#123;</div><div class="line">  <span class="keyword">for</span> (i=<span class="number">0</span>;i&lt;pPort-&gt;nBuffers;i++)&#123;</div><div class="line">    OMX_FillThisBuffer(pPort-&gt;hTunnelComponent,</div><div class="line">        pPort-&gt;ppBufferHdrs[i]);</div><div class="line">  &#125;</div><div class="line">&#125;</div></pre></td></tr></table></figure>
<p>###3.2.3 函数<br>本小节描述了OpenMAX IL API中的函数方法。</p>
<p>####3.2.3.1  OMX_Init<br><code>OMX_Init</code>方法初始化OpenMAX Core。<code>OMX_Init</code>应该在OpenMAX中首先被调用，并且仅被调用一次（如果中间没有调用<code>OMX_Deinit</code>的话）。如果<code>OMX_Init</code>被调用两次，应该返回<code>OMX_ErrorNone</code>但初始化请求被忽略。Core都应该在20毫秒内返回这个调用。</p>
<p><code>OMX_Init()</code>用法如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div></pre></td><td class="code"><pre><div class="line"><span class="function">OMX_API OMX_ERRORTYPE OMX_APIENTRY <span class="title">OMX_Init</span><span class="params">()</span></span></div></pre></td></tr></table></figure>
<p>#####3.2.3.1.1  先决条件<br>此方法没有先决条件。</p>
<p>#####3.2.3.1.2  方法的结果/输出<br>如果命令成功执行，返回值为OMX_ErrorNone。否则，将返回合适的OpenMAX错误值。如果次函数返回成功，OpenMAX core函数则可以被使用。</p>
<p>#####3.2.3.1.3  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* Initialize OpenMax and create some components */</span></div><div class="line">OMX_Init();</div><div class="line">OMX_GetHandle(hMp3Decoder, <span class="string">"OMX.CompanyXYZ.mp3.decoder"</span>, pAppData, pCallbacks);</div><div class="line">OMX_GetHandle(hAudioMixer, <span class="string">"OMX.CompanyXYZ.audio.mixer"</span>, pAppData, pCallbacks);</div></pre></td></tr></table></figure>
<p>####3.2.3.2  OMX_Deinit<br><code>OMX_Deinit</code>方法释放OpenMAX core。<code>OMX_Deinit</code>应该在OpenMAX core中当所有OpenMAX相关的资源被释放后最后被调用。core应该在20毫秒以内返回此调用。但更好的方法是让每个组件回到loaded状态再释放他们，做这些事情可能需要超过20毫秒调用时间。它进一步要求OpenMAX core来跟踪所有组件句柄，在某些平台上这可能会增加不必要的复杂性。</p>
<p>OMX_Deinit方法用法如下。</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div></pre></td><td class="code"><pre><div class="line"><span class="function">OMX_API OMX_ERRORTYPE OMX_APIENTRY <span class="title">OMX_Deinit</span><span class="params">()</span></span></div></pre></td></tr></table></figure>
<p>#####3.2.3.2.1  先决条件<br>使用OMX_Deinit需要系统中所有组件句柄已被释放，意味着所有组件相关的资源已被释放。</p>
<p>####3.2.3.2.2  方法的结果/输出<br><code>OMX_Deinit</code>返回<code>OMX_ERRORTYPE</code>。如果命令成功执行，返回结果为<code>OMX_ErrorNone</code>。否则返回合适的OpenMAX错误。</p>
<p>#####3.2.3.2.3  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div><div class="line">11</div><div class="line">12</div><div class="line">13</div><div class="line">14</div><div class="line">15</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* Determine if a component of a particular name exists. */</span></div><div class="line">OMX_Init();</div><div class="line">eError = OMX_ErrorNone;</div><div class="line"><span class="keyword">for</span> (i=<span class="number">0</span>; OMX_ErrorNone == eError; i++)</div><div class="line">&#123;</div><div class="line">  eError = OMX_ComponentNameEnum(szCompEnumName, <span class="number">256</span>, i);</div><div class="line">  <span class="keyword">if</span> ((OMX_ErrorNone == eError) &amp;&amp;</div><div class="line">      (!<span class="built_in">strcmp</span>(szCompEnumName, szComponentName))</div><div class="line">  &#123;</div><div class="line">    OMX_Deinit();</div><div class="line">    <span class="keyword">return</span> OMX_TRUE;</div><div class="line">  &#125;</div><div class="line">&#125;</div><div class="line">OMX_Deinit();</div><div class="line"><span class="keyword">return</span> OMX_FALSE;</div></pre></td></tr></table></figure>
<p>####3.2.3.3  OMX_ComponentNameEnum<br><code>OMX_ComponentNameEnum</code>方法会枚举所有组件中识别的组件来检测运行时系统中的所有组件。组件名称的列举没有严格顺序，但每个名字只能被列举一次。如果OpenMAX core支持运行期间加入新组件，当第一次列举组件名时，它仅需要检测新安装的组件（例如，当nIndex的值为0x0）。</p>
<p>方法<code>OMX_ComponentNameEnum</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div></pre></td><td class="code"><pre><div class="line"><span class="function">OMX_API OMX_ERRORTYPE OMX_APIENTRY <span class="title">OMX_ComponentNameEnum</span><span class="params">(</span></span></div><div class="line">    OMX_OUT OMX_STRING cComponentName,</div><div class="line">    OMX_IN OMX_U32 nNameLength,</div><div class="line">    OMX_IN OMX_U32 nIndex</div><div class="line">)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>cComponentName</em> [输出]</td>
<td>指向以0结尾的组件名字符串的指针。组件名字符串大小限制为127字节加上结尾的null最大长度为128字节。例如一个合法的组件名为”OMX.<vendor_name>.AUDIO.DSP.MIXER\0”。名字应该以”OMX.”开始加上厂商指定的字符串</vendor_name></td>
</tr>
<tr>
<td><em>nNameLength</em> [输入]</td>
<td>cComponentName字符串中字符大小。由于组件名不得超过128个字符（不包括结尾的null），调用者应该提供一个至少128字符的输入字符串</td>
</tr>
<tr>
<td><em>nIndex</em> [输入]</td>
<td>包含组件列表索引的数值。增加nIndex的值来多次调用<code>OMX_ComponentNameEnum</code>来列举系统中所有的组件名直到返回<code>OMX_ErrorNoMore</code>。如果系统中有N个组件安装，则nIndex的取值范围是0到N-1。</td>
</tr>
</tbody>
</table>
<p>#####3.2.3.3.1  先决条件<br><code>OMX_ComponentNameEnum</code>可以在<code>OMX_Init</code>函数后调用。</p>
<p>#####3.2.3.3.2  方法的结果/输出<br>如果OMX_ComponentNameEnum成功执行，返回值为OMX_ErrorNone。如果nIndex值超过了系统中组件个数-1，则返回OMX_ErrorNoMore。否则应返回合适的OpenMAX错误。</p>
<p>#####3.2.3.3.3  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* print a list of all components */</span></div><div class="line">eError = OMX_ErrorNone;</div><div class="line"><span class="keyword">for</span> (i=<span class="number">0</span>; OMX_ErrorNoMore != eError; i++)</div><div class="line">&#123;</div><div class="line">  eError = OMX_ComponentNameEnum(szCompName, <span class="number">256</span>, i);</div><div class="line">  <span class="keyword">if</span> (OMX_ErrorNone == eError)</div><div class="line">    <span class="built_in">printf</span>(<span class="string">"Component %i: %s\n"</span>, szCompName);</div><div class="line">&#125;</div></pre></td></tr></table></figure>
<p>####3.2.3.4  OMX_GetHandle<br><code>OMX_GetHandle</code>方法会根据指定的组件名定位组件，加载组件进入内存并验证其有效性。如果组件有效，<code>OMX_GetHandle</code>会调用组件方法来填充组件句柄并设置回调。<code>OMX_GetHandle</code>方法会分配真正的<code>OMX_HANDLETYPE</code>结构体，保证正确的填写，然后用新创建的句柄指针更新*pHandle的值。组件应该在20毫秒内返回这个调用。</p>
<p>每次OMX_GetHandle方法成功返回，会创建一个新的组件实例。在组件可以被使用之前，IL客户端应该配置新创建的处于OMX_StateLoaded状态的组件。</p>
<p>由于组件是通过名称来请求，这里定义了命名规则。OpenMAX组件的名字是null结尾的字符串，格式如下：</p>
<p>“OMX.<vendor_name>.<vendor_specified_convention>”.</vendor_specified_convention></vendor_name></p>
<p>不同厂商之间的组件名称没有标准。</p>
<p><code>OMX_GetHandle</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line"><span class="function">OMX_API OMX_ERRORTYPE OMX_APIENTRY <span class="title">OMX_GetHandle</span><span class="params">(</span></span></div><div class="line">    OMX_OUT OMX_HANDLETYPE * pHandle,</div><div class="line">    OMX_IN OMX_STRING cComponentName,</div><div class="line">    OMX_IN OMX_PTR pAppData,</div><div class="line">    OMX_IN OMX_CALLBACKTYPE * pCallBacks</div><div class="line">)</div></pre></td></tr></table></figure>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>pHandle</em> [输出]</td>
<td>指向OMX_HANDLETYPE的指针，由此方法填充</td>
</tr>
<tr>
<td><em>cComponentName</em> [输入]</td>
<td>指向以null结果的组件名称的字符串指针。组件名字符串大小限制为127字节加上结尾的null最大长度为128字节。例如一个合法的组件名为”OMX.<vendor_name>.AUDIO.DSP.MIXER\0”。名字应该以”OMX.”开始加上厂商指定的字符串</vendor_name></td>
</tr>
<tr>
<td><em>pAppData</em> [输入]</td>
<td>指向IL客户端定义的值的指针，在回调用返回。这样IL客户端可以知道回调的来源。</td>
</tr>
<tr>
<td><em>pCallBacks</em> [输入]</td>
<td>指向OMX_CALLBACKTYPE结构体的指针，包含了组件使用的给此IL客户端的回调函数</td>
</tr>
</tbody>
</table>
<p>#####3.2.3.4.1  先决条件<br>OpenxMax core应该被初始化。</p>
<p>#####3.2.3.4.2  方法的结果/输出<br>如果成功，此方法返回一个有效的组件句柄给IL客户端。</p>
<p>#####3.2.3.4.3  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div><div class="line">9</div><div class="line">10</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* determine maximum number of instantiations of a component */</span></div><div class="line">eError = OMX_ErrorNone;</div><div class="line"><span class="keyword">for</span> (i=<span class="number">0</span>; OMX_ErrorNone == eError; i++)</div><div class="line">&#123;</div><div class="line">  eError = OMX_GetHandle(&amp;hComp[i],</div><div class="line">  szComponentName,</div><div class="line">  pAppData,</div><div class="line">  pCallbacks);</div><div class="line">&#125;</div><div class="line"><span class="built_in">printf</span>(<span class="string">"Created %i instantiations.\n"</span>,i);</div></pre></td></tr></table></figure>
<p>####3.2.3.5  OMX_FreeHandle<br><code>OMX_FreeHandle</code>方法会释放一个由<code>OMX_GetHandle</code>方法分配的句柄。组件应该在20毫秒内返回此方法。 IL客户端只能当组件是<code>OMX_StateLoaded</code>或<code>OMX_StateInvalid</code>状态是调用<code>OMX_FreeHandle</code>。在其他状态调用<code>OMX_FreeHandle</code>可能导致组件花费超过推荐的20毫秒，并且用来作为一个错误恢复机制。</p>
<p><code>OMX_FreeHandle</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div></pre></td><td class="code"><pre><div class="line"><span class="function">OMX_API OMX_ERRORTYPE OMX_APIENTRY <span class="title">OMX_FreeHandle</span><span class="params">(</span></span></div><div class="line">  OMX_IN OMX_HANDLETYPE hComponent )</div></pre></td></tr></table></figure>
<p>唯一的参数定义如下。</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>待释放的组件句柄</td>
</tr>
</tbody>
</table>
<p>#####3.2.3.5.1  先决条件<br>调用此方法的时候，组件应该处于<code>OMX_StateLoade</code>d或<code>OMX_StateInvalid</code>状态。</p>
<p>#####3.2.3.5.2  方法的结果/输出<br>组件相关的资源被释放。</p>
<p>#####3.2.3.5.3  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* stop executing component and clean up component */</span></div><div class="line">OMX_SendCommand(hComp, OMX_CommandStateSet, OMX_StateIdle, <span class="number">0</span>);</div><div class="line">OMX_SendCommand(hComp, OMX_CommandStateSet, OMX_StateLoaded, <span class="number">0</span>);</div><div class="line"><span class="keyword">do</span> &#123;</div><div class="line">  OMX_GetState(hComp, &amp;eState);</div><div class="line">&#125; <span class="keyword">while</span> (OMX_StateLoaded != eState);</div><div class="line">OMX_FreeHandle(hComp);</div></pre></td></tr></table></figure>
<p>####3.2.3.6  OMX_SetupTunnel<br><code>OMX_SetupTunnel</code>方法设置输入和输出端口之间的管道通信。此方法是一个实际的方法而不是一个宏。<code>OMX_SetupTunnel</code>方法会调用组件的<code>ComponentTunnelRequest()</code>方法来建立管道。</p>
<p>在建立输入端口的非管道通信时， 参数<code>hOutput</code>的值应该为0x0.当建立输出端口的非管道通信时，<code>hInput</code>的值应该为0x0。</p>
<p>在设置输出和输入端口之间的管道通信时， 此方法首先调用输出端口的组件上的ComponentTunnelRequest()。如果调用成功，会接着调用输入端口的组件上的ComponentTunnelRequest()。如果这两次调用失败一次，则此方法会将输入和输入端口都设置成非管道通信。</p>
<p>组件可能用专用通信来代替管道通信只要输入输出端口都支持专有通信。IL客户端无法区分管道通信和专有通信。</p>
<p>组件应该在20毫秒以内返回此调用。</p>
<p>Base profile的组件不支持这个方法，此时应该返回<code>OMX_ErrorNotImplemented</code>。具体关于设置两个组件之间的数据管道描述可见3.4.1.2小节。<code>OMX_SetupTunnel</code>定义如下。</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line"><span class="function">OMX_API OMX_ERRORTYPE OMX_APIENTRY <span class="title">OMX_SetupTunnel</span><span class="params">(</span></span></div><div class="line">    OMX_IN OMX_HANDLETYPE hOutput,</div><div class="line">    OMX_IN OMX_U32 nPortOutput,</div><div class="line">    OMX_IN OMX_HANDLETYPE hInput,</div><div class="line">    OMX_IN OMX_U32 nPortInput</div><div class="line">)</div></pre></td></tr></table></figure>
<p>参数定义如下：<br>| 参数 | 说明 |<br>| —— | —— |<br>| <em>hOutput</em> [输出] | 包含管道中输出端口的组件的句柄。输出端口在参数<code>nPortOutput</code>中定义。根据定义，输出端口的方向是<code>OMX_DirOutput</code>。如果这个参数是0x0，那么组件<code>hInput</code>上端口<code>hPortInput</code>会被设置为非管道通信。|<br>| <em>nPortOutput</em> [输入] | 表示组件<code>hOutput</code>上用于管道或专有通信的输出端口。|<br>| <em>hInput</em> [输入] |包含管道中输入端口的组件的句柄。输入端口在参数<code>nPortInput</code>中定义。根据定义，输入端口的方向是<code>OMX_DirInput</code>。如果这个参数是0x0，那么组件<code>hOutput</code>上端口<code>hPortOutput</code>会被设置为非管道通信。|<br>| <em>nPortInput</em> [输入] | 表示组件<code>hInput</code>上用于管道或专有通信的输入端口。 |</p>
<p>#####3.2.3.6.1  先决条件<br>每一个建立管道的组件应该处于<code>OMX_StateLoaded</code>装填，或者端口被禁用。</p>
<p>#####3.2.3.6.2  方法的结果/输出<br>如果此方法当输出和输入组件都已提供，管道或专有通信已在指定的输出和输入端口之间建立时返回成功。当只有一个输入或输出组件提供或者在处理时发生了错误，端口会被设置成非管道通信。</p>
<p>#####3.2.3.6.3  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* set up tunnel between two components then transition to idle */</span></div><div class="line">OMX_SetupTunnel(hCompA, nCompAOutPort, hCompB, nCompBInPort);</div><div class="line">OMX_SendCommand(hCompA, OMX_CommandStateSet, OMX_StateIdle, <span class="number">0</span>);</div><div class="line">OMX_SendCommand(hCompB, OMX_CommandStateSet, OMX_StateIdle, <span class="number">0</span>);</div></pre></td></tr></table></figure>
<p>##3.3  OpenMAX组件方法和结构<br>OpenMAX组件定义在<code>OMX_Component.h</code>头文件中。结构体OMX_COMPONENTTYPE持有了组件的数据字段和函数入口。</p>
<p>###3.3.1 nSize<br><code>nSize</code> 为结构体大小的字节数。这个值不论结构体用作函数输入或是输出时都应该被指定。</p>
<p>###3.3.2 nVersion<br><code>nVersion</code>为创建结构体的OpenMAX协议的版本好。结构体的创建者负责初始化这个值。每一个结构体的使用者应该验证，这样它可以知道怎么使用这个版本的结构体。</p>
<p>###3.3.3 pComponentPrivate<br><code>pComponentPrivate</code>是一个组件私有数据空间的指针。组件在第一次加载时分配并初始化这个成员。应用不应该访问这个数据空间。</p>
<p>###3.3.4 pApplicationPrivate<br><code>pApplicationPrivate</code>是一个指向应用私有数据空间的指针。组件在调用<code>OMX_SetCallbacks</code>时初始化这个字段，这个字段当组件回调时返回提供给IL客户端。</p>
<p>###3.3.5 GetComponentVersion<br>IL客户端通过宏<code>OMX_GetComponentVersion</code>调用组件的<code>GetComponentVersion</code>。见<code>OMX_GetComponentVersion</code>在3.2.2.1小节的定义，描述了其语义。</p>
<p><code>GetComponentVersion</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*GetComponentVersion)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_OUT OMX_STRING pComponentName,</div><div class="line">    OMX_OUT OMX_VERSIONTYPE* pComponentVersion,</div><div class="line">    OMX_OUT OMX_VERSIONTYPE* pSpecVersion,</div><div class="line">    OMX_OUT OMX_UUIDTYPE* pComponentUUID);</div></pre></td></tr></table></figure>
<p>###3.3.6 SendCommand<br>IL客户端通过<code>OMX_SendCommand</code>宏来调用组件的SendCommand方法。见小节3.2.2.2中<code>OMX_SendCommand</code>的定义，描述了其语义。</p>
<p><code>SendCommand</code>定义如下：<br><figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*SendCommand)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_COMMANDTYPE Cmd,</div><div class="line">    OMX_IN OMX_U32 nParam,</div><div class="line">    OMX_IN OMX_PTR pCmdData);</div></pre></td></tr></table></figure></p>
<p>###3.3.7 GetParameter<br>IL客户端或者一个管道组件通过<code>OMX_GetParameter</code>宏调用组件的<code>GetParameter</code>方法。见小节3.2.2.8中<code>OMX_GetParameter</code>的定义，描述了其语义。</p>
<p><code>GetParameter</code>定义如下。<br><figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*GetParameter)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_INDEXTYPE nParamIndex,</div><div class="line">    OMX_INOUT OMX_PTR ComponentParameterStructure);</div></pre></td></tr></table></figure></p>
<p>###3.3.8 SetParameter<br>IL客户端或者一个管道组件通过<code>OMX_SetParameter</code>宏调用组件的<code>SetParameter</code>方法。见小节3.2.2.9中<code>OMX_SetParameter</code>的定义，描述了其语义。</p>
<p><code>SetParameter</code>定义如下：<br><figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*SetParameter)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_INDEXTYPE nIndex,</div><div class="line">    OMX_IN OMX_PTR ComponentParameterStructure);</div></pre></td></tr></table></figure></p>
<p>###3.3.9 GetConfig<br>IL客户端通过<code>OMX_GetConfig</code>宏来调用组件的<code>GetConfig</code>方法。见小节3.2.2.10中<code>OMX_GetConfig</code>的定义，描述了其语义。<br><code>GetConfig</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*GetConfig)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_INDEXTYPE nIndex,</div><div class="line">    OMX_INOUT OMX_PTR pComponentConfigStructure);</div></pre></td></tr></table></figure>
<p>###3.3.10  SetConfig<br>IL客户端通过<code>OMX_SetConfig</code>宏来调用组件的<code>SetConfig</code>方法。见小节3.2.2.11中<code>OMX_SetConfig</code>的定义，描述了其语义。</p>
<p><code>SetConfig</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*SetConfig)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_INDEXTYPE nIndex,</div><div class="line">    OMX_IN OMX_PTR pComponentConfigStructure);</div></pre></td></tr></table></figure>
<p>###3.3.11  GetExtensionIndex<br>IL客户端通过<code>OMX_GetExtensionIndex</code>宏来调用组件的<code>GetExtenstionIndex</code>方法。见小节3.2.2.12中<code>OMX_GetExtensionIndex</code>的定义，描述了其语义。</p>
<p><code>GetExtensionIndex</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*GetExtensionIndex)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_STRING cParameterName,</div><div class="line">    OMX_OUT OMX_INDEXTYPE* pIndexType);</div></pre></td></tr></table></figure>
<p>###3.3.12  GetState<br>IL客户端通过<code>OMX_GetState</code>宏来调用组件的<code>GetState</code>方法。见小节3.2.2.13中<code>OMX_GetState</code>的定义，描述了其语义。</p>
<p><code>GetState</code>定义如下：<br><figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*GetState)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_OUT OMX_STATETYPE* pState);</div></pre></td></tr></table></figure></p>
<p>###3.3.13  ComponentTunnelRequest<br><code>OMX_ComponentTunnelRequest</code>方法会和另一个OpenMAX组件交互来确定管道或简历管道是否可行。此方法的返回值可以决定管道是否可行或者专有通信或管道已经使用。</p>
<p>interop profile的组件应该支持通过兼容的参数和组件建立管道。组件也可以支持专有通信。如果支持管有通信，会使用厂商特定的专有通信协议。唯一的要求是返回正确的记过。专有通信设置细节留给厂商来实现。</p>
<p><code>ComponentTunnelRequest</code>方法在支持管道通信的两端的组件上调用。当这个放在在提供输出端口的组件上调用时。组件应该做下面的事：</p>
<ol>
<li>在pTunnelSetup中表明提供者的参数。</li>
<li>设置<code>OMX_PORTTUNNELFLAG_READONLY</code>标志来表明从这个输出端口出来的buffer是只读的而且buffer不可以被组件共享或修改。</li>
</ol>
<p>当这个方法在提供输入端口的组件上调用，组件应该做下面的事：</p>
<ol>
<li>使用若干次GetParameter调用检查端口间数据的兼容性。</li>
<li>检查输出端口的buffer提供参数，并使用OMX_SetParameter和OMX_IndexParamCompBufferSupplier索引来通知输出端口哪个端口提供这些buffer。</li>
</ol>
<p>如果这个方法使用NULL作为pTunnelComp参数调用，端口应该设置与IL客户端的非管道通信。</p>
<p>组件应该在5毫秒内返回这个调用。</p>
<p><code>ComponentTunnelRequest</code>定义如下：<br><figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*ComponentTunnelRequest)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComp,</div><div class="line">    OMX_IN OMX_U32 nPort,</div><div class="line">    OMX_IN OMX_HANDLETYPE hTunneledComp,</div><div class="line">    OMX_IN OMX_U32 nTunneledPort,</div><div class="line">    OMX_INOUT OMX_TUNNELSETUPTYPE* pTunnelSetup);</div></pre></td></tr></table></figure></p>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComp</em> [输入]</td>
<td>调用RequestTunnel目标和参与管道的一个组件句柄。</td>
</tr>
<tr>
<td><em>nPort</em> [输入]</td>
<td>属于hComp，参与管道的端口索引</td>
</tr>
<tr>
<td><em>hTunneledComp</em> [输入]</td>
<td>管道中另一个组件的句柄。当这个参数为NULL，在nPort中指定端口应该设置为和IL客户端进行非管道通信。</td>
</tr>
<tr>
<td><em>nTunneledPort</em> [输入]</td>
<td>hTunneledComp，参与管道的端口索引</td>
</tr>
<tr>
<td><em>pTunnelSetup</em> [输入,输出]</td>
<td>这个结构包含了组件间管道通信的数据。提供者字段可以被两个组件填充，回调字段被输出端口的组件填充。只读标识可以被两个组件设置。</td>
</tr>
</tbody>
</table>
<p>####3.3.13.1  先决条件<br>组件应该处于OMX_StateLoaded状态。</p>
<p>####3.3.13.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* Translate a SetupTunnel call to two ComponentTunnelRequest calls */</span></div><div class="line">pCompOut = (OMX_COMPONENTTYPE *)hOutput;</div><div class="line">pCompIn = (OMX_COMPONENTTYPE *)hInput;</div><div class="line">pCompOut-&gt;ComponentTunnelRequest(hOutput, nPortOutput, hInput,</div><div class="line">    nPortInput, &amp;oTunnelSetup);</div><div class="line">pCompIn-&gt;ComponentTunnelRequest(hInput, nPortInput, hOutput,</div><div class="line">    nPortOutput, &amp;oTunnelSetup);</div></pre></td></tr></table></figure>
<p>###3.3.14  UseBuffer<br>IL客户端或一个管道组件通过<code>OMX_UseBuffer</code>宏来调用组件的<code>UseBuffer</code>方法。见小节3.2.2.14中<code>OMX_UseBuffer</code>的定义，描述了其语义。</p>
<p><code>UseBuffer</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*UseBuffer)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_INOUT OMX_BUFFERHEADERTYPE** ppBufferHdr,</div><div class="line">    OMX_IN OMX_U32 nPortIndex,</div><div class="line">    OMX_IN OMX_PTR pAppPrivate,</div><div class="line">    OMX_IN OMX_U32 nSizeBytes,</div><div class="line">    OMX_IN OMX_U8* pBuffer);</div></pre></td></tr></table></figure>
<p>###3.3.15  AllocateBuffer<br>IL客户端通过<code>OMX_AllocateBuffer</code>宏来调用组件的<code>AllocateBuffer</code>方法。见小节3.2.2.15中<code>OMX_AllocateBuffer</code>的定义，描述了其语义。</p>
<p><code>AllocateBuffer</code>定义如下：<br><figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*AllocateBuffer)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_INOUT OMX_BUFFERHEADERTYPE** pBuffer,</div><div class="line">    OMX_IN OMX_U32 nPortIndex,</div><div class="line">    OMX_IN OMX_PTR pAppPrivate,</div><div class="line">    OMX_IN OMX_U32 nSizeBytes);</div></pre></td></tr></table></figure></p>
<p>###3.3.16  FreeBuffer<br>IL客户端或一个管道组件通过<code>OMX_FreeBuffer</code>宏来调用组件的<code>FreeBuffer</code>方法。见小节3.2.2.16中<code>OMX_FreeBuffer</code>的定义，描述了其语义。</p>
<p><code>FreeBuffer</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*FreeBuffer)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_U32 nPortIndex,</div><div class="line">    OMX_IN OMX_BUFFERHEADERTYPE* pBuffer);</div></pre></td></tr></table></figure>
<p>###3.3.17  EmptyThisBuffer<br>IL客户端或一个管道组件通过<code>OMX_EmptyThisBuffer</code>宏来调用组件的<code>EmptyThisBuffer</code>方法。见小节3.2.2.17中<code>OMX_EmptyThisBuffer</code>的定义，描述了其语义。</p>
<p><code>EmptyThisBuffer</code>定义如下：<br><figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*EmptyThisBuffer)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_BUFFERHEADERTYPE* pBuffer);</div></pre></td></tr></table></figure></p>
<p>###3.3.18  FillThisBuffer<br>IL客户端或一个管道组件通过<code>OMX_FillThisBuffer</code>宏来调用组件的<code>FillThisBuffer</code>方法。见小节3.2.2.18中<code>OMX_FillThisBuffer</code>的定义，描述了其语义。</p>
<p><code>FillThisBuffer</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*FillThisBuffer)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_BUFFERHEADERTYPE* pBuffer);</div></pre></td></tr></table></figure>
<p>###3.3.19  SetCallbacks<br>SetCallbacks方法允许core从IL客户端到组件传递回调结构体。这是一个阻塞调用。组件应该在5毫秒内返回这个调用。</p>
<p><code>SetCallbacks</code>定义如下：<br><figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*SetCallbacks)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent,</div><div class="line">    OMX_IN OMX_CALLBACKTYPE* pCallbacks,</div><div class="line">    OMX_IN OMX_PTR pAppData);</div></pre></td></tr></table></figure></p>
<p>参数定义如下：</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
<tr>
<td><em>pCallbacks</em> [输入]</td>
<td>指向OMX_CALLBACKTYPE结构体的指针，用于给组件提供回调信息。</td>
</tr>
<tr>
<td><em>pAppData</em> [输入]</td>
<td>指向IL客户端定义的一个值的指针（例如，一个指针或一个数据结构体），允许IL客户端中的回调来确定回调的上下文</td>
</tr>
</tbody>
</table>
<p>####3.3.19.1  先决条件<br>组件应处于<code>OMX_StateLoaded</code>状态。</p>
<p>####3.3.19.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div><div class="line">5</div><div class="line">6</div><div class="line">7</div><div class="line">8</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* On GetHandle (for statically linked components):</span></div><div class="line">create component, initialize it, and set its callbacks */</div><div class="line">pComp = (OMX_COMPONENTTYPE *)<span class="built_in">malloc</span>(<span class="keyword">sizeof</span>(OMX_COMPONENTTYPE));</div><div class="line">hHandle = (OMX_HANDLETYPE)pComp;</div><div class="line">pComp-&gt;nVersion = version_1_0;</div><div class="line">pComp-&gt;nSize = <span class="keyword">sizeof</span>(OMX_COMPONENTTYPE);</div><div class="line">OMX_ComponentRegistered[i].pInitialize(hHandle);</div><div class="line">pComp-&gt;SetCallbacks(hHandle, pCallBacks, pAppData);</div></pre></td></tr></table></figure>
<p>###3.3.20  ComponentDeinit<br>当core希望处理掉组件时调用<code>ComponentDeinit</code>方法</p>
<p><code>ComponentDeinit</code>定义如下：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div></pre></td><td class="code"><pre><div class="line">OMX_ERRORTYPE (*ComponentDeInit)(</div><div class="line">    OMX_IN OMX_HANDLETYPE hComponent);</div></pre></td></tr></table></figure>
<p>唯一的参数如下。</p>
<table>
<thead>
<tr>
<th>参数</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td><em>hComponent</em> [输入]</td>
<td>执行调用的组件句柄</td>
</tr>
</tbody>
</table>
<p>这个方法没有先决条件。IL客户端可以不管组件的状态来执行这个方法，这样即使组件对状态变化已经不响应仍然可以保证释放。但是，正确关闭还是推荐当组件是OMX_StateLoaded状态时执行ComponentDeinit。</p>
<p>####3.3.20.2  调用顺序实例代码<br>下面的实例代码展示了调用顺序：</p>
<figure class="highlight c"><table><tr><td class="gutter"><pre><div class="line">1</div><div class="line">2</div><div class="line">3</div><div class="line">4</div></pre></td><td class="code"><pre><div class="line"><span class="comment">/* On FreeHandle: de-initialize component and destroy it */</span></div><div class="line">pComp = (OMX_COMPONENTTYPE*)hComponent;</div><div class="line">(pComp-&gt;ComponentDeInit)(hComponent);</div><div class="line">OMX_OSAL_Free(pComp);</div></pre></td></tr></table></figure>
<p>##3.4  调用顺序<br>本小节描述了IL客户端，OpenMAX core 和组件在一些有意义的用户场景下如何动态交互。分别为初始化，释放，数据流，数据管道建立，数据管道中的数据流，动态端口重配置。Core，组件和可能实现的资源管理器之间的交互也一并描述。</p>
<p>###3.4.1 初始化<br>本小节描述了初始化OpenMAX组件的操作。组件可以被IL客户端直接操作，可以相互建立管道，或两者兼而有之。管道和非管道清楚的被区分，但这两种情况可以在一个组件的框架中同时存在。</p>
<p>####3.4.1.1  非管道初始化<br>图 3-3 显示了IL客户端应该如何初始化一个OpenMAX组件。</p>
<p><img src="img/3_3.png" alt=""></p>
<p><strong>图 3-3. 组件初始化</strong></p>
<p>首先，IL客户端应该调用<code>OMX_GetHandle</code>函数，通过core激活真正的组件创建（1.1）。同样，组件所有配置的资源也应该加载到内存中。Core通过<code>SetCallbacks</code>方法（1.2）传递给IL客户端的回调函数给组件。如果上一部成功，一个有效的句柄在1.3步返回，组件会进入<code>OMX_StateLoaded</code>状态。</p>
<p>IL客户端应该配置组件和它的端口。为此，IL core应该调用<code>OMX_SetParameter</code>宏，如果需要的话，它可以多次调用（步骤1.4）。</p>
<p>当客户端完成了配置阶段，他可以请求组件切换状态至<code>OMX_StateIdle</code>。只有在这个请求之后，IL客户端才会为该组件的所有端口设置buffer。IL客户端应该使用<code>OMX_AllocateBuffer</code>或<code>OMX_UseBuffer</code>设置buffer。如果IL客户端要求组件建立管道，它不会分配buffer应该管道的组件分配其buffer。更多管道细节，见3.4.1.2小节。</p>
<p>这个过程可以重复多次，取决于端口数和每个端口所需的buffer数。如果使用OMX_UseBuffer， IL客户端应该分配一个buffer并传递给组件。此外，如果IL客户端可以请求组件调用<code>OMX_AllocateBuffer</code>方法来分配buffer和buffer头。在后一种情况下，组件应该分配buffer和相关的头并返回给IL客户端。</p>
<p>一旦这些初始化配置步骤完成，组件应该完成状态转换并返回一个SendCommand请求完成事件给客户端（步骤2.8）。</p>
<p>现在组件已准备完成，可以被IL客户端使用。</p>
<p>####3.4.1.2  管道初始化<br>为了避免数据buffer在IL客户端和OpenMAX组件之间来回传递，可以建立数据管道这样组件的输出buffer会直接传递给链中下一个组件的输入端口。</p>
<p>考虑如图3-4所示的例子，起重IL客户端生成数据给一个三个组件的管道，标识A，B，C。组件C是一个sink，不返回数据给IL客户端。</p>
<p><img src="img/3_4.png" alt=""></p>
<p><strong>图 3-4. OpenMAX组件之间数据管道的例子</strong></p>
<p>注意在使用专有或管道通信时，所有的回调永远指向IL客户端端并由其管理。管道的设置和初始化需要详细描述，基于下面的步骤：</p>
<ul>
<li>组件由<code>OMX_GetHandle</code>调用构建。</li>
<li>管道中的组件，第一个组件的输出和第二个组件的输入端口相连。应该在这个阶段决定提供buffer的端口</li>
<li>在<code>OMX_SetupTunnel</code>完成后，设置了输入端口的提供者之后，IL客户端可以覆盖输入端口对于buffer提供者的选择。这反过来又会重新改变输出端口的提供者。</li>
</ul>
<p>在<code>OMX_StateLoaded</code>向<code>OMX_StateIdle</code>改变的时候，每个组件在每个启用端口上的所需buffer没有被分配之前不应该转移。</p>
<p>仅当组件处于<code>OMX_StateLoaded</code>状态或端口被禁用时<code>OMX_SetupTunnel</code>可以被调用。图3-5描述了建立的过程：</p>
<p><img src="img/3_5.png" alt=""></p>
<p><strong>图 3-5. 管道建立</strong></p>
<p>当管道组件在<code>OMX_StateLoaded</code>状态时，IL客户端应该调用IL core的<code>OMX_SetupTunnel</code>函数启动数据设置过程（步骤1.0）。</p>
<p>作为结果，IL core应该顺序调用组件A和B的<code>ComponentTunnelRequest</code>方法。小节3.1.2.9中定义的结构体<code>OMX_TUNNELSETUPTYPE</code>应该由IL core传递首先传递给拥有输出端口的组件。组件收到这个的调用，应该填写这个结构体并返回给core。如果<code>ComponentTunnelRequest</code>调用返回成功，IL core应该在第二个组件上调用同样的函数（1.3），传递由第一个组件填充的结构体<code>OMX_TUNNELSETUPTYPE</code>。组件也应该检查peer组件上的输出端口是否和自己的输入端口兼容（例如，数据类型是否一致）（1.4）。如果第二个组件兼容管道设置参数，<code>ComponentTunnelRequest</code>调用应该将返回给第一个组件协商的结果（1.5）并返回成功（1.6）。IL core应该检查是否两次调用<code>ComponentTunnelRequest</code>均没有返回错误。如果是这样，最初的<code>OMX_SetupTunnel</code>将返回成功。</p>
<p>如果在组件B上调用<code>ComponentTunnelRequest</code>失败，组件A将被设置为非管道模式。会再一次调用<code>ComponentTunnelRequest</code>，这次组件B的句柄和参数<code>pTunnelSetup</code>设置为NULL</p>
<p>管道建立成功之后，如图3-6所示， IL客户端可以覆盖buffer提供者的协商。</p>
<p><img src="img/3_6.png" alt=""></p>
<p><strong>图 3-6. IL客户端覆盖buffer提供者</strong></p>
<p>如果IL客户端想覆盖管道组件之间的指定哪个组件为buffer提供者的协商，它应该在提供输入端口组件上调用SetParameter方法。这个组件负责通过同样的调用SetParameter来通知管道上另一个组件新的buffer提供者。</p>
<p>管道初始化阶段的最后一个步骤就是将状态由OMX_StateLoaded转到OMX_StateLoaded，并调用buffer分配。图3-7描述了管道已创建并配置时状态切换的行为。</p>
<p><img src="img/3_7.png" alt=""></p>
<p><strong>图3-7. 管道举例</strong></p>
<p>组件A通过管道连接组件B，组件B为buffer提供者。</p>
<p>组件B通过管道连接组件C，组件C为buffer提供者。</p>
<p>图3-8描述了在状态转换时每个管道上组件的行为。</p>
<p><img src="img/3_8.png" alt=""></p>
<p><strong>图 3-8. 管道组件时状态转换到idle</strong></p>
<p>每一个组件上的供应端口应该通过<code>OMX_UseBuffer</code>传递他的buffer给它管道另一端的非供应端口。所有的提供端口传递buffer之后，组件会等待所有非供应端口接收到通过<code>OMX_UseBuffer</code>传递过来的buffer。</p>
<p>在图3-8中，组件A接受到IL客户端的状态切换请求。组件A和组件B通过管道连接。B的输入端口是管道上的buffer提供者。在这种情况下，组件A应该等他的所有输出组件收到所学的buffer。</p>
<p>同时，IL客户端请求组件B改变他的状态。这种情况下，组件B有一个buffer提供端口，即输入端口，它应该在组件A的输出端口上调用<code>UseBuffer</code>。然后，组件B等待它输出端口上所有所需的buffer。</p>
<p>现在组件A有了所有所学的buffer，因此他可以开始执行到<code>OMX_StateIdle</code>状态的切换。转换的确切顺序可以是不同的，因为它依赖平台，操作系统和具体实现。唯一的规则是等到所有的资源可用。</p>
<p>IL客户端请求组件C切换状态。组件C的行为和B一样：组件C把所有所学的buffer给组件B，然后可以切换他的状态，因为他不需要其他任何的buffer。</p>
<p>最后，组件B可以切换状态到<code>OMX_StateIdle</code>因为它已获得所有所学的buffer。</p>
<p>###3.4.2 数据流<br>OpenMAX定义了数据通信的两种方法：</p>
<ul>
<li>管道通信，端口直接和另一个组件上的端口交换数据。</li>
<li>非管道通信，端口仅和IL客户端交换数据。</li>
</ul>
<p>端口可以通过专有通信来实现数据管道，可以利用平台特定的功能。下面消极描述了每种通信方式所固有的数据流程。</p>
<p>####3.4.2.1  非管道数据流<br>一个需要传递数据buffer给输入端口的IL客户端应该调用<code>OMX_EmptyThisBuffer</code>。</p>
<p>相反，对于组件的输出端口，IL客户端应首选给可写入输出数据的组件提供一个或多个空buffer，调用<code>OMX_FillThisBuffer</code>可以完成这个任务。但一个buffer在组件输出端口上可用是，组件应该发送<code>OMX_FillBufferDone</code>回调。之前调用SetBacks可以让组件知道回调函数的入口。</p>
<p>注意，如果不适用数据管道，IL客户端完全负责组件间的数据buffer移动。</p>
<p>图3-9描绘了数据流相关的动态行为。</p>
<p><img src="img/3_9.png" alt=""></p>
<p><strong>图 3-9. 非管道组件之间的数据流</strong></p>
<p>####3.4.2.2  管道数据流<br>在数据管道中，OpenMAX组件之间直接传递数据buffer而不是返回给IL客户端。此数据流使用的约定和所有buffer和IL客户端交换的情况不同。</p>
<p>如果buffer提供者是输出组件，它应该在管道上的另外的管道调用<code>OMX_EmptyThisBuffer</code>传递待清空的buffer。当输入组件结束这个操作，它应该通过调用<code>OMX_FillThisBuffer</code>返回buffer给输出组件。</p>
<p>如果buffer提供者是输入组件，通信机制是一样的，但是由在输出组件上调用<code>OMX_FillThisBuffer</code>发起的，图3-10描述了这一过程。</p>
<p><img src="img/3_10.png" alt=""></p>
<p><strong>图 3-10. 管道组件之间的数据流</strong></p>
<p>####3.4.2.3  专有通信<br>在一些平台上，组件之间数据管道可以通过专有通信机制进行优化，它可以基于一些特定的硬件例如DMA或共享内存。在标准数据管道设置阶段，这些自检以专有的方式进行设置。虽然IL客户端使用标准的<code>OMX_SetupTunnel</code>调用，平台特定的优化可以优化组件之间的传递通道。</p>
<p>假设一个链组件A，B，C支持专有通信，数据流如图3-11所示。</p>
<p><img src="img/3_11.png" alt=""></p>
<p><strong>图 3-11. 组件之间专有通信的数据流</strong></p>
<p>假设所有组件处于<code>OMX_StateExecuting</code>状态，IL客户端调用<code>OMX_EmptyThisBuffer</code>发送两个buffer给组件A（步骤1.0和1.1）。给定数据管道设置，组件A的输出被发送到组件B的输入端口。组件B的输出被发送到组件C的输入端口，这是接收器。</p>
<p>没有回调会被调用，因为组件使用他们的专有机制类转移数据。</p>
<p>组件A完成处理buffer后，仅发送<code>OMX_EmptyBufferDone</code>回调给IL客户端。</p>
<p>尽管在这种情况下不使用buffer相关的回调，注意组件可能仍然使用<code>OMX_EventHandler</code>的回调入口产生事件给IL客户端。</p>
<p>###3.4.3 反初始化<br>本节介绍了管道和非管道组件的反初始化。</p>
<p>####3.4.3.1  非管道的反初始化<br>当IL客户端决定停止执行和处理组件，它应该首先切换组件到<code>OMX_StateIdle</code>，这样所有的buffer会回到他们的提供者。</p>
<p>当切换到<code>OMX_StateIdle</code>完成后，IL客户端可以请求组件切换到<code>OMX_StateLoaded</code>组件。IL客户端应该通过调用<code>OMX_FreeBuffer</code>释放所有组件的buffer。<code>OMX_FreeBuffer</code>方法需要组件从指定的端口删除指定的buffer。如果组件通过调用<code>OMX_AllocateBuffer</code>分配buffer，组件也应该释放buffer内存。如果IL客户端分配内存并通过<code>OMX_UseBuffer</code>调用分配给组件，IL客户但应该在调用<code>OMX_FreeBuffer</code>后释放buffer内存。</p>
<p>当所有的buffer被释放后，组件将完成状态转换。最后，IL客户端调用<code>OMX_FreeHandle</code>函数来处理组件。</p>
<p>每一个非管道端口都会执行此程序。图3-12描述了非管道的反初始化。</p>
<p><img src="img/3_12.png" alt=""></p>
<p><strong>图 3-12. 非管道组件的反初始化</strong></p>
<p>管道端口应该遵守组件反初始化程序，如3.4.3.2小节所述。</p>
<p>####3.4.3.2  管道反初始化<br>图3-13描述了组件上管道端口的反初始化</p>
<p><img src="img/3_13.png" alt=""></p>
<p><strong>图 3-13. 管道组件的反初始化</strong></p>
<p>###3.4.4 端口禁用和启用<br>禁用端口会导致其行为和组件转移到OMX_StateLoaded一样。因此，所有端口的buffer会回到提供者，被禁端口上分配的所有buffer被释放。启用端口和这个过程相反，putting a port that is effectively in the OMX_StateLoaded state into the component’s state.因此，如果组件在端口有buffer的状态时，启用端口会获得buffer。同理，如果组件正在交换buffer，启用端口将开始交换buffer。</p>
<p>注意，如果组件在OMX_StateLoaded状态时禁用端口，端口有效状态仍然和组件状态分离。因此，当组件从OMX_StateLoaded转移至OMX_StateIdle，任何禁用端口不会获得buffer，而是相反，保留在OMX_StateLoaded状态。端口禁用和启用的描述可分为管道和非管道两种情况。</p>
<p>####3.4.4.1  管道端口禁用和启用<br>图3-14描述了管道端口的禁用和启用的行为。</p>
<p><img src="img/3_14.png" alt=""></p>
<p><strong>图 3-14. 管道端口的禁用和启用</strong></p>
<p>####3.4.4.2  非管道端口禁用和启用<br>图3-15描述了非管道端口的禁用和启用程序。具体关于OMX_AllocateBuffer, OMX_UseBuffer, and OMX_FreeBuffer的讨论这里省略。关于这些函数更多细节描述可分别见3.3.15, 3.3.14, 和3.3.16小节,</p>
<p><img src="img/3_15.png" alt=""></p>
<p><strong>图 3-15. 非管道端口禁用和启用</strong></p>
<p>###3.4.5 端口动态重配置<br>本小节描述一个组件如果动态的改变端口的设置。</p>
<p>下面的例子展示了通常需要此功能的地方：</p>
<ul>
<li>一个视频解码器解析了一个序列头并发现了输出图像的帧大小，因此其输出端口相关的buffer应该被重新安排。</li>
<li>音频流的参数动态变化，解码器应该更改其端口设置。</li>
</ul>
<p>图3-16展示了一个视频解码器和视频渲染器，两者都和IL客户端交换数据，可以动态的改变他们的端口设置。</p>
<p><img src="img/3_16.png" alt=""></p>
<p><strong>Figure 3-16. 端口动态重配置</strong></p>
<p>一开始IL客户端将视频解码器和渲染器都至于OMX_StateExecuting状态（1.0到1.3）。在这个阶段，视频解码器的输出端口和渲染器的输入端口没有配置，因为视频帧的尺寸未知。解码器需要开始解析输入bit流来获得这些信息。</p>
<p>事实上，IL客户端在步骤1.4中发送第一个buffer给解码器。假设第一块buffer中包含了视频序列头，OpenMAX解码组件会解析并改变相应的端口设置。然后OpenMAX解码组件应该产生OMX_PortSettingsChanged事件通知IL客户端（步骤1.5）。一旦IL客户端收到这个回调，他应该禁用视频解码器的的输出端口和渲染器的输入端口（步骤1.6到1.11）。</p>
<p>然后IL客户端用OMX_GetConfig读取新的端口设置并为输出端口用正确的尺寸分配一个或多个buffer。一旦buffer被分配，他也会使用OMX_UseBuffer和视频渲染器通信（1.17）。视频渲染器的输入端口应该也用OMX_SetConfig进行设置（1.18）。</p>
<p>最后，端口可以被启用，正常的处理可以继续。</p>
<p>###3.4.6 资源管理器<br>本小节买哦数了资源管理器的入口。组件和资源管理器的接口仅用一个实例展示。只有IL客户端可组件之间的接口是OpenMAX标准定义的一部分。IL客户端可以使用资源管理器的入口。</p>
<p>图3-17提出了IL客户端忽略资源管理器的行为。资源管理器只处理内部组件，且Il客户端没有采取任何特殊动作。</p>
<p><img src="img/3_17.png" alt=""></p>
<p><strong>图 3-17. 有资源管理器的情况下loaded到idle的状态转换</strong></p>
<p>在图3-17，IL客户端不知道资源管理器的存在。在OpenMAX组件的实现中，有一个对资源管理器的异步调用。</p>
<p>OpenMAX组件提供了一个回调函数给资源管理器，将收到请求完成的信号。</p>
<p>图3-17展示了资源管理器的一种可能的实现，并且显示了他是如何对客户端透明的。函数AcquireResourceRequest和AcquireResourceResponse是例子。本规范只关心IL客户端可组件之间的接口。组件和厂商/特定管理器之间的交互的详细信息超出本规范的范围。</p>
<p>图3-18提出一个更负责的用例。</p>
<p><img src="img/3_18.png" alt=""></p>
<p><strong>图 3-18. 繁忙的资源管理</strong></p>
<p>在图3-18中，两个不同的OpenMAX组件，A和B，需要同一个资源来工作。他们有不同的优先级。这里，与前面的示例一样，IL客户端使用从loaded到idle的标准切换来设置组件并分配所需的所有资源。</p>
<p>第一个组件A，拥有资源的所有权，从资源管理器获得。组件A切换到idle状态并且准备执行。</p>
<p>第二个组件B，要求相同的资源，但在这种情况下资源管理器拒绝它应为一个更高优先级的组件A有该资源。这个事件会发送给IL客户端，包含了OMX_ErrorInsufficientResources值的错误。如果IL客户端Y决定需要当资源再次可用时收到消息，他可以直接让组件B切换到状态OMX_StateWaitForResources。这个操作将组件B置于等待队列中，知道资源x变得可用。或者，IL客户端Y可以请求组件B切换到loaded状态。</p>
<p>图3-18也显示了资源X变得可用时组件的行为。组件A改变状态到loaded并释放所有资源。资源管理器知道资源可用并调用已在等待队列的组件B。</p>
<p>当资源管理器提供了组件所等待的所有资源时，组件通过OMX_EventResourcesAcquired事件通知IL客户端所有资源已获得。IL客户端应该提供组件所有需要的buffer，组件可以改变自己的状态到OMX_StateIdle并通知客户端状态改变。该等待队列是状态自动改变的唯一例子。</p>
<p>在图3-18中，组件A和B的优先级不是在IL层进行比较的，并且没有实现或提出抢占机制。应该和资源管理器通信的外部策略管理器应该负有这个责任。关于这个策略管理器的描述超出了本文和OpenMAX标准的讨论范围。</p>
<p>图3-19展示了一个例子，客户端主动使用资源管理器API。</p>
<p><img src="img/3_19.png" alt=""></p>
<p><strong>图 3-19. 从Loaded到WaitForResources的状态切换</strong></p>
<p>当IL客户端希望在资源再次可用时收到通知，它可以请求状态由OMX_StateLoaded切换到OMX_StateWaitForResources。OMX_StateWaitForResources的解释可以看3.1.1.2.5小节。</p>
<p>在这种情况下，客户端将组件放入等待队列，有资源管理器处理。当资源可以或立即可用时，会有效的进行到idle状态的切换。在任何情况下，客户端收到两个不同的OMX_EventHandler回调对应两个不同的状态切换。</p>
<p>WaitForResourceRequest和WaitForResourceResponse两个函数如图3-19所示，不再本协议中定义，但为组件和资源管理器交互的例子。</p>
<p>IL客户端可以决定在一个特定的时间停止等待。在这种情况下，它应该请求组件切换回loaded状态，如图3-20所示。</p>
<p><img src="img/3_20.png" alt=""><br><strong>图 3-20. 从等待状态中移除组件</strong>        </p>
]]></content>
    
    <summary type="html">
    
      &lt;p&gt;#3 OpenMAX IL控制API&lt;br&gt;OpenMAX IL API允许IL客户端控制音频、视频、图像领域上的组件。“其他”领域还包括额外的一些功能，例如音视频同步。OpenMAX IL API的使用者往往是一个多媒体框架。在本文档的其他部分，OpenMAX IL AP
    
    </summary>
    
    
  </entry>
  
  <entry>
    <title></title>
    <link href="http://yoursite.com/2017/03/31/chapter1/"/>
    <id>http://yoursite.com/2017/03/31/chapter1/</id>
    <published>2017-03-31T03:00:43.043Z</published>
    <updated>2017-03-31T02:59:52.669Z</updated>
    
    <content type="html"><![CDATA[<h1 id="概述"><a href="#概述" class="headerlink" title="概述"></a>概述</h1><h2 id="1-1-介绍"><a href="#1-1-介绍" class="headerlink" title="1.1  介绍"></a>1.1  介绍</h2><p>本文档详细介绍了OpenMAX集成层（IL）的API。由Khronos Group提出， 用于音视频以及图像编解码在嵌入式/移动设备上的底层接口的开放标准。主要目标是将编解码器进行系统抽象，使之适配与各种操作系统和软件平台。</p>
<h3 id="1-1-1-关于Khronos-Group"><a href="#1-1-1-关于Khronos-Group" class="headerlink" title="1.1.1 关于Khronos Group"></a>1.1.1 关于Khronos Group</h3><p>The Khronos Group is a member-funded industry consortium focused on the creation of open standard APIs to enable the authoring and playback of dynamic media on a wide variety of platforms and devices. All Khronos members may contribute to the development of Khronos API specifications, may vote at various stages before public deployment, and may accelerate the delivery of their multimedia platforms and applications through early access to specification drafts and conformance tests. The Khronos Group is responsible for open APIs such as OpenGL ES, OpenML, and OpenVG.</p>
<p>Khronos Group是一个行业联盟成员资助重点的API使创作，在多种平台和设备的动态媒体播放开放标准的建立。所有Khronos成员可能有助于Khronos API规范的发展，可能会投票前公共部署的各个阶段，并可以通过早期访问规范的草稿和一致性测试加速多媒体平台和应用的交付。Khronos Group负责如OpenGL ES API开放，开放多媒体程序库，和OpenVG。</p>
<h3 id="1-1-2-OpenMAX简史"><a href="#1-1-2-OpenMAX简史" class="headerlink" title="1.1.2 OpenMAX简史"></a>1.1.2 OpenMAX简史</h3><p>The OpenMAX set of APIs was originally conceived as a method of enabling portability of codecs and media applications throughout the mobile device landscape. Brought into the Khronos Group in mid-2004 by a handful of key mobile hardware companies, OpenMAX has gained the contributions of companies and institutions stretching the breadth of the multimedia field. As such, OpenMAX stands to unify the industry in taking steps toward media codec portability. Stepping beyond mobile platforms, the general nature of the OpenMAX IL API makes it applicable to all media platforms.</p>
<p>API集的OpenMAX原先是一种使编解码器和媒体在移动设备应用程序的可移植性景观的方法。进入Khronos集团在2004年由少数关键的移动硬件公司，OpenMAX取得贡献的公司和机构延伸的多媒体领域的广度。因此，OpenMAX站统一采取措施向媒体编解码器的可移植性的行业。跨越移动平台，对OpenMAX IL的一般性质的API使得它适用于所有媒体平台。</p>
<p>##1.2  OpenMAX集成层<br>The OpenMAX IL API strives to give media codecs portability across an array of platforms. The interface abstracts the hardware and software architecture in the system. Each codec and relevant transform is encapsulated in a component interface. The OpenMAX IL API allows the user to load, control, connect, and unload the individual components. This flexible core architecture allows the Integration Layer to easily implement almost any media use case and mesh with existing graph-based media frameworks.</p>
<p>OpenMAX IL的API力求给媒体编解码器在一系列的平台的可移植性。接口抽象了系统的硬件和软件体系结构。每个编解码器和相关的变换封装在一个组件接口。OpenMAX IL的API允许用户负荷，控制，连接，和卸载单独的组件。这种灵活的核心架构允许集成层轻松地实现几乎所有的媒体使用情况和网格与现有的基于图形的媒体框架。</p>
<p>###1.2.1 主要特性和优点<br>The OpenMAX IL API gives applications and media frameworks the ability to interface with multimedia codecs and supporting components (i.e., sources and sinks) in a unified manner. The codecs themselves may be any combination of hardware or software and are completely transparent to the user. Without a standardized interface of this nature, codec vendors must write to proprietary or closed interfaces to integrate into mobile devices. In this case, the portability of the codec is minimal at best, costing many development-years of effort in re-tooling these solutions between systems. Thus, the IL incorporates a specialized arsenal of features, honed to combat the problem of portability among many vastly different media systems. Such features include:</p>
<p>OpenMAX IL的API为应用程序和多媒体框架的能力和多媒体编解码器的接口和支持组件（即，源和汇）在一个统一的方式。可能是自己的编解码器的硬件或软件的任意组合，对用户是完全透明的。如果没有这种标准化的接口，编解码器的厂商必须写入专有或封闭的接口，以整合到移动设备。在这种情况下，可编解码器的可移植性是最小的，成本的许多发展多年的努力，在重新设计这些解决方案之间的系统。因此，IL将专业阿森纳的特点，磨练战斗的便携性问题的许多不同的媒体系统之间。这些特点包括：</p>
<ul>
<li>灵活的基于组件的API Core</li>
<li>可以轻松添加新的编解码器</li>
<li>Coverage of targeted domains (audio, video, and imaging) while remaining easily extensible by both the Khronos Group and individual vendors目标域（音频，视频，覆盖范围和成像）而其余的易扩展由Khronos集团和个体商贩</li>
<li>Capable of being implemented as either static or dynamic libraries能够被实现为静态或动态库</li>
<li>Retention of key features and configuration options needed by parent software (such as media frameworks)保留关键特征与配置选项needed by父母软件（such as媒体框架）</li>
<li>Ease of communication between the client and the codecs and between codecs themselves在客户端与编解码器和之间的通信编解码器之间自己缓解</li>
</ul>
<h3 id="1-2-2-设计理念"><a href="#1-2-2-设计理念" class="headerlink" title="1.2.2 设计理念"></a>1.2.2 设计理念</h3><p>As previously stated, the key focus of the OpenMAX IL API is portability of media codecs. The diversity of existing devices and media implementation solutions necessitates that the OpenMAX IL target the higher level of the media software stack as<br>the key initial user. For most operating systems, this means an existing media framework. Thus, much of the OpenMAX IL API is defined by requirements generated by the needs of media frameworks. Similarly, the IL is designed to allow the media framework layer to be as lightweight as possible. The result is an interface that is easily pluggable into most software stacks across operating system and framework boundaries. Likewise, several features of media frameworks were perceived to be handled at higher levels and not included in the API. Among these is the issue of file handling, which, if desired, may<br>be easily added to the IL structure outside of the standard. The design of the API also strove to accommodate as many system architectures as possible. The resulting design uses highly asynchronous communications, which allows processing to take place in another thread, on multiple processing elements, or on specialized hardware. In addition, the ability of hardware-accelerated codecs to communicate directly with one another via tunneling affords implementation architectures even greater flexibility and efficiency.</p>
<p>如前所述，对OpenMAX IL的重点API是媒体编解码器的可移植性。多样性的现有设备和媒体解决方案必须实现OpenMAX IL的目标媒体软件栈的较高水平<br>关键初始用户。对于大多数操作系统，这意味着现有的媒体框架。因此，大部分的OpenMAX IL的API是由媒体框架的需求而产生的需求定义。同样，IL的设计允许媒体框架层尽可能轻。其结果是一个接口，容易嵌入到大多数软件栈跨操作系统和框架的边界。同样，媒体框架的几个功能被认为是在更高的水平，而不是在API中处理。其中之一是文件处理的问题，如果需要，可以<br>容易添加到IL以外的标准结构。API的设计也力求尽可能容纳尽可能多的系统架构。由此产生的设计采用高度异步通信，它允许处理发生在另一个线程，在多个处理元素，或在专门的硬件。此外，硬件加速解码能力与另一个直接通过隧道提供了更大的灵活性和效率，实现结构。</p>
<p>###1.2.3 软件的景观<br>In most systems, a user-level media framework already exists. The OpenMAX IL API is designed to easily fit below these frameworks with little to no overhead between the interfaces. In most cases, the media framework provided by the operating system can be replaced with a thin layer that simply translates the API. Figure 1-1 illustrates the software landscape for the OpenMAX IL API.</p>
<p>在大多数系统中，用户级媒体框架已经存在。OpenMAX IL的API的设计非常适合在这些框架几乎没有开销之间的接口。在大多数情况下，操作系统提供的媒体框架可以用一个简单的API层来替换。图1-1显示了OpenMAX IL的API软件景观。</p>
<p><img src="img/1_1.png" alt=""></p>
<p><strong>Figure 1-1. OpenMAX IL API Software Landscape</strong></p>
<p>To remove possible reader confusion, the OpenMAX standard also defines a set of Development Layer (DL) primitives on which codecs can be built. The DL primitives and their full relationship to the IL are specified in other OpenMAX specification<br>documents.</p>
<p>为了消除可能的读者混淆，OpenMAX标准还定义了一套开发层（DL）原语，编解码器可建。DL元素及其对IL完全的关系在其他OpenMAX规范规定<br>文件.</p>
<p>###1.2.4 利益相关者<br>A few categories of stakeholders represent the broad array of companies participating in the production of multimedia solutions, each with their own interest in the IL API.</p>
<p>一些类别的利益相关者代表了广泛的参与多媒体解决方案的生产企业，每个都有自己的兴趣在IL的API。</p>
<p>####1.2.4.1  芯片厂商<br>Silicon vendors (SV) are responsible for delivering a representative set of OpenMAX IL components that are specific to the vendor’s platform. The vendors are anticipated to also supply components that are representative of the capabilities of their platforms.</p>
<p>芯片厂商（SV）负责提供一组有代表性的OpenMAX IL成分是特定于供应商的平台。预计供应商还将提供代表其平台能力的组件。</p>
<p>####1.2.4.2  独立软件供应商<br>Independent software vendors (ISV) are anticipated to deliver additional differentiated OpenMAX IL components that may or may not be specific to a given silicon vendor’s platform.</p>
<p>独立软件供应商（ISV）预计将提供额外的分化OpenMAX IL的组件，可能会或可能不会具体到一个给定的硅供应商的平台。</p>
<p>####1.2.4.3  操作系统厂商<br>Operating System Vendors (OSV) are anticipated to deliver software multimedia framework and standard reference OpenMAX IL components that enable integration of the representative silicon vendor’s components and ISV components. The OSV is responsible for conformance testing of the standard reference OpenMAX components.</p>
<p>操作系统厂商（OSV）预计交付软件的多媒体框架和标准OpenMAX IL组件，使代表硅供应商的组件和软件组件的集成。OSV负责标准参考OpenMAX组件一致性测试。</p>
<p>####1.2.4.4  原始设备制造商<br>Original Equipment Manufacturers (OEM) are anticipated to modify and optimize the integration of OpenMAX components provided by SVs, ISVs, and OSVs to their specific product architectures to enable delivery of OpenMAX integrated multimedia devices. OEMs may also develop and integrate their own proprietary OpenMAX components.</p>
<p>原始设备制造商（OEM）预计修改和OpenMAX成分的SVS，ISV提供的优化整合，以其独特的产品架构和OSVs使OpenMAX集成多媒体设备交货。OEM可以开发和整合自己的专有OpenMAX组件。</p>
<p>###1.2.5 接口<br>The OpenMAX IL API is a component-based media API that consists of two main segments: the core API and the component API.</p>
<p>OpenMAX IL的API是一个基于组件的多媒体API，主要分为两部分：核心接口(core API)和组件接口(componet API)。</p>
<p>####1.2.5.1  核心<br>The OpenMAX IL core is used for dynamically loading and unloading components and for facilitating component communication. Once loaded, the API allows the user to communicate directly with the component, which eliminates any overhead for high commands. Similarly, the core allows a user to establish a communication tunnel between two components. Once established, the core API is no longer used and communications flow directly between components.</p>
<p>OpenMAX IL的核心是用于动态加载和卸载的组件和组件之间通信的便利。一旦加载，API允许用户直接与组件进行通信，从而消除了高命令的任何开销。同样，核心允许用户在两个组件之间建立通信通道。一旦建立，核心API不再使用和通信流组件之间的直接。</p>
<p>####1.2.5.2  组件<br>In the OpenMAX Integration Layer, components represent individual blocks of functionality. Components can be sources, sinks, codecs, filters, splitters, mixers, or any other data operator. Depending on the implementation, a component could possibly represent a piece of hardware, a software codec, another processor, or a combination thereof.</p>
<p>在OpenMAX集成层、组件代表独立的功能块。组件可以是源、汇、编解码器、滤波器、功分器、混频器、或任何其他数据操作。根据实现，一个组件可能代表一个硬件，一个软件编解码器，另一个处理器，或其组合。</p>
<p>The individual parameters of a component can be set or retrieved through a set of associated data structures, enumerations, and interfaces. The parameters include data relevant to the component’s operation (i.e., codec options) or the actual execution state of the component.</p>
<p>Buffer status, errors, and other time-sensitive data are relayed to the application via a set of callback functions. These are set via the normal parameter facilities and allow the API to expose more of the asynchronous nature of system architectures.</p>
<p>一个组件的各个参数可以设置或检索，通过一组相关的数据结构和接口，枚举。参数包括与组件操作相关的数据（即编解码器选项）或组件的实际执行状态。</p>
<p>Data communication to and from a component is conducted through interfaces called ports. Ports represent both the connection for components to the data stream and the buffers needed to maintain the connection. Users may send data to components through input ports or receive data through output ports. Similarly, a communication tunnel between two components can be established by connecting the output port of one component to a similarly formatted input port of another component.</p>
<p>数据通信和从一个组件是通过接口称为端口。端口代表组件与数据流的连接以及维护连接所需的缓冲区。用户可以通过输入端口发送数据到组件，或者通过输出端口接收数据。类似地，通过将一个组件的输出端口连接到另一个组件的类似格式化的输入端口，可以建立两个组件之间的通信通道。</p>
<p>##1.3  Definitions<br>When this specification discusses requirements and features of the OpenMAX IL API, specific words are used to convey their necessity in an implementation. Table 1-1 shows a list of these words.</p>
<p>当这个规范讨论要求和OpenMAX IL的功能API，具体的词来表达他们的需要的实现。表1-1列出了这些话。</p>
<table>
<thead>
<tr>
<th>Word</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<td>May</td>
<td>The stated functionality is an optional requirement for an implementation of the OpenMAX IL API. Optional features are not required by the specification but may have conformance requirements if they are implemented. This is an optional feature as in “The component may have vendor specific extensions.”</td>
</tr>
<tr>
<td>Shall</td>
<td>The stated functionality is a requirement for an implementation of the OpenMAX IL API. If a component fails to meet a shall statement, it is not considered to conform to this specification. Shall is always used as a requirement, as in “The component designers shall produce good documentation.”</td>
</tr>
<tr>
<td>Should</td>
<td>The stated functionality is not a requirement for an implementation of the OpenMAX IL API but is recommended or is a good practice. Should is usually used as follows: “The component should begin processing buffers immediately after it transitions to the OMX_StateExecuting state.” While this is good practice, there may be a valid reason to delay processing buffers, such as not having input data available.</td>
</tr>
<tr>
<td>Will</td>
<td>The stated functionality is not a requirement for an implementation of the OpenMAX IL API. Will is usually used when referring to a third party, as in “the application framework will correctly handle errors.”</td>
</tr>
</tbody>
</table>
<p><strong>Table 1-1. Definitions of Commonly Used Words</strong></p>
<p>##1.4  作者<br>The following individuals, listed alphabetically by company, contributed to the OpenMAX Integration Layer Application Programming Interface Specification.</p>
<p>OpenMAX IL API协议由下列人员按公司字母表排列顺序完成。</p>
<ul>
<li>Gordon Grigor (ATI)</li>
<li>Andrew Rostaing (Beatnik)</li>
<li>Chris Grigg (Beatnik)</li>
<li>Russell Tillitt (Beatnik)</li>
<li>Roger Nixon (Broadcom)</li>
<li>Brian Murray (Freescale)</li>
<li>Norbert Schwagmann (Infineon)</li>
<li>Mark Kokes (Nokia)</li>
<li>Samu Kaajas (Nokia)</li>
<li>Yeshwant Muthusamy (Nokia)</li>
<li>Jim Van Welzen (NVIDIA)</li>
<li>David Siorpaes (STMicroelectronics)</li>
<li>Diego Melpignano (STMicroelectronics)</li>
<li>Giulio Urlini (STMicroelectronics)</li>
<li>Kevin Butchart (Symbian)</li>
<li>Viviana Dudau (Symbian)</li>
<li>David Newman (Texas Instruments)</li>
<li>Leo Estevez (Texas Instruments)</li>
<li>Richard Baker (Texas Instruments)</li>
</ul>
]]></content>
    
    <summary type="html">
    
      &lt;h1 id=&quot;概述&quot;&gt;&lt;a href=&quot;#概述&quot; class=&quot;headerlink&quot; title=&quot;概述&quot;&gt;&lt;/a&gt;概述&lt;/h1&gt;&lt;h2 id=&quot;1-1-介绍&quot;&gt;&lt;a href=&quot;#1-1-介绍&quot; class=&quot;headerlink&quot; title=&quot;1.1  介绍&quot;&gt;&lt;/a&gt;
    
    </summary>
    
    
  </entry>
  
</feed>