1 /* 2 * Copyright (C) 2011 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 ************************************************************************ 18 * @file M4DECODER_Common.h 19 * @brief Shell Decoder common interface declaration 20 * @note This file declares the common interfaces that decoder shells must implement 21 * 22 ************************************************************************ 23 */ 24 #ifndef __M4DECODER_COMMON_H__ 25 #define __M4DECODER_COMMON_H__ 26 27 #include "M4OSA_Types.h" 28 #include "M4OSA_Error.h" 29 #include "M4OSA_OptionID.h" 30 #include "M4OSA_CoreID.h" 31 32 #include "M4READER_Common.h" 33 #include "M4VIFI_FiltersAPI.h" 34 35 #include "M4_Utils.h" 36 37 /* ----- Errors and Warnings ----- */ 38 39 /** 40 * Warning: there is no new decoded frame to render since the last rendering 41 */ 42 #define M4WAR_VIDEORENDERER_NO_NEW_FRAME M4OSA_ERR_CREATE(M4_WAR, M4DECODER_COMMON, 0x0001) 43 /** 44 * Warning: the deblocking filter is not implemented 45 */ 46 #define M4WAR_DEBLOCKING_FILTER_NOT_IMPLEMENTED M4OSA_ERR_CREATE(M4_WAR, M4DECODER_COMMON,\ 47 0x000002) 48 49 50 /* Error: Stream H263 profiles (other than 0) are not supported */ 51 #define M4ERR_DECODER_H263_PROFILE_NOT_SUPPORTED M4OSA_ERR_CREATE(M4_ERR,\ 52 M4DECODER_MPEG4, 0x0001) 53 /* Error: Stream H263 not baseline not supported (Supported sizes are CIF, QCIF or SQCIF) */ 54 #define M4ERR_DECODER_H263_NOT_BASELINE M4OSA_ERR_CREATE(M4_ERR,\ 55 M4DECODER_MPEG4, 0x0002) 56 57 /** 58 ************************************************************************ 59 * enum M4DECODER_AVCProfileLevel 60 * @brief This enum defines the AVC decoder profile and level for the current instance 61 * @note This options can be read from decoder via M4DECODER_getOption_fct 62 ************************************************************************ 63 */ 64 typedef enum 65 { 66 M4DECODER_AVC_kProfile_0_Level_1 = 0, 67 M4DECODER_AVC_kProfile_0_Level_1b, 68 M4DECODER_AVC_kProfile_0_Level_1_1, 69 M4DECODER_AVC_kProfile_0_Level_1_2, 70 M4DECODER_AVC_kProfile_0_Level_1_3, 71 M4DECODER_AVC_kProfile_0_Level_2, 72 M4DECODER_AVC_kProfile_0_Level_2_1, 73 M4DECODER_AVC_kProfile_0_Level_2_2, 74 M4DECODER_AVC_kProfile_0_Level_3, 75 M4DECODER_AVC_kProfile_0_Level_3_1, 76 M4DECODER_AVC_kProfile_0_Level_3_2, 77 M4DECODER_AVC_kProfile_0_Level_4, 78 M4DECODER_AVC_kProfile_0_Level_4_1, 79 M4DECODER_AVC_kProfile_0_Level_4_2, 80 M4DECODER_AVC_kProfile_0_Level_5, 81 M4DECODER_AVC_kProfile_0_Level_5_1, 82 M4DECODER_AVC_kProfile_and_Level_Out_Of_Range = 255 83 } M4DECODER_AVCProfileLevel; 84 85 /** 86 ************************************************************************ 87 * enum M4DECODER_OptionID 88 * @brief This enum defines the decoder options 89 * @note These options can be read from or written to a decoder via M4DECODER_getOption_fct 90 ************************************************************************ 91 */ 92 typedef enum 93 { 94 /** 95 Get the version of the core decoder 96 */ 97 M4DECODER_kOptionID_Version = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x01), 98 /** 99 Get the size of the currently decoded video 100 */ 101 M4DECODER_kOptionID_VideoSize = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x02), 102 /** 103 Set the conversion filter to use at rendering 104 */ 105 M4DECODER_kOptionID_OutputFilter = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x03), 106 /** 107 Activate the Deblocking filter 108 */ 109 M4DECODER_kOptionID_DeblockingFilter = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x04), 110 /** 111 Get nex rendered frame CTS 112 */ 113 M4DECODER_kOptionID_NextRenderedFrameCTS = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON,\ 114 0x05), 115 116 /** 117 Set the YUV data to the dummy video decoder 118 */ 119 M4DECODER_kOptionID_DecYuvData = 120 M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x06), 121 /** 122 Set the YUV data with color effect applied to the dummy video decoder 123 */ 124 M4DECODER_kOptionID_YuvWithEffectNonContiguous = 125 M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x07), 126 127 M4DECODER_kOptionID_YuvWithEffectContiguous = 128 M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x08), 129 130 M4DECODER_kOptionID_EnableYuvWithEffect = 131 M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x09), 132 133 /** 134 * Get the supported video decoders and capabilities */ 135 M4DECODER_kOptionID_VideoDecodersAndCapabilities = 136 M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_COMMON, 0x10), 137 138 /* common to MPEG4 decoders */ 139 /** 140 * Get the DecoderConfigInfo */ 141 M4DECODER_MPEG4_kOptionID_DecoderConfigInfo = M4OSA_OPTION_ID_CREATE(M4_READ,\ 142 M4DECODER_MPEG4, 0x01), 143 144 /* last decoded cts */ 145 M4DECODER_kOptionID_AVCLastDecodedFrameCTS = M4OSA_OPTION_ID_CREATE(M4_READ, M4DECODER_AVC,\ 146 0x01) 147 /* Last decoded cts */ 148 149 } M4DECODER_OptionID; 150 151 152 /** 153 ************************************************************************ 154 * struct M4DECODER_MPEG4_DecoderConfigInfo 155 * @brief Contains info read from the MPEG-4 VideoObjectLayer. 156 ************************************************************************ 157 */ 158 typedef struct 159 { 160 M4OSA_UInt8 uiProfile; /**< profile and level as defined in the Visual 161 Object Sequence header, if present */ 162 M4OSA_UInt32 uiTimeScale; /**< time scale as parsed in VOL header */ 163 M4OSA_UInt8 uiUseOfResynchMarker; /**< Usage of resynchronization marker */ 164 M4OSA_Bool bDataPartition; /**< If 1 data partitioning is used. */ 165 M4OSA_Bool bUseOfRVLC; /**< Usage of RVLC for the stream */ 166 167 } M4DECODER_MPEG4_DecoderConfigInfo; 168 169 170 /** 171 *********************************************************************** 172 * structure M4DECODER_VideoSize 173 * @brief This structure defines the video size (width and height) 174 * @note This structure is used to retrieve via the M4DECODER_getOption_fct 175 * function the size of the current decoded video 176 ************************************************************************ 177 */ 178 typedef struct _M4DECODER_VideoSize 179 { 180 M4OSA_UInt32 m_uiWidth; /**< video width in pixels */ 181 M4OSA_UInt32 m_uiHeight; /**< video height in pixels */ 182 183 } M4DECODER_VideoSize; 184 185 /** 186 ************************************************************************ 187 * structure M4DECODER_OutputFilter 188 * @brief This structure defines the conversion filter 189 * @note This structure is used to retrieve the filter function 190 * pointer and its user data via the function 191 * M4DECODER_getOption_fct with the option 192 * M4DECODER_kOptionID_OutputFilter 193 ************************************************************************ 194 */ 195 typedef struct _M4DECODER_OutputFilter 196 { 197 M4OSA_Void *m_pFilterFunction; /**< pointer to the filter function */ 198 M4OSA_Void *m_pFilterUserData; /**< user data of the filter */ 199 200 } M4DECODER_OutputFilter; 201 202 /** 203 ************************************************************************ 204 * enum M4DECODER_VideoType 205 * @brief This enum defines the video types used to create decoders 206 * @note This enum is used internally by the VPS to identify a currently supported 207 * video decoder interface. Each decoder is registered with one of this type associated. 208 * When a decoder instance is needed, this type is used to identify and 209 * and retrieve its interface. 210 ************************************************************************ 211 */ 212 typedef enum 213 { 214 M4DECODER_kVideoTypeMPEG4 = 0, 215 M4DECODER_kVideoTypeMJPEG, 216 M4DECODER_kVideoTypeAVC, 217 M4DECODER_kVideoTypeWMV, 218 M4DECODER_kVideoTypeREAL, 219 M4DECODER_kVideoTypeYUV420P, 220 221 M4DECODER_kVideoType_NB /* number of decoders, keep it as last enum entry */ 222 223 } M4DECODER_VideoType ; 224 225 typedef struct { 226 M4OSA_UInt32 mProfile; 227 M4OSA_UInt32 mLevel; 228 } VideoProfileLevel; 229 230 typedef struct { 231 VideoProfileLevel *profileLevel; 232 M4OSA_UInt32 profileNumber; 233 } VideoComponentCapabilities; 234 235 typedef struct { 236 M4_StreamType codec; 237 VideoComponentCapabilities *component; 238 M4OSA_UInt32 componentNumber; 239 } VideoDecoder; 240 241 typedef struct { 242 VideoDecoder *decoder; 243 M4OSA_UInt32 decoderNumber; 244 } M4DECODER_VideoDecoders; 245 /** 246 ************************************************************************ 247 * @brief creates an instance of the decoder 248 * @note allocates the context 249 * 250 * @param pContext: (OUT) Context of the decoder 251 * @param pStreamHandler: (IN) Pointer to a video stream description 252 * @param pGlobalInterface: (IN) Pointer to the M4READER_GlobalInterface structure that must 253 * be used by the decoder to read data from the stream 254 * @param pDataInterface: (IN) Pointer to the M4READER_DataInterface structure that must 255 * be used by the decoder to read data from the stream 256 * @param pAccessUnit (IN) Pointer to an access unit (allocated by the caller) 257 * where the decoded data are stored 258 * 259 * @return M4NO_ERROR there is no error 260 * @return M4ERR_STATE State automaton is not applied 261 * @return M4ERR_ALLOC a memory allocation has failed 262 * @return M4ERR_PARAMETER at least one parameter is not properly set (in DEBUG only) 263 ************************************************************************ 264 */ 265 typedef M4OSA_ERR (M4DECODER_create_fct) (M4OSA_Context *pContext, 266 M4_StreamHandler *pStreamHandler, 267 M4READER_GlobalInterface *pGlobalInterface, 268 M4READER_DataInterface *pDataInterface, 269 M4_AccessUnit *pAccessUnit, 270 M4OSA_Void* pUserData); 271 272 /** 273 ************************************************************************ 274 * @brief destroy the instance of the decoder 275 * @note after this call the context is invalid 276 * 277 * @param context: (IN) Context of the decoder 278 * 279 * @return M4NO_ERROR There is no error 280 * @return M4ERR_PARAMETER The context is invalid (in DEBUG only) 281 ************************************************************************ 282 */ 283 typedef M4OSA_ERR (M4DECODER_destroy_fct) (M4OSA_Context context); 284 285 /** 286 ************************************************************************ 287 * @brief get an option value from the decoder 288 * @note this function follows the set/get option mechanism described in OSAL 3.0 289 * it allows the caller to retrieve a property value: 290 * -the version number of the decoder 291 * -the size (widthxheight) of the image 292 * 293 * @param context: (IN) Context of the decoder 294 * @param optionId: (IN) indicates the option to set 295 * @param pValue: (IN/OUT) pointer to structure or value (allocated by user) where 296 * option is stored 297 * @return M4NO_ERROR there is no error 298 * @return M4ERR_PARAMETER The context is invalid (in DEBUG only) 299 * @return M4ERR_BAD_OPTION_ID when the option ID is not a valid one 300 * @return M4ERR_STATE State automaton is not applied 301 ************************************************************************ 302 */ 303 typedef M4OSA_ERR (M4DECODER_getOption_fct)(M4OSA_Context context, M4OSA_OptionID optionId, 304 M4OSA_DataOption pValue); 305 306 /** 307 ************************************************************************ 308 * @brief set an option value of the decoder 309 * @note this function follows the set/get option mechanism described in OSAL 3.0 310 * it allows the caller to set a property value: 311 * -the conversion filter to use at rendering 312 * 313 * @param context: (IN) Context of the decoder 314 * @param optionId: (IN) Identifier indicating the option to set 315 * @param pValue: (IN) Pointer to structure or value (allocated by user) 316 * where option is stored 317 * @return M4NO_ERROR There is no error 318 * @return M4ERR_BAD_OPTION_ID The option ID is not a valid one 319 * @return M4ERR_STATE State automaton is not applied 320 * @return M4ERR_PARAMETER The option parameter is invalid 321 ************************************************************************ 322 */ 323 typedef M4OSA_ERR (M4DECODER_setOption_fct)(M4OSA_Context context, M4OSA_OptionID optionId, 324 M4OSA_DataOption pValue); 325 326 /** 327 ************************************************************************ 328 * @brief Decode Access Units up to a target time 329 * @note Parse and decode the stream until it is possible to output a decoded image for which 330 * the composition time is equal or greater to the passed targeted time 331 * The data are read from the reader data interface 332 * 333 * @param context: (IN) Context of the decoder 334 * @param pTime: (IN/OUT) IN: Time to decode up to (in milli secondes) 335 * OUT:Time of the last decoded frame (in ms) 336 * @param bJump: (IN) 0 if no jump occured just before this call 337 * 1 if a a jump has just been made 338 * @param tolerance: (IN) We may decode an earlier frame within the tolerance. 339 * The time difference is specified in milliseconds. 340 * 341 * @return M4NO_ERROR there is no error 342 * @return M4ERR_PARAMETER at least one parameter is not properly set 343 * @return M4WAR_NO_MORE_AU there is no more access unit to decode (end of stream) 344 ************************************************************************ 345 */ 346 typedef M4OSA_ERR (M4DECODER_decode_fct) (M4OSA_Context context, M4_MediaTime* pTime, 347 M4OSA_Bool bJump, M4OSA_UInt32 tolerance); 348 349 /** 350 ************************************************************************ 351 * @brief Renders the video at the specified time. 352 * @note 353 * @param context: (IN) Context of the decoder 354 * @param pTime: (IN/OUT) IN: Time to render to (in milli secondes) 355 * OUT:Time of the actually rendered frame (in ms) 356 * @param pOutputPlane:(OUT) Output plane filled with decoded data (converted) 357 * @param bForceRender:(IN) 1 if the image must be rendered even it has already been 358 * 0 if not (in which case the function can return 359 * M4WAR_VIDEORENDERER_NO_NEW_FRAME) 360 * @return M4NO_ERROR There is no error 361 * @return M4ERR_PARAMETER At least one parameter is not properly set 362 * @return M4ERR_STATE State automaton is not applied 363 * @return M4ERR_ALLOC There is no more available memory 364 * @return M4WAR_VIDEORENDERER_NO_NEW_FRAME If the frame to render has already been rendered 365 ************************************************************************ 366 */ 367 typedef M4OSA_ERR (M4DECODER_render_fct) (M4OSA_Context context, M4_MediaTime* pTime, 368 M4VIFI_ImagePlane* pOutputPlane, 369 M4OSA_Bool bForceRender); 370 371 /** 372 ************************************************************************ 373 * structure M4DECODER_VideoInterface 374 * @brief This structure defines the generic video decoder interface 375 * @note This structure stores the pointers to functions of one video decoder type. 376 * The decoder type is one of the M4DECODER_VideoType 377 ************************************************************************ 378 */ 379 typedef struct _M4DECODER_VideoInterface 380 { 381 M4DECODER_create_fct* m_pFctCreate; 382 M4DECODER_destroy_fct* m_pFctDestroy; 383 M4DECODER_getOption_fct* m_pFctGetOption; 384 M4DECODER_setOption_fct* m_pFctSetOption; 385 M4DECODER_decode_fct* m_pFctDecode; 386 M4DECODER_render_fct* m_pFctRender; 387 } M4DECODER_VideoInterface; 388 389 #endif /*__M4DECODER_COMMON_H__*/ 390