MFXVideoDECODE

This class of functions implements a complete decoder that decompresses input bitstreams directly to output frame surfaces.

 

Member Functions

 

MFXVideoDECODE_Query

Queries the feature capability

MFXVideoDECODE_QueryIOSurf

Queries the number of frames required for decoding

MFXVideoDECODE_DecodeHeader

Parses the bitstream to obtain the video parameters for initialization

MFXVideoDECODE_Init

Initializes the decoding operation

MFXVideoDECODE_Reset

Resets the current decoding operation and prepares for the next decoding operation

MFXVideoDECODE_Close

Terminates the decoding operation and de-allocates any internal memory

MFXVideoDECODE_GetVideoParam

Obtains the current working parameter set

MFXVideoDECODE_GetDecodeStat

Obtains statistics during decoding

MFXVideoDECODE_GetPayload

Obtains user data or SEI messages embedded in the bitstream

MFXVideoDECODE_SetSkipMode

Set decoder skip mode

MFXVideoDECODE_DecodeFrameAsync

Performs decoding from the input bitstream to the output frame surface

MFXVideoDECODE_DecodeHeader

Syntax

 

mfxStatus MFXVideoDECODE_DecodeHeader(mfxSession session, mfxBitstream *bs, mfxVideoParam *par);

Parameters

 

session

SDK session handle

 

bs

Pointer to the bitstream

 

par

Pointer to the mfxVideoParam structure

Description

 

This function parses the input bitstream and fills the mfxVideoParam structure with appropriate values, such as resolution and frame rate, for the Init function. The application can then pass the resulting mfxVideoParam structure to the MFXVideoDECODE_Init function for decoder initialization.

An application can call this function at any time before or after decoder initialization. If the SDK finds a sequence header in the bitstream, the function moves the bitstream pointer to the first bit of the sequence header. Otherwise, the function moves the bitstream pointer close to the end of the bitstream buffer but leaves enough data in the buffer to avoid possible loss of start code.

The CodecId field of the mfxVideoParam structure is a mandated field (to be filled by the application) to identify the coding standard.

The application can retrieve a copy of the bitstream header, by attaching the mfxExtCodingOptionSPSPPS structure to the mfxVideoParam structure.

Return Status

 

MFX_ERR_NONE

The function successfully filled mfxVideoParam structure. It does not mean that the stream can be decoded by SDK. The application should call MFXVideoDECODE_Query function to check if decoding of the stream is supported.

 

MFX_ERR_MORE_DATA

The function requires more bitstream data.

Change History

 

This function is available since SDK API 1.0.

Syntax

 

mfxStatus MFXVideoDECODE_Query(mfxSession session, mfxVideoParam *in, mfxVideoParam *out);

Parameters

 

session

SDK session handle

 

in

Pointer to the mfxVideoParam structure as input

 

out

Pointer to the mfxVideoParam structure as output

Description

 

This function works in one of two modes:

  1. If the in pointer is zero, the function returns the class configurability in the output mfxVideoParam structure. A non-zero value in each field of the output structure indicates that the field is configurable by the SDK implementation with the MFXVideoDECODE_Init function).

  2. If the in parameter is non-zero, the function checks the validity of the fields in the input mfxVideoParam structure. Then the function returns the corrected values to the output mfxVideoParam structure. If there is insufficient information to determine the validity or correction is impossible, the function zeros the fields. This feature can verify whether the SDK implementation supports certain profiles, levels or bitrates.

The application can call this function before or after it initializes the decoder. The CodecId field of the output mfxVideoParam structure is a mandated field (to be filled by the application) to identify the coding standard.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

 

MFX_ERR_UNSUPPORTED

The function failed to identify a specific implementation.

 

MFX_WRN_PARTIAL_ACCELERATION

The underlying hardware does not fully support the specified video parameters; The decoding may be partially accelerated. Only SDK HW implementations may return this status code.

 

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM

The function detected some video parameters were incompatible with others; incompatibility resolved.

Change History

 

This function is available since SDK API 1.0.

Syntax

 

mfxStatus MFXVideoDECODE_QueryIOSurf(mfxSession session, mfxVideoParam *par, mfxFrameAllocRequest *request);

Parameters

 

session

SDK session handle

 

par

Pointer to the mfxVideoParam structure as input

 

request

Pointer to the mfxFrameAllocRequest structure as output

Description

 

The function returns minimum and suggested numbers of the output frame surfaces required for decoding initialization and their type. Init will call the external allocator for the required frames with the same set of numbers.

The use of this function is recommended. For more information, see the section Working with hardware acceleration.

The CodecId field of the mfxVideoParam structure is a mandated field (to be filled by the application) to identify the coding standard.

This function does not validate I/O parameters except those used in calculating the number of output surfaces.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

 

MFX_WRN_PARTIAL_ACCELERATION

The underlying hardware does not fully support the specified video parameters; The decoding may be partially accelerated. Only SDK HW implementations may return this status code.

 

MFX_ERR_INVALID_VIDEO_PARAM

The function detected invalid video parameters. These parameters may be out of the valid range, or the combination of them resulted in incompatibility. Incompatibility not resolved.

 

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM

The function detected some video parameters were incompatible with others; incompatibility resolved.

Change History

 

This function is available since SDK API 1.0.

MFXVideoDECODE_Init

Syntax

 

mfxStatus MFXVideoDECODE_Init(mfxSession session, mfxVideoParam *par);

Parameters

 

session

SDK session handle

 

par

Pointer to the mfxVideoParam structure

Description

 

This function allocates memory and prepares tables and necessary structures for decoding. This function also does extensive validation to determine whether the configuration is supported as specified in the input parameters.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

 

MFX_WRN_PARTIAL_ACCELERATION

The underlying hardware does not fully support the specified video parameters; The decoding may be partially accelerated. Only SDK hardware implementations return this status code.

 

MFX_ERR_INVALID_VIDEO_PARAM

The function detected invalid video parameters. These parameters may be out of the valid range, or the combination of parameters resulted in an incompatibility error. Incompatibility was not resolved.

 

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM

The function detected some video parameters were incompatible; Incompatibility resolved.

 

MFX_ERR_UNDEFINED_BEHAVIOR

The function is called twice without a close.

Change History

 

This function is available since SDK API 1.0.

Syntax

 

mfxStatus MFXVideoDECODE_Reset(mfxSession session, mfxVideoParam *par);

Parameters

 

session

SDK session handle

 

par

Pointer to the mfxVideoParam structure

Description

 

This function stops the current decoding operation and restores internal structures or parameters for a new decoding operation.

Reset serves two purposes:

·        It recovers the decoder from errors.

·        It restarts decoding from a new position.

The function resets the old sequence header (sequence parameter set in H.264, or sequence header in MPEG-2 and VC-1). The decoder will expect a new sequence header before it decodes the next frame and will skip any bitstream before encountering the new sequence header.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

 

MFX_ERR_INVALID_VIDEO_PARAM

The function detected that video parameters are wrong or they conflict with initialization parameters. Reset is impossible.

 

 

MFX_ERR_INCOMPATIBLE_VIDEO_PARAM

The function detected that provided by the application video parameters are incompatible with initialization parameters. Reset requires additional memory allocation and cannot be executed. The application should close the SDK component and then reinitialize it.

 

 

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM

The function detected some video parameters were incompatible; Incompatibility resolved.

 

Change History

 

This function is available since SDK API 1.0.

Syntax

 

mfxStatus MFXVideoDECODE_Close(mfxSession session);

Parameters

 

session

SDK session handle

Description

 

This function terminates the current decoding operation and de-allocates any internal tables or structures.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

Syntax

 

mfxStatus MFXVideoDECODE_GetVideoParam(mfxSession session, mfxVideoParam *par);

Parameters

 

session

SDK session handle

 

par

Pointer to the corresponding parameter structure

Description

 

This function retrieves current working parameters to the specified output structure. If extended buffers are to be returned, the application must allocate those extended buffers and attach them as part of the output structure.

The application can retrieve a copy of the bitstream header, by attaching the mfxExtCodingOptionSPSPPS structure to the mfxVideoParam structure.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

Syntax

 

mfxStatus MFXVideoDECODE_GetDecodeStat(mfxSession session, mfxDecodeStat *stat);

Parameters

 

session

SDK session handle

 

stat

Pointer to the mfxDecodeStat structure

Description

 

This function obtains statistics collected during decoding.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

Syntax

 

mfxStatus MFXVideoDECODE_GetPayload(mfxSession session, mfxU64 *ts, mfxPayload *payload);

Parameters

 

session

SDK session handle

 

ts

Pointer to the user data time stamp in units of 90 KHz; divide ts by 90,000 (90 KHz) to obtain the time in seconds; the time stamp matches the payload with a specific decoded frame.

 

payload

Pointer to the mfxPayload structure; the payload contains user data in MPEG-2 or SEI messages in H.264.

Description

 

This function extracts user data (MPEG-2) or SEI (H.264) messages from the bitstream. Internally, the decoder implementation stores encountered user data or SEI messages. The application may call this function multiple times to retrieve the user data or SEI messages, one at a time.

If there is no payload available, the function returns with payloadàNumBit=0.

Return Status

 

MFX_ERR_NONE

The function completed successfully and the output buffer is ready for decoding.

 

MFX_ERR_NOT_ENOUGH_BUFFER

The payload buffer size is insufficient.

Change History

 

This function is available since SDK API 1.0.

Syntax

 

mfxStatus MFXVideoDECODE_SetSkipMode(mfxSession session, mfxSkipMode mode);

Parameters

 

session

SDK session handle

 

mode

Decoder skip mode. See the mfxSkipMode enumerator for details.

Description

 

This function sets the decoder skip mode. The application may use it to increase decoding performance by sacrificing output quality. The rising of skip level firstly results in skipping of some decoding operations like deblocking and then leads to frame skipping; firstly, B then P. Particular details are platform dependent.

Return Status

 

MFX_ERR_NONE

The function completed successfully and the output surface is ready for decoding.

 

MFX_WRN_VALUE_NOT_CHANGED

The skip mode is not affected as the maximum or minimum skip range is reached.

Change History

 

This function is available since SDK API 1.0.

Syntax

 

mfxStatus MFXVideoDECODE_DecodeFrameAsync(mfxSession session, mfxBitstream *bs, mfxFrameSurface1 *surface_work, mfxFrameSurface1 **surface_out, mfxSyncPoint *syncp);

Parameters

 

Session

SDK session handle

 

Bs

Pointer to the input bitstream

 

surface_work

Pointer to the working frame buffer for the decoder

 

surface_out

Pointer to the output frame in the display order

 

Syncp

Pointer to the sync point associated with this operation

Description

 

This function decodes the input bitstream to a single output frame.

The surface_work parameter provides a working frame buffer for the decoder. The application should allocate the working frame buffer, which stores decoded frames. If the function requires caching frames after decoding, the function locks the frames and the application must provide a new frame buffer in the next call.

If, and only if, the function returns MFX_ERR_NONE, the pointer surface_out points to the output frame in the display order. If there are no further frames, the function will reset the pointer to zero and return the appropriate status code.

Before decoding the first frame, a sequence header—sequence parameter set in H.264 or sequence header in MPEG-2 and VC-1—must be present. The function skips any bitstreams before it encounters the new sequence header.

The input bitstream bs can be of any size. If there are not enough bits to decode a frame, the function returns MFX_ERR_MORE_DATA, and consumes all input bits except if a partial start code or sequence header is at the end of the buffer. In this case, the function leaves the last few bytes in the bitstream buffer. If there is more incoming bitstream, the application should append the incoming bitstream to the bitstream buffer. Otherwise, the application should ignore the remaining bytes in the bitstream buffer and apply the end of stream procedure described below.

The application must set bs to NULL to signal end of stream. The application may need to call this function several times to drain any internally cached frames until the function returns MFX_ERR_MORE_DATA.

If more than one frame is in the bitstream buffer, the function decodes until the buffer is consumed. The decoding process can be interrupted for events such as if the decoder needs additional working buffers, is readying a frame for retrieval, or encountering a new header. In these cases, the function returns appropriate status code and moves the bitstream pointer to the remaining data.

The decoder may return MFX_ERR_NONE without taking any data from the input bitstream buffer. If the application appends additional data to the bitstream buffer, it is possible that the bitstream buffer may contain more than 1 frame. It is recommended that the application invoke the function repeatedly until the function returns MFX_ERR_MORE_DATA, before appending any more data to the bitstream buffer.

This function is asynchronous.

Return Status

 

MFX_ERR_NONE

The function completed successfully and the output surface is ready for decoding.

 

MFX_ERR_MORE_DATA

The function requires more bitstream at input before decoding can proceed.

 

MFX_ERR_MORE_SURFACE

The function requires more frame surface at output before decoding can proceed.

 

MFX_ERR_DEVICE_LOST

Hardware device was lost; See the Working with Microsoft* DirectX* Applications section for further information.

 

MFX_WRN_DEVICE_BUSY

Hardware device is currently busy. Call this function again in a few milliseconds.

 

MFX_WRN_VIDEO_PARAM_CHANGED

The decoder detected a new sequence header in the bitstream. Video parameters may have changed.

 

MFX_ERR_INCOMPATIBLE_VIDEO_PARAM

The decoder detected incompatible video parameters in the bitstream and failed to follow them.

 

MFX_ERR_REALLOC_SURFACE

Bigger surface_work required. May be returned only if mfxInfoMFX::EnableReallocRequest was set to ON during initialization.

Change History

 

This function is available since SDK API 1.0.

For more complete information about compiler optimizations, see our Optimization Notice.