728 lines
38 KiB
C
Executable File
728 lines
38 KiB
C
Executable File
/* Copyright (c) 2006 NVIDIA Corporation. All rights reserved.
|
||
*
|
||
* NVIDIA Corporation and its licensors retain all intellectual property
|
||
* and proprietary rights in and to this software, related documentation
|
||
* and any modifications thereto. Any use, reproduction, disclosure or
|
||
* distribution of this software and related documentation without an
|
||
* express license agreement from NVIDIA Corporation is strictly prohibited.
|
||
*/
|
||
|
||
/** @file GFMxDec.h
|
||
GFSDK MPEG Decode API header file.
|
||
*/
|
||
|
||
#ifndef _GF_MPEG_DEC__
|
||
#define _GF_MPEG_DEC__
|
||
|
||
#include "nvtypes.h"
|
||
#include "GFVx.h"
|
||
#include "GFDef.h"
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" { // only need to export C interface if
|
||
// used by C++ source code
|
||
#endif
|
||
|
||
/** @addtogroup groupMxDec MxDecAPI MPEG Decode API
|
||
<ul>
|
||
<li> @ref pageMxDecAppNotes
|
||
<ul>
|
||
<li> @ref pageMxDecAppNotes1
|
||
</ul>
|
||
</ul>
|
||
*/
|
||
/*@{*/
|
||
|
||
/****************************************************************************************************/
|
||
// MXDECCapFlags
|
||
/** MxDecAPI property flag: Support for Simple Profile.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
#define GF_MXDEC_CAP_SIMPLE 0x00000001
|
||
/** MxDecAPI property flag: Support for simple profile.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
|
||
#define GF_MXDEC_CAP_SCALE 0x00000002
|
||
/** MxDecAPI property flag: Support for simple scale profile.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
|
||
#define GF_MXDEC_CAP_CORE 0x00000004
|
||
/** MxDecAPI property flag: Support for CORE profile.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
|
||
#define GF_MXDEC_CAP_MAIN 0x00000008
|
||
/** MxDecAPI property flag: Support for MAIN profile.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
|
||
/** MxDecAPI property flag: Support for N_bit profile.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
#define GF_MXDEC_CAP_N_BIT 0x00000010
|
||
|
||
/** MxDecAPI property flag: Support for LEVEL 1.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
#define GF_MXDEC_CAP_LEVEL1 0x00000100
|
||
|
||
/** MxDecAPI property flag: Support for LEVEL 2.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
#define GF_MXDEC_CAP_LEVEL2 0x00000200
|
||
|
||
/** MxDecAPI property flag: Support for LEVEL 3.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
#define GF_MXDEC_CAP_LEVEL3 0x00000400
|
||
|
||
/** MxDecAPI property flag: Support for LEVEL 4.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
#define GF_MXDEC_CAP_LEVEL4 0x00000800
|
||
|
||
/** MxDecAPI property flag: Support for Post Processing's de-blocking.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
#define GF_MXDEC_CAP_DB 0x00001000
|
||
|
||
/** MxDecAPI property flag: Support for Post Processing's de-ringing.
|
||
@see GFMXDECTABLE::MxDecGetProperty, GFPROPERTY::Capability
|
||
*/
|
||
#define GF_MXDEC_CAP_DR 0x00002000
|
||
|
||
/****************************************************************************************************/
|
||
/** This structure holds the video object plane (VOP) information. */
|
||
typedef struct _GFMXDECVOP
|
||
{
|
||
NvU32 uiVOPinfo; /**< Set new VOP information */
|
||
NvU32 uiFFORWARD; /**< FCODE_FORWARD, ignore this value if it is I frame */
|
||
PGFRMSURFACE pRef; /**< Reference VOP, ignore this item, if current VOP is an I */
|
||
PGFRMSURFACE pCur; /**< Current VOP */
|
||
PGFRECT pRefRect; /**< Specifies a rectangular area within the pRef surface for the
|
||
GFMxDecAPI to use with the reference image. This field only takes
|
||
effect when MXDEC_VOP_SPECIFY_REFSURF_RECT is set. The rectangle<6C>s
|
||
top and left should be aligned by the application, which should call
|
||
GFMxDecGetAttribute() with MXDEC_ATTR_MP4_DEC_VOP_RECT_TOP_ALIGNMENT
|
||
and MXDEC_ATTR_MP4_DEC_VOP_RECT_LEFT_ALIGNMENT to get the required
|
||
alignment. The rectangle's width and height should exactly match the
|
||
image width and height that is encoded in the bit stream. */
|
||
|
||
PGFRECT pCurRect; /**< Specifies a rectangular area of the pCur surface within which the
|
||
GFMxDecAPI should place the decoded image output. This field only takes
|
||
effect if MXDEC_VOP_SPECIFY_CURSURF_RECT is set. The rectangle<6C>s top and
|
||
left should be aligned by the application, which should call GFMxDecGetAttribute()
|
||
with MXDEC_ATTR_MP4_DEC_VOP_RECT_TOP_ALIGNMENT and
|
||
MXDEC_ATTR_MP4_DEC_VOP_RECT_LEFT_ALIGNMENT to get the required alignment.
|
||
The rectangle's width and height should exactly match the image width and
|
||
height that is encoded in the bit stream. */
|
||
}GFMXDECVOP, *PGFMXDECVOP;
|
||
|
||
/****************************************************************************************************/
|
||
//uiVOPinfo values
|
||
/** GFMXDECVOP::uiVOPinfo : If set, this is P VOP. If unset, it is I VOP.
|
||
@see GFMXDECVOP, GFMXDECTABLE::MxDecSetVOP */
|
||
#define MXDEC_VOP_P_VOP 0x1
|
||
|
||
/** GFMXDECVOP::uiVOPinfo : This parameter comes as a part of the bitstream.
|
||
This indicates that rounding should be performed while doing Motion Compensation.
|
||
@see GFMXDECVOP, GFMXDECTABLE::MxDecSetVOP */
|
||
#define MXDEC_VOP_ROUNDING_ONE 0x2
|
||
|
||
/** GFMXDECVOP::uiVOPinfo : If set, this bitstream is short video header format.
|
||
@see GFMXDECVOP, GFMXDECTABLE::MxDecSetVOP */
|
||
#define MXDEC_VOP_SHORT_HEADER 0x4
|
||
|
||
/** GFMXDECVOP::uiVOPinfo : If set, If this flag is set, pRefSurfRect must be set.
|
||
GFMxDec will reference image in pRefSurfRect area of pRef surface. Otherwise, GFMxDec will reference the whole pRef surface area.
|
||
@see GFMXDECVOP, GFMXDECTABLE::MxDecSetVOP */
|
||
#define MXDEC_VOP_SPECIFY_REFSURF_RECT 0x8
|
||
|
||
/** GFMXDECVOP::uiVOPinfo : If this flag is set, pCurSurfRect must be set. GFMxDec will output decoded image to
|
||
pCurSurfRect area of pCur surface. Otherwise, GFMxDec will output to pCur surface starting from top left corner , the width and
|
||
height are equal to pCur surface width and height.
|
||
@see GFMXDECVOP, GFMXDECTABLE::MxDecSetVOP */
|
||
#define MXDEC_VOP_SPECIFY_CURSURF_RECT 0x10
|
||
|
||
/****************************************************************************************************/
|
||
/** This structure holds the postprocessing information. */
|
||
typedef struct _GFMXDECPP
|
||
{
|
||
PGFRMSURFACE* pDestSurf; /**< Pointer to an array of surfaces that will hold the result from Post Processing
|
||
pointer to an array of surfaces to accommodate auto post processing. */
|
||
PGFRMSURFACE* pSrcSurf; /**< Pointer to an array of surfaces to be post processed pointer to an array of surfaces
|
||
to accommodate auto post processing. */
|
||
PGFRECT pRect; /**< Rectangular area to be processed for both source and destination surfaces.
|
||
@see GFRECT */
|
||
NvU32 numofDestSurf; /**< Number of Destination Surfaces. If MXDEC_PP_AUTO flag is set, this parameter must be filled. */
|
||
NvU32 numofSrcSurf; /**< Number of Source Surfaces. If MXDEC_PP_AUTO flag is set, this parameter must be filled. */
|
||
NvU8 * lpQuantiser; /**< Pointer to array of quantization steps (QPs) for macroblocks in
|
||
the source VOP. The GFMxDecAPI automatically saved the last
|
||
two decoded VOP<4F>s QP tables. The application may not need to
|
||
reload the table if it can make sure the source VOP is one of the
|
||
last decoded VOPs. This field must be filled if
|
||
MXDEC_PP_RELOAD_QUANTIZER is set. */
|
||
NvU32 PPOption; /**< Post-processing option. */
|
||
/**< <table>
|
||
<tr><td>#MXDEC_PP_DB_ON</td>
|
||
<td>Turn on DeBlocking filter for this frame</td></tr>
|
||
<tr><td>#MXDEC_PP_DR_ON</td>
|
||
<td>Turn on DeRinging filter for this frame</td></tr>
|
||
<tr><td>#MXDEC_PP_AUTO</td>
|
||
<td>Auto trigger Post Processing by Hardware</td></tr>
|
||
<tr><td>#MXDEC_PP_RELOAD_QUANTIZER</td>
|
||
<td>Reload the source VOP's qunantizers</td></tr>
|
||
<tr><td>#MXDEC_PP_OP_ASYNC</td>
|
||
<td>Enables ASYNC mode</td></tr>
|
||
</table>
|
||
*/
|
||
} GFMXDECPP, *PGFMXDECPP;
|
||
|
||
/****************************************************************************************************/
|
||
// PPOption
|
||
/** GFMXDECPP::PPOption : Turn on DeBlocking filter for this frame.
|
||
@see GFMXDECPP, GFMXDECTABLE::MxDecPostProcessing */
|
||
#define MXDEC_PP_DB_ON 0x1
|
||
|
||
/** GFMXDECPP::PPOption : Turn on DeRinging filter for this frame.
|
||
@see GFMXDECPP, GFMXDECTABLE::MxDecPostProcessing */
|
||
#define MXDEC_PP_DR_ON 0x2
|
||
|
||
/** GFMXDECPP::PPOption : Auto trigger Post Processing by Hardware.
|
||
@see GFMXDECPP, GFMXDECTABLE::MxDecPostProcessing */
|
||
#define MXDEC_PP_AUTO 0x4
|
||
|
||
/** GFMXDECPP::PPOption : Reload the source VOP's qunantizers.
|
||
@see GFMXDECPP, GFMXDECTABLE::MxDecPostProcessing */
|
||
#define MXDEC_PP_RELOAD_QUANTIZER 0x8
|
||
|
||
/** GFMXDECPP::PPOption : enables ASYN mode. GFMxDecPostProcessing()
|
||
will return after pushing the commands but without waiting for them to
|
||
complete. This option is useful to achieve some paralellism because
|
||
post-processed frame is usually not used right away for rendering. So
|
||
there is enough time for hardware to complete the decoding before this
|
||
frame will be used by app. It is ok to call PostProcessing even when
|
||
decoding of this frame is not complete. Inside GPU, hardware synchronizes
|
||
with the decoder.
|
||
@see GFMXDECPP, GFMXDECTABLE::MxDecPostProcessing */
|
||
#define MXDEC_PP_OP_ASYNC 0x00000010
|
||
|
||
/****************************************************************************************************/
|
||
//pStatus
|
||
/** Argument pStatus in GFMxDecGetStatus() : GFMxDecGetStatus() can be called by the application to indicate whether 1 frame
|
||
has been decoded or not.
|
||
@see GFMXDECTABLE::MxDecGetStatus */
|
||
#define GF_DECODER_FRAME_DONE 0x00000010
|
||
|
||
/** Argument pStatus in GFMxDecGetStatus() : GFMxDecGetStatus() can be called by the application to indicate whether post-processing
|
||
engine is done with the frame or not.
|
||
@see GFMXDECTABLE::MxDecGetStatus */
|
||
#define GF_DECODER_PP_FRAME_DONE 0x00000020
|
||
|
||
/****************************************************************************************************/
|
||
/** GFMxDecSet::uiFeature : Application sets this attribute to register a callback function and
|
||
its correpnding parameter to read bitstream data */
|
||
#define MXDEC_SET_READBITSTREAM 1
|
||
|
||
/** GFMxDecSet::uiFeature Application needs to set this flag in order to send MPEG4 bitstream data in Prefill Mode;
|
||
When this is set:
|
||
- application does not need to register any bitstream-read callback function as data will be fed upfront.
|
||
- application needs to set an attribute MXDEC_ATTR_PRE_DETERMINED_BOUNDARY to indicate that data will be fed on frame boundary.
|
||
@see GFMXDECTABLE::MxDecSet */
|
||
#define GFMXDEC_OPTION_PREFILLBUFFER 0x00000002
|
||
|
||
/****************************************************************************************************/
|
||
/** Structure holding the callback function pointer.
|
||
Used in registering the callback function
|
||
The callback function is a function which the API calls to request a portion of the bit stream from the application.
|
||
@see GFMXDECTABLE::MxDecSet
|
||
*/
|
||
typedef struct _GFMXDECCALLBACK
|
||
{
|
||
void *pPara; /**< pPara is a parameter passed from application and the application
|
||
wants the API to callback with this parameter. */
|
||
NvU32 (*pCallBack)(void * pPara, NvU8 ** ppBuffer, NvS32 * BufferLength, NvU32 uFlag);
|
||
/**<
|
||
Application callback function pointer.
|
||
Register a callback function for fetching MPEG stream data.
|
||
|
||
If application set MXDEC_ATTR_PRE_DETERMINED_BOUNDARY, application should
|
||
return MXDEC_BOUNDARY_REACHED when the boundary is detected.
|
||
If APP does not set MXDEC_ATTR_PRE_DETERMINED_BOUNDARY, 0 should be returned.
|
||
|
||
@param *pPara Parameter to pass on to application callback function
|
||
@param ppBuffer Buffer Pointer
|
||
@param BufferLength Parameter to pass on to application callback function
|
||
@param uFlag Flag for reading bitstream backward/forward.
|
||
<table>
|
||
<tr><td>#MXDEC_READ_BITSTREAM_FORWARD</td>
|
||
<td>Read bitstream in forward direction</td></tr>
|
||
<tr><td>#MXDEC_READ_BITSTREAM_BACKWARD</td>
|
||
<td>Read bitstream in backward direction</td></tr>
|
||
</table>
|
||
|
||
@retval The number of bytes read successfully, 0 if no bytes read.
|
||
*/
|
||
}GFMXDECCALLBACK, *PGFMXDECCALLBACK;
|
||
|
||
/****************************************************************************************************/
|
||
/** Returned by application when MXDEC_ATTR_PRE_DETERMINED_BOUNDARY is set and boundary is detected. */
|
||
#define MXDEC_BOUNDARY_REACHED 0x00000001
|
||
|
||
// for backward/forward reading bitstream flags
|
||
/** Read bitstream in forward direction.
|
||
@see GFMXDECCALLBACK
|
||
*/
|
||
#define MXDEC_READ_BITSTREAM_FORWARD 0x00000002
|
||
|
||
/** Read bitstream in backward direction.
|
||
@see GFMXDECCALLBACK
|
||
*/
|
||
#define MXDEC_READ_BITSTREAM_BACKWARD 0x00000003
|
||
|
||
/****************************************************************************************************/
|
||
//uiVOLinfo
|
||
/** GFMXDECMP4SETVOL::uiVOLinfo : If set indicates that VOL is in short header format.
|
||
@see GFMXDECMP4SETVOL*/
|
||
#define MXDEC_MP4_SET_SHORT_HEADER 0x00000001
|
||
|
||
/****************************************************************************************************/
|
||
/** This structure hold information of the PreFill buffer.
|
||
*/
|
||
typedef struct _GFMXDECPREFILLBUFFER
|
||
{
|
||
NvU8* pPreFillBuffer; /**< Input, Prefill buffer pointer filled by application. */
|
||
NvU32 PreFillBufferLength; /**< Input, Length of pref-fill buffer. */
|
||
NvU32 PreFillBufferBytesConsumed; /**< Output, Amount of bytes consumed by the component. */
|
||
NvU32 prefill_enabled; /**< Flag to identify if prefill buffer is supplied by application. */
|
||
} GFMXDECPREFILLBUFFER;
|
||
|
||
/****************************************************************************************************/
|
||
/** This structure hold the information needed for decoding a Video Object Layer (VOL).
|
||
@see GFMXDECTABLE::MxDecMP4DecVOL */
|
||
typedef struct _GFMXDECMP4DECVOL
|
||
{
|
||
NvU32 uiVOLinfo; /**< Indicates format of the VOL. Set by API. */
|
||
/**< <table>
|
||
<tr><td>#MXDEC_MP4_SHORT_HEADER</td>
|
||
<td>Short header format detected</td></tr>
|
||
<tr><td>#MXDEC_MP4_DATA_PARTITION</td>
|
||
<td>Data Partitioning mode detected</td></tr>
|
||
<tr><td>#MXDEC_MP4_PROFILE_LEVEL</td>
|
||
<td>Profile and level field is valid</td></tr>
|
||
<tr><td>#MXDEC_MP4_PRIORITY</td>
|
||
<td>Priority field is valid</td></tr>
|
||
<tr><td>#MXDEC_MP4_VSOTYPE</td>
|
||
<td>Visual object type field is valid</td></tr>
|
||
<tr><td>#MXDEC_MP4_VIDEO_SIGNAL</td>
|
||
<td>VideoFormat and VideoRange fields are valid</td></tr>
|
||
<tr><td>#MXDEC_MP4_COLOR_DESCRIPTION</td>
|
||
<td>Color, Transfer and Matrix fields are valid</td></tr>
|
||
<tr><td>#MXDEC_MP4_VOID</td>
|
||
<td>VObjectID field is valid</td></tr>
|
||
<tr><td>#MXDEC_MP4_VOLID</td>
|
||
<td>VOLID field is valid</td></tr>
|
||
</table>
|
||
*/
|
||
NvU32 uiWidth; /**< Display width, set by API */
|
||
NvU32 uiHeight; /**< Display height, set by API */
|
||
unsigned int Profile; /**< Mpeg4 Profile. Set by API.*/
|
||
/**< <table>
|
||
<tr><td>#MXDEC_MP4_SIMPLE_PROFILE</td><td>Profile is simple profile</td></tr>
|
||
<tr><td>#MXDEC_MP4_ADVANCE_SIMPLE_PROFILE</td><td>Profile is advance simple profile</td></tr>
|
||
</table>
|
||
*/
|
||
unsigned int Level; /**< Mpeg4 Level. Set by API. */
|
||
unsigned int VObjectID; /**< Video Object ID. Set by API. */
|
||
unsigned int VOLID; /**< Video Object Layer ID. Set by API. */
|
||
unsigned int Priority; /**< Priority(of what (???)). Set by API. */
|
||
unsigned int VSOType; /**< VSO(full form(???)) Type. Set by API. */
|
||
unsigned int VideoFormat; /**< Video Format (what are the possible values (???)). Set by API. */
|
||
unsigned int VideoRange; /**< Video Range. Set by API. */
|
||
unsigned int Color; /**< Color primaries. */
|
||
unsigned int Transfer; /**< Transfer charateristics. */
|
||
unsigned int Matrix; /**< Matrix coefficients(???). */
|
||
GFMXDECPREFILLBUFFER prefill;
|
||
}GFMXDECMP4DECVOL, *PGFMXDECMP4DECVOL;
|
||
|
||
/****************************************************************************************************/
|
||
//uiVOLinfo
|
||
/** GFMXDECMP4DECVOL::uiVOLinfo : Short header format detected.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_SHORT_HEADER 0x00000001
|
||
|
||
/** GFMXDECMP4DECVOL::uiVOLinfo : Data Partitioning mode detected.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_DATA_PARTITION 0x00000002
|
||
|
||
/** GFMXDECMP4DECVOL::uiVOLinfo : Profile and level field is valid.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_PROFILE_LEVEL 0x00000004
|
||
|
||
/** GFMXDECMP4DECVOL::uiVOLinfo : Priority field is valid.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_PRIORITY 0x00000008
|
||
|
||
/** GFMXDECMP4DECVOL::uiVOLinfo : Visual object type field is valid.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_VSOTYPE 0x00000010
|
||
|
||
/** GFMXDECMP4DECVOL::uiVOLinfo : VideoFormat and VideoRange fields are valid.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_VIDEO_SIGNAL 0x00000020
|
||
|
||
/** GFMXDECMP4DECVOL::uiVOLinfo : Color, Transfer and Matrix fields are valid.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_COLOR_DESCRIPTION 0x00000040
|
||
|
||
/** GFMXDECMP4DECVOL::uiVOLinfo : VObjectID field is valid.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_VOID 0x00000080
|
||
|
||
/** GFMXDECMP4DECVOL::uiVOLinfo : VOLID field is valid.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_VOLID 0x00000100
|
||
|
||
/****************************************************************************************************/
|
||
//Profile
|
||
/** GFMXDECMP4DECVOL::Profile : Profile is simple profile.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_SIMPLE_PROFILE 0x00000000
|
||
|
||
/** GFMXDECMP4DECVOL::Profile : Profile is advance simple profile.
|
||
@see GFMXDECMP4DECVOL, GFMXDECTABLE::MxDecMP4DecVOL */
|
||
#define MXDEC_MP4_ADVANCE_SIMPLE_PROFILE 0x00000009
|
||
|
||
/****************************************************************************************************/
|
||
//resync options
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to next nearest VOL.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_FORWARD_NEAREST_VOL 0x1
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to next nearest VOP.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_FORWARD_NEAREST_VOP 0x2
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to next nearest I-VOP.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_FORWARD_NEAREST_I_VOP 0x4
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to next VOL.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_FORWARD_NEXT_VOL 0x8
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to next VOL.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_FORWARD_NEXT_VOP 0x10
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to next I-VOP.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_FORWARD_NEXT_I_VOP 0x20
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to previous nearest VOL.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_BACKWARD_NEAREST_VOL 0x40
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to previous nearest VOP.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_BACKWARD_NEAREST_VOP 0x80
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to previous nearest I-VOP.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_BACKWARD_NEAREST_I_VOP 0x100
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to previous VOL.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_BACKWARD_PREVIOUS_VOL 0x200
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to previous VOP.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_BACKWARD_PREVIOUS_VOP 0x400
|
||
|
||
/** Argument ResyncOption for GFMXDECTABLE::MxDecMP4DecResync : Resync to previous I-VOP.
|
||
@see GFMXDECTABLE::MxDecMP4DecResync */
|
||
#define MXDEC_MP4_RESYNC_BACKWARD_PREVIOUS_I_VOP 0x800
|
||
|
||
/****************************************************************************************************/
|
||
/** This structure hold the information needed for decoding a Video Object Plane (VOP).
|
||
@see GFMXDECTABLE::MxDecMP4DecVOP */
|
||
typedef struct _GFMXDECMP4DECVOP
|
||
{
|
||
PGFRMSURFACE pRef; /**< Reference VOP, ignore this item, if current VOP is an I. Set by application. */
|
||
PGFRMSURFACE pCur; /**< Current VOP. Set by application. */
|
||
PGFRECT pRefRect; /**< Reference rectangle. Set by application.
|
||
pRefRect specifies a rectangle area for GFMxDec to reference the reference image.
|
||
This rectangle area should be within the pRef surface. The rectangle top, left should
|
||
be aligned by application. Application should call GFMxDecGetAttribute() with
|
||
MXDEC_ATTR_MP4_DEC_VOP_RECT_TOP_ALIGNMENT and MXDEC_ATTR_MP4_DEC_VOP_RECT_LEFT_ALIGNMENT
|
||
attributions to get the required alignment. This rectangle's width and height should
|
||
exactly match with the image width and height which has been coded in bit stream. If
|
||
pRefRect is NULL, GFMxDec will use pRef surface width and height as reference image dimension.
|
||
*/
|
||
PGFRECT pCurRect; /**< Current rectangle. Set by application.
|
||
pCurRect specifies a rectangle area for GFMxDec to output the decoded image.
|
||
This field only take effect when MXDEC_MP4_DEC_VOP_SPECIFY_REFSURF_RECT flag is set.
|
||
This rectangle area should be within the pCur surface. The rectangle top, left should be
|
||
aligned by application. Application should call GFMxDecGetAttribute() with
|
||
MXDEC_ATTR_MP4_DEC_VOP_RECT_TOP_ALIGNMENT and MXDEC_ATTR_MP4_DEC_VOP_RECT_LEFT_ALIGNMENT
|
||
attributions to get the required alignment. This rectangle's width and height should exactly
|
||
match with the image width and height which has been coded in bit stream. If pCurRect is NULL,
|
||
GFMxDec will use pCur surface dimension as decoded image dimension.
|
||
*/
|
||
NvU32 uiVOPinfo; /**< Get current VOP information. Set by API.
|
||
<table><tr><td>#MXDEC_MP4_VOP_P</td><td>VOP is coded as P-VOP</td></tr>
|
||
<tr><td>#MXDEC_MP4_NOT_CODED</td><td>VOP is not coded</td></tr>
|
||
<tr><td>(???)What about I-VOP?</td><td>(???)</td></tr></table>
|
||
*/
|
||
NvU32 uiTimeStamp; /**< Time to display this VOP, in milliseconds. Set by API. */
|
||
NvU8 *pMBInfo; /**< Pointer to array where information of whether the MB is decoded or not is stored.
|
||
Each element will tell if this corresponding MB is wrong. Set by API. */
|
||
NvU32 uiVOPOption; /**< Must be used to set ASYNC option */
|
||
|
||
GFMXDECPREFILLBUFFER prefill;
|
||
}GFMXDECMP4DECVOP, *PGFMXDECMP4DECVOP;
|
||
|
||
/** GFMXDECMP4DECVOP::uiVOPOption: enables ASYNC mode. GFMxDecMP4DecVOP()
|
||
will return after pushing the commands but without waiting for them to
|
||
complete. This option is useful to achieve some paralellism because
|
||
decoded frame is usually not used right away for rendering. So
|
||
there is enough time for hardware to complete the decoding before this
|
||
frame will be used by app. It is ok to call PostProcessing even when
|
||
decoding of this frame is not complete. Inside GPU, hardware synchronizes
|
||
with the decoder. */
|
||
#define MXDEC_MP4DECVOP_OP_ASYNC 0x00000001
|
||
|
||
|
||
/****************************************************************************************************/
|
||
//uiVOPinfo
|
||
/** GFMXDECMP4DECVOP::uiVOPinfo : VOP is coded as P-VOP.
|
||
@see GFMXDECMP4DECVOP */
|
||
#define MXDEC_MP4_VOP_P 0x00000001
|
||
|
||
/** GFMXDECMP4DECVOP::uiVOPinfo : VOP is not coded.
|
||
@see GFMXDECMP4DECVOP */
|
||
#define MXDEC_MP4_NOT_CODED 0x00000002 //Not coded VOP
|
||
|
||
/****************************************************************************************************/
|
||
//when GF_ERROR is return check the following flag
|
||
/** This flag is set when atleast one MB is wrong. If application has setup pMBinfo, it can check which MB is wrong. */
|
||
#define MXDEC_MP4_BAD_MB 0x00010000
|
||
|
||
/****************************************************************************************************/
|
||
|
||
#define MXDEC_ATTR_PRE_DETERMINED_BOUNDARY 0x00000001
|
||
/**< MxDecAPI Attribute : Application will determine the decoding boundary, for MPEG4, this boundary means VOL
|
||
and VOP boundary. For certain file formats, those boundary information are stored in the video file, application
|
||
can easily use those information to determine the boundary. If APP wants API to detect the boundary, application
|
||
should not disable this attribute. This is mainly for streaming case, where application does not have those handy
|
||
boundary information. API will automatically detect those boundaries. Application does not need to parse the
|
||
bitstream to detect those boundaries.\n
|
||
Value to be passed to GFMxDecSetAttribute for setting this attribute:
|
||
<table><tr><td>*pInfo == 1</td><td>Application will determine the decoding boudary</td></tr>
|
||
<tr><td>*pInfo == 0</td><td>Application will not determine the decoding boudary</td></tr></table>
|
||
@see GFMXDECTABLE::MxDecSetAttribute
|
||
*/
|
||
|
||
#define MXDEC_ATTR_MP4_DEC_VOP_RECT_TOP_ALIGNMENT 0x00000002
|
||
/**< MxDecAPI Attribute : This attribute only can be used for GFMxDecGetAttribute. If application wants to set pDestRect
|
||
in GFMXDECVOP or GFMXDECMP4DECVOP, application must use this attribute to get alignment information and align the rectangle
|
||
top & left corner accordingly. Value returned by GFMxDecGetAttribute:\n
|
||
*pInfo: Top field alignment in term of lines
|
||
@see GFMXDECTABLE::MxDecGetAttribute
|
||
*/
|
||
|
||
#define MXDEC_ATTR_MP4_DEC_VOP_RECT_LEFT_ALIGNMENT 0x00000003
|
||
/**< MxDecAPI Attribute : This attribute only can be used for GFMxDecGetAttribute. If application wants to set pDestRect
|
||
in GFMXDECVOP or GFMXDECMP4DECVOP, application must use those attributes to get alignment information and align the rectangle
|
||
top & left corner accordinately. Value returned by GFMxDecGetAttrubute:\n
|
||
*pInfo: left field alignment in term of pixels
|
||
@see GFMXDECTABLE::MxDecGetAttribute
|
||
*/
|
||
|
||
#define GF_MXDEC_ATTR_DEC_ENABLE_RAISE_WAIT 0x00000004
|
||
/**< MxDecAPI Attribute : This attribute only can be used for GFMxDecSetAttribute.
|
||
Value passed to GFMxDecSetAttribute:\n
|
||
<table>
|
||
<tr><td>*pInfo == 1</td>
|
||
<td>Raisevectors are allocated per Surface.\n
|
||
There will be 2 (3 if PostProcessing is ON) sets of raise-wait happening\n
|
||
1) Decoder raises On_Frame_Decoded, and VxBlt waits.\n
|
||
2) (If enabled in APP) PostProcessing API raises On_PP_Frame_Done, and VxBlt waits.\n
|
||
3) VxBlt raises On_Bltted, and Decoder waits.</td></tr>
|
||
<tr><td>*pInfo == 0 (Default)</td>
|
||
<td>We do not allocate surface raise vectors but a single raise vector.\n
|
||
1) In Decoder, we poll Frame_done, and return only after its done.\n
|
||
2) In PostProcessing we poll PP_Frame_done, and return only after its done.\n
|
||
3) It is observed that Frame_done & PP_Frame_done bits are affected only if raise is done on those.\n
|
||
Thats why single raise vector is still needed. This raise vector is not in any suface but in MxDecHandle.</td></tr>
|
||
</table>
|
||
@see GFMXDECTABLE::MxDecSetAttribute
|
||
*/
|
||
|
||
#define MXDEC_ATTR_DISABLE_EC 0x00000005
|
||
/**< MxDecAPI Attribute : Application can disable Error Concealment (EC) by setting this attribute. By default, EC is enabled.
|
||
Decoder has The Error Robustness (ER) and Concealment (EC) for mpeg4 decoding.
|
||
|
||
Error Robustness (Always ON) :
|
||
The ER means the code will detect any error in the bitstream at proper places and will still proceed ahead for decoding the
|
||
remaining stream, for posible non-errored data.
|
||
|
||
Error Concealment (Default ON): Can be disabled by this very attribute MXDEC_ATTR_DISABLE_EC.
|
||
EC means, the decoder will try to use previously decoded information to simulate the lost data. The below steps of EC:
|
||
|
||
Lost Motion Vector recovery and concealment:
|
||
1. Rational interpolation: Predict the lost MV from the current frame
|
||
2. Use MV from prev frame
|
||
3. Use MV from step 3 and 4, to reconstruct 2 sets of the texture data for lost MB.
|
||
|
||
@see GFMXDECTABLE::MxDecSetAttribute */
|
||
|
||
#define MXDEC_ATTR_MP4_DEC_GET_MBERR_MAP_MATRIX 0x00000006
|
||
/**< MxDecAPI Attribute : This attribute only can be used for GFMxDecGetAttribute. If application wants to get MB error map for
|
||
till recently decoded frame. Input parameter is a character array pMBErrMapMatrix of size "number of MBs in a frame". On returning
|
||
this call fills this char array with 1s & 0s. 1: MB correctly decoded & 0: MB corrupted. This is cumulative err map till this call
|
||
is made. In this API call after copying the err map to the char array, internal map is resit to all clean MBs. \n
|
||
Interpretation of block referenced by \a pInfo parameter:
|
||
<pre>
|
||
NvU8 * pMBErrMapMatrix
|
||
</pre>
|
||
@see GFMXDECTABLE::MxDecGetAttribute
|
||
*/
|
||
|
||
/****************************************************************************************************/
|
||
|
||
/** Typesafe function for opening this component.
|
||
|
||
@param hRm (GFRmHandle) Handle specific to Resource Manager API
|
||
@param phMxDec (GFMxDecHandle *) Pointer to handle specific to MxDecAPI
|
||
@param state (GF_STATE_TYPE) The state is used to decide if a new ChHandle is to be allocated for MxDec component or not.
|
||
The values that state can take are:
|
||
<table><tr><td>#GF_STATE_DEFAULT</td></tr>
|
||
<tr><td>#GF_STATE_NEW_OR_SHARE</td></tr>
|
||
<tr><td>#GF_STATE_NEW_ONLY</td></tr>
|
||
<tr><td>#GF_STATE_SHARE_ONLY</td></tr></table>
|
||
|
||
@param hCh (GFRmChHandle) Resource Manager Channel Handle
|
||
|
||
@retval GF_SUCCESS : If successful
|
||
@retval GF_ERROR : If error occured
|
||
*/
|
||
/**< Typesafe functions for opening and closing this component.
|
||
This API also checks for hardware resources needed through GFRmHwResourceConstraint().
|
||
Trying to open a second video instance will fail due to existing open context.
|
||
*/
|
||
|
||
GF_RETTYPE GFMxDecOpen(GFRmHandle hRm, GFMxDecHandle *phMxDec,
|
||
GF_STATE_TYPE state, GFRmChHandle hCh);
|
||
|
||
/** Typesafe function for opening this component.
|
||
|
||
@param phMxDec (GFMxDecHandle *) Pointer to handle specific to MxDecAPI
|
||
|
||
Close the video instance.
|
||
*/
|
||
void GFMxDecClose(GFMxDecHandle *phMxDec);
|
||
|
||
GF_RETTYPE GFMxDecGetProperty (GFMxDecHandle MxHandle, PGFPROPERTY pMXProp);
|
||
GF_RETTYPE GFMxDecPostProcessing (GFMxDecHandle pdec, PGFMXDECPP pP);
|
||
GF_RETTYPE GFMxDecSetAttribute (GFMxDecHandle pdec, NvU32 uiFeature, NvU32 *pInfo);
|
||
GF_RETTYPE GFMxDecGetAttribute (GFMxDecHandle pdec, NvU32 uiFeature, NvU32 *pInfo);
|
||
GF_RETTYPE GFMxDecSet (GFMxDecHandle pdec, NvU32 uiFeature, void *pInfo);
|
||
GF_RETTYPE GFMxDecMP4DecVOL (GFMxDecHandle pdec, PGFMXDECMP4DECVOL pVOL);
|
||
GF_RETTYPE GFMxDecMP4DecVOP (GFMxDecHandle pdec, PGFMXDECMP4DECVOP pVOP);
|
||
GF_RETTYPE GFMxDecMP4DecResync (GFMxDecHandle pdec, NvU32 ResyncOption);
|
||
|
||
//return value
|
||
#define GFMXDEC_ERROR_NOT_SUPPORT_FORMAT (GFMXD_ERROR | 0x00000001)
|
||
/**< This error is returned when the input file format is not supported by the decoder. */
|
||
#define GFMXDEC_ERROR_HEADER_DAMAGED (GFMXD_ERROR | 0x00000002)
|
||
/**< This error is returned when the header of the mpeg4 stream is damaged. */
|
||
#define GFMXDEC_ERROR_NO_VOL_HEADER (GFMXD_ERROR | 0x00000003)
|
||
/**< This error is returned when no Video Object Layer (VOL) header is detected. */
|
||
#define GFMXDEC_ERROR_NOT_ENOUGH_SYSTEM_MEM (GFMXD_ERROR | 0x00000004)
|
||
/**< This error is returned when system is out of memory. */
|
||
|
||
//return value
|
||
#define GFMXDEC_ERROR_DETECTED_VOL (GFMXD_ERROR | 0x00000005)
|
||
/**< This error is returned when VOL was detected while decoding VOP. */
|
||
#define GFMXDEC_ERROR_END_OF_FILE (GFMXD_ERROR | 0x00000006)
|
||
/**< This error is returned when end of file is reached. */
|
||
#define GFMXDEC_ERROR_CORRUPTED_VOP (GFMXD_ERROR | 0x00000007)
|
||
/**< This error is returned when the VOP is corrupted and cannot be recovered. */
|
||
|
||
//return value
|
||
#define GFMXDEC_ERROR_RESYNC_END_OF_FILE (GFMXD_ERROR | 0x00000008)
|
||
/**< This error is returned when end of file is reached while looking for resync marker. */
|
||
#define GFMXDEC_ERROR_RESYNC_DETECTED_VOL (GFMXD_ERROR | 0x00000009)
|
||
/**< This error is returned when a VOL start is detected while searching for VOP resync marker. */
|
||
#define GFMXDECMP4_DSP_TIMEOUT (GFMXD_ERROR | 0x00000010)
|
||
/**< This error is returned when DSP does not return anything for a predetermined timeout period. This error indicates possibility of DSP hang. */
|
||
#define GFMXDEC_ERROR_START_CODE (GFMXD_ERROR | 0x00000011)
|
||
/**< This error is returned when no start code is found in a chunk of data. */
|
||
|
||
/*@}*/
|
||
|
||
/** @page pageMxDecAppNotes MxDecAPI Application Notes
|
||
@section pageMxDecAppNotes1 Programming Sequence
|
||
|
||
The following procedure requires that GFRmOpen() is called first to start
|
||
GFSDK usage.
|
||
|
||
|
||
1. Initialize the display panel by using GFRmIxInit().\n
|
||
|
||
2. Open the display component by calling GFDxOpen() to get the GFMxDecAPI Dxhandle.\n
|
||
|
||
3. Initialize the display start address, stride and bits per pixel using GFDxSetDisplay().\n
|
||
|
||
4. Get the various attributes of the display panel (width, height, etc) using GFDxGetAttribute().\n
|
||
|
||
5. For clearing the screen, open the graphics component using GFGxOpen() and use GFGxFillRect() for filling the screen with
|
||
some color (say, black).\n
|
||
|
||
6. Open the FDev component for performing file I/O using GFFDevOpen() and mount it using GFFDevMount().\n
|
||
|
||
7. Open the Vx component using GFVxOpen() and get the GFVxAPI VxHandle. \n
|
||
|
||
8. Query the properties with GFVxGetProperty() to see whether this GFVxAPI version supports MPEG decoding.\n
|
||
|
||
9. If it supports MPEG decoding, call GFMxDecOpen() to get the GFMxDecAPI MxHandle.\n
|
||
|
||
10. Call GFMxDecGetProperty() to query properties. Check whether this GFMxDAPI version can support the desired
|
||
MPEG profile and level.\n
|
||
|
||
11. If the properties check out, call GFRmSurfaceAlloc() to allocate at least one reference surface and one
|
||
current surface for decoding purposes.\n
|
||
|
||
12. If the postprocessing engine is needed, allocate one surface to hold the postprocessing results.\n
|
||
|
||
13. For display purposes, the decoder application could call GFVxBlt() for the following two scenarios. \n
|
||
(a) Performing color space conversion and then a stretch blit to the primary surface directly. \n
|
||
(b) Blitting to the overlay surface.\n
|
||
Please refer to the latest GFVxAPI document for additional information. \n
|
||
|
||
14. The decoder application should decode VOP-by-VOP. Call GFMxDecSetVOP() to set up the VOP<4F>s characteristics.\n
|
||
|
||
15. After the decoder application has decoded enough macroblocks, call GFMxDecSetMBs() to trigger the hardware
|
||
to decode those macroblocks until all macroblocks in the current VOP are finished. GFMxDecSetMBs() may initiate
|
||
the postprocessing engine or video engine automatically.\n
|
||
|
||
16. Before exiting the application, the decoder application should call GFRmSurfaceFree() to free the surfaces
|
||
that have been allocated. \n
|
||
|
||
17. Call GFMxClose() with the MxHandle to release the resources of the decoder module.\n
|
||
|
||
18. Similarly, call the close functions of the other components which have been opened.\n
|
||
|
||
*/
|
||
|
||
#ifdef __cplusplus
|
||
} // only need to export C interface if
|
||
// used by C++ source code
|
||
#endif
|
||
|
||
#endif
|
||
|