VideoDECODE

Functions that implement a complete decoder that decompresses input bitstreams directly to output frame surfaces.

API

MFXVideoDECODE_Query

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

Works in one of two modes:

• If the in parameter is zero, the function returns the class configurability in the output structure. A non-zero value in each field of the output structure indicates that the field is configurable by the implementation with the MFXVideoDECODE_Init function.

• If the in parameter is non-zero, the function checks the validity of the fields in the input structure. Then the function returns the corrected values to the output 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 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 structure is a mandated field (to be filled by the application) to identify the coding standard.

Since

This function is available since API version 1.0.

Parameters:

• session – [in] Session handle.

• in – [in] Pointer to the mfxVideoParam structure as input.

• out – [out] Pointer to the mfxVideoParam structure as output.

Returns:

MFX_ERR_NONE The function completed successfully.

MFX_ERR_UNSUPPORTED The function failed to identify a specific implementation for the required features.

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

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

Important

The MFXVideoDECODE_Query() is mandatory when implementing a decoder.

MFXVideoDECODE_DecodeHeader

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

Parses the input bitstream and fills the mfxVideoParam structure with appropriate values, such as resolution and frame rate, for the Init API function.

The application can then pass the resulting structure to the MFXVideoDECODE_Init function for decoder initialization.

An application can call this API function at any time before or after decoder initialization. If the library 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.

Since

This function is available since API version 1.0.

Parameters:

• session – [in] Session handle.

• bs – [in] Pointer to the bitstream.

• par – [in] Pointer to the mfxVideoParam structure.

Returns:

• MFX_ERR_NONE The function successfully filled the structure. It does not mean that the stream can be decoded by the library. 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.

• MFX_ERR_UNSUPPORTED CodecId field of the mfxVideoParam structure indicates some unsupported codec.

• MFX_ERR_INVALID_HANDLE Session is not initialized.

• MFX_ERR_NULL_PTR bs or par pointer is NULL.

MFXVideoDECODE_QueryIOSurf

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

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 Working with Hardware Acceleration section.

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.

Since

This function is available since API version 1.0.

Parameters:

• session – [in] Session handle.

• par – [in] Pointer to the mfxVideoParam structure as input.

• request – [in] Pointer to the mfxFrameAllocRequest structure as output.

Returns:

MFX_ERR_NONE The function completed successfully.

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_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The encoding may be partially accelerated. Only hardware implementations may return this status code.

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

MFXVideoDECODE_Init

mfxStatus MFXVideoDECODE_Init(mfxSession session, mfxVideoParam *par)

Allocates memory and prepares tables and necessary structures for encoding.

This function also does extensive validation to ensure if the configuration, as specified in the input parameters, is supported.

Since

This function is available since API version 1.0.

Parameters:

• session – [in] Session handle.

• par – [in] Pointer to the mfxVideoParam structure.

Returns:

MFX_ERR_NONE The function completed successfully.

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_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The encoding may be partially accelerated. Only hardware implementations may return this status code.

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

MFX_ERR_UNDEFINED_BEHAVIOR The function is called twice without a close.

Important

The MFXVideoDECODE_Init() is mandatory when implementing a decoder.

MFXVideoDECODE_Reset

mfxStatus MFXVideoDECODE_Reset(mfxSession session, mfxVideoParam *par)

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.

Since

This function is available since API version 1.0.

Parameters:

• session – [in] Session handle.

• par – [in] Pointer to the mfxVideoParam structure.

Returns:

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 video parameters provided by the application are incompatible with initialization parameters. Reset requires additional memory allocation and cannot be executed. The application should close the component and then reinitialize it.

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

MFXVideoDECODE_Close

mfxStatus MFXVideoDECODE_Close(mfxSession session)

Terminates the current decoding operation and de-allocates any internal tables or structures.

Since

This function is available since API version 1.0.

Parameters:

session – [in] Session handle.

Returns:

MFX_ERR_NONE The function completed successfully.

Important

The MFXVideoDECODE_Close() is mandatory when implementing a decoder.

MFXVideoDECODE_GetVideoParam

mfxStatus MFXVideoDECODE_GetVideoParam(mfxSession session, mfxVideoParam *par)

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.

Since

This function is available since API version 1.0.

Parameters:

• session – [in] Session handle.

• par – [in] Pointer to the corresponding parameter structure.

Returns:

MFX_ERR_NONE The function completed successfully.

MFXVideoDECODE_GetDecodeStat

mfxStatus MFXVideoDECODE_GetDecodeStat(mfxSession session, mfxDecodeStat *stat)

Obtains statistics collected during decoding.

Since

This function is available since API version 1.0.

Parameters:

• session – [in] Session handle.

• stat – [in] Pointer to the mfxDecodeStat structure.

Returns:

MFX_ERR_NONE The function completed successfully.

MFXVideoDECODE_SetSkipMode

mfxStatus MFXVideoDECODE_SetSkipMode(mfxSession session, mfxSkipMode mode)

Sets the decoder skip mode.

The application may use this API function to increase decoding performance by sacrificing output quality. Increasing the skip level first results in skipping of some decoding operations like deblocking and then leads to frame skipping; first B, then P. Particular details are platform dependent.

Since

This function is available since API version 1.0.

Parameters:

• session – [in] Session handle.

• mode – [in] Decoder skip mode. See the mfxSkipMode enumerator for details.

Returns:

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.

MFXVideoDECODE_GetPayload

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

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 API 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.

Since

This function is available since API version 1.0.

Parameters:

• session – [in] Session handle.

• ts – [in] 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 – [in] Pointer to the mfxPayload structure; the payload contains user data in MPEG-2 or SEI messages in H.264.

Returns:

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.

MFXVideoDECODE_DecodeFrameAsync

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

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, it 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 API 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 one 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.

Starting from API 2.0 it is possible to pass NULL instead of surface_work. In such case runtime will allocate output frames internally.

This function is asynchronous.

Since

This function is available since API version 1.0.

Parameters:

• session – [in] Session handle.

• bs – [in] Pointer to the input bitstream.

• surface_work – [in] Pointer to the working frame buffer for the decoder.

• surface_out – [out] Pointer to the output frame in the display order.

• syncp – [out] Pointer to the sync point associated with this operation.

Returns:

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 after MFXVideoCORE_SyncOperation or 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.

MFX_WRN_ALLOC_TIMEOUT_EXPIRED Timeout expired for internal output frame allocation (if set with

mfxExtAllocationHints and NULL passed as surface_work). Repeat the call in a few milliseconds or re-initialize decoder with higher surface limit.

Important

The MFXVideoDECODE_DecodeFrameAsync() is mandatory when implementing a decoder.