* @{
*
* The video processing API uses the same paradigm as for decoding:
- * - Query for supported capabilities;
+ * - Query for supported filters;
* - Set up a video processing pipeline;
* - Send video processing parameters through VA buffers.
*
- * \section api_vpp_caps Query for supported capabilities
+ * \section api_vpp_caps Query for supported filters
*
* Checking whether video processing is supported can be performed
* with vaQueryConfigEntrypoints() and the profile argument set to
- * #VAProfileNone.
+ * #VAProfileNone. If video processing is supported, then the list of
+ * returned entry-points will include #VAEntrypointVideoProc.
*
* \code
* VAEntrypoint *entrypoints;
* }
* \endcode
*
- * Then, video processing pipeline capabilities, i.e. which video
- * filters does the driver support, can be checked with the
- * vaQueryVideoProcPipelineCaps() function.
+ * Then, the vaQueryVideoProcFilters() function is used to query the
+ * list of video processing filters.
*
* \code
- * VAProcPipelineCap pipeline_caps[VAProcFilterCount];
- * unsigned int num_pipeline_caps = VAProcFilterCount;
+ * VAProcFilterType filters[VAProcFilterCount];
+ * unsigned int num_filters = VAProcFilterCount;
*
- * // num_pipeline_caps shall be initialized to the length of the array
- * vaQueryVideoProcPipelineCaps(va_dpy, vpp_ctx, &pipe_caps, &num_pipeline_caps);
+ * // num_filters shall be initialized to the length of the array
+ * vaQueryVideoProcFilters(va_dpy, vpp_ctx, &filters, &num_filters);
* \endcode
*
* Finally, individual filter capabilities can be checked with
* VABufferID filter_bufs[VAProcFilterCount];
* unsigned int num_filter_bufs;
*
- * for (i = 0; i < num_pipeline_caps; i++) {
- * VAProcPipelineCap * const pipeline_cap = &pipeline_caps[i];
- * switch (pipeline_cap->type) {
+ * for (i = 0; i < num_filters; i++) {
+ * switch (filters[i]) {
* case VAProcFilterNoiseReduction: { // Noise reduction filter
* VAProcFilterParameterBuffer denoise;
* denoise.type = VAProcFilterNoiseReduction;
* VAProcFilterParameterBufferDeinterlacing deint;
* deint.type = VAProcFilterDeinterlacing;
* deint.algorithm = VAProcDeinterlacingMotionAdaptive;
- * deint.forward_references =
- * malloc(cap->num_forward_references * sizeof(VASurfaceID));
- * deint.num_forward_references = 0; // none for now
- * deint.backward_references =
- * malloc(cap->num_backward_references * sizeof(VASurfaceID));
- * deint.num_backward_references = 0; // none for now
* vaCreateBuffer(va_dpy, vpp_ctx,
* VAProcFilterParameterBufferType, sizeof(deint), 1,
* &deint, &deint_filter
* }
* \endcode
*
+ * 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.
+ * \code
+ * // 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));
+ * \endcode
+ *
* \section api_vpp_submit Send video processing parameters through VA buffers
*
* Video processing pipeline parameters are submitted for each source
*
* vaCreateBuffer(va_dpy, vpp_ctx,
* VAProcPipelineParameterBuffer, sizeof(*pipeline_param), 1,
- * NULL, &pipeline_param
+ * NULL, &pipeline_buf
* );
*
* // Setup output region for this surface
* pipeline_param->output_background_color = 0;
* if (first surface to render)
* pipeline_param->output_background_color = 0xff000000; // black
- * pipeline_param->flags = VA_FILTER_SCALING_HQ;
+ * 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);
*
- * VAProcFilterParameterBufferDeinterlacing *deint_param;
- * vaMapBuffer(va_dpy, deint_filter, &deint_param);
- * // Update deinterlacing parameters, if necessary
- * ...
- * vaUnmapBuffer(va_dpy, deint_filter);
+ * // 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);
VAProcFilterSharpening,
/** \brief Color balance parameters. */
VAProcFilterColorBalance,
- /** \brief Color standard conversion. */
- VAProcFilterColorStandard,
- /** \brief Max number of video filters. */
+ /** \brief Skin Tone Enhancement. */
+ VAProcFilterSkinToneEnhancement,
VAProcFilterCount
} VAProcFilterType;
VAProcDeinterlacingMotionAdaptive,
/** \brief Motion compensated deinterlacing algorithm. */
VAProcDeinterlacingMotionCompensated,
- /** \brief Max number of deinterlacing algorithms. */
+ /** \brief Number of deinterlacing algorithms. */
VAProcDeinterlacingCount
} VAProcDeinterlacingType;
VAProcColorBalanceBrightness,
/** \brief Contrast. */
VAProcColorBalanceContrast,
- /** \brief Max number of color balance operations. */
+ /** \brief Automatically adjusted saturation. */
+ VAProcColorBalanceAutoSaturation,
+ /** \brief Automatically adjusted brightness. */
+ VAProcColorBalanceAutoBrightness,
+ /** \brief Automatically adjusted contrast. */
+ VAProcColorBalanceAutoContrast,
+ /** \brief Number of color balance attributes. */
VAProcColorBalanceCount
} VAProcColorBalanceType;
VAProcColorStandardSMPTE240M,
/** \brief Generic film. */
VAProcColorStandardGenericFilm,
+ /** \brief Number of color standards. */
+ VAProcColorStandardCount
} VAProcColorStandardType;
+/** @name Video pipeline flags */
+/**@{*/
+/** \brief Specifies whether to apply subpictures when processing a surface. */
+#define VA_PROC_PIPELINE_SUBPICTURES 0x00000001
+/**
+ * \brief 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.
+ */
+#define VA_PROC_PIPELINE_FAST 0x00000002
+/**@}*/
+
/** @name Video filter flags */
/**@{*/
/** \brief Specifies whether the filter shall be present in the pipeline. */
#define VA_PROC_FILTER_MANDATORY 0x00000001
/**@}*/
+/** @name Pipeline end flags */
+/**@{*/
+/** \brief Specifies the pipeline is the last. */
+#define VA_PIPELINE_FLAG_END 0x00000004
+/**@}*/
+
/** \brief Video processing pipeline capabilities. */
-typedef struct _VAProcPipelineCap {
- /** \brief Video filter type. */
- VAProcFilterType type;
- /** \brief Video filter flags. See video filter flags. */
- unsigned int flags;
-} VAProcPipelineCap;
+typedef struct _VAProcPipelineCaps {
+ /** \brief Pipeline flags. See VAProcPipelineParameterBuffer::pipeline_flags. */
+ unsigned int pipeline_flags;
+ /** \brief Extra filter flags. See VAProcPipelineParameterBuffer::filter_flags. */
+ unsigned int filter_flags;
+ /** \brief Number of forward reference frames that are needed. */
+ unsigned int num_forward_references;
+ /** \brief Number of backward reference frames that are needed. */
+ unsigned int num_backward_references;
+ /** \brief List of color standards supported on input. */
+ VAProcColorStandardType *input_color_standards;
+ /** \brief Number of elements in \ref input_color_standards array. */
+ unsigned int num_input_color_standards;
+ /** \brief List of color standards supported on output. */
+ VAProcColorStandardType *output_color_standards;
+ /** \brief Number of elements in \ref output_color_standards array. */
+ unsigned int num_output_color_standards;
+} VAProcPipelineCaps;
/** \brief Specification of values supported by the filter. */
typedef struct _VAProcFilterValueRange {
/**
* \brief Video processing pipeline configuration.
*
- * This buffers defines a video processing pipeline. As for any buffer
- * passed to \c vaRenderPicture(), this is one-time usage model. However,
- * the actual filters to be applied are provided in the \c filters field,
- * so they can be re-used in other processing pipelines.
+ * This buffer defines a video processing pipeline. As for any buffer
+ * passed to \c vaRenderPicture(), this is a one-time usage model.
+ * However, the actual filters to be applied are provided in the
+ * \c filters field, so they can be re-used in other processing
+ * pipelines.
*
* The target surface is specified by the \c render_target argument of
* \c vaBeginPicture(). The general usage model is described as follows:
* background color.
*/
typedef struct _VAProcPipelineParameterBuffer {
- /** \brief Source surface ID. */
+ /**
+ * \brief Source surface ID.
+ *
+ * ID of the source surface to process. If subpictures are associated
+ * with the video surfaces then they shall be rendered to the target
+ * surface, if the #VA_PROC_PIPELINE_SUBPICTURES pipeline flag is set.
+ */
VASurfaceID surface;
/**
* \brief Region within the source surface to be processed.
*/
const VARectangle *surface_region;
/**
+ * \brief Requested input color primaries.
+ *
+ * Color primaries are implicitly converted throughout the processing
+ * pipeline. The video processor chooses the best moment to apply
+ * this conversion. The set of supported color primaries primaries
+ * for input shall be queried with vaQueryVideoProcPipelineCaps().
+ */
+ VAProcColorStandardType surface_color_standard;
+ /**
* \brief Region within the output surface.
*
* Pointer to a #VARectangle defining the region within the output
* Background color used to fill in pixels that reside outside of the
* specified \ref output_region. The color is specified in ARGB format:
* [31:24] alpha, [23:16] red, [15:8] green, [7:0] blue.
+ *
+ * Unless the alpha value is zero or the \ref output_region represents
+ * the whole target surface size, implementations shall not render the
+ * source surface to the target surface directly. Rather, in order to
+ * maintain the exact semantics of \ref output_background_color, the
+ * driver shall use a temporary surface and fill it in with the
+ * appropriate background color. Next, the driver will blend this
+ * temporary surface into the target surface.
*/
unsigned int output_background_color;
/**
- * \brief Pipeline flags. See vaPutSurface() flags.
+ * \brief Requested output color primaries.
+ */
+ VAProcColorStandardType output_color_standard;
+ /**
+ * \brief Pipeline filters. See video pipeline flags.
*
- * Pipeline flags:
+ * Flags to control the pipeline, like whether to apply subpictures
+ * or not, notify the driver that it can opt for power optimizations,
+ * should this be needed.
+ */
+ unsigned int pipeline_flags;
+ /**
+ * \brief Extra filter flags. See vaPutSurface() flags.
+ *
+ * Filter flags are used as a fast path, wherever possible, to use
+ * vaPutSurface() flags instead of explicit filter parameter buffers.
+ *
+ * Allowed filter flags API-wise. Use vaQueryVideoProcPipelineCaps()
+ * to check for implementation details:
* - Bob-deinterlacing: \c VA_FRAME_PICTURE, \c VA_TOP_FIELD,
* \c VA_BOTTOM_FIELD. Note that any deinterlacing filter
* (#VAProcFilterDeinterlacing) will override those flags.
* - Color space conversion: \c VA_SRC_BT601, \c VA_SRC_BT709,
- * \c VA_SRC_SMPTE_240. Note that any color standard filter
- * (#VAProcFilterColorStandard) will override those flags.
+ * \c VA_SRC_SMPTE_240.
* - Scaling: \c VA_FILTER_SCALING_DEFAULT, \c VA_FILTER_SCALING_FAST,
* \c VA_FILTER_SCALING_HQ, \c VA_FILTER_SCALING_NL_ANAMORPHIC.
*/
- unsigned int flags;
+ unsigned int filter_flags;
/**
* \brief Array of filters to apply to the surface.
*
* The list of filters shall be ordered in the same way the driver expects
- * them. i.e. as was returned from vaQueryVideoProcPipelineCaps().
+ * them. i.e. as was returned from vaQueryVideoProcFilters().
* Otherwise, a #VA_STATUS_ERROR_INVALID_FILTER_CHAIN is returned
* from vaRenderPicture() with this buffer.
*
VABufferID *filters;
/** \brief Actual number of filters. */
unsigned int num_filters;
+ /** \brief Array of forward reference frames. */
+ VASurfaceID *forward_references;
+ /** \brief Number of forward reference frames that were supplied. */
+ unsigned int num_forward_references;
+ /** \brief Array of backward reference frames. */
+ VASurfaceID *backward_references;
+ /** \brief Number of backward reference frames that were supplied. */
+ unsigned int num_backward_references;
} VAProcPipelineParameterBuffer;
/**
/** \brief Filter type. */
VAProcFilterType type;
/** \brief Value. */
- /* XXX: use VAGenericValue? */
float value;
} VAProcFilterParameterBuffer;
+/** @name De-interlacing flags */
+/**@{*/
+/**
+ * \brief Bottom field first in the input frame.
+ * if this is not set then assumes top field first.
+ */
+#define VA_DEINTERLACING_BOTTOM_FIELD_FIRST 0x0001
+/**
+ * \brief Bottom field used in deinterlacing.
+ * if this is not set then assumes top field is used.
+ */
+#define VA_DEINTERLACING_BOTTOM_FIELD 0x0002
+/**
+ * \brief A single field is stored in the input frame.
+ * if this is not set then assumes the frame contains two interleaved fields.
+ */
+#define VA_DEINTERLACING_ONE_FIELD 0x0004
+/**@}*/
+
/** \brief Deinterlacing filter parametrization. */
typedef struct _VAProcFilterParameterBufferDeinterlacing {
/** \brief Filter type. Shall be set to #VAProcFilterDeinterlacing. */
VAProcFilterType type;
/** \brief Deinterlacing algorithm. */
VAProcDeinterlacingType algorithm;
- /** \brief Array of forward reference frames. */
- VASurfaceID *forward_references;
- /** \brief Number of forward reference frames that were supplied. */
- unsigned int num_forward_references;
- /** \brief Array of backward reference frames. */
- VASurfaceID *backward_references;
- /** \brief Number of backward reference frames that were supplied. */
- unsigned int num_backward_references;
+ /** \brief Deinterlacing flags. */
+ unsigned int flags;
} VAProcFilterParameterBufferDeinterlacing;
/**
VAProcFilterType type;
/** \brief Color balance attribute. */
VAProcColorBalanceType attrib;
- /** \brief Color balance value. */
+ /**
+ * \brief Color balance value.
+ *
+ * Special case for automatically adjusted attributes. e.g.
+ * #VAProcColorBalanceAutoSaturation,
+ * #VAProcColorBalanceAutoBrightness,
+ * #VAProcColorBalanceAutoContrast.
+ * - If \ref value is \c 1.0 +/- \c FLT_EPSILON, the attribute is
+ * automatically adjusted and overrides any other attribute of
+ * the same type that would have been set explicitly;
+ * - If \ref value is \c 0.0 +/- \c FLT_EPSILON, the attribute is
+ * disabled and other attribute of the same type is used instead.
+ */
float value;
} VAProcFilterParameterBufferColorBalance;
-/** \brief Color standard filter parametrization. */
-typedef struct _VAProcFilterParameterBufferColorStandard {
- /** \brief Filter type. Shall be set to #VAProcFilterColorStandard. */
- VAProcFilterType type;
- /** \brief Color standard to use. */
- VAProcColorStandardType standard;
-} VAProcFilterParameterBufferColorStandard;
-
/**
* \brief Default filter cap specification (single range value).
*
typedef struct _VAProcFilterCapDeinterlacing {
/** \brief Deinterlacing algorithm. */
VAProcDeinterlacingType type;
- /** \brief Number of forward references needed for deinterlacing. */
- unsigned int num_forward_references;
- /** \brief Number of backward references needed for deinterlacing. */
- unsigned int num_backward_references;
} VAProcFilterCapDeinterlacing;
/** \brief Capabilities specification for the color balance filter. */
VAProcFilterValueRange range;
} VAProcFilterCapColorBalance;
-/** \brief Capabilities specification for the color standard filter. */
-typedef struct _VAProcFilterCapColorStandard {
- /** \brief Color standard type. */
- VAProcColorStandardType type;
-} VAProcFilterCapColorStandard;
-
/**
- * \brief Queries video processing pipeline capabilities.
+ * \brief Queries video processing filters.
*
* This function returns the list of video processing filters supported
- * by the driver. The \c pipeline_caps array is allocated by the user and
- * \c num_pipeline_caps shall be initialized to the number of allocated
+ * by the driver. The \c filters array is allocated by the user and
+ * \c 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 \c num_pipeline_caps. Otherwise,
- * \c VA_STATUS_ERROR_MAX_NUM_EXCEEDED is returned and \c num_pipeline_caps
+ * of filters will be overwritten into \c num_filters. Otherwise,
+ * \c VA_STATUS_ERROR_MAX_NUM_EXCEEDED is returned and \c num_filters
* is adjusted to the number of elements that would be returned if enough
* space was available.
*
*
* @param[in] dpy the VA display
* @param[in] context the video processing context
- * @param[out] pipeline_caps the output array of #VAProcPipelineCap elements
- * @param[in,out] num_pipeline_caps the number of elements allocated on input,
+ * @param[out] filters the output array of #VAProcFilterType elements
+ * @param[in,out] num_filters the number of elements allocated on input,
* the number of elements actually filled in on output
*/
VAStatus
-vaQueryVideoProcPipelineCaps(
+vaQueryVideoProcFilters(
VADisplay dpy,
VAContextID context,
- VAProcPipelineCap *pipeline_caps,
- unsigned int *num_pipeline_caps
+ VAProcFilterType *filters,
+ unsigned int *num_filters
);
/**
unsigned int *num_filter_caps
);
+/**
+ * \brief Queries video processing pipeline capabilities.
+ *
+ * This function returns the video processing pipeline capabilities. The
+ * \c 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 \c 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 \c num_*
+ * fields. Otherwise, \c VA_STATUS_ERROR_MAX_NUM_EXCEEDED is returned
+ * and \c num_* fields are adjusted to the number of elements that would
+ * be returned if enough space was available.
+ *
+ * @param[in] dpy the VA display
+ * @param[in] context the video processing context
+ * @param[in] filters the array of VA buffers defining the video
+ * processing pipeline
+ * @param[in] num_filters the number of elements in filters
+ * @param[in,out] pipeline_caps the video processing pipeline capabilities
+ */
+VAStatus
+vaQueryVideoProcPipelineCaps(
+ VADisplay dpy,
+ VAContextID context,
+ VABufferID *filters,
+ unsigned int num_filters,
+ VAProcPipelineCaps *pipeline_caps
+);
+
/**@}*/
#ifdef __cplusplus
OSDN Git Service
