/*
* Copyright (C) 2011 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
******************************************************************************
* @file M4PTO3GPP_API.h
* @brief The Pictures to 3GPP Converter.
* @note M4PTO3GPP produces 3GPP compliant audio/video files
* from an AMR NB audio file and raw pictures into a MPEG-4/h263 3GPP file.
******************************************************************************
*/
#ifndef __M4PTO3GPP_API_H__
#define __M4PTO3GPP_API_H__
/**
* OSAL basic types and errors */
#include "M4OSA_Types.h"
#include "M4OSA_Error.h"
/**
* OSAL types for file access */
#include "M4OSA_FileReader.h"
#include "M4OSA_FileWriter.h"
/**
* Definition of M4_VersionInfo */
#include "M4TOOL_VersionInfo.h"
/**
* Definitions of M4VIFI_ImagePlane */
#include "M4VIFI_FiltersAPI.h"
/**
* Common definitions of video editing components */
#include "M4_VideoEditingCommon.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* Public type of the M4PTO3GPP context */
typedef M4OSA_Void* M4PTO3GPP_Context;
/**
******************************************************************************
* enum M4PTO3GPP_ReplaceAudioMode
* @brief This enumeration defines the way the audio is managed if it is shorter than the video
******************************************************************************
*/
typedef enum
{
M4PTO3GPP_kAudioPaddingMode_None = 0, /**< Audio track is kept shorter than the video track*/
M4PTO3GPP_kAudioPaddingMode_Silence, /**< If audio is shorter, silence is added at the end*/
M4PTO3GPP_kAudioPaddingMode_Loop /**< If audio is shorter, loop back to the beginning
when the whole track has been processed */
} M4PTO3GPP_AudioPaddingMode;
/**
******************************************************************************
* struct M4PTO3GPP_OutputFileMaxSize
* @brief Defines the maximum size of the 3GPP file produced by the PTO3GPP
******************************************************************************
*/
typedef enum
{
M4PTO3GPP_k50_KB, /**< Output 3GPP file size is limited to 50 Kbytes */
M4PTO3GPP_k75_KB, /**< Output 3GPP file size is limited to 75 Kbytes */
M4PTO3GPP_k100_KB, /**< Output 3GPP file size is limited to 100 Kbytes */
M4PTO3GPP_k150_KB, /**< Output 3GPP file size is limited to 150 Kbytes */
M4PTO3GPP_k200_KB, /**< Output 3GPP file size is limited to 200 Kbytes */
M4PTO3GPP_k300_KB, /**< Output 3GPP file size is limited to 300 Kbytes */
M4PTO3GPP_k400_KB, /**< Output 3GPP file size is limited to 400 Kbytes */
M4PTO3GPP_k500_KB, /**< Output 3GPP file size is limited to 500 Kbytes */
M4PTO3GPP_kUNLIMITED=-1 /**< Output 3GPP file size is not limited */
} M4PTO3GPP_OutputFileMaxSize;
/**
******************************************************************************
* M4OSA_ERR (M4PTO3GPP_PictureCallbackFct) (M4OSA_Void* pPictureCtxt,
* M4VIFI_ImagePlane* pImagePlanes, M4OSA_Double* pPictureDuration);
* @brief The integrator must implement a function following this prototype.
* Its goal is to feed the PTO3GPP with YUV420 pictures.
*
* @note This function is given to the PTO3GPP in the M4PTO3GPP_Params structure
* @param pContext (IN) The integrator own context
* @param pImagePlanes(IN/OUT) Pointer to an array of three valid image planes
* @param pPictureDuration(OUT) Duration of the returned picture
*
* @return M4NO_ERROR: No error
* @return M4PTO3GPP_WAR_LAST_PICTURE: The returned image is the last one
* @return M4ERR_PARAMETER: At least one of the function parameters is null (bebug only)
******************************************************************************
*/
typedef M4OSA_ERR (M4PTO3GPP_PictureCallbackFct) (M4OSA_Void* pPictureCtxt,
M4VIFI_ImagePlane* pImagePlanes,
M4OSA_Double* pPictureDuration);
/**
******************************************************************************
* struct M4PTO3GPP_Params
* @brief M4PTO3GPP parameters definition
******************************************************************************
*/
typedef struct
{
/**< Output video compression format, H263 or MPEG4 */
M4VIDEOEDITING_VideoFormat OutputVideoFormat;
/**< Output frame size : SQCIF to VGA*/
M4VIDEOEDITING_VideoFrameSize OutputVideoFrameSize;
/**< Targeted Output bit-rate, see enum*/
M4VIDEOEDITING_Bitrate OutputVideoBitrate;
/**< Maximum size of the output 3GPP file, see enum */
M4PTO3GPP_OutputFileMaxSize OutputFileMaxSize;
/**< Callback function to be called by the PTO3GPP to get the input pictures*/
M4PTO3GPP_PictureCallbackFct* pPictureCallbackFct;
/**< Context to be given as third argument of the picture callback function call*/
M4OSA_Void* pPictureCallbackCtxt;
/**< File descriptor of the input audio track file */
M4OSA_Void* pInputAudioTrackFile;
/**< Format of the audio file */
M4VIDEOEDITING_FileType AudioFileFormat;
/**< Type of processing to apply when audio is shorter than video*/
M4PTO3GPP_AudioPaddingMode AudioPaddingMode;
/**< File descriptor of the output 3GPP file */
M4OSA_Void* pOutput3gppFile;
/**< File descriptor of the temporary file to store metadata ("moov.bin") */
M4OSA_Void* pTemporaryFile;
/**< Number of input YUV frames to encode */
M4OSA_UInt32 NbVideoFrames;
M4OSA_Int32 videoProfile;
M4OSA_Int32 videoLevel;
} M4PTO3GPP_Params;
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_GetVersion(M4_VersionInfo* pVersionInfo);
* @brief Get the M4PTO3GPP version.
* @note Can be called anytime. Do not need any context.
* @param pVersionInfo (OUT) Pointer to a version info structure
* @return M4NO_ERROR: No error
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_GetVersion(M4_VersionInfo* pVersionInfo);
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_Init(M4PTO3GPP_Context* pContext);
* @brief Initializes the M4PTO3GPP (allocates an execution context).
* @note
* @param pContext (OUT) Pointer on the M4PTO3GPP context to allocate
* @param pFileReadPtrFct (IN) Pointer to OSAL file reader functions
* @param pFileWritePtrFct (IN) Pointer to OSAL file writer functions
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pContext is M4OSA_NULL
* @return M4ERR_ALLOC: The context structure could not be allocated
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_Init(M4PTO3GPP_Context* pContext, M4OSA_FileReadPointer* pFileReadPtrFct,
M4OSA_FileWriterPointer* pFileWritePtrFct);
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_Open(M4PTO3GPP_Context pContext, M4PTO3GPP_Params* pParams);
* @brief Set the M4PTO3GPP input and output files.
* @note It opens the input file, but the output file may not be created yet.
* @param pContext (IN) M4PTO3GPP context
* @param pParams (IN) Pointer to the parameters for the PTO3GPP.
* @note The pointed structure can be de-allocated after this function returns because
* it is internally copied by the PTO3GPP
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_STATE: M4PTO3GPP is not in an appropriate state
* for this function to be called
* @return M4ERR_ALLOC: There is no more available memory
* @return ERR_PTO3GPP_INVALID_VIDEO_FRAME_SIZE_FOR_H263 The output video frame
* size parameter is incompatible with H263 encoding
* @return ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_FORMAT
* The output video format parameter is undefined
* @return ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_BITRATE
* The output video bit-rate parameter is undefined
* @return ERR_PTO3GPP_UNDEFINED_OUTPUT_VIDEO_FRAME_SIZE
* The output video frame size parameter is undefined
* @return ERR_PTO3GPP_UNDEFINED_OUTPUT_FILE_SIZE
* The output file size parameter is undefined
* @return ERR_PTO3GPP_UNDEFINED_AUDIO_PADDING
* The output audio padding parameter is undefined
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_Open(M4PTO3GPP_Context pContext, M4PTO3GPP_Params* pParams);
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_Step(M4PTO3GPP_Context pContext);
* @brief Perform one step of trancoding.
* @note
* @param pContext (IN) M4PTO3GPP context
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pContext is M4OSA_NULL
* @return M4ERR_STATE: M4PTO3GPP is not in an appropriate state
* for this function to be called
* @return M4PTO3GPP_WAR_END_OF_PROCESSING: Encoding completed
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_Step(M4PTO3GPP_Context pContext);
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_Close(M4PTO3GPP_Context pContext);
* @brief Finish the M4PTO3GPP transcoding.
* @note The output 3GPP file is ready to be played after this call
* @param pContext (IN) M4PTO3GPP context
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pContext is M4OSA_NULL
* @return M4ERR_STATE: M4PTO3GPP is not in an appropriate state
* for this function to be called
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_Close(M4PTO3GPP_Context pContext);
/**
******************************************************************************
* M4OSA_ERR M4PTO3GPP_CleanUp(M4PTO3GPP_Context pContext);
* @brief Free all resources used by the M4PTO3GPP.
* @note The context is no more valid after this call
* @param pContext (IN) M4PTO3GPP context
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pContext is M4OSA_NULL
******************************************************************************
*/
M4OSA_ERR M4PTO3GPP_CleanUp(M4PTO3GPP_Context pContext);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* __M4PTO3GPP_API_H__ */