M4PTO3GPP_API.h revision 0a389ab70db304fb840e33f33781ecc0503eae3c 
1/*
2 * Copyright (C) 2004-2011 NXP Software
3 * Copyright (C) 2011 The Android Open Source Project
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17/**
18 ******************************************************************************
19 * @file    M4PTO3GPP_API.h
20 * @brief    The Pictures to 3GPP Converter.
21 * @note    M4PTO3GPP produces 3GPP compliant audio/video  files
22 *            from an AMR NB audio file and raw pictures into a MPEG-4/h263 3GPP file.
23 ******************************************************************************
24 */
25
26#ifndef __M4PTO3GPP_API_H__
27#define __M4PTO3GPP_API_H__
28
29/**
30 *    OSAL basic types and errors */
31#include "M4OSA_Types.h"
32#include "M4OSA_Error.h"
33
34/**
35 *    OSAL types for file access */
36#include "M4OSA_FileReader.h"
37#include "M4OSA_FileWriter.h"
38
39/**
40 *    Definition of M4_VersionInfo */
41#include "M4TOOL_VersionInfo.h"
42
43/**
44 * Definitions of M4VIFI_ImagePlane */
45#include "M4VIFI_FiltersAPI.h"
46
47/**
48 * Common definitions of video editing components */
49#include "M4_VideoEditingCommon.h"
50
51
52#ifdef __cplusplus
53extern "C" {
54#endif
55
56/**
57 *    Public type of the M4PTO3GPP context */
58typedef M4OSA_Void* M4PTO3GPP_Context;
59
60
61/**
62 ******************************************************************************
63 * enum        M4PTO3GPP_ReplaceAudioMode
64 * @brief    This enumeration defines the way the audio is managed if it is shorter than the video
65 ******************************************************************************
66 */
67typedef enum
68{
69    M4PTO3GPP_kAudioPaddingMode_None = 0,  /**< Audio track is kept shorter than the video track*/
70    M4PTO3GPP_kAudioPaddingMode_Silence,   /**< If audio is shorter, silence is added at the end*/
71    M4PTO3GPP_kAudioPaddingMode_Loop       /**< If audio is shorter, loop back to the beginning
72                                                when the whole track has been processed */
73} M4PTO3GPP_AudioPaddingMode;
74
75
76/**
77 ******************************************************************************
78 * struct    M4PTO3GPP_OutputFileMaxSize
79 * @brief    Defines the maximum size of the 3GPP file produced by the PTO3GPP
80 ******************************************************************************
81 */
82typedef enum
83{
84    M4PTO3GPP_k50_KB,            /**< Output 3GPP file size is limited to 50 Kbytes  */
85    M4PTO3GPP_k75_KB,            /**< Output 3GPP file size is limited to 75 Kbytes  */
86    M4PTO3GPP_k100_KB,           /**< Output 3GPP file size is limited to 100 Kbytes */
87    M4PTO3GPP_k150_KB,           /**< Output 3GPP file size is limited to 150 Kbytes */
88    M4PTO3GPP_k200_KB,           /**< Output 3GPP file size is limited to 200 Kbytes */
89    M4PTO3GPP_k300_KB,           /**< Output 3GPP file size is limited to 300 Kbytes */
90    M4PTO3GPP_k400_KB,           /**< Output 3GPP file size is limited to 400 Kbytes */
91    M4PTO3GPP_k500_KB,           /**< Output 3GPP file size is limited to 500 Kbytes */
92    M4PTO3GPP_kUNLIMITED=-1      /**< Output 3GPP file size is not limited           */
93} M4PTO3GPP_OutputFileMaxSize;
94
95/**
96 ******************************************************************************
97 * M4OSA_ERR (M4PTO3GPP_PictureCallbackFct) (M4OSA_Void* pPictureCtxt,
98 * M4VIFI_ImagePlane* pImagePlanes, M4OSA_Double* pPictureDuration);
99 * @brief    The integrator must implement a function following this prototype.
100 *            Its goal is to feed the PTO3GPP with YUV420 pictures.
101 *
102 * @note    This function is given to the PTO3GPP in the M4PTO3GPP_Params structure
103 * @param    pContext    (IN) The integrator own context
104 * @param    pImagePlanes(IN/OUT) Pointer to an array of three valid image planes
105 * @param    pPictureDuration(OUT) Duration of the returned picture
106 *
107 * @return    M4NO_ERROR:    No error
108 * @return    M4PTO3GPP_WAR_LAST_PICTURE: The returned image is the last one
109 * @return    M4ERR_PARAMETER: At least one of the function parameters is null (bebug only)
110 ******************************************************************************
111 */
112typedef M4OSA_ERR (M4PTO3GPP_PictureCallbackFct) (M4OSA_Void* pPictureCtxt,
113                                                  M4VIFI_ImagePlane* pImagePlanes,
114                                                  M4OSA_Double* pPictureDuration);
115
116
117/**
118 ******************************************************************************
119 * struct    M4PTO3GPP_Params
120 * @brief    M4PTO3GPP parameters definition
121 ******************************************************************************
122 */
123typedef struct
124{
125    /**< Output video compression format, H263 or MPEG4 */
126    M4VIDEOEDITING_VideoFormat      OutputVideoFormat;
127    /**< Output frame size : SQCIF to VGA*/
128    M4VIDEOEDITING_VideoFrameSize   OutputVideoFrameSize;
129    /**< Targeted Output bit-rate, see enum*/
130    M4VIDEOEDITING_Bitrate          OutputVideoBitrate;
131    /**< Maximum size of the output 3GPP file, see enum */
132    M4PTO3GPP_OutputFileMaxSize     OutputFileMaxSize;
133    /**< Callback function to be called by the PTO3GPP to get the input pictures*/
134    M4PTO3GPP_PictureCallbackFct*   pPictureCallbackFct;
135    /**< Context to be given as third argument of the picture callback function call*/
136    M4OSA_Void*                     pPictureCallbackCtxt;
137    /**< File descriptor of the input audio track file */
138    M4OSA_Void*                     pInputAudioTrackFile;
139    /**< Format of the audio file */
140    M4VIDEOEDITING_FileType         AudioFileFormat;
141    /**< Type of processing to apply when audio is shorter than video*/
142    M4PTO3GPP_AudioPaddingMode      AudioPaddingMode;
143    /**< File descriptor of the output 3GPP file */
144    M4OSA_Void*                     pOutput3gppFile;
145     /**< File descriptor of the temporary file to store metadata ("moov.bin") */
146    M4OSA_Void*                     pTemporaryFile;
147    /**< Number of input YUV frames to encode */
148    M4OSA_UInt32                    NbVideoFrames;
149} M4PTO3GPP_Params;
150
151/**
152 ******************************************************************************
153 * M4OSA_ERR M4PTO3GPP_GetVersion(M4_VersionInfo* pVersionInfo);
154 * @brief    Get the M4PTO3GPP version.
155 * @note    Can be called anytime. Do not need any context.
156 * @param    pVersionInfo        (OUT) Pointer to a version info structure
157 * @return    M4NO_ERROR:            No error
158 ******************************************************************************
159 */
160M4OSA_ERR M4PTO3GPP_GetVersion(M4_VersionInfo* pVersionInfo);
161
162/**
163 ******************************************************************************
164 * M4OSA_ERR M4PTO3GPP_Init(M4PTO3GPP_Context* pContext);
165 * @brief    Initializes the M4PTO3GPP (allocates an execution context).
166 * @note
167 * @param    pContext            (OUT) Pointer on the M4PTO3GPP context to allocate
168 * @param   pFileReadPtrFct     (IN) Pointer to OSAL file reader functions
169 * @param   pFileWritePtrFct    (IN) Pointer to OSAL file writer functions
170 * @return    M4NO_ERROR:            No error
171 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL
172 * @return    M4ERR_ALLOC:        The context structure could not be allocated
173 ******************************************************************************
174 */
175M4OSA_ERR M4PTO3GPP_Init(M4PTO3GPP_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
176                         M4OSA_FileWriterPointer* pFileWritePtrFct);
177
178/**
179 ******************************************************************************
180 * M4OSA_ERR M4PTO3GPP_Open(M4PTO3GPP_Context pContext, M4PTO3GPP_Params* pParams);
181 * @brief    Set the M4PTO3GPP input and output files.
182 * @note    It opens the input file, but the output file may not be created yet.
183 * @param    pContext            (IN) M4PTO3GPP context
184 * @param    pParams                (IN) Pointer to the parameters for the PTO3GPP.
185 * @note    The pointed structure can be de-allocated after this function returns because
186 *            it is internally copied by the PTO3GPP
187 * @return    M4NO_ERROR:            No error
188 * @return    M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL
189 * @return    M4ERR_STATE:        M4PTO3GPP is not in an appropriate state
190 *                                for this function to be called
191 * @return    M4ERR_ALLOC:        There is no more available memory
192 * @return    ERR_PTO3GPP_INVALID_VIDEO_FRAME_SIZE_FOR_H263 The output video frame
193 *                                size parameter is incompatible with H263 encoding
194 * @return    ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_FORMAT
195 *                          The output video format  parameter is undefined
196 * @return    ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_BITRATE
197 *                        The output video bit-rate parameter is undefined
198 * @return    ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_FRAME_SIZE
199 *                        The output video frame size parameter is undefined
200 * @return    ERR_PTO3GPP_UNDEFINED_OUTPUT_FILE_SIZE
201 *                          The output file size parameter is undefined
202 * @return    ERR_PTO3GPP_UNDEFINED_AUDIO_PADDING
203 *                        The output audio padding parameter is undefined
204 ******************************************************************************
205 */
206M4OSA_ERR M4PTO3GPP_Open(M4PTO3GPP_Context pContext, M4PTO3GPP_Params* pParams);
207
208/**
209 ******************************************************************************
210 * M4OSA_ERR M4PTO3GPP_Step(M4PTO3GPP_Context pContext);
211 * @brief    Perform one step of trancoding.
212 * @note
213 * @param    pContext            (IN) M4PTO3GPP context
214 * @return    M4NO_ERROR:            No error
215 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL
216 * @return    M4ERR_STATE:        M4PTO3GPP is not in an appropriate state
217 *                                for this function to be called
218 * @return    M4PTO3GPP_WAR_END_OF_PROCESSING:    Encoding completed
219 ******************************************************************************
220 */
221M4OSA_ERR M4PTO3GPP_Step(M4PTO3GPP_Context pContext);
222
223/**
224 ******************************************************************************
225 * M4OSA_ERR M4PTO3GPP_Close(M4PTO3GPP_Context pContext);
226 * @brief    Finish the M4PTO3GPP transcoding.
227 * @note    The output 3GPP file is ready to be played after this call
228 * @param    pContext            (IN) M4PTO3GPP context
229 * @return    M4NO_ERROR:            No error
230 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL
231 * @return    M4ERR_STATE:        M4PTO3GPP is not in an appropriate state
232 *                                for this function to be called
233 ******************************************************************************
234 */
235M4OSA_ERR M4PTO3GPP_Close(M4PTO3GPP_Context pContext);
236
237/**
238 ******************************************************************************
239 * M4OSA_ERR M4PTO3GPP_CleanUp(M4PTO3GPP_Context pContext);
240 * @brief    Free all resources used by the M4PTO3GPP.
241 * @note    The context is no more valid after this call
242 * @param    pContext            (IN) M4PTO3GPP context
243 * @return    M4NO_ERROR:            No error
244 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL
245 ******************************************************************************
246 */
247M4OSA_ERR M4PTO3GPP_CleanUp(M4PTO3GPP_Context pContext);
248
249
250#ifdef __cplusplus
251}
252#endif /* __cplusplus */
253
254#endif /* __M4PTO3GPP_API_H__ */
255
256