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    M4OSA_Int32   videoProfile;
149    M4OSA_Int32   videoLevel;
150} M4PTO3GPP_Params;
151
152/**
153 ******************************************************************************
154 * M4OSA_ERR M4PTO3GPP_GetVersion(M4_VersionInfo* pVersionInfo);
155 * @brief    Get the M4PTO3GPP version.
156 * @note    Can be called anytime. Do not need any context.
157 * @param    pVersionInfo        (OUT) Pointer to a version info structure
158 * @return    M4NO_ERROR:            No error
159 ******************************************************************************
160 */
161M4OSA_ERR M4PTO3GPP_GetVersion(M4_VersionInfo* pVersionInfo);
162
163/**
164 ******************************************************************************
165 * M4OSA_ERR M4PTO3GPP_Init(M4PTO3GPP_Context* pContext);
166 * @brief    Initializes the M4PTO3GPP (allocates an execution context).
167 * @note
168 * @param    pContext            (OUT) Pointer on the M4PTO3GPP context to allocate
169 * @param   pFileReadPtrFct     (IN) Pointer to OSAL file reader functions
170 * @param   pFileWritePtrFct    (IN) Pointer to OSAL file writer functions
171 * @return    M4NO_ERROR:            No error
172 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL
173 * @return    M4ERR_ALLOC:        The context structure could not be allocated
174 ******************************************************************************
175 */
176M4OSA_ERR M4PTO3GPP_Init(M4PTO3GPP_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
177                         M4OSA_FileWriterPointer* pFileWritePtrFct);
178
179/**
180 ******************************************************************************
181 * M4OSA_ERR M4PTO3GPP_Open(M4PTO3GPP_Context pContext, M4PTO3GPP_Params* pParams);
182 * @brief    Set the M4PTO3GPP input and output files.
183 * @note    It opens the input file, but the output file may not be created yet.
184 * @param    pContext            (IN) M4PTO3GPP context
185 * @param    pParams                (IN) Pointer to the parameters for the PTO3GPP.
186 * @note    The pointed structure can be de-allocated after this function returns because
187 *            it is internally copied by the PTO3GPP
188 * @return    M4NO_ERROR:            No error
189 * @return    M4ERR_PARAMETER:    At least one parameter is M4OSA_NULL
190 * @return    M4ERR_STATE:        M4PTO3GPP is not in an appropriate state
191 *                                for this function to be called
192 * @return    M4ERR_ALLOC:        There is no more available memory
193 * @return    ERR_PTO3GPP_INVALID_VIDEO_FRAME_SIZE_FOR_H263 The output video frame
194 *                                size parameter is incompatible with H263 encoding
195 * @return    ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_FORMAT
196 *                          The output video format  parameter is undefined
197 * @return    ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_BITRATE
198 *                        The output video bit-rate parameter is undefined
199 * @return    ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_FRAME_SIZE
200 *                        The output video frame size parameter is undefined
201 * @return    ERR_PTO3GPP_UNDEFINED_OUTPUT_FILE_SIZE
202 *                          The output file size parameter is undefined
203 * @return    ERR_PTO3GPP_UNDEFINED_AUDIO_PADDING
204 *                        The output audio padding parameter is undefined
205 ******************************************************************************
206 */
207M4OSA_ERR M4PTO3GPP_Open(M4PTO3GPP_Context pContext, M4PTO3GPP_Params* pParams);
208
209/**
210 ******************************************************************************
211 * M4OSA_ERR M4PTO3GPP_Step(M4PTO3GPP_Context pContext);
212 * @brief    Perform one step of trancoding.
213 * @note
214 * @param    pContext            (IN) M4PTO3GPP context
215 * @return    M4NO_ERROR:            No error
216 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL
217 * @return    M4ERR_STATE:        M4PTO3GPP is not in an appropriate state
218 *                                for this function to be called
219 * @return    M4PTO3GPP_WAR_END_OF_PROCESSING:    Encoding completed
220 ******************************************************************************
221 */
222M4OSA_ERR M4PTO3GPP_Step(M4PTO3GPP_Context pContext);
223
224/**
225 ******************************************************************************
226 * M4OSA_ERR M4PTO3GPP_Close(M4PTO3GPP_Context pContext);
227 * @brief    Finish the M4PTO3GPP transcoding.
228 * @note    The output 3GPP file is ready to be played after this call
229 * @param    pContext            (IN) M4PTO3GPP context
230 * @return    M4NO_ERROR:            No error
231 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL
232 * @return    M4ERR_STATE:        M4PTO3GPP is not in an appropriate state
233 *                                for this function to be called
234 ******************************************************************************
235 */
236M4OSA_ERR M4PTO3GPP_Close(M4PTO3GPP_Context pContext);
237
238/**
239 ******************************************************************************
240 * M4OSA_ERR M4PTO3GPP_CleanUp(M4PTO3GPP_Context pContext);
241 * @brief    Free all resources used by the M4PTO3GPP.
242 * @note    The context is no more valid after this call
243 * @param    pContext            (IN) M4PTO3GPP context
244 * @return    M4NO_ERROR:            No error
245 * @return    M4ERR_PARAMETER:    pContext is M4OSA_NULL
246 ******************************************************************************
247 */
248M4OSA_ERR M4PTO3GPP_CleanUp(M4PTO3GPP_Context pContext);
249
250
251#ifdef __cplusplus
252}
253#endif /* __cplusplus */
254
255#endif /* __M4PTO3GPP_API_H__ */
256
257