HardwareAPI.h revision 4e2bddfcd1052c9acf2969e1403d0a796ad4293c
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 28namespace 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. 48struct 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 index 56// "OMX.google.android.index.storeMetaDataInBuffers" or 57// "OMX.google.android.index.storeANWBufferInMetadata" 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 parameter. 66// 67// Currently, this is used to pass meta data from video source (camera component, for instance) to 68// video encoder to avoid memcpying of input video frame data, as well as to pass dynamic output 69// buffer to video decoder. To do this, bStoreMetaData is set to OMX_TRUE. 70// 71// If bStoreMetaData is set to false, real YUV frame data will be stored in input buffers, and 72// the output buffers contain either real YUV frame data, or are themselves native handles as 73// directed by enable/use-android-native-buffer parameter settings. 74// In addition, if no OMX_SetParameter() call is made on a port with the corresponding extension 75// index, the component should not assume that the client is not using metadata mode for the port. 76// 77// If the component supports this using the "OMX.google.android.index.storeANWBufferInMetadata" 78// extension and bStoreMetaData is set to OMX_TRUE, data is passed using the VideoNativeMetadata 79// layout as defined below. Each buffer will be accompanied by a fence. The fence must signal 80// before the buffer can be used (e.g. read from or written into). When returning such buffer to 81// the client, component must provide a new fence that must signal before the returned buffer can 82// be used (e.g. read from or written into). The component owns the incoming fenceFd, and must close 83// it when fence has signaled. The client will own and close the returned fence file descriptor. 84// 85// If the component supports this using the "OMX.google.android.index.storeMetaDataInBuffers" 86// extension and bStoreMetaData is set to OMX_TRUE, data is passed using VideoGrallocMetadata 87// (the layout of which is the VideoGrallocMetadata defined below). Camera input can be also passed 88// as "CameraSource", the layout of which is vendor dependent. 89// 90// Metadata buffers are registered with the component using UseBuffer calls, or can be allocated 91// by the component for encoder-metadata-output buffers. 92struct StoreMetaDataInBuffersParams { 93 OMX_U32 nSize; 94 OMX_VERSIONTYPE nVersion; 95 OMX_U32 nPortIndex; 96 OMX_BOOL bStoreMetaData; 97}; 98 99// Meta data buffer layout used to transport output frames to the decoder for 100// dynamic buffer handling. 101struct VideoGrallocMetadata { 102 MetadataBufferType eType; // must be kMetadataBufferTypeGrallocSource 103#ifdef OMX_ANDROID_COMPILE_AS_32BIT_ON_64BIT_PLATFORMS 104 OMX_PTR pHandle; 105#else 106 buffer_handle_t pHandle; 107#endif 108}; 109 110// Legacy name for VideoGrallocMetadata struct. 111struct VideoDecoderOutputMetaData : public VideoGrallocMetadata {}; 112 113struct VideoNativeMetadata { 114 MetadataBufferType eType; // must be kMetadataBufferTypeANWBuffer 115#ifdef OMX_ANDROID_COMPILE_AS_32BIT_ON_64BIT_PLATFORMS 116 OMX_PTR pBuffer; 117#else 118 struct ANativeWindowBuffer* pBuffer; 119#endif 120 int nFenceFd; // -1 if unused 121}; 122 123// A pointer to this struct is passed to OMX_SetParameter() when the extension 124// index "OMX.google.android.index.prepareForAdaptivePlayback" is given. 125// 126// This method is used to signal a video decoder, that the user has requested 127// seamless resolution change support (if bEnable is set to OMX_TRUE). 128// nMaxFrameWidth and nMaxFrameHeight are the dimensions of the largest 129// anticipated frames in the video. If bEnable is OMX_FALSE, no resolution 130// change is expected, and the nMaxFrameWidth/Height fields are unused. 131// 132// If the decoder supports dynamic output buffers, it may ignore this 133// request. Otherwise, it shall request resources in such a way so that it 134// avoids full port-reconfiguration (due to output port-definition change) 135// during resolution changes. 136// 137// DO NOT USE THIS STRUCTURE AS IT WILL BE REMOVED. INSTEAD, IMPLEMENT 138// METADATA SUPPORT FOR VIDEO DECODERS. 139struct PrepareForAdaptivePlaybackParams { 140 OMX_U32 nSize; 141 OMX_VERSIONTYPE nVersion; 142 OMX_U32 nPortIndex; 143 OMX_BOOL bEnable; 144 OMX_U32 nMaxFrameWidth; 145 OMX_U32 nMaxFrameHeight; 146}; 147 148// A pointer to this struct is passed to OMX_SetParameter when the extension 149// index for the 'OMX.google.android.index.useAndroidNativeBuffer' extension is 150// given. This call will only be performed if a prior call was made with the 151// 'OMX.google.android.index.enableAndroidNativeBuffers' extension index, 152// enabling use of Android native buffers. 153struct UseAndroidNativeBufferParams { 154 OMX_U32 nSize; 155 OMX_VERSIONTYPE nVersion; 156 OMX_U32 nPortIndex; 157 OMX_PTR pAppPrivate; 158 OMX_BUFFERHEADERTYPE **bufferHeader; 159 const sp<ANativeWindowBuffer>& nativeBuffer; 160}; 161 162// A pointer to this struct is passed to OMX_GetParameter when the extension 163// index for the 'OMX.google.android.index.getAndroidNativeBufferUsage' 164// extension is given. The usage bits returned from this query will be used to 165// allocate the Gralloc buffers that get passed to the useAndroidNativeBuffer 166// command. 167struct GetAndroidNativeBufferUsageParams { 168 OMX_U32 nSize; // IN 169 OMX_VERSIONTYPE nVersion; // IN 170 OMX_U32 nPortIndex; // IN 171 OMX_U32 nUsage; // OUT 172}; 173 174// An enum OMX_COLOR_FormatAndroidOpaque to indicate an opaque colorformat 175// is declared in media/stagefright/openmax/OMX_IVCommon.h 176// This will inform the encoder that the actual 177// colorformat will be relayed by the GRalloc Buffers. 178// OMX_COLOR_FormatAndroidOpaque = 0x7F000001, 179 180// A pointer to this struct is passed to OMX_SetParameter when the extension 181// index for the 'OMX.google.android.index.prependSPSPPSToIDRFrames' extension 182// is given. 183// A successful result indicates that future IDR frames will be prefixed by 184// SPS/PPS. 185struct PrependSPSPPSToIDRFramesParams { 186 OMX_U32 nSize; 187 OMX_VERSIONTYPE nVersion; 188 OMX_BOOL bEnable; 189}; 190 191// Structure describing a media image (frame) 192// Currently only supporting YUV 193// @deprecated. Use MediaImage2 instead 194struct MediaImage { 195 enum Type { 196 MEDIA_IMAGE_TYPE_UNKNOWN = 0, 197 MEDIA_IMAGE_TYPE_YUV, 198 }; 199 200 enum PlaneIndex { 201 Y = 0, 202 U, 203 V, 204 MAX_NUM_PLANES 205 }; 206 207 Type mType; 208 uint32_t mNumPlanes; // number of planes 209 uint32_t mWidth; // width of largest plane (unpadded, as in nFrameWidth) 210 uint32_t mHeight; // height of largest plane (unpadded, as in nFrameHeight) 211 uint32_t mBitDepth; // useable bit depth 212 struct PlaneInfo { 213 uint32_t mOffset; // offset of first pixel of the plane in bytes 214 // from buffer offset 215 uint32_t mColInc; // column increment in bytes 216 uint32_t mRowInc; // row increment in bytes 217 uint32_t mHorizSubsampling; // subsampling compared to the largest plane 218 uint32_t mVertSubsampling; // subsampling compared to the largest plane 219 }; 220 PlaneInfo mPlane[MAX_NUM_PLANES]; 221}; 222 223struct MediaImage2 { 224 enum Type { 225 MEDIA_IMAGE_TYPE_UNKNOWN = 0, 226 MEDIA_IMAGE_TYPE_YUV, 227 MEDIA_IMAGE_TYPE_YUVA, 228 MEDIA_IMAGE_TYPE_RGB, 229 MEDIA_IMAGE_TYPE_RGBA, 230 MEDIA_IMAGE_TYPE_Y, 231 }; 232 233 enum PlaneIndex { 234 Y = 0, 235 U = 1, 236 V = 2, 237 R = 0, 238 G = 1, 239 B = 2, 240 A = 3, 241 MAX_NUM_PLANES = 4, 242 }; 243 244 Type mType; 245 uint32_t mNumPlanes; // number of planes 246 uint32_t mWidth; // width of largest plane (unpadded, as in nFrameWidth) 247 uint32_t mHeight; // height of largest plane (unpadded, as in nFrameHeight) 248 uint32_t mBitDepth; // useable bit depth (always MSB) 249 uint32_t mBitDepthAllocated; // bits per component (must be 8 or 16) 250 251 struct PlaneInfo { 252 uint32_t mOffset; // offset of first pixel of the plane in bytes 253 // from buffer offset 254 int32_t mColInc; // column increment in bytes 255 int32_t mRowInc; // row increment in bytes 256 uint32_t mHorizSubsampling; // subsampling compared to the largest plane 257 uint32_t mVertSubsampling; // subsampling compared to the largest plane 258 }; 259 PlaneInfo mPlane[MAX_NUM_PLANES]; 260}; 261 262// A pointer to this struct is passed to OMX_GetParameter when the extension 263// index for the 'OMX.google.android.index.describeColorFormat' 264// extension is given. This method can be called from any component state 265// other than invalid. The color-format, frame width/height, and stride/ 266// slice-height parameters are ones that are associated with a raw video 267// port (input or output), but the stride/slice height parameters may be 268// incorrect. bUsingNativeBuffers is OMX_TRUE if native android buffers will 269// be used (while specifying this color format). 270// 271// The component shall fill out the MediaImage structure that 272// corresponds to the described raw video format, and the potentially corrected 273// stride and slice-height info. 274// 275// The behavior is slightly different if bUsingNativeBuffers is OMX_TRUE, 276// though most implementations can ignore this difference. When using native buffers, 277// the component may change the configured color format to an optimized format. 278// Additionally, when allocating these buffers for flexible usecase, the framework 279// will set the SW_READ/WRITE_OFTEN usage flags. In this case (if bUsingNativeBuffers 280// is OMX_TRUE), the component shall fill out the MediaImage information for the 281// scenario when these SW-readable/writable buffers are locked using gralloc_lock. 282// Note, that these buffers may also be locked using gralloc_lock_ycbcr, which must 283// be supported for vendor-specific formats. 284// 285// For non-YUV packed planar/semiplanar image formats, or if bUsingNativeBuffers 286// is OMX_TRUE and the component does not support this color format with native 287// buffers, the component shall set mNumPlanes to 0, and mType to MEDIA_IMAGE_TYPE_UNKNOWN. 288 289// @deprecated: use DescribeColorFormat2Params 290struct DescribeColorFormatParams { 291 OMX_U32 nSize; 292 OMX_VERSIONTYPE nVersion; 293 // input: parameters from OMX_VIDEO_PORTDEFINITIONTYPE 294 OMX_COLOR_FORMATTYPE eColorFormat; 295 OMX_U32 nFrameWidth; 296 OMX_U32 nFrameHeight; 297 OMX_U32 nStride; 298 OMX_U32 nSliceHeight; 299 OMX_BOOL bUsingNativeBuffers; 300 301 // output: fill out the MediaImage fields 302 MediaImage sMediaImage; 303}; 304 305// A pointer to this struct is passed to OMX_GetParameter when the extension 306// index for the 'OMX.google.android.index.describeColorFormat2' 307// extension is given. This is operationally the same as DescribeColorFormatParams 308// but can be used for HDR and RGBA/YUVA formats. 309struct DescribeColorFormat2Params { 310 OMX_U32 nSize; 311 OMX_VERSIONTYPE nVersion; 312 // input: parameters from OMX_VIDEO_PORTDEFINITIONTYPE 313 OMX_COLOR_FORMATTYPE eColorFormat; 314 OMX_U32 nFrameWidth; 315 OMX_U32 nFrameHeight; 316 OMX_U32 nStride; 317 OMX_U32 nSliceHeight; 318 OMX_BOOL bUsingNativeBuffers; 319 320 // output: fill out the MediaImage2 fields 321 MediaImage2 sMediaImage; 322}; 323 324// A pointer to this struct is passed to OMX_SetParameter or OMX_GetParameter 325// when the extension index for the 326// 'OMX.google.android.index.configureVideoTunnelMode' extension is given. 327// If the extension is supported then tunneled playback mode should be supported 328// by the codec. If bTunneled is set to OMX_TRUE then the video decoder should 329// operate in "tunneled" mode and output its decoded frames directly to the 330// sink. In this case nAudioHwSync is the HW SYNC ID of the audio HAL Output 331// stream to sync the video with. If bTunneled is set to OMX_FALSE, "tunneled" 332// mode should be disabled and nAudioHwSync should be ignored. 333// OMX_GetParameter is used to query tunneling configuration. bTunneled should 334// return whether decoder is operating in tunneled mode, and if it is, 335// pSidebandWindow should contain the codec allocated sideband window handle. 336struct ConfigureVideoTunnelModeParams { 337 OMX_U32 nSize; // IN 338 OMX_VERSIONTYPE nVersion; // IN 339 OMX_U32 nPortIndex; // IN 340 OMX_BOOL bTunneled; // IN/OUT 341 OMX_U32 nAudioHwSync; // IN 342 OMX_PTR pSidebandWindow; // OUT 343}; 344 345// Color description parameters. This is passed via OMX_SetConfig or OMX_GetConfig 346// to video encoders and decoders when the 347// 'OMX.google.android.index.describeColorAspects' extension is given. 348// 349// Video encoders: the framework uses OMX_SetConfig to specify color aspects 350// of the coded video before the component transitions to idle state. 351// 352// Video decoders: the framework uses OMX_SetConfig to specify color aspects 353// of the coded video parsed from the container before the component transitions 354// to idle state. If the bitstream contains color information, the component should 355// update the appropriate color aspects - unless the bitstream contains the 356// "unspecified" value. For "reserved" values, the component should set the aspect 357// to "Other". 358// 359// The framework subsequently uses OMX_GetConfig to get any updates of the 360// color aspects from the decoder. If the color aspects change at any time 361// during the processing of the stream, the component shall signal a 362// OMX_EventPortSettingsChanged event with data2 set to the extension index 363// (or OMX_IndexConfigCommonOutputCrop, as it is handled identically). Component 364// shall not signal a separate event purely for color aspect change, if it occurs 365// together with a port definition (e.g. size) or crop change. 366// 367// NOTE: this structure is expected to grow in the future if new color aspects are 368// added to codec bitstreams. OMX component should not require a specific nSize 369// though could verify that nSize is at least the size of the structure at the 370// time of implementation. All new fields will be added at the end of the structure 371// ensuring backward compatibility. 372 373struct DescribeColorAspectsParams { 374 OMX_U32 nSize; // IN 375 OMX_VERSIONTYPE nVersion; // IN 376 OMX_U32 nPortIndex; // IN 377 OMX_U32 nRange; // IN/OUT (one of the ColorAspects.Range enums) 378 OMX_U32 nPrimaries; // IN/OUT (one of the ColorAspects.Primaries enums) 379 OMX_U32 nTransfer; // IN/OUT (one of the ColorAspects.Transfer enums) 380 OMX_U32 nMatrixCoeffs; // IN/OUT (one of the ColorAspects.MatrixCoeffs enums) 381}; 382 383struct ColorAspects { 384 // this is in sync with the range values in graphics.h 385 enum Range : uint32_t { 386 RangeUnspecified, 387 RangeFull, 388 RangeLimited, 389 RangeOther = 0xff, 390 }; 391 392 enum Primaries : uint32_t { 393 PrimariesUnspecified, 394 PrimariesBT709_5, // Rec.ITU-R BT.709-5 or equivalent 395 PrimariesBT470_6M, // Rec.ITU-R BT.470-6 System M or equivalent 396 PrimariesBT601_6_625, // Rec.ITU-R BT.601-6 625 or equivalent 397 PrimariesBT601_6_525, // Rec.ITU-R BT.601-6 525 or equivalent 398 PrimariesGenericFilm, // Generic Film 399 PrimariesBT2020, // Rec.ITU-R BT.2020 or equivalent 400 PrimariesOther = 0xff, 401 }; 402 403 // this partially in sync with the transfer values in graphics.h prior to the transfers 404 // unlikely to be required by Android section 405 enum Transfer : uint32_t { 406 TransferUnspecified, 407 TransferLinear, // Linear transfer characteristics 408 TransferSRGB, // sRGB or equivalent 409 TransferSMPTE170M, // SMPTE 170M or equivalent (e.g. BT.601/709/2020) 410 TransferGamma22, // Assumed display gamma 2.2 411 TransferGamma28, // Assumed display gamma 2.8 412 TransferST2084, // SMPTE ST 2084 for 10/12/14/16 bit systems 413 TransferHLG, // ARIB STD-B67 hybrid-log-gamma 414 415 // transfers unlikely to be required by Android 416 TransferSMPTE240M = 0x40, // SMPTE 240M 417 TransferXvYCC, // IEC 61966-2-4 418 TransferBT1361, // Rec.ITU-R BT.1361 extended gamut 419 TransferST428, // SMPTE ST 428-1 420 TransferOther = 0xff, 421 }; 422 423 enum MatrixCoeffs : uint32_t { 424 MatrixUnspecified, 425 MatrixBT709_5, // Rec.ITU-R BT.709-5 or equivalent 426 MatrixBT470_6M, // KR=0.30, KB=0.11 or equivalent 427 MatrixBT601_6, // Rec.ITU-R BT.601-6 625 or equivalent 428 MatrixSMPTE240M, // SMPTE 240M or equivalent 429 MatrixBT2020, // Rec.ITU-R BT.2020 non-constant luminance 430 MatrixBT2020Constant, // Rec.ITU-R BT.2020 constant luminance 431 MatrixOther = 0xff, 432 }; 433 434 // this is in sync with the standard values in graphics.h 435 enum Standard : uint32_t { 436 StandardUnspecified, 437 StandardBT709, // PrimariesBT709_5 and MatrixBT709_5 438 StandardBT601_625, // PrimariesBT601_6_625 and MatrixBT601_6 439 StandardBT601_625_Unadjusted, // PrimariesBT601_6_625 and KR=0.222, KB=0.071 440 StandardBT601_525, // PrimariesBT601_6_525 and MatrixBT601_6 441 StandardBT601_525_Unadjusted, // PrimariesBT601_6_525 and MatrixSMPTE240M 442 StandardBT2020, // PrimariesBT2020 and MatrixBT2020 443 StandardBT2020Constant, // PrimariesBT2020 and MatrixBT2020Constant 444 StandardBT470M, // PrimariesBT470_6M and MatrixBT470_6M 445 StandardFilm, // PrimariesGenericFilm and KR=0.253, KB=0.068 446 StandardOther = 0xff, 447 }; 448}; 449 450} // namespace android 451 452extern android::OMXPluginBase *createOMXPlugin(); 453 454#endif // HARDWARE_API_H_ 455