MFXVideoVPP

This class of functions performs video processing before encoding.

Member Functions

 

MFXVideoVPP_Query

Queries the feature capability

MFXVideoVPP_QueryIOSurf

Queries the number of input and output surface frames required for video processing

MFXVideoVPP_Init

Initializes the VPP operation

MFXVideoVPP_Reset

Resets the current video processing operation and prepares for the next operation

MFXVideoVPP_Close

Terminates the video processing operation and de-allocates internal memory

MFXVideoVPP_GetVideoParam

Obtains the current working parameter set

MFXVideoVPP_GetVPPStat

Obtains statistics collected during video processing

MFXVideoVPP_RunFrameVPPAsync

Performs video processing on the frame level

 

 

MFXVideoVPP_Query

Syntax

 

mfxStatus MFXVideoVPP_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 either of two modes:

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

  2. If in is non-zero, the function checks the validity of the fields in the input mfxVideoParam structure. Then the function returns the corrected values in the output mfxVideoParam 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.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

 

MFX_ERR_UNSUPPORTED

The SDK 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 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.

 

 

 

MFXVideoVPP_QueryIOSurf

Syntax

 

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

Parameters

 

session

SDK session handle

 

par

Pointer to the mfxVideoParam structure as input

 

request

Pointer to the output mfxFrameAllocRequest structure; use request[0] for input requirements and request[1] for output requirements for video processing.

Description

 

This function returns minimum and suggested numbers of input and output 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.

The function is recommended. For more information, see the Working with hardware acceleration.

This function does not validate I/O parameters except those used in calculating the number of input and 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 video processing may be partially accelerated. Only SDK HW implementation 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.

 

 

 

MFXVideoVPP_Init

Syntax

 

mfxStatus MFXVideoVPP_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 video processing. This function also does extensive validation to ensure the configuration, as specified in the input parameters, is supported.

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 video processing may be partially accelerated. Only SDK HW implementation 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.

 

MFX_ERR_UNDEFINED_BEHAVIOR

The function was called twice without a close.

 

MFX_WRN_FILTER_SKIPPED

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

Change History

 

This function is available since SDK API 1.0. SDK API 1.6 added new return status, MFX_WRN_FILTER_SKIPPED.

 

 

 

MFXVideoVPP_Reset

Syntax

 

mfxStatus MFXVideoVPP_Reset(mfxSession session, mfxVideoParam *par);

Parameters

 

session

SDK session handle

 

par

Pointer to the mfxVideoParam structure

Description

 

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

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 with others; incompatibility resolved.

Change History

 

This function is available since SDK API 1.0.

 

 

 

MFXVideoVPP_Close

Syntax

 

mfxStatus MFXVideoVPP_Close(mfxSession session);

Parameters

 

session

SDK session handle

Description

 

This function terminates the current video processing operation and de-allocates internal tables and structures.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

 

 

 

MFXVideoVPP_GetVideoParam

Syntax

 

mfxStatus MFXVideoVPP_GetVideoParam(mfxSession session, mfxVideoParam *par);

Parameters

 

session

SDK session handle

 

par

Pointer to the corresponding parameter structure

Description

 

This function obtains current working parameters to the specified output structure. To return extended buffers, the application must allocate those extended buffers and attach them as part of the output structure.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

 

 

 

MFXVideoVPP_GetVPPStat

Syntax

 

mfxStatus MFXVideoVPP_GetVPPStat(mfxSession session, mfxVPPStat *stat);

Parameters

 

session

SDK session handle

 

stat

Pointer to the mfxVPPStat structure

Description

 

This function obtains statistics collected during video processing.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

 

 

 

MFXVideoVPP_RunFrameVPPAsync

Syntax

 

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

Parameters

 

session

SDK session handle

 

in

Pointer to the input video surface structure

 

out

Pointer to the output video surface structure

 

aux

Optional pointer to the auxiliary data structure

 

syncp

Pointer to the output sync point

Description

 

This function 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 section Video Processing Procedures 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.

Return Status

 

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 in a few milliseconds.

Change History

 

This function is available since SDK API 1.0.

 

 

 

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