• Home
  • History
  • Annotate
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1  /*
2   * Copyright (C) 2009 The Android Open Source Project
3   *
4   * Licensed under the Apache License, Version 2.0 (the "License");
5   * you may not use this file except in compliance with the License.
6   * You may obtain a copy of the License at
7   *
8   *      http://www.apache.org/licenses/LICENSE-2.0
9   *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  #ifndef HARDWARE_API_H_
18  
19  #define HARDWARE_API_H_
20  
21  #include <media/hardware/OMXPluginBase.h>
22  #include <media/hardware/MetadataBufferType.h>
23  #include <system/window.h>
24  #include <utils/RefBase.h>
25  
26  #include <OMX_Component.h>
27  
28  namespace android {
29  
30  // A pointer to this struct is passed to the OMX_SetParameter when the extension
31  // index for the 'OMX.google.android.index.enableAndroidNativeBuffers' extension
32  // is given.
33  //
34  // When Android native buffer use is disabled for a port (the default state),
35  // the OMX node should operate as normal, and expect UseBuffer calls to set its
36  // buffers.  This is the mode that will be used when CPU access to the buffer is
37  // required.
38  //
39  // When Android native buffer use has been enabled for a given port, the video
40  // color format for the port is to be interpreted as an Android pixel format
41  // rather than an OMX color format.  Enabling Android native buffers may also
42  // change how the component receives the native buffers.  If store-metadata-mode
43  // is enabled on the port, the component will receive the buffers as specified
44  // in the section below. Otherwise, unless the node supports the
45  // 'OMX.google.android.index.useAndroidNativeBuffer2' extension, it should
46  // expect to receive UseAndroidNativeBuffer calls (via OMX_SetParameter) rather
47  // than UseBuffer calls for that port.
48  struct EnableAndroidNativeBuffersParams {
49      OMX_U32 nSize;
50      OMX_VERSIONTYPE nVersion;
51      OMX_U32 nPortIndex;
52      OMX_BOOL enable;
53  };
54  
55  // A pointer to this struct is passed to OMX_SetParameter() when the extension
56  // index "OMX.google.android.index.storeMetaDataInBuffers"
57  // is given.
58  //
59  // When meta data is stored in the video buffers passed between OMX clients
60  // and OMX components, interpretation of the buffer data is up to the
61  // buffer receiver, and the data may or may not be the actual video data, but
62  // some information helpful for the receiver to locate the actual data.
63  // The buffer receiver thus needs to know how to interpret what is stored
64  // in these buffers, with mechanisms pre-determined externally. How to
65  // interpret the meta data is outside of the scope of this method.
66  //
67  // Currently, this is specifically used to pass meta data from video source
68  // (camera component, for instance) to video encoder to avoid memcpying of
69  // input video frame data. To do this, bStoreMetaData is set to OMX_TRUE.
70  // If bStoreMetaData is set to false, real YUV frame data will be stored
71  // in the buffers. In addition, if no OMX_SetParameter() call is made
72  // with the corresponding extension index, real YUV data is stored
73  // in the buffers.
74  //
75  // For video decoder output port, the metadata buffer layout is defined below.
76  //
77  // Metadata buffers are registered with the component using UseBuffer calls.
78  struct StoreMetaDataInBuffersParams {
79      OMX_U32 nSize;
80      OMX_VERSIONTYPE nVersion;
81      OMX_U32 nPortIndex;
82      OMX_BOOL bStoreMetaData;
83  };
84  
85  // Meta data buffer layout used to transport output frames to the decoder for
86  // dynamic buffer handling.
87  struct VideoDecoderOutputMetaData {
88    MetadataBufferType eType;
89    buffer_handle_t pHandle;
90  };
91  
92  // A pointer to this struct is passed to OMX_SetParameter() when the extension
93  // index "OMX.google.android.index.prepareForAdaptivePlayback" is given.
94  //
95  // This method is used to signal a video decoder, that the user has requested
96  // seamless resolution change support (if bEnable is set to OMX_TRUE).
97  // nMaxFrameWidth and nMaxFrameHeight are the dimensions of the largest
98  // anticipated frames in the video.  If bEnable is OMX_FALSE, no resolution
99  // change is expected, and the nMaxFrameWidth/Height fields are unused.
100  //
101  // If the decoder supports dynamic output buffers, it may ignore this
102  // request.  Otherwise, it shall request resources in such a way so that it
103  // avoids full port-reconfiguration (due to output port-definition change)
104  // during resolution changes.
105  //
106  // DO NOT USE THIS STRUCTURE AS IT WILL BE REMOVED.  INSTEAD, IMPLEMENT
107  // METADATA SUPPORT FOR VIDEO DECODERS.
108  struct PrepareForAdaptivePlaybackParams {
109      OMX_U32 nSize;
110      OMX_VERSIONTYPE nVersion;
111      OMX_U32 nPortIndex;
112      OMX_BOOL bEnable;
113      OMX_U32 nMaxFrameWidth;
114      OMX_U32 nMaxFrameHeight;
115  };
116  
117  // A pointer to this struct is passed to OMX_SetParameter when the extension
118  // index for the 'OMX.google.android.index.useAndroidNativeBuffer' extension is
119  // given.  This call will only be performed if a prior call was made with the
120  // 'OMX.google.android.index.enableAndroidNativeBuffers' extension index,
121  // enabling use of Android native buffers.
122  struct UseAndroidNativeBufferParams {
123      OMX_U32 nSize;
124      OMX_VERSIONTYPE nVersion;
125      OMX_U32 nPortIndex;
126      OMX_PTR pAppPrivate;
127      OMX_BUFFERHEADERTYPE **bufferHeader;
128      const sp<ANativeWindowBuffer>& nativeBuffer;
129  };
130  
131  // A pointer to this struct is passed to OMX_GetParameter when the extension
132  // index for the 'OMX.google.android.index.getAndroidNativeBufferUsage'
133  // extension is given.  The usage bits returned from this query will be used to
134  // allocate the Gralloc buffers that get passed to the useAndroidNativeBuffer
135  // command.
136  struct GetAndroidNativeBufferUsageParams {
137      OMX_U32 nSize;              // IN
138      OMX_VERSIONTYPE nVersion;   // IN
139      OMX_U32 nPortIndex;         // IN
140      OMX_U32 nUsage;             // OUT
141  };
142  
143  // An enum OMX_COLOR_FormatAndroidOpaque to indicate an opaque colorformat
144  // is declared in media/stagefright/openmax/OMX_IVCommon.h
145  // This will inform the encoder that the actual
146  // colorformat will be relayed by the GRalloc Buffers.
147  // OMX_COLOR_FormatAndroidOpaque  = 0x7F000001,
148  
149  // A pointer to this struct is passed to OMX_SetParameter when the extension
150  // index for the 'OMX.google.android.index.prependSPSPPSToIDRFrames' extension
151  // is given.
152  // A successful result indicates that future IDR frames will be prefixed by
153  // SPS/PPS.
154  struct PrependSPSPPSToIDRFramesParams {
155      OMX_U32 nSize;
156      OMX_VERSIONTYPE nVersion;
157      OMX_BOOL bEnable;
158  };
159  
160  // Structure describing a media image (frame)
161  // Currently only supporting YUV
162  struct MediaImage {
163      enum Type {
164          MEDIA_IMAGE_TYPE_UNKNOWN = 0,
165          MEDIA_IMAGE_TYPE_YUV,
166      };
167  
168      enum PlaneIndex {
169          Y = 0,
170          U,
171          V,
172          MAX_NUM_PLANES
173      };
174  
175      Type mType;
176      size_t mNumPlanes;              // number of planes
177      size_t mWidth;                  // width of largest plane (unpadded, as in nFrameWidth)
178      size_t mHeight;                 // height of largest plane (unpadded, as in nFrameHeight)
179      size_t mBitDepth;               // useable bit depth
180      struct PlaneInfo {
181          size_t mOffset;             // offset of first pixel of the plane in bytes
182                                      // from buffer offset
183          size_t mColInc;             // column increment in bytes
184          size_t mRowInc;             // row increment in bytes
185          size_t mHorizSubsampling;   // subsampling compared to the largest plane
186          size_t mVertSubsampling;    // subsampling compared to the largest plane
187      };
188      PlaneInfo mPlane[MAX_NUM_PLANES];
189  };
190  
191  // A pointer to this struct is passed to OMX_GetParameter when the extension
192  // index for the 'OMX.google.android.index.describeColorFormat'
193  // extension is given.  This method can be called from any component state
194  // other than invalid.  The color-format, frame width/height, and stride/
195  // slice-height parameters are ones that are associated with a raw video
196  // port (input or output), but the stride/slice height parameters may be
197  // incorrect. bUsingNativeBuffers is OMX_TRUE if native android buffers will
198  // be used (while specifying this color format).
199  //
200  // The component shall fill out the MediaImage structure that
201  // corresponds to the described raw video format, and the potentially corrected
202  // stride and slice-height info.
203  //
204  // The behavior is slightly different if bUsingNativeBuffers is OMX_TRUE,
205  // though most implementations can ignore this difference. When using native buffers,
206  // the component may change the configured color format to an optimized format.
207  // Additionally, when allocating these buffers for flexible usecase, the framework
208  // will set the SW_READ/WRITE_OFTEN usage flags. In this case (if bUsingNativeBuffers
209  // is OMX_TRUE), the component shall fill out the MediaImage information for the
210  // scenario when these SW-readable/writable buffers are locked using gralloc_lock.
211  // Note, that these buffers may also be locked using gralloc_lock_ycbcr, which must
212  // be supported for vendor-specific formats.
213  //
214  // For non-YUV packed planar/semiplanar image formats, or if bUsingNativeBuffers
215  // is OMX_TRUE and the component does not support this color format with native
216  // buffers, the component shall set mNumPlanes to 0, and mType to MEDIA_IMAGE_TYPE_UNKNOWN.
217  struct DescribeColorFormatParams {
218      OMX_U32 nSize;
219      OMX_VERSIONTYPE nVersion;
220      // input: parameters from OMX_VIDEO_PORTDEFINITIONTYPE
221      OMX_COLOR_FORMATTYPE eColorFormat;
222      OMX_U32 nFrameWidth;
223      OMX_U32 nFrameHeight;
224      OMX_U32 nStride;
225      OMX_U32 nSliceHeight;
226      OMX_BOOL bUsingNativeBuffers;
227  
228      // output: fill out the MediaImage fields
229      MediaImage sMediaImage;
230  };
231  
232  // A pointer to this struct is passed to OMX_SetParameter or OMX_GetParameter
233  // when the extension index for the
234  // 'OMX.google.android.index.configureVideoTunnelMode' extension is  given.
235  // If the extension is supported then tunneled playback mode should be supported
236  // by the codec. If bTunneled is set to OMX_TRUE then the video decoder should
237  // operate in "tunneled" mode and output its decoded frames directly to the
238  // sink. In this case nAudioHwSync is the HW SYNC ID of the audio HAL Output
239  // stream to sync the video with. If bTunneled is set to OMX_FALSE, "tunneled"
240  // mode should be disabled and nAudioHwSync should be ignored.
241  // OMX_GetParameter is used to query tunneling configuration. bTunneled should
242  // return whether decoder is operating in tunneled mode, and if it is,
243  // pSidebandWindow should contain the codec allocated sideband window handle.
244  struct ConfigureVideoTunnelModeParams {
245      OMX_U32 nSize;              // IN
246      OMX_VERSIONTYPE nVersion;   // IN
247      OMX_U32 nPortIndex;         // IN
248      OMX_BOOL bTunneled;         // IN/OUT
249      OMX_U32 nAudioHwSync;       // IN
250      OMX_PTR pSidebandWindow;    // OUT
251  };
252  
253  }  // namespace android
254  
255  extern android::OMXPluginBase *createOMXPlugin();
256  
257  #endif  // HARDWARE_API_H_
258