M4ENCODER_common.h revision b5c7784c96a606890eb8a8b560153ef4a5d1a0d9 
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    M4ENCODER_common.h
19 * @note    This file defines the types internally used by the VES to abstract encoders
20
21 ******************************************************************************
22*/
23#ifndef __M4ENCODER_COMMON_H__
24#define __M4ENCODER_COMMON_H__
25
26#ifdef __cplusplus
27extern "C" {
28#endif /* __cplusplus */
29
30
31/**
32 * Video preprocessing common interface */
33#include "M4VPP_API.h"
34
35/**
36 * Writer common interface */
37#include "M4WRITER_common.h"
38
39/* IMAGE STAB */
40/* percentage of image suppressed (computed from the standard dimension).*/
41#define M4ENCODER_STAB_FILTER_CROP_PERCENTAGE 10
42        /* WARNING: take the inferior even dimension, ex: 10% for QCIF output => 192x158 */
43
44/**
45 ******************************************************************************
46 * enum        M4ENCODER_OpenMode
47 * @brief    Definition of open mode for the encoder.
48 * @note    DEFAULT  : pointer to M4ENCODER_open() which use default parameters
49 *          ADVANCED : pointer to M4ENCODER_open_advanced() which allow to customize
50 *                     various encoding parameters
51 ******************************************************************************
52*/
53typedef enum
54{
55    M4ENCODER_OPEN_DEFAULT,
56    M4ENCODER_OPEN_ADVANCED
57} M4ENCODER_OpenMode;
58
59 /**
60 ******************************************************************************
61 * enum        M4ENCODER_FrameRate
62 * @brief    Thie enum defines the encoded video framerates.
63 ******************************************************************************
64*/
65typedef enum
66{
67    M4ENCODER_k5_FPS,
68    M4ENCODER_k7_5_FPS,
69    M4ENCODER_k10_FPS,
70    M4ENCODER_k12_5_FPS,
71    M4ENCODER_k15_FPS,
72    M4ENCODER_k20_FPS,
73    M4ENCODER_k25_FPS,
74    M4ENCODER_k30_FPS,
75    M4ENCODER_kVARIABLE_FPS,            /**< Variable video bitrate */
76    M4ENCODER_kUSE_TIMESCALE            /**< Advanced encoding, use timescale indication rather
77                                                than framerate */
78} M4ENCODER_FrameRate;
79
80/**
81 ******************************************************************************
82 * enum        M4ENCODER_InputFormat
83 * @brief    Thie enum defines the video format of the grabbing.
84 ******************************************************************************
85*/
86typedef enum
87{
88    M4ENCODER_kIYUV420=0,   /**< YUV 4:2:0 planar (standard input for mpeg-4 video) */
89    M4ENCODER_kIYUV422,        /**< YUV422 planar */
90    M4ENCODER_kIYUYV,        /**< YUV422 interlaced, luma first */
91    M4ENCODER_kIUYVY,        /**< YUV422 interlaced, chroma first */
92    M4ENCODER_kIJPEG,        /**< JPEG compressed frames */
93    M4ENCODER_kIRGB444,        /**< RGB 12 bits 4:4:4 */
94    M4ENCODER_kIRGB555,        /**< RGB 15 bits 5:5:5 */
95    M4ENCODER_kIRGB565,        /**< RGB 16 bits 5:6:5 */
96    M4ENCODER_kIRGB24,        /**< RGB 24 bits 8:8:8 */
97    M4ENCODER_kIRGB32,        /**< RGB 32 bits  */
98    M4ENCODER_kIBGR444,        /**< BGR 12 bits 4:4:4 */
99    M4ENCODER_kIBGR555,        /**< BGR 15 bits 5:5:5 */
100    M4ENCODER_kIBGR565,        /**< BGR 16 bits 5:6:5 */
101    M4ENCODER_kIBGR24,        /**< BGR 24 bits 8:8:8 */
102    M4ENCODER_kIBGR32        /**< BGR 32 bits  */
103} M4ENCODER_InputFormat;
104
105/**
106 ******************************************************************************
107 * enum        M4ENCODER_Format
108 * @brief    Thie enum defines the video compression formats.
109 ******************************************************************************
110*/
111typedef enum
112{
113    M4ENCODER_kMPEG4 = 0,
114    M4ENCODER_kH263,
115    M4ENCODER_kH264,
116    M4ENCODER_kJPEG,
117    M4ENCODER_kMJPEG,
118    M4ENCODER_kNULL,
119    M4ENCODER_kYUV420,            /**< No compression */
120    M4ENCODER_kYUV422,            /**< No compression */
121
122    M4ENCODER_kVideo_NB /* number of decoders, keep it as last enum entry */
123} M4ENCODER_Format;
124
125/**
126 ******************************************************************************
127 * enum        M4ENCODER_FrameWidth
128 * @brief    Thie enum defines the avalaible frame Width.
129 ******************************************************************************
130*/
131typedef enum
132{
133    M4ENCODER_SQCIF_Width = 128,    /**< SQCIF 128x96 */
134    M4ENCODER_QQVGA_Width = 160,    /**< QQVGA 160x120 */
135    M4ENCODER_QCIF_Width  = 176,    /**< QCIF 176x144 */
136    M4ENCODER_QVGA_Width  = 320,    /**< QVGA 320x240 */
137    M4ENCODER_CIF_Width   = 352,    /**< CIF 352x288 */
138    M4ENCODER_VGA_Width   = 640,    /**< VGA 640x480 */
139    M4ENCODER_SVGA_Width  = 800,    /**< SVGA 800x600 */
140    M4ENCODER_XGA_Width   = 1024,    /**< XGA 1024x768 */
141    M4ENCODER_XVGA_Width  = 1280,    /**< XVGA 1280x1024 */
142/* +PR LV5807 */
143    M4ENCODER_WVGA_Width  = 800,    /**< WVGA 800 x 480 */
144    M4ENCODER_NTSC_Width  = 720,    /**< NTSC 720 x 480 */
145/* -PR LV5807 */
146
147/* +CR Google */
148    M4ENCODER_640_360_Width       = 640,        /**< 640x360 */
149    // StageFright encoders require %16 resolution
150    M4ENCODER_854_480_Width     = 848, /**< 848x480 */
151    M4ENCODER_HD1280_Width         = 1280,            /**< 720p 1280x720 */
152    // StageFright encoders require %16 resolution
153    M4ENCODER_HD1080_Width      = 1088, /**< 720p 1088x720 */
154    M4ENCODER_HD960_Width          = 960            /**< 720p 960x720 */
155
156/* -CR Google */
157
158} M4ENCODER_FrameWidth;
159
160/**
161 ******************************************************************************
162 * enum        M4ENCODER_FrameHeight
163 * @brief    Thie enum defines the avalaible frame Height.
164 ******************************************************************************
165*/
166typedef enum
167{
168    M4ENCODER_SQCIF_Height = 96,    /**< SQCIF 128x96 */
169    M4ENCODER_QQVGA_Height = 120,    /**< QQVGA 160x120 */
170    M4ENCODER_QCIF_Height  = 144,    /**< QCIF 176x144 */
171    M4ENCODER_QVGA_Height  = 240,    /**< QVGA 320x240 */
172    M4ENCODER_CIF_Height   = 288,    /**< CIF 352x288 */
173    M4ENCODER_VGA_Height   = 480,    /**< VGA 340x480 */
174    M4ENCODER_SVGA_Height  = 600,    /**< SVGA 800x600 */
175    M4ENCODER_XGA_Height   = 768,    /**< XGA 1024x768 */
176    M4ENCODER_XVGA_Height  = 1024,    /**< XVGA 1280x1024 */
177/* +PR LV5807 */
178    M4ENCODER_WVGA_Height  = 480,    /**< WVGA 800 x 480 */
179    M4ENCODER_NTSC_Height  = 480,    /**< NTSC 720 x 480 */
180/* -PR LV5807 */
181
182/* +CR Google */
183    M4ENCODER_640_360_Height       = 360,        /**< 640x360 */
184    M4ENCODER_854_480_Height       = 480,        /**< 854x480 */
185    M4ENCODER_HD1280_Height     = 720,        /**< 720p 1280x720 */
186    M4ENCODER_HD1080_Height     = 720,        /**< 720p 1080x720 */
187    M4ENCODER_HD960_Height      = 720        /**< 720p 960x720 */
188
189/* -CR Google */
190} M4ENCODER_FrameHeight;
191
192/**
193 ******************************************************************************
194 * enum        M4ENCODER_Bitrate
195 * @brief    Thie enum defines the avalaible bitrates.
196 ******************************************************************************
197*/
198typedef enum
199{
200    M4ENCODER_k28_KBPS    = 28000,
201    M4ENCODER_k40_KBPS    = 40000,
202    M4ENCODER_k64_KBPS    = 64000,
203    M4ENCODER_k96_KBPS    = 96000,
204    M4ENCODER_k128_KBPS = 128000,
205    M4ENCODER_k192_KBPS = 192000,
206    M4ENCODER_k256_KBPS = 256000,
207    M4ENCODER_k384_KBPS = 384000,
208    M4ENCODER_k512_KBPS = 512000,
209    M4ENCODER_k800_KBPS = 800000
210
211} M4ENCODER_Bitrate;
212
213/* IMAGE STAB */
214
215/**
216 ******************************************************************************
217 * enum            M4ENCODER_StabMode
218 * @brief        The current mode of the stabilization filter.
219 ******************************************************************************
220*/
221typedef enum
222{
223    M4ENCODER_kStabOff = 0,        /**< stabilization filter is disabled */
224    M4ENCODER_kStabCentered,    /**< stabilization filter is enabled. */
225                                /**< Video input and output must have the same dimensions. Output
226                                    image will have black borders */
227    M4ENCODER_kStabGrabMore        /**< stabilization filter is enabled. */
228                                /**< Video input dimensions must be bigger than output. The ratio
229                                        is indicated by M4ENCODER_STAB_FILTER_CROP_PERCENTAGE */
230
231} M4ENCODER_StabMode;
232
233/**
234 ******************************************************************************
235 * enum            M4ENCODER_FrameMode
236 * @brief        Values to drive the encoder behaviour (type of frames produced)
237 ******************************************************************************
238*/
239typedef enum
240{
241    M4ENCODER_kNormalFrame = 0,   /**< let the encoder decide which type of frame to encode */
242    M4ENCODER_kLastFrame   = 1,   /**< force encoder the flush all its buffers because it is
243                                         last frame  */
244    M4ENCODER_kIFrame      = 2    /**< force encoder to generate an I frame */
245
246} M4ENCODER_FrameMode;
247
248/**
249 ******************************************************************************
250 * struct    M4ENCODER_Params
251 * @brief    This structure defines all the settings avalaible when encoding.
252 ******************************************************************************
253*/
254typedef struct
255{
256    /* Input */
257    M4ENCODER_InputFormat    InputFormat;        /**< Input video format (grabbing) */
258    M4ENCODER_FrameWidth    InputFrameWidth;    /**< Input Frame width (grabbing) */
259    M4ENCODER_FrameHeight    InputFrameHeight;    /**< Input Frame height (grabbing) */
260
261    /* Output */
262    M4ENCODER_FrameWidth    FrameWidth;            /**< Frame width  */
263    M4ENCODER_FrameHeight    FrameHeight;        /**< Frame height  */
264    M4ENCODER_Bitrate        Bitrate;            /**< Bitrate, see enum  */
265    M4ENCODER_FrameRate        FrameRate;            /**< Framerate, see enum  */
266    M4ENCODER_Format        Format;                /**< Video compression format, H263, MPEG4,
267                                                         MJPEG ...  */
268
269} M4ENCODER_Params;
270
271/**
272 ******************************************************************************
273 * struct    M4ENCODER_AdvancedParams
274 * @brief    This structure defines the advanced settings available for MPEG-4 encoding.
275 ******************************************************************************
276*/
277typedef struct
278{
279    /**
280     * Input parameters (grabber coupled with encoder): */
281    M4ENCODER_InputFormat    InputFormat;                /**< Input video format */
282    M4ENCODER_FrameWidth    InputFrameWidth;            /**< Input Frame width */
283    M4ENCODER_FrameHeight    InputFrameHeight;            /**< Input Frame height */
284
285    /**
286     * Common settings for H263 and MPEG-4: */
287    M4ENCODER_FrameWidth    FrameWidth;                    /**< Frame width  */
288    M4ENCODER_FrameHeight    FrameHeight;                /**< Frame height  */
289    M4OSA_UInt32            Bitrate;                    /**< Free value for the bitrate */
290    /**< Framerate (if set to M4ENCODER_kUSE_TIMESCALE use uiRateFactor & uiTimeScale instead) */
291    M4ENCODER_FrameRate        FrameRate;
292    /**< Video compression format: H263 or MPEG4 */
293    M4ENCODER_Format        Format;
294    M4OSA_UInt32            uiHorizontalSearchRange; /**< Set to 0 will use default value (15) */
295    M4OSA_UInt32            uiVerticalSearchRange;   /**< Set to 0 will use default value (15) */
296    /**< Set to 0 will use default value (0x7FFF i.e. let engine decide when to put an I) */
297    M4OSA_UInt32            uiStartingQuantizerValue;
298    /**< Enable if priority is quality, Disable if priority is framerate */
299    M4OSA_Bool                bInternalRegulation;
300    /**< Ratio between the encoder frame rate and the actual frame rate */
301    M4OSA_UInt8                uiRateFactor;
302    /**< I frames periodicity, set to 0 will use default value */
303    M4OSA_UInt32            uiIVopPeriod;
304    /**< Motion estimation [default=0 (all tools), disable=8 (no tool)] */
305    M4OSA_UInt8             uiMotionEstimationTools;
306
307    /**
308     * Settings for MPEG-4 only: */
309    M4OSA_UInt32            uiTimeScale;                /**< Free value for the timescale */
310    M4OSA_Bool                bErrorResilience;           /**< Disabled by default */
311    /**< Disabled by default (if enabled, bErrorResilience should be enabled too!) */
312    M4OSA_Bool                bDataPartitioning;
313    M4OSA_Bool              bAcPrediction;           /**< AC prediction [default=1, disable=0] */
314
315} M4ENCODER_AdvancedParams;
316
317/**
318 ******************************************************************************
319 * struct    M4ENCODER_StillPictureParams
320 * @brief    This structure defines all the settings avalaible when encoding still
321 *            picture.
322 ******************************************************************************
323*/
324typedef struct
325{
326    M4ENCODER_FrameWidth    FrameWidth;            /**< Frame width  */
327    M4ENCODER_FrameHeight    FrameHeight;        /**< Frame height  */
328    M4OSA_UInt32            Quality;            /**< Bitrate, see enum  */
329    M4ENCODER_Format        InputFormat;        /**< YUV 420 or 422  */
330    M4ENCODER_Format        Format;                /**< Video compression format, H263, MPEG4,
331                                                         MJPEG ...  */
332    M4OSA_Bool                PreProcessNeeded;    /**< Is the call to the VPP is necessary */
333    M4OSA_Bool                EncodingPerStripes;    /**< Is encoding per stripes */
334
335} M4ENCODER_StillPictureParams;
336
337/**
338 ******************************************************************************
339 * struct    M4ENCODER_Header
340 * @brief    This structure defines the buffer where the sequence header is put.
341 ******************************************************************************
342*/
343typedef struct
344{
345    M4OSA_MemAddr8    pBuf;        /**< Buffer for the header */
346    M4OSA_UInt32    Size;        /**< Size of the data */
347
348} M4ENCODER_Header;
349
350/**
351 ******************************************************************************
352 * enum    M4ENCODER_OptionID
353 * @brief This enums defines all avalaible options.
354 ******************************************************************************
355*/
356typedef enum
357{
358    /**< set the fragment size, option value is M4OSA_UInt32 type */
359    M4ENCODER_kOptionID_VideoFragmentSize    = M4OSA_OPTION_ID_CREATE (M4_WRITE,\
360                                                     M4ENCODER_COMMON, 0x01),
361
362    /**< set the stabilization filtering, option value is M4ENCODER_StabMode type */
363    M4ENCODER_kOptionID_ImageStabilization    = M4OSA_OPTION_ID_CREATE (M4_WRITE,\
364                                                          M4ENCODER_COMMON, 0x02),
365
366    /**< prevent writting of any AU, option value is M4OSA_Bool type */
367    M4ENCODER_kOptionID_InstantStop            = M4OSA_OPTION_ID_CREATE (M4_WRITE,\
368                                                         M4ENCODER_COMMON, 0x03),
369
370    /**< get the DSI (encoder header) generated by the encoder */
371    M4ENCODER_kOptionID_EncoderHeader        = M4OSA_OPTION_ID_CREATE (M4_READ ,\
372                                                             M4ENCODER_COMMON, 0x04),
373/*+ CR LV6775 -H.264 Trimming  */
374
375    M4ENCODER_kOptionID_SetH264ProcessNALUfctsPtr= M4OSA_OPTION_ID_CREATE (M4_READ ,\
376                                                             M4ENCODER_COMMON, 0x05),
377    M4ENCODER_kOptionID_H264ProcessNALUContext        = M4OSA_OPTION_ID_CREATE (M4_READ ,\
378                                                             M4ENCODER_COMMON, 0x06)
379/*-CR LV6775 -H.264 Trimming  */
380} M4ENCODER_OptionID;
381
382/*+ CR LV6775 -H.264 Trimming  */
383typedef M4OSA_ERR (H264MCS_ProcessEncodedNALU_fct)(M4OSA_Void*ainstance,M4OSA_UInt8* inbuff,
384                               M4OSA_Int32  inbuf_size,
385                               M4OSA_UInt8 *outbuff, M4OSA_Int32 *outbuf_size);
386//*- CR LV6775 -H.264 Trimming  */
387
388typedef M4OSA_Void* M4ENCODER_Context;
389
390typedef M4OSA_ERR (M4ENCODER_init) (
391        M4ENCODER_Context* pContext,
392        M4WRITER_DataInterface* pWriterDataInterface,
393        M4VPP_apply_fct* pVPPfct,
394        M4VPP_Context pVPPctxt,
395        M4OSA_Void* pExternalAPI,
396        M4OSA_Void* pUserData
397);
398
399typedef M4OSA_ERR (M4ENCODER_open) (
400        M4ENCODER_Context pContext,
401        M4SYS_AccessUnit* pAU,
402        M4OSA_Void* pParams     /* Can be M4ENCODER_Params, M4ENCODER_AdvancedParams or
403                                    M4ENCODER_StillPictureParams */
404);
405
406typedef M4OSA_ERR (M4ENCODER_start) (M4ENCODER_Context pContext);
407typedef M4OSA_ERR (M4ENCODER_stop) (M4ENCODER_Context pContext);
408typedef M4OSA_ERR (M4ENCODER_pause) (M4ENCODER_Context pContext);
409typedef M4OSA_ERR (M4ENCODER_resume) (M4ENCODER_Context pContext);
410typedef M4OSA_ERR (M4ENCODER_close) (M4ENCODER_Context pContext);
411typedef M4OSA_ERR (M4ENCODER_cleanup) (M4ENCODER_Context pContext);
412typedef M4OSA_ERR (M4ENCODER_regulBitRate) (M4ENCODER_Context pContext);
413
414typedef M4OSA_ERR (M4ENCODER_encode) (
415        M4ENCODER_Context pContext,
416        M4VIFI_ImagePlane* pInPlane,
417        M4OSA_Double Cts,
418        M4ENCODER_FrameMode FrameMode
419);
420
421typedef M4OSA_ERR (M4ENCODER_setOption)    (
422        M4ENCODER_Context pContext,
423        M4OSA_UInt32 optionID,
424        M4OSA_DataOption optionValue
425);
426
427typedef M4OSA_ERR (M4ENCODER_getOption)    (
428        M4ENCODER_Context pContext,
429        M4OSA_UInt32 optionID,
430        M4OSA_DataOption optionValue
431);
432
433/**
434 ******************************************************************************
435 * struct    M4ENCODER_GlobalInterface
436 * @brief    Defines all the functions required for an encoder shell.
437 ******************************************************************************
438*/
439
440typedef struct _M4ENCODER_GlobalInterface
441{
442    M4ENCODER_init*                pFctInit;
443    M4ENCODER_open*                pFctOpen;
444
445    M4ENCODER_start*            pFctStart;          /* Grabber mode */
446    M4ENCODER_stop*                pFctStop;           /* Grabber mode */
447
448    M4ENCODER_pause*            pFctPause;          /* Grabber mode */
449    M4ENCODER_resume*            pFctResume;         /* Grabber mode */
450
451    M4ENCODER_close*            pFctClose;
452    M4ENCODER_cleanup*            pFctCleanup;
453
454    M4ENCODER_regulBitRate*     pFctRegulBitRate;
455    M4ENCODER_encode*            pFctEncode;         /* Standalone mode */
456
457    M4ENCODER_setOption*        pFctSetOption;
458    M4ENCODER_getOption*        pFctGetOption;
459} M4ENCODER_GlobalInterface;
460
461
462#ifdef __cplusplus
463}
464#endif /* __cplusplus */
465
466#endif /*__M4ENCODER_COMMON_H__*/
467
468