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*/
64typedef 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*/
92typedef 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*/
158typedef 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*/
178typedef 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*/
195typedef 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*/
212typedef 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
225typedef struct {
226    M4OSA_UInt32 mProfile;
227    M4OSA_UInt32 mLevel;
228} VideoProfileLevel;
229
230typedef struct {
231    VideoProfileLevel *profileLevel;
232    M4OSA_UInt32 profileNumber;
233} VideoComponentCapabilities;
234
235typedef struct {
236    M4_StreamType codec;
237    VideoComponentCapabilities *component;
238    M4OSA_UInt32 componentNumber;
239} VideoDecoder;
240
241typedef 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*/
265typedef 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*/
283typedef 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*/
303typedef 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*/
323typedef 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*/
346typedef 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*/
367typedef 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*/
379typedef 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