2 * Copyright (c) 2007, Intel Corp.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
8 * Redistributions of source code must retain the above copyright notice,
9 * this list of conditions and the following disclaimer.
10 * Redistributions in binary form must reproduce the above copyright notice,
11 * this list of conditions and the following disclaimer in the documentation
12 * and/or other materials provided with the distribution.
13 * Neither the name of Intel Corporation nor the names of its contributors
14 * may be used to endorse or promote products derived from this software
15 * without specific prior written permission.
17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
21 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
23 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
26 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 * Video Decode Acceleration API Specification
32 * <jonathan.bian@intel.com>
35 * rev 0.10 (12/10/2006 Jonathan Bian) - Initial draft
36 * rev 0.11 (12/15/2006 Jonathan Bian) - Fixed some errors
37 * rev 0.12 (02/05/2007 Jonathan Bian) - Added VC-1 data structures for slice level decode
38 * rev 0.13 (02/28/2007 Jonathan Bian) - Added GetDisplay()
39 * rev 0.14 (04/13/2007 Jonathan Bian) - Fixed MPEG-2 PictureParameter structure, cleaned up a few funcs.
40 * rev 0.15 (04/20/2007 Jonathan Bian) - Overhauled buffer management
41 * rev 0.16 (05/02/2007 Jonathan Bian) - Added error codes and fixed some issues with configuration
42 * rev 0.17 (05/07/2007 Jonathan Bian) - Added H.264/AVC data structures for slice level decode.
43 * rev 0.18 (05/14/2007 Jonathan Bian) - Added data structures for MPEG-4 slice level decode
44 * and MPEG-2 motion compensation.
45 * rev 0.19 (08/06/2007 Jonathan Bian) - Removed extra type for bitplane data.
46 * rev 0.20 (08/08/2007 Jonathan Bian) - Added missing fields to VC-1 PictureParameter structure.
49 * Thanks to Waldo Bastian for many valuable feedbacks.
61 This is a decode only interface currently. The basic steps are:
63 - Negotiate a mutually acceptable configuration with the server to lock
64 down profile, entrypoints, and other attributes that will not change on
65 a frame-by-frame basis.
66 - Create a decode context which represents a "virtualized" hardware decode
68 - Get and fill decode buffers with picture level, slice level and macroblock
69 level data (depending on entrypoints)
70 - Pass the decode buffers to the server to decode the current frame
72 Initialization & Configuration Management
74 - Find out supported profiles
75 - Find out entrypoints for a given profile
76 - Find out configuration attributes for a given profile/entrypoint pair
77 - Create a configuration for use by the decoder
81 typedef void* VADisplay; /* window system dependent */
83 typedef int VAStatus; /* Return status type from functions */
84 /* Values for the return status */
85 #define VA_STATUS_SUCCESS 0x00000000
86 #define VA_STATUS_ERROR_ALLOCATION_FAILED 0x00000001
87 #define VA_STATUS_ERROR_INVALID_CONFIG 0x00000002
88 #define VA_STATUS_ERROR_INVALID_CONTEXT 0x00000003
89 #define VA_STATUS_ERROR_INVALID_SURFACE 0x00000004
90 #define VA_STATUS_ERROR_INVALID_BUFFER 0x00000005
91 #define VA_STATUS_ERROR_ATTR_NOT_SUPPORTED 0x00000006 /* Todo: Remove */
92 #define VA_STATUS_ERROR_MAX_NUM_EXCEEDED 0x00000007
93 #define VA_STATUS_ERROR_UNSUPPORTED_PROFILE 0x00000008
94 #define VA_STATUS_ERROR_UNSUPPORTED_ENTRYPOINT 0x00000009
95 #define VA_STATUS_ERROR_UNSUPPORTED_RT_FORMAT 0x0000000a
96 #define VA_STATUS_ERROR_UNSUPPORTED_BUFFERTYPE 0x0000000b
97 #define VA_STATUS_ERROR_UNKNOWN 0xFFFFFFFF
100 * Returns a short english description of error_status
102 const char *vaErrorStr(VAStatus error_status);
106 * A display must be obtained by calling vaGetDisplay() before calling
107 * vaInitialize() and other functions. This connects the API to the
108 * native window system.
109 * For X Windows, native_dpy would be from XOpenDisplay()
111 typedef void* NativeDisplay; /* window system dependent */
113 VADisplay vaGetDisplay (
114 NativeDisplay native_dpy /* implementation specific */
117 VAStatus vaInitialize (
119 int *major_version, /* out */
120 int *minor_version /* out */
124 * After this call, all library internal resources will be cleaned up
126 VAStatus vaTerminate (
130 /* Currently defined profiles */
133 VAProfileMPEG2Simple = 0,
134 VAProfileMPEG2Main = 1,
135 VAProfileMPEG4Simple = 2,
136 VAProfileMPEG4AdvancedSimple = 3,
137 VAProfileMPEG4Main = 4,
138 VAProfileH264Baseline = 5,
139 VAProfileH264Main = 6,
140 VAProfileH264High = 7,
141 VAProfileVC1Simple = 8,
142 VAProfileVC1Main = 9,
143 VAProfileVC1Advanced = 10,
146 /* Currently defined entrypoints */
151 VAEntrypointIDCT = 3,
152 VAEntrypointMoComp = 4,
153 VAEntrypointDeblocking = 5,
156 /* Currently defined configuration attribute types */
159 VAConfigAttribRTFormat = 0,
160 VAConfigAttribSpatialResidual = 1,
161 VAConfigAttribSpatialClipping = 2,
162 VAConfigAttribIntraResidual = 3,
163 VAConfigAttribEncryption = 4,
164 } VAConfigAttribType;
167 * Configuration attributes
168 * If there is more than one value for an attribute, a default
169 * value will be assigned to the attribute if the client does not
170 * specify the attribute when creating a configuration
172 typedef struct _VAConfigAttrib {
173 VAConfigAttribType type;
174 unsigned int value; /* OR'd flags (bits) for this attribute */
177 /* attribute value for VAConfigAttribRTFormat */
178 #define VA_RT_FORMAT_YUV420 0x00000001
179 #define VA_RT_FORMAT_YUV422 0x00000002
180 #define VA_RT_FORMAT_YUV444 0x00000004
183 * if an attribute is not applicable for a given
184 * profile/entrypoint pair, then set the value to the following
186 #define VA_ATTRIB_NOT_SUPPORTED 0x80000000
188 /* Get maximum number of profiles supported by the implementation */
189 int vaMaxNumProfiles (
193 /* Get maximum number of entrypoints supported by the implementation */
194 int vaMaxNumEntrypoints (
198 /* Get maximum number of attributs supported by the implementation */
199 int vaMaxNumConfigAttributes (
204 * Query supported profiles
205 * The caller must provide a "profile_list" array that can hold at
206 * least vaMaxNumProfile() entries. The actual number of profiles
207 * returned in "profile_list" is returned in "num_profile".
209 VAStatus vaQueryConfigProfiles (
211 VAProfile *profile_list, /* out */
212 int *num_profiles /* out */
216 * Query supported entrypoints for a given profile
217 * The caller must provide an "entrypoint_list" array that can hold at
218 * least vaMaxNumEntrypoints() entries. The actual number of entrypoints
219 * returned in "entrypoint_list" is returned in "num_entrypoints".
221 VAStatus vaQueryConfigEntrypoints (
224 VAEntrypoint *entrypoint_list, /* out */
225 int *num_entrypoints /* out */
229 * Query attributes for a given profile/entrypoint pair
230 * The caller must provide an
\93attrib_list
\94 with all attributes to be
231 * queried. Upon return, the attributes in
\93attrib_list
\94 have been
232 * updated with their value. Unknown attributes or attributes that are
233 * not supported for the given profile/entrypoint pair will have their
234 * value set to VA_ATTRIB_NOT_SUPPORTED
236 VAStatus vaQueryConfigAttributes (
239 VAEntrypoint entrypoint,
240 VAConfigAttrib *attrib_list, /* in/out */
244 typedef int VAConfigID;
247 * Create a configuration for the decode pipeline
248 * it passes in the attribute list that specifies the attributes it cares
249 * about, with the rest taking default values.
251 VAStatus vaCreateConfig (
254 VAEntrypoint entrypoint,
255 VAConfigAttrib *attrib_list,
257 VAConfigID *config_id /* out */
261 * Get all attributes for a given configuration
262 * The profile of the configuration is returned in
\93profile
\94
263 * The entrypoint of the configuration is returned in
\93entrypoint
\94
264 * The caller must provide an
\93attrib_list
\94 array that can hold at least
265 * vaMaxNumConfigAttributes() entries. The actual number of attributes
266 * returned in
\93attrib_list
\94 is returned in
\93num_attribs
\94
268 VAStatus vaGetConfigAttributes (
270 VAConfigID config_id,
271 VAProfile *profile, /* out */
272 VAEntrypoint *entrypoint, /* out */
273 VAConfigAttrib *attrib_list,/* out */
274 int *num_attribs /* out */
281 * Context represents a "virtual" video decode pipeline
284 /* generic context ID type, can be re-typed for specific implementation */
285 typedef int VAContextID;
287 /* generic surface ID type, can be re-typed for specific implementation */
288 typedef int VASurfaceID;
290 #define VA_INVALID_SURFACE -1
292 typedef struct _VAContext
294 VAContextID context_id; /* to identify this context */
295 VAConfigID config_id;
296 unsigned short picture_width;
297 unsigned short picture_height;
298 VASurfaceID *render_targets;
299 int num_render_targets;
305 flags - Any combination of the following:
306 VA_PROGRESSIVE (only progressive frame pictures in the sequence when set)
308 #define VA_PROGRESSIVE 0x1
314 Surfaces are render targets for a given context. The data in the surfaces
315 are not accessible to the client and the internal data format of
316 the surface is implementatin specific.
318 Question: Is there a need to know the data format (fourcc) or just
319 differentiate between 420/422/444 is sufficient?
323 typedef struct _VASurface
325 VASurfaceID surface_id; /* uniquely identify this surface */
326 VAContextID context_id; /* which context does this surface belong */
327 unsigned short width;
328 unsigned short height;
329 int format; /* 420/422/444 */
330 void *privData; /* private to the library */
334 * Surfaces will be bound to a context when the context is created. Once
335 * a surface is bound to a given context, it can not be used to create
336 * another context. The association is removed when the context is destroyed
339 /* Surface Functions */
340 VAStatus vaCreateSurfaces (
346 VASurface *surfaces /* out */
350 * surfaces can only be destroyed after the context associated has been
353 VAStatus vaDestroySurface (
355 VASurface *surface_list,
359 VAStatus vaCreateContext (
361 VAConfigID config_id,
365 VASurface *render_targets,
366 int num_render_targets,
367 VAContext *context /* out */
370 VAStatus vaDestroyContext (
378 * Buffers are used to pass various types of data from the
379 * client to the server. The server maintains a data store
380 * for each buffer created, and the client idenfies a buffer
381 * through a unique buffer id assigned by the server.
385 typedef int VABufferID;
389 VAPictureParameterBufferType = 0,
390 VAIQMatrixBufferType = 1,
391 VABitPlaneBufferType = 2,
392 VASliceGroupMapBufferType = 3,
393 VASliceParameterBufferType = 4,
394 VASliceDataBufferType = 5,
395 VAMacroblockParameterBufferType = 6,
396 VAResidualDataBufferType = 7,
397 VADeblockingParameterBufferType = 8
400 /****************************
401 * MPEG-2 data structures
402 ****************************/
404 /* MPEG-2 Picture Parameter Buffer */
406 * For each frame or field, and before any slice data, a single
407 * picture parameter buffer must be send.
409 typedef struct _VAPictureParameterBufferMPEG2
411 unsigned short horizontal_size;
412 unsigned short vertical_size;
413 VASurfaceID forward_reference_picture;
414 VASurfaceID backward_reference_picture;
415 /* meanings of the following fields are the same as in the standard */
416 int picture_coding_type;
417 int f_code; /* pack all four fcode into this */
420 unsigned char intra_dc_precision : 2;
421 unsigned char picture_structure : 2;
422 unsigned char top_field_first : 1;
423 unsigned char frame_pred_frame_dct : 1;
424 unsigned char concealment_motion_vectors : 1;
425 unsigned char q_scale_type : 1;
426 unsigned char intra_vlc_format : 1;
427 unsigned char alternate_scan : 1;
428 unsigned char repeat_first_field : 1;
429 unsigned char progressive_frame : 1;
431 unsigned int picture_coding_extension;
433 } VAPictureParameterBufferMPEG2;
435 /* MPEG-2 Inverse Quantization Matrix Buffer */
436 typedef struct _VAIQMatrixBufferMPEG2
438 int load_intra_quantiser_matrix;
439 int load_non_intra_quantiser_matrix;
440 int load_chroma_intra_quantiser_matrix;
441 int load_chroma_non_intra_quantiser_matrix;
442 unsigned char intra_quantiser_matrix[64];
443 unsigned char non_intra_quantiser_matrix[64];
444 unsigned char chroma_intra_quantiser_matrix[64];
445 unsigned char chroma_non_intra_quantiser_matrix[64];
446 } VAIQMatrixBufferMPEG2;
449 * There will be cases where the bitstream buffer will not have enough room to hold
450 * the data for the entire slice, and the following flags will be used in the slice
451 * parameter to signal to the server for the possible cases.
452 * If a slice parameter buffer and slice data buffer pair is sent to the server with
453 * the slice data partially in the slice data buffer (BEGIN and MIDDLE cases below),
454 * then a slice parameter and data buffer needs to be sent again to complete this slice.
456 #define VA_SLICE_DATA_FLAG_ALL 0x00 /* whole slice is in the buffer */
457 #define VA_SLICE_DATA_FLAG_BEGIN 0x01 /* The beginning of the slice is in the buffer but the end if not */
458 #define VA_SLICE_DATA_FLAG_MIDDLE 0x02 /* Neither beginning nor end of the slice is in the buffer */
459 #define VA_SLICE_DATA_FLAG_END 0x04 /* end of the slice is in the buffer */
461 /* MPEG-2 Slice Parameter Buffer */
462 typedef struct _VASliceParameterBufferMPEG2
464 unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
465 unsigned int slice_data_offset;/* the offset to the first byte of slice data */
466 unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
467 unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
468 unsigned int slice_vertical_position;
469 int quantiser_scale_code;
470 int intra_slice_flag;
471 } VASliceParameterBufferMPEG2;
473 /* MPEG-2 Macroblock Parameter Buffer */
474 typedef struct _VAMacroblockParameterBufferMPEG2
476 unsigned short macroblock_address;
478 * macroblock_address (in raster scan order)
480 * bottom-right: picture-height-in-mb*picture-width-in-mb - 1
482 unsigned char macroblock_type; /* see definition below */
485 unsigned char frame_motion_type : 2;
486 unsigned char field_motion_type : 2;
487 unsigned char dct_type : 1;
489 unsigned char macroblock_modes;
491 unsigned char motion_vertical_field_select;
493 * motion_vertical_field_select:
494 * see section 6.3.17.2 in the spec
495 * only the lower 4 bits are used
496 * bit 0: first vector forward
497 * bit 1: first vector backward
498 * bit 2: second vector forward
499 * bit 3: second vector backward
501 short PMV[2][2][2]; /* see Table 7-7 in the spec */
502 unsigned short coded_block_pattern;
504 * The bitplanes for coded_block_pattern are described
505 * in Figure 6.10-12 in the spec
508 /* Number of skipped macroblocks after this macroblock */
509 unsigned short num_skipped_macroblocks;
510 } VAMacroblockParameterBufferMPEG2;
513 * OR'd flags for macroblock_type (section 6.3.17.1 in the spec)
515 #define VA_MB_TYPE_MOTION_FORWARD 0x02
516 #define VA_MB_TYPE_MOTION_BACKWARD 0x04
517 #define VA_MB_TYPE_MOTION_PATTERN 0x08
518 #define VA_MB_TYPE_MOTION_INTRA 0x10
521 * MPEG-2 Residual Data Buffer
522 * For each macroblock, there wil be 64 shorts (16-bit) in the
523 * residual data buffer
526 /****************************
527 * MPEG-4 Part 2 data structures
528 ****************************/
530 /* MPEG-4 Picture Parameter Buffer */
532 * For each frame or field, and before any slice data, a single
533 * picture parameter buffer must be send.
535 typedef struct _VAPictureParameterBufferMPEG4
537 unsigned short vop_width;
538 unsigned short vop_height;
539 VASurfaceID forward_reference_picture;
540 VASurfaceID backward_reference_picture;
543 unsigned char short_video_header : 1;
544 unsigned char chroma_format : 2;
545 unsigned char interlaced : 1;
546 unsigned char obmc_disable : 1;
547 unsigned char sprite_enable : 2;
548 unsigned char sprite_warping_accuracy : 2;
549 unsigned char quant_type : 1;
550 unsigned char quarter_sample : 1;
551 unsigned char data_partitioned : 1;
552 unsigned char reversible_vlc : 1;
554 unsigned short vol_fields;
556 unsigned char no_of_sprite_warping_points;
557 short sprite_trajectory_du[3];
558 short sprite_trajectory_dv[3];
559 unsigned char quant_precision;
562 unsigned char vop_coding_type : 2;
563 unsigned char backward_reference_vop_coding_type : 2;
564 unsigned char vop_rounding_type : 1;
565 unsigned char intra_dc_vlc_thr : 3;
566 unsigned char top_field_first : 1;
567 unsigned char alternate_vertical_scan_flag : 1;
569 unsigned short vop_fields;
571 unsigned char vop_fcode_forward;
572 unsigned char vop_fcode_backward;
573 /* short header related */
574 unsigned char num_gobs_in_vop;
575 unsigned char num_macroblocks_in_gob;
576 /* for direct mode prediction */
579 } VAPictureParameterBufferMPEG4;
581 /* MPEG-4 Inverse Quantization Matrix Buffer */
582 typedef struct _VAIQMatrixBufferMPEG4
584 int load_intra_quant_mat;
585 int load_non_intra_quant_mat;
586 unsigned char intra_quant_mat[64];
587 unsigned char non_intra_quant_mat[64];
588 } VAIQMatrixBufferMPEG4;
590 /* MPEG-4 Slice Parameter Buffer */
591 typedef struct _VASliceParameterBufferMPEG4
593 unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
594 unsigned int slice_data_offset;/* the offset to the first byte of slice data */
595 unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
596 unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
597 unsigned int macroblock_number;
599 } VASliceParameterBufferMPEG4;
605 /* VC-1 Picture Parameter Buffer */
607 * For each picture, and before any slice data, a picture parameter
608 * buffer must be send. Multiple picture parameter buffers may be
609 * sent for a single picture. In that case picture parameters will
610 * apply to all slice data that follow it until a new picture
611 * parameter buffer is sent.
614 * pic_quantizer_type should be set to the applicable quantizer
615 * type as defined by QUANTIZER (J.1.19) and either
616 * PQUANTIZER (7.1.1.8) or PQINDEX (7.1.1.6)
618 typedef struct _VAPictureParameterBufferVC1
620 VASurfaceID forward_reference_picture;
621 VASurfaceID backward_reference_picture;
622 /* if out-of-loop post-processing is done on the render
623 target, then we need to keep the in-loop decoded
624 picture as a reference picture */
625 VASurfaceID inloop_decoded_picture;
627 /* sequence layer for AP or meta data for SP and MP */
630 unsigned char interlace : 1; /* SEQUENCE_LAYER::INTERLACE */
631 unsigned char syncmarker : 1;/* METADATA::SYNCMARKER */
632 unsigned char overlap : 1;/* METADATA::OVERLAP */
634 unsigned char sequence_fields;
637 unsigned short coded_width; /* ENTRY_POINT_LAYER::CODED_WIDTH */
638 unsigned short coded_height; /* ENTRY_POINT_LAYER::CODED_HEIGHT */
639 unsigned char closed_entry; /* ENTRY_POINT_LAYER::CLOSED_ENTRY */
640 unsigned char broken_link; /* ENTRY_POINT_LAYER::BROKEN_LINK */
641 unsigned char loopfilter; /* ENTRY_POINT_LAYER::LOOPFILTER */
642 unsigned char conditional_overlap_flag; /* ENTRY_POINT_LAYER::CONDOVER */
643 unsigned char fast_uvmc_flag; /* ENTRY_POINT_LAYER::FASTUVMC */
646 unsigned char range_mapping_luma_flag: 1; /* ENTRY_POINT_LAYER::RANGE_MAPY_FLAG */
647 unsigned char range_mapping_luma: 3; /* ENTRY_POINT_LAYER::RANGE_MAPY */
648 unsigned char range_mapping_chroma_flag: 1; /* ENTRY_POINT_LAYER::RANGE_MAPUV_FLAG */
649 unsigned char range_mapping_chroma: 3; /* ENTRY_POINT_LAYER::RANGE_MAPUV */
651 unsigned char range_mapping_fields;
654 unsigned char b_picture_fraction; /* PICTURE_LAYER::BFRACTION */
655 unsigned char cbp_table; /* PICTURE_LAYER::CBPTAB/ICBPTAB */
656 unsigned char mb_mode_table; /* PICTURE_LAYER::MBMODETAB */
657 unsigned char range_reduction_frame;/* PICTURE_LAYER::RANGEREDFRM */
658 unsigned char rounding_control; /* PICTURE_LAYER::RNDCTRL */
659 unsigned char post_processing; /* PICTURE_LAYER::POSTPROC */
660 unsigned char picture_resolution_index; /* PICTURE_LAYER::RESPIC */
661 unsigned char luma_scale; /* PICTURE_LAYER::LUMSCALE */
662 unsigned char luma_shift; /* PICTURE_LAYER::LUMSHIFT */
665 unsigned char picture_type : 2; /* PICTURE_LAYER::PTYPE */
666 unsigned char frame_coding_mode : 3;/* PICTURE_LAYER::FCM */
667 unsigned char top_field_first : 1;/* PICTURE_LAYER::TFF */
668 unsigned char is_first_field : 1; /* set to 1 if it is the first field */
669 unsigned char intensity_compensation: 1;/* PICTURE_LAYER::INTCOMP */
671 unsigned char picture_fields;
675 unsigned char mv_type_mb : 1; /* PICTURE::MVTYPEMB */
676 unsigned char direct_mb : 1; /* PICTURE::DIRECTMB */
677 unsigned char skip_mb : 1; /* PICTURE::SKIPMB */
678 unsigned char field_tx : 1; /* PICTURE::FIELDTX */
679 unsigned char foward_mb : 1; /* PICTURE::FORWARDMB */
680 unsigned char ac_pred : 1; /* PICTURE::ACPRED */
681 unsigned char overflags : 1; /* PICTURE::OVERFLAGS */
683 unsigned char raw_coding_flag;
687 unsigned char reference_distance_flag : 1;/* PICTURE_LAYER::REFDIST_FLAG */
688 unsigned char reference_distance : 1;/* PICTURE_LAYER::REFDIST */
689 unsigned char num_reference_pictures: 1;/* PICTURE_LAYER::NUMREF */
690 unsigned char reference_field_pic_indicator : 1;/* PICTURE_LAYER::REFFIELD */
692 unsigned short reference_fields;
696 unsigned char mv_mode : 2; /* PICTURE_LAYER::MVMODE */
697 unsigned char mv_mode2 : 2; /* PICTURE_LAYER::MVMODE2 */
698 unsigned char mv_table : 3;/* PICTURE_LAYER::MVTAB/IMVTAB */
699 unsigned char two_mv_block_pattern_table: 2;/* PICTURE_LAYER::2MVBPTAB */
700 unsigned char four_mv_switch: 1; /* PICTURE_LAYER::4MVSWITCH */
701 unsigned char four_mv_block_pattern_table : 2;/* PICTURE_LAYER::4MVBPTAB */
702 unsigned char extended_mv_flag: 1;/* ENTRY_POINT_LAYER::EXTENDED_MV */
703 unsigned char extended_mv_range : 2;/* PICTURE_LAYER::MVRANGE */
704 unsigned char extended_dmv_flag : 1;/* ENTRY_POINT_LAYER::EXTENDED_DMV */
705 unsigned char extended_dmv_range : 2;/* PICTURE_LAYER::DMVRANGE */
707 unsigned int mv_fields;
711 unsigned char dquant : 2; /* ENTRY_POINT_LAYER::DQUANT */
712 unsigned char half_qp : 1; /* PICTURE_LAYER::HALFQP */
713 unsigned char pic_quantizer_scale : 1;/* PICTURE_LAYER::PQUANT */
714 unsigned char pic_quantizer_type : 1;/* PICTURE_LAYER::PQUANTIZER */
715 unsigned char dq_frame : 1; /* VOPDQUANT::DQUANTFRM */
716 unsigned char dq_profile : 2; /* VOPDQUANT::DQPROFILE */
717 unsigned char dq_sb_edge : 2; /* VOPDQUANT::DQSBEDGE */
718 unsigned char dq_db_edge : 2; /* VOPDQUANT::DQDBEDGE */
719 unsigned char dq_binary_level : 1; /* VOPDQUANT::DQBILEVEL */
720 unsigned char alt_pic_quantizer : 5;/* VOPDQUANT::ALTPQUANT */
722 unsigned long pic_quantizer_fields;
726 unsigned char variable_sized_transform_flag : 1;/* ENTRY_POINT_LAYER::VSTRANSFORM */
727 unsigned char mb_level_transform_type_flag : 1;/* PICTURE_LAYER::TTMBF */
728 unsigned char frame_level_transform_type : 2;/* PICTURE_LAYER::TTFRM */
729 unsigned char transform_ac_codingset_idx1 : 2;/* PICTURE_LAYER::TRANSACFRM */
730 unsigned char transform_ac_codingset_idx2 : 2;/* PICTURE_LAYER::TRANSACFRM2 */
731 unsigned char intra_transform_dc_table : 1;/* PICTURE_LAYER::TRANSDCTAB */
733 unsigned short transform_fields;
735 } VAPictureParameterBufferVC1;
737 /* VC-1 Bitplane Buffer
738 There will be at most three bitplanes coded in any picture header. To send
739 the bitplane data more efficiently, each byte is divided in two nibbles, with
740 each nibble carrying three bitplanes for one macroblock. The following table
741 shows the bitplane data arrangement within each nibble based on the picture
744 Picture Type Bit3 Bit2 Bit1 Bit0
745 I or BI OVERFLAGS ACPRED FIELDTX
746 P MYTYPEMB SKIPMB DIRECTMB
747 B FORWARDMB SKIPMB DIRECTMB
749 Within each byte, the lower nibble is for the first MB and the upper nibble is
750 for the second MB. E.g. the lower nibble of the first byte in the bitplane
751 buffer is for Macroblock #1 and the upper nibble of the first byte is for
752 Macroblock #2 in the first row.
755 /* VC-1 Slice Parameter Buffer */
756 typedef struct _VASliceParameterBufferVC1
758 unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
759 unsigned int slice_data_offset;/* the offset to the first byte of slice data */
760 unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
761 unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
762 unsigned int slice_vertical_position;
763 } VASliceParameterBufferVC1;
765 /* VC-1 Slice Data Buffer */
767 This is simplely a buffer containing raw bit-stream bytes
770 /****************************
771 * H.264/AVC data structures
772 ****************************/
774 typedef struct _VAPictureH264
776 VASurfaceID picture_id;
778 unsigned int TopFieldOrderCnt;
779 unsigned int BottomFieldOrderCnt;
781 /* flags in VAPictureH264 could be OR of the following */
782 #define VA_PICTURE_H264_INVALID 0x00000001
783 #define VA_PICTURE_H264_TOP_FIELD 0x00000002
784 #define VA_PICTURE_H264_BOTTOM_FIELD 0x00000004
785 #define VA_PICTURE_H264_SHORT_TERM_REFERENCE 0x00000008
786 #define VA_PICTURE_H264_LONG_TERM_REFERENCE 0x00000010
787 #define VA_PICTURE_H264_USED_AS_REFERENCE 0x00000020
789 /* H.264 Picture Parameter Buffer */
791 * For each picture, and before any slice data, a single
792 * picture parameter buffer must be send.
794 typedef struct _VAPictureParameterBufferH264
796 VAPictureH264 CurrPic;
797 VAPictureH264 ReferenceFrames[16]; /* in DPB */
798 unsigned short picture_width_in_mbs_minus1;
799 unsigned short picture_height_in_mbs_minus1;
800 unsigned char bit_depth_luma_minus8;
801 unsigned char bit_depth_chroma_minus8;
802 unsigned char num_ref_frames;
805 unsigned char chroma_format_idc : 2;
806 unsigned char residual_colour_transform_flag : 1;
807 unsigned char frame_mbs_only_flag : 1;
808 unsigned char mb_adaptive_frame_field_flag : 1;
809 unsigned char direct_8x8_inference_flag : 1;
810 unsigned char MinLumaBiPredSize8x8 : 1; /* see A.3.3.2 */
812 unsigned char seq_fields;
814 unsigned char num_slice_groups_minus1;
815 unsigned char slice_group_map_type;
816 unsigned char pic_init_qp_minus26;
817 unsigned char chroma_qp_index_offset;
818 unsigned char second_chroma_qp_index_offset;
821 unsigned char entropy_coding_mode_flag : 1;
822 unsigned char weighted_pred_flag : 1;
823 unsigned char weighted_bipred_idc : 1;
824 unsigned char transform_8x8_mode_flag : 1;
825 unsigned char field_pic_flag : 1;
826 unsigned char constrained_intra_pred_flag : 1;
828 unsigned char pic_fields;
830 unsigned short frame_num;
831 } VAPictureParameterBufferH264;
833 /* H.264 Inverse Quantization Matrix Buffer */
834 typedef struct _VAIQMatrixBufferH264
836 unsigned char ScalingList4x4[6][16];
837 unsigned char ScalingList8x8[2][64];
838 } VAIQMatrixBufferH264;
841 * H.264 Slice Group Map Buffer
842 * When VAPictureParameterBufferH264::num_slice_group_minus1 is not equal to 0,
843 * A slice group map buffer should be sent for each picture if required. The buffer
844 * is sent only when there is a change in the mapping values.
845 * The slice group map buffer map "map units" to slice groups as specified in
846 * section 8.2.2 of the H.264 spec. The buffer will contain one byte for each macroblock
847 * in raster scan order
850 /* H.264 Slice Parameter Buffer */
851 typedef struct _VASliceParameterBufferH264
853 unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
854 unsigned int slice_data_offset;/* the offset to first byte of slice data */
855 unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
856 unsigned short slice_data_bit_offset; /* bit offset in the first byte of valid data */
857 unsigned short first_mb_in_slice;
858 unsigned char slice_type;
859 unsigned char direct_spatial_mv_pred_flag;
860 unsigned char num_ref_idx_l0_active_minus1;
861 unsigned char num_ref_idx_l1_active_minus1;
862 unsigned char cabac_init_idc;
864 unsigned char disable_deblocking_filter_idc;
865 char slice_alpha_c0_offset_div2;
866 char slice_beta_offset_div2;
867 VAPictureH264 RefPicList0[32]; /* See 8.2.4.2 */
868 VAPictureH264 RefPicList1[32]; /* See 8.2.4.2 */
869 unsigned char luma_log2_weight_denom;
870 unsigned char chroma_log2_weight_denom;
871 unsigned char luma_weight_l0_flag;
872 short luma_weight_l0[32];
873 short luma_offset_l0[32];
874 unsigned char chroma_weight_l0_flag;
875 short chroma_weight_l0[32][2];
876 short chroma_offset_l0[32][2];
877 unsigned char luma_weight_l1_flag;
878 short luma_weight_l1[32];
879 short luma_offset_l1[32];
880 unsigned char chroma_weight_l1_flag;
881 short chroma_weight_l1[32][2];
882 short chroma_offset_l1[32][2];
883 } VASliceParameterBufferH264;
885 /* Buffer functions */
888 * Creates a buffer for storing a certain type of data, no data store allocated
890 VAStatus vaCreateBuffer (
892 VABufferType type, /* in */
893 VABufferID *buf_id /* out */
897 * Create data store for the buffer and initalize with "data".
898 * if "data" is null, then the contents of the buffer data store
900 * Basically there are two ways to get buffer data to the server side. One is
901 * to call vaBufferData() with a non-null "data", which results the data being
902 * copied to the data store on the server side. A different method that
903 * eliminates this copy is to pass null as "data" when calling vaBufferData(),
904 * and then use vaMapBuffer() to map the data store from the server side to the
905 * client address space for access.
907 VAStatus vaBufferData (
909 VABufferID buf_id, /* in */
910 unsigned int size, /* in */
911 unsigned int num_elements, /* in */
916 * Convey to the server how many valid elements are in the buffer.
917 * e.g. if multiple slice parameters are being held in a single buffer,
918 * this will communicate to the server the number of slice parameters
919 * that are valid in the buffer.
921 VAStatus vaBufferSetNumElements (
923 VABufferID buf_id, /* in */
924 unsigned int num_elements /* in */
928 * Map data store of the buffer into the client's address space
929 * vaBufferData() needs to be called with "data" set to NULL before
930 * calling vaMapBuffer()
932 VAStatus vaMapBuffer (
934 VABufferID buf_id, /* in */
935 void **pbuf /* out */
939 * After client making changes to a mapped data store, it needs to
940 * "Unmap" it to let the server know that the data is ready to be
941 * consumed by the server
943 VAStatus vaUnmapBuffer (
945 VABufferID buf_id /* in */
949 * After this call, the buffer is deleted and this buffer_id is no longer valid
951 VAStatus vaDestroyBuffer (
957 Render (Decode) Pictures
959 A picture represents either a frame or a field.
961 The Begin/Render/End sequence sends the decode buffers to the server
965 * Get ready to decode a picture to a target surface
967 VAStatus vaBeginPicture (
970 VASurface *render_target
974 * Send decode buffers to the server.
976 VAStatus vaRenderPicture (
984 * Make the end of rendering for a picture.
985 * The server should start processing all pending operations for this
986 * surface. This call is non-blocking. The client can start another
987 * Begin/Render/End sequence on a different render target.
989 VAStatus vaEndPicture (
1001 * This function blocks until all pending operations on the render target
1002 * have been completed. Upon return it is safe to use the render target for a
1003 * different picture.
1005 VAStatus vaSyncSurface (
1008 VASurface *render_target
1013 VASurfaceRendering = 0,
1018 * Find out any pending ops on the render target
1020 VAStatus vaQuerySurfaceStatus (
1023 VASurface *render_target,
1024 VASurfaceStatus *status /* out */
1028 * Copies the surface to a buffer
1029 * The stride of the surface will be stored in *stride
1030 * Caller should free the returned buffer with free() when done.
1032 VAStatus vaDbgCopySurfaceToBuffer(VADisplay dpy,
1034 void **buffer, /* out */
1035 unsigned int *stride /* out */
1045 /*****************************************************************************/
1047 Sample Program (w/ pseudo code)
1049 Mostly to demonstrate program flow with no error handling ...
1051 /*****************************************************************************/
1053 /* MPEG-2 VLD decode for a 720x480 frame */
1055 int major_ver, minor_ver;
1056 vaInitialize(dpy, &major_ver, &minor_ver);
1058 int max_num_profiles, max_num_entrypoints, max_num_attribs;
1059 max_num_profiles = vaMaxNumProfiles(dpy);
1060 max_num_entrypoints = vaMaxNumProfiles(dpy);
1061 max_num_attribs = vaMaxNumProfiles(dpy);
1063 /* find out whether MPEG2 MP is supported */
1064 VAProfile *profiles = malloc(sizeof(VAProfile)*max_num_profiles);
1066 vaQueryConfigProfiles(dpy, profiles, &profiles);
1068 * traverse "profiles" to locate the one that matches VAProfileMPEG2Main
1071 /* now get the available entrypoints for MPEG2 MP */
1072 VAEntrypoint *entrypoints = malloc(sizeof(VAEntrypoint)*max_num_entrypoints);
1073 int num_entrypoints;
1074 vaQueryConfigEntrypoints(dpy, VAProfileMPEG2Main, entrypoints, &num_entrypoints);
1076 /* traverse "entrypoints" to see whether VLD is there */
1078 /* Assuming finding VLD, find out the format for the render target */
1079 VAConfigAttrib attrib;
1080 attrib.type = VAConfigAttribRTFormat;
1081 vaQueryConfigAttributes(dpy, VAProfileMPEG2Main, VAEntrypointVLD,
1084 if (attrib.value & VA_RT_FORMAT_YUV420)
1085 /* Found desired RT format, keep going */
1087 VAConfigID config_id;
1088 vaCreateConfig(dpy, VAProfileMPEG2Main, VAEntrypointVLD, &attrib, 1,
1092 * create surfaces for the current target as well as reference frames
1093 * we can get by with 4 surfaces for MPEG-2
1095 VASurface surfaces[4];
1096 vaCreateSurfaces(dpy, 720, 480, VA_RT_FORMAT_YUV420, 4, surfaces);
1099 * Create a context for this decode pipe
1102 vaCreateContext(dpy, config_id, 720, 480, VA_PROGRESSIVE, surfaces,
1105 /* Create a picture parameter buffer for this frame */
1106 VABufferID picture_buf;
1107 VAPictureParameterBufferMPEG2 *picture_param;
1108 vaCreateBuffer(dpy, VAPictureParameterBufferType, &picture_buf);
1109 vaBufferData(dpy, picture_buf, sizeof(VAPictureParameterBufferMPEG2), NULL);
1110 vaMapBuffer(dpy, picture_buf, &picture_param);
1111 picture_param->horizontal_size = 720;
1112 picture_param->vertical_size = 480;
1113 picture_param->picture_coding_type = 1; /* I-frame */
1114 /* fill in picture_coding_extension fields here */
1115 vaUnmapBuffer(dpy, picture_buf);
1118 /* Create an IQ matrix buffer for this frame */
1120 VAIQMatrixBufferMPEG2 *iq_matrix;
1121 vaCreateBuffer(dpy, VAIQMatrixBufferType, &iq_buf);
1122 vaBufferData(dpy, iq_buf, sizeof(VAIQMatrixBufferMPEG2), NULL);
1123 vaMapBuffer(dpy, iq_buf, &iq_matrix);
1124 /* fill values for IQ_matrix here */
1125 vaUnmapBuffer(dpy, iq_buf);
1127 /* send the picture and IQ matrix buffers to the server */
1128 vaBeginPicture(dpy, context, &surfaces[0]);
1130 vaRenderPicture(dpy, context, &picture_buf, 1);
1131 vaRenderPicture(dpy, context, &iq_buf, 1);
1134 * Send slices in this frame to the server.
1135 * For MPEG-2, each slice is one row of macroblocks, and
1136 * we have 30 slices for a 720x480 frame
1138 for (int i = 1; i <= 30; i++) {
1140 /* Create a slice parameter buffer */
1141 VABufferID slice_param_buf;
1142 VASliceParameterBufferMPEG2 *slice_param;
1143 vaCreateBuffer(dpy, VASliceParameterBufferType, &slice_param_buf);
1144 vaBufferData(dpy, slice_param_buf, sizeof(VASliceParameterBufferMPEG2), NULL);
1145 vaMapBuffer(dpy, slice_param_buf, &slice_param);
1146 slice_param->slice_data_offset = 0;
1147 /* Let's say all slices in this bit-stream has 64-bit header */
1148 slice_param->macroblock_offset = 64;
1149 slice_param->vertical_position = i;
1150 /* set up the rest based on what is in the slice header ... */
1151 vaUnmapBuffer(dpy, slice_param_buf);
1153 /* send the slice parameter buffer */
1154 vaRenderPicture(dpy, context, &slice_param_buf, 1);
1156 /* Create a slice data buffer */
1157 unsigned char *slice_data;
1158 VABufferID slice_data_buf;
1159 vaCreateBuffer(dpy, VASliceDataBufferType, slice_data_buf);
1160 vaBufferData(dpy, slice_data_buf, x /* decoder figure out how big */, NULL);
1161 vaMapBuffer(dpy, slice_data_buf, &slice_data);
1162 /* decoder fill in slice_data */
1163 vaUnmapBuffer(dpy, slice_data_buf);
1165 /* send the slice data buffer */
1166 vaRenderPicture(dpy, context, &slice_data_buf, 1);
1169 /* all slices have been sent, mark the end for this frame */
1170 vaEndPicture(dpy, context);