/*
* 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.
*/
#ifndef __M4XVSS_API_H__
#define __M4XVSS_API_H__
#ifdef __cplusplus
extern "C" {
#endif
/**
******************************************************************************
* @file M4xVSS_API.h
* @brief API of Video Studio 2.1
* @note
******************************************************************************
*/
#define M4VSS_SUPPORT_EXTENDED_FEATURES
#include "M4VSS3GPP_API.h"
#include "M4VSS3GPP_Extended_API.h"
#include "M4DECODER_Common.h"
/* Errors codes */
/**
* End of analyzing => the user can call M4xVSS_PreviewStart or M4xVSS_SaveStart */
#define M4VSS3GPP_WAR_ANALYZING_DONE M4OSA_ERR_CREATE( M4_WAR, M4VS, 0x0001)
/**
* End of preview generating => the user can launch vps to see preview. Once preview is over,
the user must call M4xVSS_PreviewStop() to be able to save edited file, or to call another
M4xVSS_SendCommand() */
#define M4VSS3GPP_WAR_PREVIEW_READY M4OSA_ERR_CREATE( M4_WAR, M4VS, 0x0002)
/**
* End of saved file generation => the user must call M4xVSS_SaveStop() */
#define M4VSS3GPP_WAR_SAVING_DONE M4OSA_ERR_CREATE( M4_WAR, M4VS, 0x0003)
/**
* Transcoding is necessary to go further -> if the user does not want to continue,
he must call M4xVSS_sendCommand() */
#define M4VSS3GPP_WAR_TRANSCODING_NECESSARY M4OSA_ERR_CREATE( M4_WAR, M4VS, 0x0004)
/**
* In case of MMS, the output file size won't be reached */
#define M4VSS3GPP_WAR_OUTPUTFILESIZE_EXCEED M4OSA_ERR_CREATE( M4_WAR, M4VS, 0x0005)
/**
* JPG input file dimensions are too high */
#define M4VSS3GPP_ERR_JPG_TOO_BIG M4OSA_ERR_CREATE( M4_ERR, M4VS, 0x0001)
/**
* UTF Conversion, warning on the size of the temporary converted buffer*/
#define M4xVSSWAR_BUFFER_OUT_TOO_SMALL M4OSA_ERR_CREATE( M4_WAR, M4VS, 0x0006)
/**
* SWIKAR :Error whan NO_MORE_SPACE*/
#define M4xVSSERR_NO_MORE_SPACE M4OSA_ERR_CREATE( M4_ERR, M4VS, 0x0007)
/**
******************************************************************************
* enum M4xVSS_VideoEffectType
* @brief This enumeration defines the video effect types of the xVSS
******************************************************************************
*/
typedef enum
{
M4xVSS_kVideoEffectType_BlackAndWhite = M4VSS3GPP_kVideoEffectType_External+1, /* 257 */
M4xVSS_kVideoEffectType_Pink, /* 258 */
M4xVSS_kVideoEffectType_Green, /* 259 */
M4xVSS_kVideoEffectType_Sepia, /* 260 */
M4xVSS_kVideoEffectType_Negative, /* 261 */
M4xVSS_kVideoEffectType_Framing, /* 262 */
M4xVSS_kVideoEffectType_Text, /* Text overlay */ /* 263 */
M4xVSS_kVideoEffectType_ZoomIn, /* 264 */
M4xVSS_kVideoEffectType_ZoomOut, /* 265 */
M4xVSS_kVideoEffectType_Fifties, /*266 */
M4xVSS_kVideoEffectType_ColorRGB16, /*267 */
M4xVSS_kVideoEffectType_Gradient /*268*/
} M4xVSS_VideoEffectType;
/**
******************************************************************************
* enum M4xVSS_VideoTransitionType
* @brief This enumeration defines the video effect that can be applied during a transition.
******************************************************************************
*/
typedef enum
{
M4xVSS_kVideoTransitionType_External = M4VSS3GPP_kVideoTransitionType_External, /*256*/
M4xVSS_kVideoTransitionType_AlphaMagic,
M4xVSS_kVideoTransitionType_SlideTransition,
M4xVSS_kVideoTransitionType_FadeBlack
} M4xVSS_VideoTransitionType;
/**
******************************************************************************
* struct M4xVSS_PreviewSettings
* @brief This structure gathers all the information needed by the VPS for preview
******************************************************************************
*/
typedef struct
{
M4OSA_Void *p3gpPreviewFile;
M4OSA_Void *pPCMFile;
M4VIDEOEDITING_AudioSamplingFrequency outPCM_ASF;
M4OSA_Bool bAudioMono;
M4VSS3GPP_EffectSettings *Effects;
M4OSA_UInt8 nbEffects;
} M4xVSS_PreviewSettings;
/**
******************************************************************************
* prototype M4xVSS_toUTF8Fct
* @brief This prototype defines the function implemented by the integrator
* to convert a string encoded in any format to an UTF8 string.
* @note
*
* @param pBufferIn IN Buffer containing the string to convert to UTF8
* @param pBufferOut IN Buffer containing the UTF8 converted string
* @param bufferOutSize IN/OUT IN: Size of the given output buffer
* OUT: Size of the converted buffer
*
******************************************************************************
*/
typedef M4OSA_ERR (*M4xVSS_toUTF8Fct)
(
M4OSA_Void *pBufferIn,
M4OSA_UInt8 *pBufferOut,
M4OSA_UInt32 *bufferOutSize
);
/**
******************************************************************************
* prototype M4xVSS_fromUTF8Fct
* @brief This prototype defines the function implemented by the integrator
* to convert an UTF8 string to a string encoded in any format.
* @note
*
* @param pBufferIn IN Buffer containing the UTF8 string to convert
* to the desired format.
* @param pBufferOut IN Buffer containing the converted string
* @param bufferOutSize IN/OUT IN: Size of the given output buffer
* OUT: Size of the converted buffer
*
******************************************************************************
*/
typedef M4OSA_ERR (*M4xVSS_fromUTF8Fct)
(
M4OSA_UInt8 *pBufferIn,
M4OSA_Void *pBufferOut,
M4OSA_UInt32 *bufferOutSize
);
/**
******************************************************************************
* struct M4xVSS_InitParams
* @brief This structure defines parameters for xVSS.
* @note
******************************************************************************
*/
typedef struct
{
M4OSA_FileReadPointer* pFileReadPtr;
M4OSA_FileWriterPointer* pFileWritePtr;
M4OSA_Void* pTempPath;
/*Function pointer on an external text conversion function */
M4xVSS_toUTF8Fct pConvToUTF8Fct;
/*Function pointer on an external text conversion function */
M4xVSS_fromUTF8Fct pConvFromUTF8Fct;
} M4xVSS_InitParams;
/**
******************************************************************************
* prototype M4xVSS_Init
* @brief This function initializes the xVSS
* @note Initializes the xVSS edit operation (allocates an execution context).
*
* @param pContext (OUT) Pointer on the xVSS edit context to allocate
* @param params (IN) Parameters mandatory for xVSS
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_ALLOC: Memory allocation has failed
******************************************************************************
*/
M4OSA_ERR M4xVSS_Init(M4OSA_Context* pContext, M4xVSS_InitParams* params);
/**
******************************************************************************
* prototype M4xVSS_ReduceTranscode
* @brief This function changes the given editing structure in order to
* minimize the transcoding time.
* @note The xVSS analyses this structure, and if needed, changes the
* output parameters (Video codec, video size, audio codec,
* audio nb of channels) to minimize the transcoding time.
*
* @param pContext (OUT) Pointer on the xVSS edit context to allocate
* @param pSettings (IN) Edition settings (allocated by the user)
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_ALLOC: Memory allocation has failed
* @return M4ERR_STATE: This function cannot not be called at this time
******************************************************************************
*/
M4OSA_ERR M4xVSS_ReduceTranscode(M4OSA_Context pContext, M4VSS3GPP_EditSettings* pSettings);
/**
******************************************************************************
* prototype M4xVSS_SendCommand
* @brief This function gives to the xVSS an editing structure
* @note The xVSS analyses this structure, and prepare edition
* This function must be called after M4xVSS_Init, after
* M4xVSS_CloseCommand, or after M4xVSS_PreviewStop.
* After this function, the user must call M4xVSS_Step until
* it returns another error than M4NO_ERROR.
*
* @param pContext (IN) Pointer on the xVSS edit context
* @param pSettings (IN) Edition settings (allocated by the user)
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_ALLOC: Memory allocation has failed
* @return M4ERR_STATE: This function cannot not be called at this time
******************************************************************************
*/
M4OSA_ERR M4xVSS_SendCommand(M4OSA_Context pContext, M4VSS3GPP_EditSettings* pSettings);
/**
******************************************************************************
* prototype M4xVSS_PreviewStart
* @brief This function prepare the preview
* @note The xVSS create 3GP preview file and fill pPreviewSettings with
* preview parameters.
* This function must be called once M4xVSS_Step has returned
* M4VSS3GPP_WAR_ANALYZING_DONE
* After this function, the user must call M4xVSS_Step until
* it returns another error than M4NO_ERROR.
*
* @param pContext (IN) Pointer on the xVSS edit context
* @param pPreviewSettings (IN) Preview settings (allocated by the user)
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_ALLOC: Memory allocation has failed
* @return M4ERR_STATE: This function cannot not be called at this time
******************************************************************************
*/
M4OSA_ERR M4xVSS_PreviewStart(M4OSA_Context pContext, M4xVSS_PreviewSettings* pPreviewSettings);
/**
******************************************************************************
* prototype M4xVSS_PreviewStop
* @brief This function unallocate preview ressources and change xVSS
* internal state to allow saving or resend an editing command
* @note This function must be called once M4xVSS_Step has returned
* M4VSS3GPP_WAR_PREVIEW_READY
*
* @param pContext (IN) Pointer on the xVSS edit context
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_STATE: This function cannot not be called at this time
******************************************************************************
*/
M4OSA_ERR M4xVSS_PreviewStop(M4OSA_Context pContext);
/**
******************************************************************************
* prototype M4xVSS_SaveStart
* @brief This function prepare the save
* @note The xVSS create 3GP edited final file
* This function must be called once M4xVSS_Step has returned
* M4VSS3GPP_WAR_ANALYZING_DONE
* After this function, the user must call M4xVSS_Step until
* it returns another error than M4NO_ERROR.
*
* @param pContext (IN) Pointer on the xVSS edit context
* @param pFilePath (IN) If the user wants to provide a different
* output filename, else can be NULL (allocated by the user)
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_ALLOC: Memory allocation has failed
* @return M4ERR_STATE: This function cannot not be called at this time
******************************************************************************
*/
M4OSA_ERR M4xVSS_SaveStart(M4OSA_Context pContext, M4OSA_Void* pFilePath,
M4OSA_UInt32 filePathSize);
/**
******************************************************************************
* prototype M4xVSS_SaveStop
* @brief This function unallocate save ressources and change xVSS
* internal state.
* @note This function must be called once M4xVSS_Step has returned
* M4VSS3GPP_WAR_SAVING_DONE
*
* @param pContext (IN) Pointer on the xVSS edit context
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_STATE: This function cannot not be called at this time
******************************************************************************
*/
M4OSA_ERR M4xVSS_SaveStop(M4OSA_Context pContext);
/**
******************************************************************************
* prototype M4xVSS_Step
* @brief This function executes differents tasks, depending of xVSS
* internal state.
* @note This function:
* - analyses editing structure if called after M4xVSS_SendCommand
* - generates preview file if called after M4xVSS_PreviewStart
* - generates final edited file if called after M4xVSS_SaveStart
*
* @param pContext (IN) Pointer on the xVSS edit context
* @param pContext (OUT) Progress indication from 0 to 100
* @return M4NO_ERROR: No error, the user must call M4xVSS_Step again
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_STATE: This function cannot not be called at this time
* @return M4VSS3GPP_WAR_PREVIEW_READY: Preview file is generated
* @return M4VSS3GPP_WAR_SAVING_DONE: Final edited file is generated
* @return M4VSS3GPP_WAR_ANALYZING_DONE: Analyse is done
******************************************************************************
*/
M4OSA_ERR M4xVSS_Step(M4OSA_Context pContext, M4OSA_UInt8 *pProgress);
/**
******************************************************************************
* prototype M4xVSS_CloseCommand
* @brief This function deletes current editing profile, unallocate
* ressources and change xVSS internal state.
* @note After this function, the user can call a new M4xVSS_SendCommand
*
* @param pContext (IN) Pointer on the xVSS edit context
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_STATE: This function cannot not be called at this time
******************************************************************************
*/
M4OSA_ERR M4xVSS_CloseCommand(M4OSA_Context pContext);
/**
******************************************************************************
* prototype M4xVSS_CleanUp
* @brief This function deletes all xVSS ressources
* @note This function must be called after M4xVSS_CloseCommand.
*
* @param pContext (IN) Pointer on the xVSS edit context
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_STATE: This function cannot not be called at this time
******************************************************************************
*/
M4OSA_ERR M4xVSS_CleanUp(M4OSA_Context pContext);
/**
******************************************************************************
* prototype M4xVSS_GetVersion(M4_VersionInfo *pVersion)
* @brief This function get the version of the Video Studio 2.1
*
* @param pVersion (IN) Pointer on the version info struct
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
******************************************************************************
*/
M4OSA_ERR M4xVSS_GetVersion(M4_VersionInfo *pVersion);
/**
******************************************************************************
* prototype M4VSS3GPP_externalVideoEffectColor(M4OSA_Void *pFunctionContext,
* M4VIFI_ImagePlane *PlaneIn,
* M4VIFI_ImagePlane *PlaneOut,
* M4VSS3GPP_ExternalProgress *pProgress,
* M4OSA_UInt32 uiEffectKind)
*
* @brief This function apply a color effect on an input YUV420 planar frame
* @note The prototype of this effect function is exposed because it needs to
* called by the VPS during the preview
* @param pFunctionContext(IN) Contains which color to apply (not very clean ...)
* @param PlaneIn (IN) Input YUV420 planar
* @param PlaneOut (IN/OUT) Output YUV420 planar
* @param pProgress (IN/OUT) Progress indication (0-100)
* @param uiEffectKind (IN) Unused
*
* @return M4VIFI_OK: No error
******************************************************************************
*/
M4OSA_ERR M4VSS3GPP_externalVideoEffectColor
(
M4OSA_Void *pFunctionContext,
M4VIFI_ImagePlane *pInputPlanes,
M4VIFI_ImagePlane *pOutputPlanes,
M4VSS3GPP_ExternalProgress *pProgress,
M4OSA_UInt32 uiEffectKind
);
/**
******************************************************************************
* prototype M4VSS3GPP_externalVideoEffectFraming(M4OSA_Void *pFunctionContext,
* M4VIFI_ImagePlane *PlaneIn,
* M4VIFI_ImagePlane *PlaneOut,
* M4VSS3GPP_ExternalProgress *pProgress,
* M4OSA_UInt32 uiEffectKind)
*
* @brief This function add a fixed or animated image on an input YUV420 planar frame
* @note The prototype of this effect function is exposed because it needs to
* called by the VPS during the preview
* @param pFunctionContext(IN) Contains which color to apply (not very clean ...)
* @param PlaneIn (IN) Input YUV420 planar
* @param PlaneOut (IN/OUT) Output YUV420 planar
* @param pProgress (IN/OUT) Progress indication (0-100)
* @param uiEffectKind (IN) Unused
*
* @return M4VIFI_OK: No error
******************************************************************************
*/
M4OSA_ERR M4VSS3GPP_externalVideoEffectFraming
(
M4OSA_Void *pFunctionContext,
M4VIFI_ImagePlane *pInputPlanes,
M4VIFI_ImagePlane *pOutputPlanes,
M4VSS3GPP_ExternalProgress *pProgress,
M4OSA_UInt32 uiEffectKind
);
/**
******************************************************************************
* prototype M4VSS3GPP_externalVideoEffectFifties(M4OSA_Void *pFunctionContext,
* M4VIFI_ImagePlane *PlaneIn,
* M4VIFI_ImagePlane *PlaneOut,
* M4VSS3GPP_ExternalProgress *pProgress,
* M4OSA_UInt32 uiEffectKind)
*
* @brief This function make a video look as if it was taken in the fifties
* @note
* @param pUserData (IN) Context
* @param pPlaneIn (IN) Input YUV420 planar
* @param pPlaneOut (IN/OUT) Output YUV420 planar
* @param pProgress (IN/OUT) Progress indication (0-100)
* @param uiEffectKind (IN) Unused
*
* @return M4VIFI_OK: No error
* @return M4ERR_PARAMETER: pFiftiesData, pPlaneOut or pProgress are NULL (DEBUG only)
******************************************************************************
*/
M4OSA_ERR M4VSS3GPP_externalVideoEffectFifties
(
M4OSA_Void *pUserData,
M4VIFI_ImagePlane *pInputPlanes,
M4VIFI_ImagePlane *pPlaneOut,
M4VSS3GPP_ExternalProgress *pProgress,
M4OSA_UInt32 uiEffectKind
);
/**
******************************************************************************
* prototype M4VSS3GPP_externalVideoEffectZoom(M4OSA_Void *pFunctionContext,
* M4VIFI_ImagePlane *PlaneIn,
* M4VIFI_ImagePlane *PlaneOut,
* M4VSS3GPP_ExternalProgress *pProgress,
* M4OSA_UInt32 uiEffectKind)
*
* @brief This function add a fixed or animated image on an input YUV420 planar frame
* @note The prototype of this effect function is exposed because it needs to
* called by the VPS during the preview
* @param pFunctionContext(IN) Contains which zoom to apply (In/Out)
* @param PlaneIn (IN) Input YUV420 planar
* @param PlaneOut (IN/OUT) Output YUV420 planar
* @param pProgress (IN/OUT) Progress indication (0-100)
* @param uiEffectKind (IN) Unused
*
* @return M4VIFI_OK: No error
******************************************************************************
*/
M4OSA_ERR M4VSS3GPP_externalVideoEffectZoom
(
M4OSA_Void *pFunctionContext,
M4VIFI_ImagePlane *pInputPlanes,
M4VIFI_ImagePlane *pOutputPlanes,
M4VSS3GPP_ExternalProgress *pProgress,
M4OSA_UInt32 uiEffectKind
);
/**
******************************************************************************
* M4OSA_ERR M4xVSS_CreateClipSettings()
* @brief Allows filling a clip settings structure with default values
*
* @note WARNING: pClipSettings->Effects[ ] will be allocated in this function.
* pClipSettings->pFile will be allocated in this function.
*
* @param pClipSettings (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure
* @param pFile (IN) Clip file name
* @param filePathSize (IN) Size of the clip path (needed for the UTF16 conversion)
* @param nbEffects (IN) Nb of effect settings to allocate
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only)
******************************************************************************
*/
M4OSA_ERR M4xVSS_CreateClipSettings(M4VSS3GPP_ClipSettings *pClipSettings, M4OSA_Void* pFile,
M4OSA_UInt32 filePathSize, M4OSA_UInt8 nbEffects);
/**
******************************************************************************
* M4OSA_ERR M4xVSS_DuplicateClipSettings()
* @brief Duplicates a clip settings structure, performing allocations if required
*
* @param pClipSettingsDest (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure
* @param pClipSettingsOrig (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure
* @param bCopyEffects (IN) Flag to know if we have to duplicate effects
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only)
******************************************************************************
*/
M4OSA_ERR M4xVSS_DuplicateClipSettings(M4VSS3GPP_ClipSettings *pClipSettingsDest,
M4VSS3GPP_ClipSettings *pClipSettingsOrig,
M4OSA_Bool bCopyEffects);
/**
******************************************************************************
* M4OSA_ERR M4xVSS_FreeClipSettings()
* @brief Free the pointers allocated in the ClipSetting structure (pFile, Effects).
*
* @param pClipSettings (IN) Pointer to a valid M4VSS3GPP_ClipSettings structure
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: pClipSettings is M4OSA_NULL (debug only)
******************************************************************************
*/
M4OSA_ERR M4xVSS_FreeClipSettings(M4VSS3GPP_ClipSettings *pClipSettings);
/**
******************************************************************************
* prototype M4OSA_ERR M4xVSS_getMCSContext(M4OSA_Context pContext, M4OSA_Context* mcsContext)
* @brief This function returns the MCS context within the xVSS internal context
* @note This function must be called only after VSS state has moved to analyzing state
* or beyond
*
* @param pContext (IN) Pointer on the xVSS edit context
* @param mcsContext (OUT) Pointer to pointer of mcs context to return
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_STATE: This function cannot not be called at this time
******************************************************************************
*/
M4OSA_ERR M4xVSS_getMCSContext(M4OSA_Context pContext, M4OSA_Context* mcsContext);
/**
******************************************************************************
* prototype M4OSA_ERR M4xVSS_getVSS3GPPContext(M4OSA_Context pContext,
* M4OSA_Context* mcsContext)
* @brief This function returns the VSS3GPP context within the xVSS internal context
* @note This function must be called only after VSS state has moved to Generating
* preview or beyond
*
* @param pContext (IN) Pointer on the xVSS edit context
* @param vss3gppContext (OUT) Pointer to pointer of vss3gpp context to return
* @return M4NO_ERROR: No error
* @return M4ERR_PARAMETER: At least one parameter is M4OSA_NULL
* @return M4ERR_STATE: This function cannot not be called at this time
******************************************************************************
*/
M4OSA_ERR M4xVSS_getVSS3GPPContext(M4OSA_Context pContext, M4OSA_Context* vss3gppContext);
// Get supported video decoders and capabilities.
M4OSA_ERR M4xVSS_getVideoDecoderCapabilities(M4DECODER_VideoDecoders **decoders);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* __M4XVSS_API_H__ */