# VPP Structures¶

Structures used by VPP only.

## API¶

### mfxExtColorConversion¶

struct mfxExtColorConversion

A hint structure that tunes the VPP Color Conversion algorithm when attached to the mfxVideoParam structure during VPP Init.

Public Members

mfxExtBuffer Header

mfxU16 ChromaSiting

See ChromaSiting enumerator for details.

ChromaSiting is applied on input or output surface depending on the scenario:

VPP Input

VPP Output

ChromaSiting Indicates

MFX_CHROMAFORMAT_YUV420

MFX_CHROMAFORMAT_YUV422

MFX_CHROMAFORMAT_YUV444

Chroma location for input

MFX_CHROMAFORMAT_YUV444

MFX_CHROMAFORMAT_YUV420

MFX_CHROMAFORMAT_YUV422

Chroma location for output

MFX_CHROMAFORMAT_YUV420

MFX_CHROMAFORMAT_YUV420

Chroma location for input and output

MFX_CHROMAFORMAT_YUV420

MFX_CHROMAFORMAT_YUV422

Horizontal location for input and output, vertical location for input

### mfxExtDecVideoProcessing¶

struct mfxExtDecVideoProcessing

If attached to the mfxVideoParam structure during the Init stage, this buffer will instruct the decoder to resize output frames via the fixed function resize engine (if supported by hardware), utilizing direct pipe connection and bypassing intermediate memory operations. The main benefits of this mode of pipeline operation are offloading resize operation to a dedicated engine, thus reducing power consumption and memory traffic.

Public Members

mfxExtBuffer Header

struct mfxExtDecVideoProcessing::mfxIn In

Input surface description.

struct mfxExtDecVideoProcessing::mfxOut Out

Output surface description.

struct mfxIn

Input surface description.

Public Members

mfxU16 CropX

X coordinate of region of interest of the input surface.

mfxU16 CropY

Y coordinate of region of interest of the input surface.

mfxU16 CropW

Width coordinate of region of interest of the input surface.

mfxU16 CropH

Height coordinate of region of interest of the input surface.

struct mfxOut

Output surface description.

Public Members

mfxU32 FourCC

FourCC of output surface Note: Should be MFX_FOURCC_NV12.

mfxU16 ChromaFormat

Chroma Format of output surface.

Note

Should be MFX_CHROMAFORMAT_YUV420

mfxU16 Width

Width of output surface.

mfxU16 Height

Height of output surface.

mfxU16 CropX

X coordinate of region of interest of the output surface.

mfxU16 CropY

Y coordinate of region of interest of the output surface.

mfxU16 CropW

Width coordinate of region of interest of the output surface.

mfxU16 CropH

Height coordinate of region of interest of the output surface.

### mfxExtEncodedSlicesInfo¶

struct mfxExtEncodedSlicesInfo

Used by the encoder to report additional information about encoded slices. The application can attach this buffer to the mfxBitstream structure before calling the MFXVideoENCODE_EncodeFrameAsync function.

Note

Not all implementations of the encoder support this extended buffer. The application must use query mode 1 to determine if the functionality is supported. To do this, the application must attach this extended buffer to the mfxVideoParam structure and call the MFXVideoENCODE_Query function. If the function returns MFX_ERR_NONE, then the functionality is supported.

Public Members

mfxExtBuffer Header

mfxU16 SliceSizeOverflow

When mfxExtCodingOption2::MaxSliceSize is used, indicates the requested slice size was not met for one or more generated slices.

mfxU16 NumSliceNonCopliant

When mfxExtCodingOption2::MaxSliceSize is used, indicates the number of generated slices exceeds specification limits.

mfxU16 NumEncodedSlice

Number of encoded slices.

mfxU16 NumSliceSizeAlloc

SliceSize array allocation size. Must be specified by application.

mfxU16 *SliceSize

Slice size in bytes. Array must be allocated by application.

### mfxExtVppAuxData¶

struct mfxExtVppAuxData

Returns auxiliary data generated by the video processing pipeline. The encoding process may use the auxiliary data by attaching this structure to the mfxEncodeCtrl structure.

Public Members

mfxExtBuffer Header

mfxU16 PicStruct

Detected picture structure - top field first, bottom field first, progressive or unknown if video processor cannot detect picture structure. See the PicStruct enumerator for definition of these values.

### mfxExtVPPColorFill¶

struct mfxExtVPPColorFill

Configures the VPP ColorFill filter algorithm.

Public Members

mfxExtBuffer Header

mfxU16 Enable

Set to ON makes VPP fill the area between Width/Height and Crop borders. See the CodingOptionValue enumerator for values of this option.

### mfxExtVPPComposite¶

struct mfxExtVPPComposite

Used to control composition of several input surfaces in one output. In this mode, the VPP skips any other filters. The VPP returns an error if any mandatory filter is specified and returns the filter skipped warning if an optional filter is specified. The only supported filters are deinterlacing and interlaced scaling. The only supported combinations of input and output color formats are:

• RGB to RGB,

• NV12 to NV12,

• RGB and NV12 to NV12, for per the pixel alpha blending use case.

The VPP returns MFX_ERR_MORE_DATA for additional input until an output is ready. When the output is ready, the VPP returns MFX_ERR_NONE. The application must process the output frame after synchronization.

The composition process is controlled by:

• mfxFrameInfo::CropXYWH in the input surface defines the location of the picture in the input frame.

• InputStream[i].DstXYWH defines the location of the cropped input picture in the output frame.

• mfxFrameInfo::CropXYWH in the output surface defines the actual part of the output frame. All pixels in the output frame outside this region will be filled by the specified color.

If the application uses the composition process on video streams with different frame sizes, the application should provide maximum frame size in the mfxVideoParam structure during the initialization, reset, or query operations.

If the application uses the composition process, the MFXVideoVPP_QueryIOSurf function returns the cumulative number of input surfaces, that is, the number required to process all input video streams. The function sets the frame size in the mfxFrameAllocRequest equal to the size provided by the application in the mfxVideoParam structure.

The composition process supports all types of surfaces.

All input surfaces should have the same type and color format, except for the per pixel alpha blending case, where it is allowable to mix NV12 and RGB surfaces.

There are three different blending use cases:

• Luma keying. All input surfaces should have the NV12 color format specified during VPP initialization. Part of each surface, including the first one, may be rendered transparent by using LumaKeyEnable, LumaKeyMin, and LumaKeyMax values.

• Global alpha blending. All input surfaces should have the same color format, NV12 or RGB, specified during VPP initialization. Each input surface, including the first one, can be blended with underlying surfaces by using GlobalAlphaEnable and GlobalAlpha values.

• Per-pixel alpha blending. It is allowed to mix NV12 and RGB input surfaces. Each RGB input surface, including the first one, can be blended with underlying surfaces by using PixelAlphaEnable value.

It is not allowed to mix different blending use cases in the same function call.

In the special case where the destination region of the output surface defined by output crops is fully covered with destination sub-regions of the surfaces, the fast compositing mode can be enabled. The main use case for this mode is a video-wall scenario with a fixed destination surface partition into sub-regions of potentially different size.

In order to trigger this mode, the application must cluster input surfaces into tiles, defining at least one tile by setting the NumTiles field to be greater than 0, and assigning surfaces to the corresponding tiles by setting the TileId field to the value within the 0 to NumTiles range per input surface. Tiles should also satisfy the following additional constraints:

• Each tile should not have more than 8 surfaces assigned to it.

• Tile bounding boxes, as defined by the enclosing rectangles of a union of a surfaces assigned to this tile, should not intersect.

Background color may be changed dynamically through Reset. There is no default value. YUV black is (0;128;128) or (16;128;128) depending on the sample range. The library uses a YUV or RGB triple depending on output color format.

Public Members

mfxExtBuffer Header

mfxU16 Y

Y value of the background color.

mfxU16 R

R value of the background color.

mfxU16 U

U value of the background color.

mfxU16 G

G value of the background color.

mfxU16 V

V value of the background color.

mfxU16 B

B value of the background color.

mfxU16 NumTiles

Number of input surface clusters grouped together to enable fast compositing. May be changed dynamically at runtime through Reset.

mfxU16 NumInputStream

Number of input surfaces to compose one output. May be changed dynamically at runtime through Reset. Number of surfaces can be decreased or increased, but should not exceed the number specified during initialization. Query mode 2 should be used to find the maximum supported number.

mfxVPPCompInputStream *InputStream

An array of mfxVPPCompInputStream structures that describe composition of input video streams. It should consist of exactly NumInputStream elements.

### mfxExtVPPDeinterlacing¶

struct mfxExtVPPDeinterlacing

Used by the application to specify different deinterlacing algorithms.

Public Members

mfxExtBuffer Header

mfxU16 Mode

Deinterlacing algorithm. See the DeinterlacingMode enumerator for details.

mfxU16 TelecinePattern

Specifies telecine pattern when Mode = MFX_DEINTERLACING_FIXED_TELECINE_PATTERN. See the TelecinePattern enumerator for details.

mfxU16 TelecineLocation

Specifies position inside a sequence of 5 frames where the artifacts start when TelecinePattern = MFX_TELECINE_POSITION_PROVIDED

mfxU16 reserved[9]

Reserved for future use.

### mfxExtVPPDenoise¶

struct mfxExtVPPDenoise

A hint structure that configures the VPP denoise filter algorithm.

Public Members

mfxExtBuffer Header

mfxU16 DenoiseFactor

Indicates the level of noise to remove. Value range of 0 to 100 (inclusive).

### mfxExtVPPDetail¶

struct mfxExtVPPDetail

A hint structure that configures the VPP detail/edge enhancement filter algorithm.

Public Members

mfxExtBuffer Header

mfxU16 DetailFactor

Indicates the level of details to be enhanced. Value range of 0 to 100 (inclusive).

### mfxExtVPPDoNotUse¶

struct mfxExtVPPDoNotUse

Tells the VPP not to use certain filters in pipeline. See “Configurable VPP filters” table for complete list of configurable filters. The user can attach this structure to the mfxVideoParam structure when initializing video processing.

Public Members

mfxExtBuffer Header

mfxU32 NumAlg

Number of filters (algorithms) not to use

mfxU32 *AlgList

Pointer to a list of filters (algorithms) not to use

### mfxExtVPPDoUse¶

struct mfxExtVPPDoUse

Tells the VPP to include certain filters in the pipeline.

Each filter may be included in the pipeline in one of two different ways:

• Adding a filter ID to this structure. In this method, the default filter parameters are used.

• Attaching a filter configuration structure directly to the mfxVideoParam structure. In this method, adding filter ID to the mfxExtVPPDoUse structure is optional.

See Table “Configurable VPP filters” for complete list of configurable filters, their IDs, and configuration structures.

The user can attach this structure to the mfxVideoParam structure when initializing video processing.

Note

MFX_EXTBUFF_VPP_COMPOSITE cannot be enabled using mfxExtVPPDoUse because default parameters are undefined for this filter. The application must attach the appropriate filter configuration structure directly to the mfxVideoParam structure to enable it.

Public Members

mfxExtBuffer Header

mfxU32 NumAlg

Number of filters (algorithms) to use

mfxU32 *AlgList

Pointer to a list of filters (algorithms) to use

### mfxExtVPPFieldProcessing¶

struct mfxExtVPPFieldProcessing

Configures the VPP field processing algorithm. The application can attach this extended buffer to the mfxVideoParam structure to configure initialization and/or to the mfxFrameData during runtime. Runtime configuration has priority over initialization configuration. If the field processing algorithm was activated via the mfxExtVPPDoUse structure and the mfxExtVPPFieldProcessing extended buffer was not provided during initialization, this buffer must be attached to the mfxFrameData structure of each input surface.

Public Members

mfxExtBuffer Header

mfxU16 Mode

Specifies the mode of the field processing algorithm. See the VPPFieldProcessingMode enumerator for values of this option.

mfxU16 InField

When Mode is MFX_VPP_COPY_FIELD, specifies input field. See the PicType enumerator for values of this parameter.

mfxU16 OutField

When Mode is MFX_VPP_COPY_FIELD, specifies output field. See the PicType enumerator for values of this parameter.

### mfxExtVPPFrameRateConversion¶

struct mfxExtVPPFrameRateConversion

Configures the VPP frame rate conversion filter. The user can attach this structure to the mfxVideoParam structure when initializing, resetting, or querying capability of video processing.

On some platforms the advanced frame rate conversion algorithm (the algorithm based on frame interpolation) is not supported. To query its support, the application should add the MFX_FRCALGM_FRAME_INTERPOLATION flag to the Algorithm value in the mfxExtVPPFrameRateConversion structure, attach it to the structure, and call the MFXVideoVPP_Query function. If the filter is supported, the function returns a MFX_ERR_NONE status and copies the content of the input structure to the output structure. If an advanced filter is not supported, then a simple filter will be used and the function returns MFX_WRN_INCOMPATIBLE_VIDEO_PARAM, copies content of the input structure to the output structure, and corrects the Algorithm value.

If advanced FRC algorithm is not supported, both MFXVideoVPP_Init and MFXVideoVPP_Reset functions return the MFX_WRN_INCOMPATIBLE_VIDEO_PARAM status.

Public Members

mfxExtBuffer Header

mfxU16 Algorithm

See the FrcAlgm enumerator for a list of frame rate conversion algorithms.

### mfxExtVPPImageStab¶

struct mfxExtVPPImageStab

A hint structure that configures the VPP image stabilization filter.

On some platforms this filter is not supported. To query its support, the application should use the same approach that it uses to configure VPP filters: adding the filter ID to the mfxExtVPPDoUse structure or by attaching the mfxExtVPPImageStab structure directly to the mfxVideoParam structure and calling the MFXVideoVPP_Query function.

If this filter is supported, the function returns a MFX_ERR_NONE status and copies the content of the input structure to the output structure. If the filter is not supported, the function returns MFX_WRN_FILTER_SKIPPED, removes the filter from the mfxExtVPPDoUse structure, and zeroes the mfxExtVPPImageStab structure.

If the image stabilization filter is not supported, both MFXVideoVPP_Init and MFXVideoVPP_Reset functions return a MFX_WRN_FILTER_SKIPPED status.

The application can retrieve the list of active filters by attaching the mfxExtVPPDoUse structure to the mfxVideoParam structure and calling the MFXVideoVPP_GetVideoParam function. The application must allocate enough memory for the filter list.

Public Members

mfxExtBuffer Header

mfxU16 Mode

Image stabilization mode. See ImageStabMode enumerator for values.

### mfxExtVppMctf¶

struct mfxExtVppMctf

Provides setup for the Motion-Compensated Temporal Filter (MCTF) during the VPP initialization and for control parameters at runtime. By default, MCTF is off. An application may enable it by adding MFX_EXTBUFF_VPP_MCTF to the mfxExtVPPDoUse buffer or by attaching mfxExtVppMctf to the mfxVideoParam structure during initialization or reset.

Public Members

mfxExtBuffer Header

mfxU16 FilterStrength

Value in range of 0 to 20 (inclusive) to indicate the filter strength of MCTF.

The strength of the MCTF process controls the degree of possible change of pixel values eligible for MCTF - the greater the strength value, the larger the change. It is a dimensionless quantity - values in the range of 1 to 20 inclusively imply strength; value 0 stands for AUTO mode and is valid during initialization or reset only

If an invalid value is given, it is fixed to the default value of 0. If the field value is in the range of 1 to 20 inclusive, MCTF operates in fixed-strength mode with the given strength of MCTF process.

At runtime, values of 0 and greater than 20 are ignored.

### mfxExtVPPMirroring¶

struct mfxExtVPPMirroring

Configures the VPP Mirroring filter algorithm.

Public Members

mfxExtBuffer Header

mfxU16 Type

Mirroring type. See MirroringType for values.

### mfxExtVPPProcAmp¶

struct mfxExtVPPProcAmp

A hint structure that configures the VPP ProcAmp filter algorithm. The structure parameters will be clipped to their corresponding range and rounded by their corresponding increment.

Note

There are no default values for fields in this structure, all settings must be explicitly specified every time this buffer is submitted for processing.

Public Members

mfxExtBuffer Header

mfxF64 Brightness

The brightness parameter is in the range of -100.0F to 100.0F, in increments of 0.1F. Setting this field to 0.0F will disable brightness adjustment.

mfxF64 Contrast

The contrast parameter in the range of 0.0F to 10.0F, in increments of 0.01F, is used for manual contrast adjustment. Setting this field to 1.0F will disable contrast adjustment. If the parameter is negative, contrast will be adjusted automatically.

mfxF64 Hue

The hue parameter is in the range of -180F to 180F, in increments of 0.1F. Setting this field to 0.0F will disable hue adjustment.

mfxF64 Saturation

The saturation parameter is in the range of 0.0F to 10.0F, in increments of 0.01F. Setting this field to 1.0F will disable saturation adjustment.

### mfxExtVPPRotation¶

struct mfxExtVPPRotation

Configures the VPP Rotation filter algorithm.

Public Members

mfxExtBuffer Header

mfxU16 Angle

Rotation angle. See Angle enumerator for supported values.

### mfxExtVPPScaling¶

struct mfxExtVPPScaling

Configures the VPP Scaling filter algorithm. Not all combinations of ScalingMode and InterpolationMethod are supported in the library. The application must use the Query API function to determine if a combination is supported.

Public Members

mfxExtBuffer Header

mfxU16 ScalingMode

Scaling mode. See ScalingMode for values.

mfxU16 InterpolationMethod

Interpolation mode for scaling algorithm. See InterpolationMode for values.

### mfxExtVPPVideoSignalInfo¶

struct mfxExtVPPVideoSignalInfo

Used to control transfer matrix and nominal range of YUV frames. The application should provide this during initialization. Supported for multiple conversions, for example YUV to YUV, YUV to RGB, and RGB to YUV.

Note

This structure is used by VPP only and is not compatible with mfxExtVideoSignalInfo.

Public Members

mfxExtBuffer Header

mfxU16 TransferMatrix

Transfer matrix.

mfxU16 NominalRange

Nominal range.

### mfxInfoVPP¶

struct mfxInfoVPP

Specifies configurations for video processing. A zero value in any of the fields indicates that the corresponding field is not explicitly specified.

Public Members

mfxFrameInfo In

Input format for video processing.

mfxFrameInfo Out

Output format for video processing.

### mfxVPPCompInputStream¶

struct mfxVPPCompInputStream

Used to specify input stream details for composition of several input surfaces in the one output.

Public Members

mfxU32 DstX

X coordinate of location of input stream in output surface.

mfxU32 DstY

Y coordinate of location of input stream in output surface.

mfxU32 DstW

Width of of location of input stream in output surface.

mfxU32 DstH

Height of of location of input stream in output surface.

mfxU16 LumaKeyEnable

Non-zero value enables luma keying for the input stream. Luma keying is used to mark some of the areas of the frame with specified luma values as transparent. It may, for example, be used for closed captioning.

mfxU16 LumaKeyMin

Minimum value of luma key, inclusive. Pixels whose luma values fit in this range are rendered transparent.

mfxU16 LumaKeyMax

Maximum value of luma key, inclusive. Pixels whose luma values fit in this range are rendered transparent.

mfxU16 GlobalAlphaEnable

Non-zero value enables global alpha blending for this input stream.

mfxU16 GlobalAlpha

Alpha value for this stream. Should be in the range of 0 to 255, where 0 is transparent and 255 is opaque.

mfxU16 PixelAlphaEnable

Non-zero value enables per pixel alpha blending for this input stream. The stream should have RGB color format.

mfxU16 TileId

Specify the tile this video stream is assigned to. Should be in the range of 0 to NumTiles. Valid only if NumTiles > 0.

### mfxVPPStat¶

struct mfxVPPStat

Returns statistics collected during video processing.

Public Members

mfxU32 NumFrame

Total number of frames processed.

mfxU32 NumCachedFrame

Number of internally cached frames.