Classes
struct	VAProcPipelineCaps
	Video processing pipeline capabilities. More...
struct	VAProcFilterValueRange
	Specification of values supported by the filter. More...
struct	VAProcPipelineParameterBuffer
	Video processing pipeline configuration. More...
struct	VAProcFilterParameterBufferBase
	Filter parameter buffer base. More...
struct	VAProcFilterParameterBuffer
	Default filter parametrization. More...
struct	VAProcFilterParameterBufferDeinterlacing
	Deinterlacing filter parametrization. More...
struct	VAProcFilterParameterBufferColorBalance
	Color balance filter parametrization. More...
struct	VAProcFilterParameterBufferColorStandard
	Color standard filter parametrization. More...
struct	VAProcFilterCap
	Default filter cap specification (single range value). More...
struct	VAProcFilterCapDeinterlacing
	Capabilities specification for the deinterlacing filter. More...
struct	VAProcFilterCapColorBalance
	Capabilities specification for the color balance filter. More...
struct	VAProcFilterCapColorStandard
	Capabilities specification for the color standard filter. More...
Enumerations
enum	VAProcFilterType { , VAProcFilterNoiseReduction, VAProcFilterDeinterlacing, VAProcFilterSharpening, VAProcFilterColorBalance, VAProcFilterColorStandard, VAProcFilterCount }
	Video filter types. More...
enum	VAProcDeinterlacingType { , VAProcDeinterlacingBob, VAProcDeinterlacingWeave, VAProcDeinterlacingMotionAdaptive, VAProcDeinterlacingMotionCompensated, VAProcDeinterlacingCount }
	Deinterlacing types. More...
enum	VAProcColorBalanceType { , VAProcColorBalanceHue, VAProcColorBalanceSaturation, VAProcColorBalanceBrightness, VAProcColorBalanceContrast, VAProcColorBalanceAutoSaturation, VAProcColorBalanceAutoBrightness, VAProcColorBalanceAutoContrast, VAProcColorBalanceCount }
	Color balance types. More...
enum	VAProcColorStandardType { , VAProcColorStandardBT601, VAProcColorStandardBT709, VAProcColorStandardBT470M, VAProcColorStandardBT470BG, VAProcColorStandardSMPTE170M, VAProcColorStandardSMPTE240M, VAProcColorStandardGenericFilm, VAProcColorStandardCount }
	Color standard types. More...
Functions
VAStatus	vaQueryVideoProcFilters (VADisplay dpy, VAContextID context, VAProcFilterType filters, unsigned int num_filters)
	Queries video processing filters.
VAStatus	vaQueryVideoProcFilterCaps (VADisplay dpy, VAContextID context, VAProcFilterType type, void filter_caps, unsigned int num_filter_caps)
	Queries video filter capabilities.
VAStatus	vaQueryVideoProcPipelineCaps (VADisplay dpy, VAContextID context, VABufferID filters, unsigned int num_filters, VAProcPipelineCaps pipeline_caps)
	Queries video processing pipeline capabilities.
Video pipeline flags
#define	VA_PROC_PIPELINE_SUBPICTURES 0x00000001
	Specifies whether to apply subpictures when processing a surface.
#define	VA_PROC_PIPELINE_FAST 0x00000002
	Specifies whether to apply power or performance optimizations to a pipeline.
Video filter flags
#define	VA_PROC_FILTER_MANDATORY 0x00000001
	Specifies whether the filter shall be present in the pipeline.

Detailed Description

The video processing API uses the same paradigm as for decoding:

Query for supported filters;
Set up a video processing pipeline;
Send video processing parameters through VA buffers.

Query for supported filters

Checking whether video processing is supported can be performed with vaQueryConfigEntrypoints() and the profile argument set to VAProfileNone. If video processing is supported, then the list of returned entry-points will include VAEntrypointVideoProc.

 VAEntrypoint *entrypoints;
 int i, num_entrypoints, supportsVideoProcessing = 0;

 num_entrypoints = vaMaxNumEntrypoints();
 entrypoints = malloc(num_entrypoints * sizeof(entrypoints[0]);
 vaQueryConfigEntrypoints(va_dpy, VAProfileNone,
     entrypoints, &num_entrypoints);

 for (i = 0; !supportsVideoProcessing && i < num_entrypoints; i++) {
     if (entrypoints[i] == VAEntrypointVideoProc)
         supportsVideoProcessing = 1;
 }

Then, the vaQueryVideoProcFilters() function is used to query the list of video processing filters.

 VAProcFilterType filters[VAProcFilterCount];
 unsigned int num_filters = VAProcFilterCount;

 // num_filters shall be initialized to the length of the array
 vaQueryVideoProcFilters(va_dpy, vpp_ctx, &pipe_caps, &num_filters);

Finally, individual filter capabilities can be checked with vaQueryVideoProcFilterCaps().

 VAProcFilterCap denoise_caps;
 unsigned int num_denoise_caps = 1;
 vaQueryVideoProcFilterCaps(va_dpy, vpp_ctx,
     VAProcFilterNoiseReduction,
     &denoise_caps, &num_denoise_caps
 );

 VAProcFilterCapDeinterlacing deinterlacing_caps[VAProcDeinterlacingCount];
 unsigned int num_deinterlacing_caps = VAProcDeinterlacingCount;
 vaQueryVideoProcFilterCaps(va_dpy, vpp_ctx,
     VAProcFilterDeinterlacing,
     &deinterlacing_caps, &num_deinterlacing_caps
 );

Set up a video processing pipeline

A video processing pipeline buffer is created for each source surface we want to process. However, buffers holding filter parameters can be created once and for all. Rationale is to avoid multiple creation/destruction chains of filter buffers and also because filter parameters generally won't change frame after frame. e.g. this makes it possible to implement a checkerboard of videos where the same filters are applied to each video source.

The general control flow is demonstrated by the following pseudo-code:

 // Create filters
 VABufferID denoise_filter, deint_filter;
 VABufferID filter_bufs[VAProcFilterCount];
 unsigned int num_filter_bufs;

 for (i = 0; i < num_filters; i++) {
     switch (filters[i]) {
     case VAProcFilterNoiseReduction: {       // Noise reduction filter
         VAProcFilterParameterBuffer denoise;
         denoise.type  = VAProcFilterNoiseReduction;
         denoise.value = 0.5;
         vaCreateBuffer(va_dpy, vpp_ctx,
             VAProcFilterParameterBufferType, sizeof(denoise), 1,
             &denoise, &denoise_filter
         );
         filter_bufs[num_filter_bufs++] = denoise_filter;
         break;
     }

     case VAProcFilterDeinterlacing:          // Motion-adaptive deinterlacing
         for (j = 0; j < num_deinterlacing_caps; j++) {
             VAProcFilterCapDeinterlacing * const cap = &deinterlacing_caps[j];
             if (cap->type != VAProcDeinterlacingMotionAdaptive)
                 continue;

             VAProcFilterParameterBufferDeinterlacing deint;
             deint.type                   = VAProcFilterDeinterlacing;
             deint.algorithm              = VAProcDeinterlacingMotionAdaptive;
             vaCreateBuffer(va_dpy, vpp_ctx,
                 VAProcFilterParameterBufferType, sizeof(deint), 1,
                 &deint, &deint_filter
             );
             filter_bufs[num_filter_bufs++] = deint_filter;
         }
     }
 }

Once the video processing pipeline is set up, the caller shall check the implied capabilities and requirements with vaQueryVideoProcPipelineCaps(). This function can be used to validate the number of reference frames are needed by the specified deinterlacing algorithm, the supported color primaries, etc.

 // Create filters
 VAProcPipelineCaps pipeline_caps;
 VASurfaceID *forward_references;
 unsigned int num_forward_references;
 VASurfaceID *backward_references;
 unsigned int num_backward_references;
 VAProcColorStandardType in_color_standards[VAProcColorStandardCount];
 VAProcColorStandardType out_color_standards[VAProcColorStandardCount];

 pipeline_caps.input_color_standards      = NULL;
 pipeline_caps.num_input_color_standards  = ARRAY_ELEMS(in_color_standards);
 pipeline_caps.output_color_standards     = NULL;
 pipeline_caps.num_output_color_standards = ARRAY_ELEMS(out_color_standards);
 vaQueryVideoProcPipelineCaps(va_dpy, vpp_ctx,
     filter_bufs, num_filter_bufs,
     &pipeline_caps
 );

 num_forward_references  = pipeline_caps.num_forward_references;
 forward_references      =
     malloc(num__forward_references * sizeof(VASurfaceID));
 num_backward_references = pipeline_caps.num_backward_references;
 backward_references     =
     malloc(num_backward_references * sizeof(VASurfaceID));

Send video processing parameters through VA buffers

Video processing pipeline parameters are submitted for each source surface to process. Video filter parameters can also change, per-surface. e.g. the list of reference frames used for deinterlacing.

 foreach (iteration) {
     vaBeginPicture(va_dpy, vpp_ctx, vpp_surface);
     foreach (surface) {
         VARectangle output_region;
         VABufferID pipeline_buf;
         VAProcPipelineParameterBuffer *pipeline_param;

         vaCreateBuffer(va_dpy, vpp_ctx,
             VAProcPipelineParameterBuffer, sizeof(*pipeline_param), 1,
             NULL, &pipeline_param
         );

         // Setup output region for this surface
         // e.g. upper left corner for the first surface
         output_region.x     = BORDER;
         output_region.y     = BORDER;
         output_region.width =
             (vpp_surface_width - (Nx_surfaces + 1) * BORDER) / Nx_surfaces;
         output_region.height =
             (vpp_surface_height - (Ny_surfaces + 1) * BORDER) / Ny_surfaces;

         vaMapBuffer(va_dpy, pipeline_buf, &pipeline_param);
         pipeline_param->surface              = surface;
         pipeline_param->surface_region       = NULL;
         pipeline_param->output_region        = &output_region;
         pipeline_param->output_background_color = 0;
         if (first surface to render)
             pipeline_param->output_background_color = 0xff000000; // black
         pipeline_param->filter_flags         = VA_FILTER_SCALING_HQ;
         pipeline_param->filters              = filter_bufs;
         pipeline_param->num_filters          = num_filter_bufs;
         vaUnmapBuffer(va_dpy, pipeline_buf);

         // Update reference frames for deinterlacing, if necessary
         pipeline_param->forward_references      = forward_references;
         pipeline_param->num_forward_references  = num_forward_references_used;
         pipeline_param->backward_references     = backward_references;
         pipeline_param->num_backward_references = num_bacward_references_used;

         // Apply filters
         vaRenderPicture(va_dpy, vpp_ctx, &pipeline_buf, 1);
     }
     vaEndPicture(va_dpy, vpp_ctx);
 }

Define Documentation

#define VA_PROC_PIPELINE_FAST 0x00000002

Specifies whether to apply power or performance optimizations to a pipeline.

When processing several surfaces, it may be necessary to prioritize more certain pipelines than others. This flag is only a hint to the video processor so that it can omit certain filters to save power for example. Typically, this flag could be used with video surfaces decoded from a secondary bitstream.

Enumeration Type Documentation

enum VAProcColorBalanceType

Color balance types.

Enumerator:

VAProcColorBalanceHue	Hue.
VAProcColorBalanceSaturation	Saturation.
VAProcColorBalanceBrightness	Brightness.
VAProcColorBalanceContrast	Contrast.
VAProcColorBalanceAutoSaturation	Automatically adjusted saturation.
VAProcColorBalanceAutoBrightness	Automatically adjusted brightness.
VAProcColorBalanceAutoContrast	Automatically adjusted contrast.
VAProcColorBalanceCount	Number of color balance attributes.

enum VAProcColorStandardType

Color standard types.

Enumerator:

VAProcColorStandardBT601	ITU-R BT.601.
VAProcColorStandardBT709	ITU-R BT.709.
VAProcColorStandardBT470M	ITU-R BT.470-2 System M.
VAProcColorStandardBT470BG	ITU-R BT.470-2 System B, G.
VAProcColorStandardSMPTE170M	SMPTE-170M.
VAProcColorStandardSMPTE240M	SMPTE-240M.
VAProcColorStandardGenericFilm	Generic film.
VAProcColorStandardCount	Number of color standards.

enum VAProcDeinterlacingType

Deinterlacing types.

Enumerator:

VAProcDeinterlacingBob	Bob deinterlacing algorithm.
VAProcDeinterlacingWeave	Weave deinterlacing algorithm.
VAProcDeinterlacingMotionAdaptive	Motion adaptive deinterlacing algorithm.
VAProcDeinterlacingMotionCompensated	Motion compensated deinterlacing algorithm.
VAProcDeinterlacingCount	Number of deinterlacing algorithms.

enum VAProcFilterType

Video filter types.

Enumerator:

VAProcFilterNoiseReduction	Noise reduction filter.
VAProcFilterDeinterlacing	Deinterlacing filter.
VAProcFilterSharpening	Sharpening filter.
VAProcFilterColorBalance	Color balance parameters.
VAProcFilterColorStandard	Color standard conversion.
VAProcFilterCount	Number of video filters.

Function Documentation

VAStatus vaQueryVideoProcFilterCaps	(	VADisplay	dpy,
		VAContextID	context,
		VAProcFilterType	type,
		void *	filter_caps,
		unsigned int *	num_filter_caps
	)

Queries video filter capabilities.

This function returns the list of capabilities supported by the driver for a specific video filter. The filter_caps array is allocated by the user and num_filter_caps shall be initialized to the number of allocated elements in that array. Upon successful return, the actual number of filters will be overwritten into num_filter_caps. Otherwise, VA_STATUS_ERROR_MAX_NUM_EXCEEDED is returned and num_filter_caps is adjusted to the number of elements that would be returned if enough space was available.

Parameters:

[in]	dpy	the VA display
[in]	context	the video processing context
[in]	type	the video filter type
[out]	filter_caps	the output array of VAProcFilterCap elements
[in,out]	num_filter_caps	the number of elements allocated on input, the number of elements actually filled in output

VAStatus vaQueryVideoProcFilters	(	VADisplay	dpy,
		VAContextID	context,
		VAProcFilterType *	filters,
		unsigned int *	num_filters
	)

Queries video processing filters.

This function returns the list of video processing filters supported by the driver. The filters array is allocated by the user and num_filters shall be initialized to the number of allocated elements in that array. Upon successful return, the actual number of filters will be overwritten into num_filters. Otherwise, VA_STATUS_ERROR_MAX_NUM_EXCEEDED is returned and num_filters is adjusted to the number of elements that would be returned if enough space was available.

The list of video processing filters supported by the driver shall be ordered in the way they can be iteratively applied. This is needed for both correctness, i.e. some filters would not mean anything if applied at the beginning of the pipeline; but also for performance since some filters can be applied in a single pass (e.g. noise reduction + deinterlacing).

Parameters:

[in]	dpy	the VA display
[in]	context	the video processing context
[out]	filters	the output array of VAProcFilterType elements
[in,out]	num_filters	the number of elements allocated on input, the number of elements actually filled in on output

VAStatus vaQueryVideoProcPipelineCaps	(	VADisplay	dpy,
		VAContextID	context,
		VABufferID *	filters,
		unsigned int	num_filters,
		VAProcPipelineCaps *	pipeline_caps
	)

Queries video processing pipeline capabilities.

This function returns the video processing pipeline capabilities. The filters array defines the video processing pipeline and is an array of buffers holding filter parameters.

Note: the VAProcPipelineCaps structure contains user-provided arrays. If non-NULL, the corresponding num_* fields shall be filled in on input with the number of elements allocated. Upon successful return, the actual number of elements will be overwritten into the num_* fields. Otherwise, VA_STATUS_ERROR_MAX_NUM_EXCEEDED is returned and num_* fields are adjusted to the number of elements that would be returned if enough space was available.

Parameters:

[in]	dpy	the VA display
[in]	context	the video processing context
[in]	filters	the array of VA buffers defining the video processing pipeline
[in]	num_filters	the number of elements in filters
[in,out]	pipeline_caps	the video processing pipeline capabilities

Video processing API

Classes

Enumerations

Functions

Video pipeline flags

Video filter flags

Detailed Description

Query for supported filters

Set up a video processing pipeline

Send video processing parameters through VA buffers

Define Documentation

Enumeration Type Documentation

Function Documentation