VideoDECODE_VPP#

Functions that implement combined operation of decoding and video processing with multiple output frame surfaces.

API#

MFXVideoDECODE_VPP_Init#

mfxStatus MFXVideoDECODE_VPP_Init(mfxSession session, mfxVideoParam *decode_par, mfxVideoChannelParam **vpp_par_array, mfxU32 num_vpp_par)#

Initialize the SDK in (decode + vpp) mode. The logic of this function is similar to MFXVideoDECODE_Init, but application has to provide array of pointers to mfxVideoChannelParam

and num_channel_param - number of channels. Application is responsible for

memory allocation for

mfxVideoChannelParam

parameters and for each channel it should specify channel IDs:

mfxVideoChannelParam::mfxFrameInfo::ChannelId. ChannelId should be unique value within one session. ChannelID equals to the 0 is reserved for the original decoded frame. The application can attach

mfxExtInCrops to mfxVideoChannelParam::ExtParam to annotate input video frame if it wants to enable letterboxing operation.

Since

This function is available since API version 2.1.

Parameters:

  • session – [in] SDK session handle.

  • decode_par – [in] Pointer to the mfxVideoParam structure which contains initialization parameters for decoder.

  • vpp_par_array – [in] Array of pointers to mfxVideoChannelParamstructures. Each mfxVideoChannelParam contains initialization parameters for each VPP channel.

  • num_vpp_par – [in] Size of array of pointers to mfxVideoChannelParam structures.

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_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

MFX_ERR_UNDEFINED_BEHAVIOR The component is already initialized.

MFX_WRN_FILTER_SKIPPED The VPP skipped one or more filters requested by the application.

Important

The MFXVideoDECODE_VPP_Init() is mandatory when implementing a combined decode plus vpp.

MFXVideoDECODE_VPP_Reset#

mfxStatus MFXVideoDECODE_VPP_Reset(mfxSession session, mfxVideoParam *decode_par, mfxVideoChannelParam **vpp_par_array, mfxU32 num_vpp_par)#

This function is similar to MFXVideoDECODE_Reset and stops the current decoding and vpp operation, and restores internal structures or parameters for a new decoding plus vpp operation. It resets the state of the decoder and/or all initialized vpp channels. Applications have to care about draining of buffered frames for decode and all vpp channels before call this function. The application can attach mfxExtInCrops to mfxVideoChannelParam::ExtParam to annotate input video frame if it wants to enable letterboxing operation.

Since

This function is available since API version 2.1.

Parameters:

  • session – [in] Session handle.

  • decode_par – [in] Pointer to the mfxVideoParam structure which contains new initialization parameters for decoder. Might be NULL if application wants to Reset only VPP channels.

  • vpp_par_array – [in] Array of pointers to mfxVideoChannelParam structures. Each mfxVideoChannelParam contains new initialization parameters for each VPP channel.

  • num_vpp_par – [in] Size of array of pointers to mfxVideoChannelParam structures.

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. MFX_ERR_NULL_PTR Both pointers decode_par and vpp_par_array` equal to zero.

MFXVideoDECODE_VPP_GetChannelParam#

mfxStatus MFXVideoDECODE_VPP_GetChannelParam(mfxSession session, mfxVideoChannelParam *par, mfxU32 channel_id)#

Returns actual VPP parameters for selected channel which should be specified by application through

mfxVideoChannelParam::mfxFrameInfo::ChannelId.

Since

This function is available since API version 2.1.

Parameters:

  • session – [in] Session handle.

  • par – [in] Pointer to the mfxVideoChannelParam structure which allocated by application

  • channel_id – [in] specifies the requested channel’s info

Returns:

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NULL_PTR par pointer is NULL.

MFX_ERR_NOT_FOUND the library is not able to find VPP channel with such channel_id.

MFXVideoDECODE_VPP_DecodeFrameAsync#

mfxStatus MFXVideoDECODE_VPP_DecodeFrameAsync(mfxSession session, mfxBitstream *bs, mfxU32 *skip_channels, mfxU32 num_skip_channels, mfxSurfaceArray **surf_array_out)#

This function is similar to MFXVideoDECODE_DecodeFrameAsync and inherits all bitstream processing logic. As output, it allocates and returns surf_array_out array of processed surfaces according to the chain of filters specified by application in MFXVideoDECODE_VPP_Init, including original decoded frames. In the surf_array_out, the original decoded frames are returned through surfaces with mfxFrameInfo::ChannelId == 0, followed by each of the subsequent frame surfaces for each of the requested mfxVideoChannelParam entries provided to the MFXVideoCECODE_VPP_Init function. At maximum, the number of frame surfaces return is 1 + the value of num_vpp_par to the MFXVideoDECODE_VPP_Init function, but the application must be prepared to the case when some particular filters are not ready to output surfaces, so the length of surf_array_out will be less. Application should use mfxFrameInfo::ChannelId parameter to match output surface against configured filter.

An application must synchronize each output surface from the surf_array_out surface array independently.

Since

This function is available since API version 2.1.

Parameters:

  • session – [in] SDK session handle.

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

  • skip_channels – [in] Pointer to the array of ChannelIds which specifies channels with skip output frames. Memory for the array is allocated by application.

  • num_skip_channels – [in] Number of channels addressed by skip_channels.

  • surf_array_out – [out] The address of a pointer to the structure with frame surfaces.

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_NULL_PTR num_skip_channels doesn’t equal to 0 when skip_channels is NULL.

Important

The MFXVideoDECODE_VPP_DecodeFrameAsync() is mandatory when implementing a combined decode plus vpp.

MFXVideoDECODE_VPP_Close#

mfxStatus MFXVideoDECODE_VPP_Close(mfxSession session)#

This function is similar to MFXVideoDECODE_Close. It terminates the current decoding and vpp operation and de-allocates any internal tables or structures.

Since

This function is available since API version 2.1.

Parameters:

session – [in] Session handle.

Returns:

MFX_ERR_NONE The function completed successfully.

Important

The MFXVideoDECODE_VPP_Close() is mandatory when implementing a combined decode plus vpp.