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