VideoVPP#

Functions that perform video processing before encoding, rendering, or standalone.

API#

MFXVideoVPP_Query#

mfxStatus MFXVideoVPP_Query(mfxSession session, mfxVideoParam *in, mfxVideoParam *out)#

Works in one of two modes:

  • If the in pointer is zero, the function returns the class configurability in the output structure. A non-zero value in a field indicates that the implementation can configure it with Init.

  • 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 zeroes the fields.

The application can call this function before or after it initializes the preprocessor.

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 implementation does not support the specified configuration.

MFX_WRN_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The video processing 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 MFXVideoVPP_Query() function is mandatory when implementing a VPP filter.

MFXVideoVPP_QueryIOSurf#

mfxStatus MFXVideoVPP_QueryIOSurf(mfxSession session, mfxVideoParam *par, mfxFrameAllocRequest request[2])#

Returns minimum and suggested numbers of the input frame surfaces required for video processing initialization and their type.

The parameter request[0] refers to the input requirements; request[1] refers to output requirements. Init will call the external allocator for the required frames with the same set of numbers. This function does not validate I/O parameters except those used in calculating the number of input surfaces.

The use of this function is recommended.

For more information, see the Working with Hardware Acceleration section.

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; use request[0] for input requirements and request[1] for output requirements for video processing.

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 video processing 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.

MFXVideoVPP_Init#

mfxStatus MFXVideoVPP_Init(mfxSession session, mfxVideoParam *par)#

Allocates memory and prepares tables and necessary structures for video processing.

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 video processing 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.

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

Important

The MFXVideoVPP_Init() function is mandatory when implementing a VPP filter.

MFXVideoVPP_Reset#

mfxStatus MFXVideoVPP_Reset(mfxSession session, mfxVideoParam *par)#

Stops the current video processing operation and restores internal structures or parameters for a new operation.

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.

MFXVideoVPP_Close#

mfxStatus MFXVideoVPP_Close(mfxSession session)#

Terminates the current video processing 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 MFXVideoVPP_Close() function is mandatory when implementing a VPP filter.

MFXVideoVPP_GetVideoParam#

mfxStatus MFXVideoVPP_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.

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.

MFXVideoVPP_GetVPPStat#

mfxStatus MFXVideoVPP_GetVPPStat(mfxSession session, mfxVPPStat *stat)#

Obtains statistics collected during video processing.

Since

This function is available since API version 1.0.

Parameters

  • session – [in] Session handle.

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

Returns

MFX_ERR_NONE The function completed successfully.

MFXVideoVPP_RunFrameVPPAsync#

mfxStatus MFXVideoVPP_RunFrameVPPAsync(mfxSession session, mfxFrameSurface1 *in, mfxFrameSurface1 *out, mfxExtVppAuxData *aux, mfxSyncPoint *syncp)#

Processes a single input frame to a single output frame.

Retrieval of the auxiliary data is optional; the encoding process may use it. The video processing process may not generate an instant output given an input.

See the Video Processing Procedures section for details on how to correctly send input and retrieve output.

At the end of the stream, call this function with the input argument in=NULL to retrieve any remaining frames, until the function returns MFX_ERR_MORE_DATA. This function is asynchronous.

Since

This function is available since API version 1.0.

Parameters

  • session – [in] Session handle.

  • in – [in] Pointer to the input video surface structure.

  • out – [out] Pointer to the output video surface structure.

  • aux – [in] Optional pointer to the auxiliary data structure.

  • syncp – [out] Pointer to the output sync point.

Returns

MFX_ERR_NONE The output frame is ready after synchronization.

MFX_ERR_MORE_DATA Need more input frames before VPP can produce an output.

MFX_ERR_MORE_SURFACE The output frame is ready after synchronization. Need more surfaces at output for additional output frames available.

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.

MFXVideoVPP_ProcessFrameAsync#

mfxStatus MFXVideoVPP_ProcessFrameAsync(mfxSession session, mfxFrameSurface1 *in, mfxFrameSurface1 **out)#

The function processes a single input frame to a single output frame with internal allocation of output frame.

At the end of the stream, call this function with the input argument in=NULL to retrieve any remaining frames, until the function returns MFX_ERR_MORE_DATA. This function is asynchronous.

Since

This function is available since API version 2.1.

Parameters

  • session – [in] Session handle.

  • in – [in] Pointer to the input video surface structure.

  • out – [out] Pointer to the output video surface structure which is reference counted object allocated by the library.

Returns

MFX_ERR_NONE The output frame is ready after synchronization.

MFX_ERR_MORE_DATA Need more input frames before VPP can produce an output.

MFX_ERR_MEMORY_ALLOC The function failed to allocate output video frame.

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_ALLOC_TIMEOUT_EXPIRED Timeout expired for internal output frame allocation (if set with

mfxExtAllocationHints). Repeat the call in a few milliseconds or reinitialize VPP with higher surface limit.

Important

Either MFXVideoVPP_RunFrameVPPAsync() or MFXVideoVPP_ProcessFrameAsync() function is mandatory when implementing a VPP filter.