* contributed to various aspects of the API.
*/
+/**
+ * \file va.h
+ * \brief The Core API
+ *
+ * This file contains the \ref api_core "Core API".
+ */
+
#ifndef _VA_H_
#define _VA_H_
extern "C" {
#endif
+/**
+ * \mainpage Video Acceleration (VA) API
+ *
+ * \section intro Introduction
+ *
+ * The main motivation for VA-API (Video Acceleration API) is to
+ * enable hardware accelerated video decode and encode at various
+ * entry-points (VLD, IDCT, Motion Compensation etc.) for the
+ * prevailing coding standards today (MPEG-2, MPEG-4 ASP/H.263, MPEG-4
+ * AVC/H.264, VC-1/VMW3, and JPEG).
+ *
+ * VA-API is split into several modules:
+ * - \ref api_core
+ * - \ref api_enc_core
+ * - \ref api_enc_h264
+ * - \ref api_vpp
+ */
+
+/**
+ * \defgroup api_core Core API
+ *
+ * @{
+ */
+
/*
Overview
* of generic attribute values.
*/
#define VA_STATUS_ERROR_INVALID_VALUE 0x00000019
+/** \brief An unsupported filter was supplied. */
+#define VA_STATUS_ERROR_UNSUPPORTED_FILTER 0x00000020
+/** \brief An invalid filter chain was supplied. */
+#define VA_STATUS_ERROR_INVALID_FILTER_CHAIN 0x00000021
+/** \brief Indicate HW busy (e.g. run multiple encoding simultaneously). */
+#define VA_STATUS_ERROR_HW_BUSY 0x00000022
#define VA_STATUS_ERROR_UNKNOWN 0xFFFFFFFF
/* De-interlacing flags for vaPutSurface() */
/* Currently defined profiles */
typedef enum
{
+ /** \brief Profile ID used for video processing. */
+ VAProfileNone = -1,
VAProfileMPEG2Simple = 0,
VAProfileMPEG2Main = 1,
VAProfileMPEG4Simple = 2,
VAEntrypointMoComp = 4,
VAEntrypointDeblocking = 5,
VAEntrypointEncSlice = 6, /* slice level encode */
- VAEntrypointEncPicture = 7 /* pictuer encode, JPEG, etc */
+ VAEntrypointEncPicture = 7, /* pictuer encode, JPEG, etc */
+ VAEntrypointVideoProc = 10, /**< Video pre/post-processing. */
+ VAEntrypointMax
} VAEntrypoint;
/* Currently defined configuration attribute types */
*/
VAConfigAttribEncMacroblockInfo = 16,
/**@}*/
+ VAConfigAttribTypeMax
} VAConfigAttribType;
/*
#define VA_RC_VCM 0x00000008
/** \brief Constant QP. */
#define VA_RC_CQP 0x00000010
+/** \brief Variable bitrate with peak rate higher than average bitrate. */
+#define VA_RC_VBR_CONSTRAINED 0x00000020
/**@}*/
/** @name Attribute values for VAConfigAttribEncPackedHeaders */
#define VA_ENC_PACKED_HEADER_SLICE 0x00000004
/** \brief Driver supports misc packed headers. e.g. SEI for H.264. */
#define VA_ENC_PACKED_HEADER_MISC 0x00000008
+/** \brief Driver supports raw packed header, see VAEncPackedHeaderRawData */
+#define VA_ENC_PACKED_HEADER_RAW_DATA 0x0000000C
/**@}*/
/** @name Attribute values for VAConfigAttribEncInterlaced */
} value;
} VAGenericValue;
-/*
- * vaCreateSurfaces - Create an array of surfaces used for decode and display
- * dpy: display
- * width: surface width
- * height: surface height
- * format: VA_RT_FORMAT_YUV420, VA_RT_FORMAT_YUV422 or VA_RT_FORMAT_YUV444
- * num_surfaces: number of surfaces to be created
- * surfaces: array of surfaces created upon return
- */
-VAStatus vaCreateSurfaces (
- VADisplay dpy,
- int width,
- int height,
- int format,
- int num_surfaces,
- VASurfaceID *surfaces /* out */
+/** @name Surface attribute flags */
+/**@{*/
+/** \brief Surface attribute is not supported. */
+#define VA_SURFACE_ATTRIB_NOT_SUPPORTED 0x00000000
+/** \brief Surface attribute can be got through vaQuerySurfaceAttributes(). */
+#define VA_SURFACE_ATTRIB_GETTABLE 0x00000001
+/** \brief Surface attribute can be set through vaCreateSurfaces(). */
+#define VA_SURFACE_ATTRIB_SETTABLE 0x00000002
+/**@}*/
+
+/** \brief Surface attribute types. */
+typedef enum {
+ VASurfaceAttribNone = 0,
+ /**
+ * \brief Pixel format (fourcc).
+ *
+ * The value is meaningful as input to vaQuerySurfaceAttributes().
+ * If zero, the driver returns the optimal pixel format for the
+ * specified config. Otherwise, if non-zero, the value represents
+ * a pixel format (FOURCC) that is kept as is on output, if the
+ * driver supports it. Otherwise, the driver sets the value to
+ * zero and drops the \c VA_SURFACE_ATTRIB_SETTABLE flag.
+ */
+ VASurfaceAttribPixelFormat,
+ /** \brief Minimal width in pixels (int, read/write). */
+ VASurfaceAttribMinWidth,
+ /** \brief Maximal width in pixels (int, read-only). */
+ VASurfaceAttribMaxWidth,
+ /** \brief Minimal height in pixels (int, read-only). */
+ VASurfaceAttribMinHeight,
+ /** \brief Maximal height in pixels (int, read-only). */
+ VASurfaceAttribMaxHeight,
+ /** \brief Number of surface attributes. */
+ VASurfaceAttribCount
+} VASurfaceAttribType;
+
+/** \brief Surface attribute. */
+typedef struct _VASurfaceAttrib {
+ /** \brief Type. */
+ VASurfaceAttribType type;
+ /** \brief Flags. See "Surface attribute flags". */
+ unsigned int flags;
+ /** \brief Value. See "Surface attribute types" for the expected types. */
+ VAGenericValue value;
+} VASurfaceAttrib;
+
+/**
+ * \brief Get surface attributes for the supplied config.
+ *
+ * This function retrieves the surface attributes matching the supplied
+ * config. The caller shall provide an \c attrib_list with all attributes
+ * to be retrieved. Upon successful return, the attributes in \c attrib_list
+ * are updated with the requested value. Unknown attributes or attributes
+ * that are not supported for the given config will have their \c flags
+ * field set to \c VA_SURFACE_ATTRIB_NOT_SUPPORTED.
+ *
+ * @param[in] dpy the VA display
+ * @param[in] config the config identifying a codec or a video
+ * processing pipeline
+ * @param[in,out] attrib_list the list of attributes on input, with at
+ * least \c type fields filled in, and possibly \c value fields whenever
+ * necessary. The updated list of attributes and flags on output
+ * @param[in] num_attribs the number of attributes supplied in the
+ * \c attrib_list array
+ */
+VAStatus
+vaGetSurfaceAttributes(
+ VADisplay dpy,
+ VAConfigID config,
+ VASurfaceAttrib *attrib_list,
+ unsigned int num_attribs
);
+/**
+ * \brief Creates an array of surfaces
+ *
+ * Creates an array of surfaces. The optional list of attributes shall
+ * be constructed and verified through vaGetSurfaceAttributes().
+ *
+ * @param[in] dpy the VA display
+ * @param[in] format the desired surface format. See \c VA_RT_FORMAT_*
+ * @param[in] width the surface width
+ * @param[in] height the surface height
+ * @param[out] surfaces the array of newly created surfaces
+ * @param[in] num_surfaces the number of surfaces to create
+ * @param[in] attrib_list the list of (optional) attributes, or \c NULL
+ * @param[in] num_attribs the number of attributes supplied in
+ * \c attrib_list, or zero
+ */
+VAStatus
+vaCreateSurfaces(
+ VADisplay dpy,
+ unsigned int format,
+ unsigned int width,
+ unsigned int height,
+ VASurfaceID *surfaces,
+ unsigned int num_surfaces,
+ VASurfaceAttrib *attrib_list,
+ unsigned int num_attribs
+);
/*
* vaDestroySurfaces - Destroy resources associated with surfaces.
VAEncPackedHeaderDataBufferType = 26,
VAEncMiscParameterBufferType = 27,
VAEncMacroblockParameterBufferType = 28,
- VABufferTypeMax = 0xff
+/* Following are video processing buffer types */
+ /**
+ * \brief Video processing pipeline parameter buffer.
+ *
+ * This buffer describes the video processing pipeline. See
+ * #VAProcPipelineParameterBuffer for details.
+ */
+ VAProcPipelineParameterBufferType = 41,
+ /**
+ * \brief Video filter parameter buffer.
+ *
+ * This buffer describes the video filter parameters. All buffers
+ * inherit from #VAProcFilterParameterBufferBase, thus including
+ * a unique filter buffer type.
+ *
+ * The default buffer used by most filters is #VAProcFilterParameterBuffer.
+ * Filters requiring advanced parameters include, but are not limited to,
+ * deinterlacing (#VAProcFilterParameterBufferDeinterlacing),
+ * color balance (#VAProcFilterParameterBufferColorBalance), etc.
+ */
+ VAProcFilterParameterBufferType = 42,
+ VABufferTypeMax
} VABufferType;
typedef enum
VAEncMiscParameterTypeAIR = 3,
/** \brief Buffer type used to express a maximum frame size (in bits). */
VAEncMiscParameterTypeMaxFrameSize = 4,
+ /** \brief Buffer type used for HRD parameters. */
+ VAEncMiscParameterTypeHRD = 5,
} VAEncMiscParameterType;
/** \brief Packed header type. */
VAEncPackedHeaderPicture = 2,
/** \brief Packed slice header. */
VAEncPackedHeaderSlice = 3,
+ /**
+ * \brief Packed raw header.
+ *
+ * Packed raw data header can be used by the client to insert a header
+ * into the bitstream data buffer at the point it is passed, the driver
+ * will handle the raw packed header based on "has_emulation_bytes" field
+ * in the packed header parameter structure.
+ */
+ VAEncPackedHeaderRawData = 4,
/** \brief Misc packed header. See codec-specific definitions. */
VAEncPackedHeaderMiscMask = 0x80000000,
} VAEncPackedHeaderType;
unsigned int data[0];
} VAEncMiscParameterBuffer;
+
+/** \brief Rate control parameters */
typedef struct _VAEncMiscParameterRateControl
{
- unsigned int bits_per_second; /* this is the maximum bit-rate to be constrained by the rate control implementation */
- unsigned int target_percentage; /* this is the bit-rate the rate control is targeting, as a percentage of the maximum bit-rate */
- /* for example if target_percentage is 95 then the rate control will target a bit-rate that is */
- /* 95% of the maximum bit-rate */
- unsigned int window_size; /* windows size in milliseconds. For example if this is set to 500, then the rate control will guarantee the */
- /* target bit-rate over a 500 ms window */
- unsigned int initial_qp; /* initial QP at I frames */
- unsigned int min_qp;
+ /* this is the maximum bit-rate to be constrained by the rate control implementation */
+ unsigned int bits_per_second;
+ /* this is the bit-rate the rate control is targeting, as a percentage of the maximum
+ * bit-rate for example if target_percentage is 95 then the rate control will target
+ * a bit-rate that is 95% of the maximum bit-rate
+ */
+ unsigned int target_percentage;
+ /* windows size in milliseconds. For example if this is set to 500,
+ * then the rate control will guarantee the target bit-rate over a 500 ms window
+ */
+ unsigned int window_size;
+ /* initial QP at I frames */
+ unsigned int initial_qp;
+ unsigned int min_qp;
+ unsigned int basic_unit_size;
+ union
+ {
+ struct
+ {
+ unsigned int reset : 1;
+ unsigned int disable_frame_skip : 1; /* Disable frame skip in rate control mode */
+ unsigned int disable_bit_stuffing : 1; /* Disable bit stuffing in rate control mode */
+ } bits;
+ unsigned int value;
+ } rc_flags;
} VAEncMiscParameterRateControl;
typedef struct _VAEncMiscParameterFrameRate
unsigned int air_auto; /* if set to 1 then hardware auto-tune the AIR threshold */
} VAEncMiscParameterAIR;
+typedef struct _VAEncMiscParameterHRD
+{
+ unsigned int initial_buffer_fullness; /* in bits */
+ unsigned int buffer_size; /* in bits */
+} VAEncMiscParameterHRD;
+
/**
* \brief Defines a maximum frame size (in bits).
*
} slice_flags;
} VAEncSliceParameterBuffer;
-/****************************
- * H.264 specific encode data structures
- ****************************/
-
-typedef struct _VAEncSequenceParameterBufferH264Baseline
-{
- unsigned char seq_parameter_set_id;
- unsigned char level_idc;
- unsigned int intra_period;
- unsigned int intra_idr_period;
- unsigned int max_num_ref_frames;
- unsigned int picture_width_in_mbs;
- unsigned int picture_height_in_mbs;
- unsigned int bits_per_second;
- unsigned int frame_rate;
- unsigned int initial_qp;
- unsigned int min_qp;
- unsigned int basic_unit_size;
- unsigned char vui_flag;
-} VAEncSequenceParameterBufferH264Baseline;
-
-#define H264_LAST_PICTURE_EOSEQ 0x01 /* the last picture in the sequence */
-#define H264_LAST_PICTURE_EOSTREAM 0x02 /* the last picture in the stream */
-typedef struct _VAEncPictureParameterBufferH264Baseline
-{
- VASurfaceID reference_picture;
- VASurfaceID reconstructed_picture;
- VABufferID coded_buf;
- unsigned short picture_width;
- unsigned short picture_height;
- unsigned char last_picture;
-} VAEncPictureParameterBufferH264Baseline;
/****************************
* H.263 specific encode data structures
#define VA_CODED_BUF_STATUS_FRAME_SIZE_OVERFLOW 0x1000
#define VA_CODED_BUF_STATUS_AIR_MB_OVER_THRESHOLD 0xff0000
-/*
- * device independent data structure for codedbuffer
+/**
+ * \brief The coded buffer segment contains a single NAL unit.
+ *
+ * This flag indicates that the coded buffer segment contains a
+ * single NAL unit. This flag might be useful to the user for
+ * processing the coded buffer.
+ */
+#define VA_CODED_BUF_STATUS_SINGLE_NALU 0x10000000
+
+/**
+ * \brief Coded buffer segment.
+ *
+ * #VACodedBufferSegment is an element of a linked list describing
+ * some information on the coded buffer. The coded buffer segment
+ * could contain either a single NAL unit, or more than one NAL unit.
+ * It is recommended (but not required) to return a single NAL unit
+ * in a coded buffer segment, and the implementation should set the
+ * VA_CODED_BUF_STATUS_SINGLE_NALU status flag if that is the case.
*/
typedef struct _VACodedBufferSegment {
- unsigned int size;/* size of the data buffer in the coded buffer segment, in bytes */
- unsigned int bit_offset; /* bit offset into the data buffer where valid bitstream data begins */
- unsigned int status; /* status set by the driver on the coded buffer*/
- unsigned int reserved; /* for future use */
- void *buf; /* pointer to the beginning of the data buffer in the coded buffer segment */
- void *next; /* pointer to the next VACodedBufferSegment */
+ /**
+ * \brief Size of the data buffer in this segment (in bytes).
+ */
+ unsigned int size;
+ /** \brief Bit offset into the data buffer where the video data starts. */
+ unsigned int bit_offset;
+ /** \brief Status set by the driver. See \c VA_CODED_BUF_STATUS_*. */
+ unsigned int status;
+ /** \brief Reserved for future use. */
+ unsigned int reserved;
+ /** \brief Pointer to the start of the data buffer. */
+ void *buf;
+ /**
+ * \brief Pointer to the next #VACodedBufferSegment element,
+ * or \c NULL if there is none.
+ */
+ void *next;
} VACodedBufferSegment;
/*
#define VA_FOURCC_YV12 0x32315659
#define VA_FOURCC_P208 0x38303250
#define VA_FOURCC_IYUV 0x56555949
+#define VA_FOURCC_YV24 0x34325659
+#define VA_FOURCC_YV32 0x32335659
/* byte order */
#define VA_LSB_FIRST 1
int num_attributes
);
+/**@}*/
+
#ifdef __cplusplus
}
#endif