src/va.h

   1 /*
   2  * Video Decode Acceleration API Specification
   3  *
   4  * Rev. 0.18
   5  * <jonathan.bian@intel.com>
   6  *
   7  * Revision History:
   8  * rev 0.10 (12/10/06 Jonathan Bian) - Initial draft
   9  * rev 0.11 (12/15/06 Jonathan Bian) - Fixed some errors
  10  * rev 0.12 (02/05/07 Jonathan Bian) - Added VC-1 data structures for slice level decode
  11  * rev 0.13 (02/28/07 Jonathan Bian) - Added GetDisplay()
  12  * rev 0.14 (04/13/07 Jonathan Bian) - Fixed MPEG-2 PictureParameter struct, cleaned up a few funcs.
  13  * rev 0.15 (04/20/07 Jonathan Bian) - Overhauled buffer management
  14  * rev 0.16 (05/02/07 Jonathan Bian) - Added error codes and fixed some issues with configuration
  15  * rev 0.17 (05/07/07 Jonathan Bian) - Added H.264/AVC data structures for slice level decode.
  16  * rev 0.18 (05/14/07 Jonathan Bian) - Added data structures for MPEG-4 slice level decode
  17  *                                     and MPEG-2 motion compensation.
  18  *
  19  * Acknowledgements:
  20  *  Thanks to Waldo Bastian for many valuable feedbacks.
  21  */
  22
  23 #ifndef _VA_H_
  24 #define _VA_H_
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /*
  31 Overview
  32
  33 This is a decode only interface currently.  The basic steps are:
  34
  35 - Negotiate a mutually acceptable configuration with the server to lock
  36   down profile, entrypoints, and other attributes that will not change on
  37   a frame-by-frame basis.
  38 - Create a decode context which represents a "virtualized" hardware decode
  39   device
  40 - Get and fill decode buffers with picture level, slice level and macroblock
  41   level data (depending on entrypoints)
  42 - Pass the decode buffers to the server to decode the current frame
  43
  44 Initialization & Configuration Management
  45
  46 - Find out supported profiles
  47 - Find out entrypoints for a given profile
  48 - Find out configuration attributes for a given profile/entrypoint pair
  49 - Create a configuration for use by the decoder
  50
  51 */
  52
  53 typedef void* VADisplay;        /* window system dependent */
  54
  55 typedef int VAStatus;   /* Return status type from functions */
  56 /* Values for the return status */
  57 #define VA_STATUS_SUCCESS                       0x00000000
  58 #define VA_STATUS_ERROR_ALLOCATION_FAILED       0x00000001
  59 #define VA_STATUS_ERROR_INVALID_CONFIG          0x00000002
  60 #define VA_STATUS_ERROR_INVALID_CONTEXT         0x00000003
  61 #define VA_STATUS_ERROR_INVALID_SURFACE         0x00000004
  62 #define VA_STATUS_ERROR_INVALID_BUFFER          0x00000005
  63 #define VA_STATUS_ERROR_ATTR_NOT_SUPPORTED      0x00000006 /* Todo: Remove */
  64 #define VA_STATUS_ERROR_MAX_NUM_EXCEEDED        0x00000007
  65 #define VA_STATUS_ERROR_UNSUPPORTED_PROFILE             0x00000008
  66 #define VA_STATUS_ERROR_UNSUPPORTED_ENTRYPOINT  0x00000009
  67 #define VA_STATUS_ERROR_UNSUPPORTED_RT_FORMAT   0x0000000a
  68 #define VA_STATUS_ERROR_UNSUPPORTED_BUFFERTYPE  0x0000000b
  69 #define VA_STATUS_ERROR_UNKNOWN                 0xFFFFFFFF
  70
  71 /*
  72  * Returns a short english description of error_status
  73  */
  74 const char *vaErrorStr(VAStatus error_status);
  75
  76 /*
  77  * Initialization:
  78  * A display must be obtained by calling vaGetDisplay() before calling
  79  * vaInitialize() and other functions. This connects the API to the
  80  * native window system.
  81  * For X Windows, native_dpy would be from XOpenDisplay()
  82  */
  83 typedef void* NativeDisplay;    /* window system dependent */
  84
  85 VADisplay vaGetDisplay (
  86     NativeDisplay native_dpy    /* implementation specific */
  87 );
  88
  89 VAStatus vaInitialize (
  90     VADisplay dpy,
  91     int *major_version,  /* out */
  92     int *minor_version   /* out */
  93 );
  94
  95 /*
  96  * After this call, all library internal resources will be cleaned up
  97  */
  98 VAStatus vaTerminate (
  99     VADisplay dpy
 100 );
 101
 102 /* Currently defined profiles */
 103 typedef enum
 104 {
 105     VAProfileMPEG2Simple                = 0,
 106     VAProfileMPEG2Main                  = 1,
 107     VAProfileMPEG4Simple                = 2,
 108     VAProfileMPEG4AdvancedSimple        = 3,
 109     VAProfileMPEG4Main                  = 4,
 110     VAProfileH264Baseline               = 5,
 111     VAProfileH264Main                   = 6,
 112     VAProfileH264High                   = 7,
 113     VAProfileVC1Simple                  = 8,
 114     VAProfileVC1Main                    = 9,
 115     VAProfileVC1Advanced                = 10,
 116 } VAProfile;
 117
 118 /* Currently defined entrypoints */
 119 typedef enum
 120 {
 121     VAEntrypointVLD             = 1,
 122     VAEntrypointIZZ             = 2,
 123     VAEntrypointIDCT            = 3,
 124     VAEntrypointMoComp          = 4,
 125     VAEntrypointDeblocking      = 5,
 126 } VAEntrypoint;
 127
 128 /* Currently defined configuration attribute types */
 129 typedef enum
 130 {
 131     VAConfigAttribRTFormat              = 0,
 132     VAConfigAttribSpatialResidual       = 1,
 133     VAConfigAttribSpatialClipping       = 2,
 134     VAConfigAttribIntraResidual         = 3,
 135     VAConfigAttribEncryption            = 4,
 136 } VAConfigAttribType;
 137
 138 /*
 139  * Configuration attributes
 140  * If there is more than one value for an attribute, a default
 141  * value will be assigned to the attribute if the client does not
 142  * specify the attribute when creating a configuration
 143  */
 144 typedef struct _VAConfigAttrib {
 145     VAConfigAttribType type;
 146     unsigned int value; /* OR'd flags (bits) for this attribute */
 147 } VAConfigAttrib;
 148
 149 /* attribute value for VAConfigAttribRTFormat */
 150 #define VA_RT_FORMAT_YUV420     0x00000001
 151 #define VA_RT_FORMAT_YUV422     0x00000002
 152 #define VA_RT_FORMAT_YUV444     0x00000004
 153
 154 /*
 155  * if an attribute is not applicable for a given
 156  * profile/entrypoint pair, then set the value to the following
 157  */
 158 #define VA_ATTRIB_NOT_SUPPORTED 0x80000000
 159
 160 /* Get maximum number of profiles supported by the implementation */
 161 int vaMaxNumProfiles (
 162     VADisplay dpy
 163 );
 164
 165 /* Get maximum number of entrypoints supported by the implementation */
 166 int vaMaxNumEntrypoints (
 167     VADisplay dpy
 168 );
 169
 170 /* Get maximum number of attributs supported by the implementation */
 171 int vaMaxNumConfigAttributes (
 172     VADisplay dpy
 173 );
 174
 175 /*
 176  * Query supported profiles
 177  * The caller must provide a "profile_list" array that can hold at
 178  * least vaMaxNumProfile() entries. The actual number of profiles
 179  * returned in "profile_list" is returned in "num_profile".
 180  */
 181 VAStatus vaQueryConfigProfiles (
 182     VADisplay dpy,
 183     VAProfile *profile_list,    /* out */
 184     int *num_profiles           /* out */
 185 );
 186
 187 /*
 188  * Query supported entrypoints for a given profile
 189  * The caller must provide an "entrypoint_list" array that can hold at
 190  * least vaMaxNumEntrypoints() entries. The actual number of entrypoints
 191  * returned in "entrypoint_list" is returned in "num_entrypoints".
 192  */
 193 VAStatus vaQueryConfigEntrypoints (
 194     VADisplay dpy,
 195     VAProfile profile,
 196     VAEntrypoint *entrypoint_list,      /* out */
 197     int *num_entrypoints                /* out */
 198 );
 199
 200 /*
 201  * Query attributes for a given profile/entrypoint pair
 202  * The caller must provide an \93attrib_list\94 with all attributes to be
 203  * queried.  Upon return, the attributes in \93attrib_list\94 have been
 204  * updated with their value.  Unknown attributes or attributes that are
 205  * not supported for the given profile/entrypoint pair will have their
 206  * value set to VA_ATTRIB_NOT_SUPPORTED
 207  */
 208 VAStatus vaQueryConfigAttributes (
 209     VADisplay dpy,
 210     VAProfile profile,
 211     VAEntrypoint entrypoint,
 212     VAConfigAttrib *attrib_list, /* in/out */
 213     int num_attribs
 214 );
 215
 216 typedef int VAConfigID;
 217
 218 /*
 219  * Create a configuration for the decode pipeline
 220  * it passes in the attribute list that specifies the attributes it cares
 221  * about, with the rest taking default values.
 222  */
 223 VAStatus vaCreateConfig (
 224     VADisplay dpy,
 225     VAProfile profile,
 226     VAEntrypoint entrypoint,
 227     VAConfigAttrib *attrib_list,
 228     int num_attribs,
 229     VAConfigID *config_id /* out */
 230 );
 231
 232 /*
 233  * Get all attributes for a given configuration
 234  * The profile of the configuration is returned in \93profile\94
 235  * The entrypoint of the configuration is returned in \93entrypoint\94
 236  * The caller must provide an \93attrib_list\94 array that can hold at least
 237  * vaMaxNumConfigAttributes() entries. The actual number of attributes
 238  * returned in \93attrib_list\94 is returned in \93num_attribs\94
 239  */
 240 VAStatus vaGetConfigAttributes (
 241     VADisplay dpy,
 242     VAConfigID config_id,
 243     VAProfile *profile,         /* out */
 244     VAEntrypoint *entrypoint,   /* out */
 245     VAConfigAttrib *attrib_list,/* out */
 246     int *num_attribs            /* out */
 247 );
 248
 249
 250 /*
 251  * Context
 252  *
 253  * Context represents a "virtual" video decode pipeline
 254  */
 255
 256 /* generic context ID type, can be re-typed for specific implementation */
 257 typedef int VAContextID;
 258
 259 /* generic surface ID type, can be re-typed for specific implementation */
 260 typedef int VASurfaceID;
 261
 262 #define VA_INVALID_SURFACE      -1
 263
 264 typedef struct _VAContext
 265 {
 266     VAContextID         context_id; /* to identify this context */
 267     VAConfigID          config_id;
 268     unsigned short      picture_width;
 269     unsigned short      picture_height;
 270     VASurfaceID         *render_targets;
 271     int                 num_render_targets;
 272     int                 flags;
 273     void                *privData;
 274 } VAContext;
 275
 276 /*
 277     flags - Any combination of the following:
 278       VA_PROGRESSIVE (only progressive frame pictures in the sequence when set)
 279 */
 280 #define VA_PROGRESSIVE  0x1
 281
 282 /*
 283
 284 Surface Management
 285
 286 Surfaces are render targets for a given context. The data in the surfaces
 287 are not accessible to the client and the internal data format of
 288 the surface is implementatin specific.
 289
 290 Question: Is there a need to know the data format (fourcc) or just
 291 differentiate between 420/422/444 is sufficient?
 292
 293 */
 294
 295 typedef struct _VASurface
 296 {
 297     VASurfaceID         surface_id; /* uniquely identify this surface */
 298     VAContextID         context_id; /* which context does this surface belong */
 299     unsigned short      width;
 300     unsigned short      height;
 301     int                 format; /* 420/422/444 */
 302     void                *privData; /* private to the library */
 303 } VASurface;
 304
 305 /*
 306  * Surfaces will be bound to a context when the context is created. Once
 307  * a surface is bound to a given context, it can not be used to create
 308  * another context. The association is removed when the context is destroyed
 309  */
 310
 311 /* Surface Functions */
 312 VAStatus vaCreateSurfaces (
 313     VADisplay dpy,
 314     int width,
 315     int height,
 316     int format,
 317     int num_surfaces,
 318     VASurface *surfaces /* out */
 319 );
 320
 321 /*
 322  * surfaces can only be destroyed after the context associated has been
 323  * destroyed
 324  */
 325 VAStatus vaDestroySurface (
 326     VADisplay dpy,
 327     VASurface *surface_list,
 328     int num_surfaces
 329 );
 330
 331 VAStatus vaCreateContext (
 332     VADisplay dpy,
 333     VAConfigID config_id,
 334     int picture_width,
 335     int picture_height,
 336     int flag,
 337     VASurface *render_targets,
 338     int num_render_targets,
 339     VAContext *context          /* out */
 340 );
 341
 342 VAStatus vaDestroyContext (
 343     VADisplay dpy,
 344     VAContext *context
 345 );
 346
 347 /*
 348  *
 349  *      Buffers
 350  *      Buffers are used to pass various types of data from the
 351  *      client to the server. The server maintains a data store
 352  *      for each buffer created, and the client idenfies a buffer
 353  *      through a unique buffer id assigned by the server.
 354  *
 355  */
 356
 357 typedef int VABufferID;
 358
 359 typedef enum
 360 {
 361     VAPictureParameterBufferType        = 0,
 362     VAPictureBitPlaneBufferType         = 1,
 363     VAIQMatrixBufferType                = 2,
 364     VABitPlaneBufferType                = 3,
 365     VASliceGroupMapBufferType           = 4,
 366     VASliceParameterBufferType          = 5,
 367     VASliceDataBufferType               = 6,
 368     VAMacroblockParameterBufferType     = 7,
 369     VAResidualDataBufferType            = 8,
 370     VADeblockingParameterBufferType     = 9,
 371 } VABufferType;
 372
 373 /****************************
 374  * MPEG-2 data structures
 375  ****************************/
 376
 377 /* MPEG-2 Picture Parameter Buffer */
 378 typedef struct _VAPictureParameterBufferMPEG2
 379 {
 380     unsigned short horizontal_size;
 381     unsigned short vertical_size;
 382     VASurfaceID forward_reference_picture;
 383     VASurfaceID backward_reference_picture;
 384     /* meanings of the following fields are the same as in the standard */
 385     int picture_coding_type;
 386     int f_code; /* pack all four fcode into this */
 387     union {
 388         struct {
 389             unsigned char intra_dc_precision            : 2;
 390             unsigned char picture_structure             : 2;
 391             unsigned char top_field_first               : 1;
 392             unsigned char frame_pred_frame_dct          : 1;
 393             unsigned char concealment_motion_vectors    : 1;
 394             unsigned char q_scale_type                  : 1;
 395             unsigned char intra_vlc_format              : 1;
 396             unsigned char alternate_scan                : 1;
 397             unsigned char repeat_first_field            : 1;
 398             unsigned char progressive_frame             : 1;
 399         };
 400         unsigned int picture_coding_extension;
 401     };
 402 } VAPictureParameterBufferMPEG2;
 403
 404 /* MPEG-2 Inverse Quantization Matrix Buffer */
 405 typedef struct _VAIQMatrixBufferMPEG2
 406 {
 407     int load_intra_quantiser_matrix;
 408     int load_non_intra_quantiser_matrix;
 409     int load_chroma_intra_quantiser_matrix;
 410     int load_chroma_non_intra_quantiser_matrix;
 411     unsigned char intra_quantiser_matrix[64];
 412     unsigned char non_intra_quantiser_matrix[64];
 413     unsigned char chroma_intra_quantiser_matrix[64];
 414     unsigned char chroma_non_intra_quantiser_matrix[64];
 415 } VAIQMatrixBufferMPEG2;
 416
 417 /*
 418  * There will be cases where the bitstream buffer will not have enough room to hold
 419  * the data for the entire slice, and the following flags will be used in the slice
 420  * parameter to signal to the server for the possible cases.
 421  * If a slice parameter buffer and slice data buffer pair is sent to the server with
 422  * the slice data partially in the slice data buffer (BEGIN and MIDDLE cases below),
 423  * then a slice parameter and data buffer needs to be sent again to complete this slice.
 424  */
 425 #define VA_SLICE_DATA_FLAG_ALL          0x00    /* whole slice is in the buffer */
 426 #define VA_SLICE_DATA_FLAG_BEGIN        0x01    /* The beginning of the slice is in the buffer but the end if not */
 427 #define VA_SLICE_DATA_FLAG_MIDDLE       0x02    /* Neither beginning nor end of the slice is in the buffer */
 428 #define VA_SLICE_DATA_FLAG_END          0x04    /* end of the slice is in the buffer */
 429
 430 /* MPEG-2 Slice Parameter Buffer */
 431 typedef struct _VASliceParameterBufferMPEG2
 432 {
 433     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 434     unsigned int slice_data_offset;/* the offset to the first byte of slice data */
 435     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 436     unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
 437     unsigned int slice_vertical_position;
 438     int quantiser_scale_code;
 439     int intra_slice_flag;
 440 } VASliceParameterBufferMPEG2;
 441
 442 /* MPEG-2 Macroblock Parameter Buffer */
 443 typedef struct _VAMacroblockParameterBufferMPEG2
 444 {
 445     unsigned short macroblock_address;
 446     /*
 447      * macroblock_address (in raster scan order)
 448      * top-left: 0
 449      * bottom-right: picture-height-in-mb*picture-width-in-mb - 1
 450      */
 451     unsigned char macroblock_type;  /* see definition below */
 452     union {
 453         struct {
 454             unsigned char frame_motion_type             : 2;
 455             unsigned char field_motion_type             : 2;
 456             unsigned char dct_type                      : 1;
 457         };
 458         unsigned char macroblock_modes;
 459     };
 460     unsigned char motion_vertical_field_select;
 461     /*
 462      * motion_vertical_field_select:
 463      * see section 6.3.17.2 in the spec
 464      * only the lower 4 bits are used
 465      * bit 0: first vector forward
 466      * bit 1: first vector backward
 467      * bit 2: second vector forward
 468      * bit 3: second vector backward
 469      */
 470     short PMV[2][2][2]; /* see Table 7-7 in the spec */
 471     unsigned short coded_block_pattern;
 472     /*
 473      * The bitplanes for coded_block_pattern are described
 474      * in Figure 6.10-12 in the spec
 475      */
 476 } VAMacroblockParameterBufferMPEG2;
 477
 478 /*
 479  * OR'd flags for macroblock_type (section 6.3.17.1 in the spec)
 480  */
 481 #define VA_MB_TYPE_MOTION_FORWARD       0x02
 482 #define VA_MB_TYPE_MOTION_BACKWARD      0x04
 483 #define VA_MB_TYPE_MOTION_PATTERN       0x08
 484 #define VA_MB_TYPE_MOTION_INTRA         0x10
 485
 486 /*
 487  * MPEG-2 Residual Data Buffer
 488  * For each macroblock, there wil be 64 shorts (16-bit) in the
 489  * residual data buffer
 490  */
 491
 492 /****************************
 493  * MPEG-4 Part 2 data structures
 494  ****************************/
 495
 496 /* MPEG-4 Picture Parameter Buffer */
 497 typedef struct _VAPictureParameterBufferMPEG4
 498 {
 499     unsigned short vop_width;
 500     unsigned short vop_height;
 501     VASurfaceID forward_reference_picture;
 502     VASurfaceID backward_reference_picture;
 503     union {
 504         struct {
 505             unsigned char short_video_header            : 1;
 506             unsigned char chroma_format                 : 2;
 507             unsigned char interlaced                    : 1;
 508             unsigned char obmc_disable                  : 1;
 509             unsigned char sprite_enable                 : 2;
 510             unsigned char sprite_warping_accuracy       : 2;
 511             unsigned char quant_type                    : 1;
 512             unsigned char quarter_sample                : 1;
 513             unsigned char data_partitioned              : 1;
 514             unsigned char reversible_vlc                : 1;
 515         };
 516         unsigned short vol_fields;
 517     };
 518     unsigned char no_of_sprite_warping_points;
 519     short sprite_trajectory_du[3];
 520     short sprite_trajectory_dv[3];
 521     unsigned char quant_precision;
 522     union {
 523         struct {
 524             unsigned char vop_coding_type               : 2;
 525             unsigned char backward_reference_vop_coding_type    : 2;
 526             unsigned char vop_rounding_type             : 1;
 527             unsigned char intra_dc_vlc_thr              : 3;
 528             unsigned char top_field_first               : 1;
 529             unsigned char alternate_vertical_scan_flag  : 1;
 530         };
 531         unsigned short vop_fields;
 532     };
 533     unsigned char vop_fcode_forward;
 534     unsigned char vop_fcode_backward;
 535     /* short header related */
 536     unsigned char num_gobs_in_vop;
 537     unsigned char num_macroblocks_in_gob;
 538     /* for direct mode prediction */
 539     short TRB;
 540     short TRD;
 541 } VAPictureParameterBufferMPEG4;
 542
 543 /* MPEG-4 Inverse Quantization Matrix Buffer */
 544 typedef struct _VAIQMatrixBufferMPEG4
 545 {
 546     int load_intra_quant_mat;
 547     int load_non_intra_quant_mat;
 548     unsigned char intra_quant_mat[64];
 549     unsigned char non_intra_quant_mat[64];
 550 } VAIQMatrixBufferMPEG4;
 551
 552 /* MPEG-4 Slice Parameter Buffer */
 553 typedef struct _VASliceParameterBufferMPEG4
 554 {
 555     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 556     unsigned int slice_data_offset;/* the offset to the first byte of slice data */
 557     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 558     unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
 559     unsigned int macroblock_number;
 560     int quant_scale;
 561 } VASliceParameterBufferMPEG4;
 562
 563 /*
 564  VC-1 data structures
 565 */
 566
 567 /* VC-1 Picture Parameter Buffer */
 568 typedef struct _VAPictureParameterBufferVC1
 569 {
 570     VASurfaceID forward_reference_picture;
 571     VASurfaceID backward_reference_picture;
 572     /* if out-of-loop post-processing is done on the render
 573        target, then we need to keep the in-loop decoded
 574        picture as a reference picture */
 575     VASurfaceID inloop_decoded_picture;
 576
 577     unsigned short coded_width;         /* ENTRY_POINT_LAYER::CODED_WIDTH */
 578     unsigned short coded_height;        /* ENTRY_POINT_LAYER::CODED_HEIGHT */
 579     unsigned char closed_entry;         /* ENTRY_POINT_LAYER::CLOSED_ENTRY */
 580     unsigned char broken_link;          /* ENTRY_POINT_LAYER::BROKEN_LINK */
 581     unsigned char conditional_overlap_flag; /* ENTRY_POINT_LAYER::CONDOVER */
 582     unsigned char fast_uvmc_flag;       /* ENTRY_POINT_LAYER::FASTUVMC */
 583     unsigned char b_picture_fraction;   /* PICTURE_LAYER::BFRACTION */
 584     unsigned char cbp_table;            /* PICTURE_LAYER::CBPTAB/ICBPTAB */
 585     unsigned char mb_mode_table;        /* PICTURE_LAYER::MBMODETAB */
 586     unsigned char range_reduction_frame;/* PICTURE_LAYER::RNDCTRL */
 587     unsigned char rounding_control;     /* PICTURE_LAYER::RNDCTRL */
 588     unsigned char post_processing;      /* PICTURE_LAYER::POSTPROC */
 589     unsigned char picture_resolution_index;     /* PICTURE_LAYER::RESPIC */
 590     unsigned char luma_scale;           /* PICTURE_LAYER::LUMSCALE */
 591     unsigned char luma_shift;           /* PICTURE_LAYER::LUMSHIFT */
 592     union {
 593         struct {
 594             unsigned char picture_type  : 2;    /* PICTURE_LAYER::PTYPE */
 595             unsigned char frame_coding_mode     : 3;/* PICTURE_LAYER::FCM */
 596             unsigned char top_field_first       : 1;/* PICTURE_LAYER::TFF */
 597         };
 598         unsigned char picture_fields;
 599     };
 600     union {
 601        struct {
 602             unsigned char mv_type_mb    : 1;    /* PICTURE::MVTYPEMB */
 603             unsigned char direct_mb     : 1;    /* PICTURE::DIRECTMB */
 604             unsigned char skip_mb       : 1;    /* PICTURE::SKIPMB */
 605             unsigned char field_tx      : 1;    /* PICTURE::FIELDTX */
 606             unsigned char foward_mb     : 1;    /* PICTURE::FORWARDMB */
 607             unsigned char ac_pred       : 1;    /* PICTURE::ACPRED */
 608             unsigned char overflags     : 1;    /* PICTURE::OVERFLAGS */
 609         };
 610         unsigned char raw_coding_flag;
 611     };
 612     union {
 613         struct {
 614             unsigned char reference_distance_flag : 1;/* PICTURE_LAYER::REFDIST_FLAG */
 615             unsigned char reference_distance    : 1;/* PICTURE_LAYER::REFDIST */
 616             unsigned char num_reference_pictures: 1;/* PICTURE_LAYER::NUMREF */
 617             unsigned char reference_field_pic_indicator : 1;/* PICTURE_LAYER::REFFIELD */
 618         };
 619         unsigned short reference_fields;
 620     };
 621     union {
 622         struct {
 623             unsigned char mv_mode       : 2;    /* PICTURE_LAYER::MVMODE */
 624             unsigned char mv_mode2      : 2;    /* PICTURE_LAYER::MVMODE2 */
 625             unsigned char mv_table      : 3;/* PICTURE_LAYER::MVTAB/IMVTAB */
 626             unsigned char two_mv_block_pattern_table: 2;/* PICTURE_LAYER::2MVBPTAB */
 627             unsigned char four_mv_switch: 1;    /* PICTURE_LAYER::4MVSWITCH */
 628             unsigned char four_mv_block_pattern_table : 2;/* PICTURE_LAYER::4MVBPTAB */
 629             unsigned char extended_mv_flag: 1;/* ENTRY_POINT_LAYER::EXTENDED_MV */
 630             unsigned char extended_mv_range : 2;/* PICTURE_LAYER::MVRANGE */
 631             unsigned char extended_dmv_flag : 1;/* ENTRY_POINT_LAYER::EXTENDED_DMV */
 632             unsigned char extended_dmv_range : 2;/* PICTURE_LAYER::DMVRANGE */
 633         };
 634         unsigned int mv_fields;
 635     };
 636     union {
 637         struct {
 638             unsigned char dquant        : 2;    /* ENTRY_POINT_LAYER::DQUANT */
 639             unsigned char half_qp       : 1;    /* PICTURE_LAYER::HALFQP */
 640             unsigned char pic_quantizer_scale : 1;/* PICTURE_LAYER::PQUANT */
 641             unsigned char pic_quantizer_type : 1;/* PICTURE_LAYER::PQUANTIZER */
 642             unsigned char dq_frame      : 1;    /* VOPDQUANT::DQUANTFRM */
 643             unsigned char dq_profile    : 1;    /* VOPDQUANT::DQPROFILE */
 644             unsigned char dq_binary_level : 1;  /* VOPDQUANT::DQBILEVEL */
 645             unsigned char alt_pic_quantizer : 5;/* VOPDQUANT::ALTPQUANT */
 646         };
 647         unsigned short pic_quantizer_fields;
 648     };
 649     union {
 650         struct {
 651             unsigned char variable_sized_transform_flag : 1;/* ENTRY_POINT_LAYER::VSTRANSFORM */
 652             unsigned char mb_level_transform_type_flag  : 1;/* PICTURE_LAYER::TTMBF */
 653             unsigned char frame_level_transform_type    : 2;/* PICTURE_LAYER::TTFRM */
 654             unsigned char transform_ac_codingset_idx1   : 2;/* PICTURE_LAYER::TRANSACFRM */
 655             unsigned char transform_ac_codingset_idx2   : 2;/* PICTURE_LAYER::TRANSACFRM2 */
 656             unsigned char intra_transform_dc_table      : 1;/* PICTURE_LAYER::TRANSDCTAB */
 657         };
 658         unsigned short transform_fields;
 659     };
 660 } VAPictureParameterBufferVC1;
 661
 662 /* VC-1 Bitplane Buffer
 663 There will be at most three bitplanes coded in any picture header. To send
 664 the bitplane data more efficiently, each byte is divided in two nibbles, with
 665 each nibble carrying three bitplanes for one macroblock.  The following table
 666 shows the bitplane data arrangement within each nibble based on the picture
 667 type.
 668
 669 Picture Type    Bit3            Bit2            Bit1            Bit0
 670 I or BI                         OVERFLAGS       ACPRED          FIELDTX
 671 P                               MYTYPEMB        SKIPMB          DIRECTMB
 672 B                               FORWARDMB       SKIPMB          DIRECTMB
 673
 674 Within each byte, the lower nibble is for the first MB and the upper nibble is
 675 for the second MB.  E.g. the lower nibble of the first byte in the bitplane
 676 buffer is for Macroblock #1 and the upper nibble of the first byte is for
 677 Macroblock #2 in the first row.
 678 */
 679
 680 /* VC-1 Slice Parameter Buffer */
 681 typedef struct _VASliceParameterBufferVC1
 682 {
 683     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 684     unsigned int slice_data_offset;/* the offset to the first byte of slice data */
 685     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 686     unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
 687     unsigned int slice_vertical_position;
 688 } VASliceParameterBufferVC1;
 689
 690 /* VC-1 Slice Data Buffer */
 691 /*
 692 This is simplely a buffer containing raw bit-stream bytes
 693 */
 694
 695 /****************************
 696  * H.264/AVC data structures
 697  ****************************/
 698
 699 typedef struct _VAPictureH264
 700 {
 701     VASurfaceID picture_id;
 702     unsigned int flags;
 703     unsigned int TopFieldOrderCnt;
 704     unsigned int BottomFieldOrderCnt;
 705 } VAPictureH264;
 706 /* flags in VAPictureH264 could be OR of the following */
 707 #define VA_PICTURE_H264_INVALID                 0x00000001
 708 #define VA_PICTURE_H264_TOP_FIELD               0x00000002
 709 #define VA_PICTURE_H264_BOTTOM_FIELD            0x00000004
 710 #define VA_PICTURE_H264_SHORT_TERM_REFERENCE    0x00000008
 711 #define VA_PICTURE_H264_LONG_TERM_REFERENCE     0x00000010
 712 #define VA_PICTURE_H264_USED_AS_REFERENCE       0x00000020
 713
 714 /* H.264 Picture Parameter Buffer */
 715 typedef struct _VAPictureParameterBufferH264
 716 {
 717     VAPictureH264 CurrPic;
 718     VAPictureH264 ReferenceFrames[16];  /* in DPB */
 719     unsigned short picture_width_in_mbs_minus1;
 720     unsigned short picture_height_in_mbs_minus1;
 721     unsigned char bit_depth_luma_minus8;
 722     unsigned char bit_depth_chroma_minus8;
 723     unsigned char num_ref_frames;
 724     union {
 725         struct {
 726             unsigned char chroma_format_idc                     : 2;
 727             unsigned char residual_colour_transform_flag        : 1;
 728             unsigned char frame_mbs_only_flag                   : 1;
 729             unsigned char mb_adaptive_frame_field_flag          : 1;
 730             unsigned char direct_8x8_inference_flag             : 1;
 731         };
 732         unsigned char seq_fields;
 733     };
 734     unsigned char num_slice_groups_minus1;
 735     unsigned char slice_group_map_type;
 736     unsigned char pic_init_qp_minus26;
 737     unsigned char chroma_qp_index_offset;
 738     unsigned char second_chroma_qp_index_offset;
 739     union {
 740         struct {
 741             unsigned char entropy_coding_mode_flag      : 1;
 742             unsigned char weighted_pred_flag            : 1;
 743             unsigned char weighted_bipred_idc           : 1;
 744             unsigned char transform_8x8_mode_flag       : 1;
 745             unsigned char field_pic_flag                : 1;
 746         };
 747         unsigned char pic_fields;
 748     };
 749     unsigned short frame_num;
 750 } VAPictureParameterBufferH264;
 751
 752 /* H.264 Inverse Quantization Matrix Buffer */
 753 typedef struct _VAIQMatrixBufferH264
 754 {
 755     unsigned char ScalingList4x4[6][16];
 756     unsigned char ScalingList8x8[2][64];
 757 } VAIQMatrixBufferH264;
 758
 759 /*
 760  * H.264 Slice Group Map Buffer
 761  * When VAPictureParameterBufferH264::num_slice_group_minus1 is not equal to 0,
 762  * A slice group map buffer should be sent for each picture if required. The buffer
 763  * is sent only when there is a change in the mapping values.
 764  * The slice group map buffer map "map units" to slice groups as specified in
 765  * section 8.2.2 of the H.264 spec. The buffer will contain one byte for each macroblock
 766  * in raster scan order
 767  */
 768
 769 /* H.264 Slice Parameter Buffer */
 770 typedef struct _VASliceParameterBufferH264
 771 {
 772     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 773     unsigned int slice_data_offset;/* the offset to first byte of slice data */
 774     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 775     unsigned short slice_data_bit_offset; /* bit offset in the first byte of valid data */
 776     unsigned short first_mb_in_slice;
 777     unsigned char slice_type;
 778     unsigned char direct_spatial_mv_pred_flag;
 779     unsigned char num_ref_idx_10_active_minus1;
 780     unsigned char num_ref_idx_11_active_minus1;
 781     unsigned char cabac_init_idc;
 782     char slice_qp_delta;
 783     unsigned char disable_deblocking_filter_idc;
 784     char slice_alpha_c0_offset_div2;
 785     char slice_beta_offset_div2;
 786     VAPictureH264 RefPicList0[32];      /* See 8.2.4.2 */
 787     VAPictureH264 RefPicList1[32];      /* See 8.2.4.2 */
 788     unsigned char luma_log2_weight_denom;
 789     unsigned char chroma_log2_weight_denom;
 790 } VASliceParameterBufferH264;
 791
 792 /* Buffer functions */
 793
 794 /*
 795  * Creates a buffer for storing a certain type of data, no data store allocated
 796  */
 797 VAStatus vaCreateBuffer (
 798     VADisplay dpy,
 799     VABufferType type,  /* in */
 800     VABufferID *buf_id  /* out */
 801 );
 802
 803 /*
 804  * Create data store for the buffer and initalize with "data".
 805  * if "data" is null, then the contents of the buffer data store
 806  * are undefined.
 807  * Basically there are two ways to get buffer data to the server side. One is
 808  * to call vaBufferData() with a non-null "data", which results the data being
 809  * copied to the data store on the server side.  A different method that
 810  * eliminates this copy is to pass null as "data" when calling vaBufferData(),
 811  * and then use vaMapBuffer() to map the data store from the server side to the
 812  * client address space for access.
 813  */
 814 VAStatus vaBufferData (
 815     VADisplay dpy,
 816     VABufferID buf_id,  /* in */
 817     unsigned int size,  /* in */
 818     unsigned int num_elements, /* in */
 819     void *data          /* in */
 820 );
 821
 822 /*
 823  * Convey to the server how many valid elements are in the buffer.
 824  * e.g. if multiple slice parameters are being held in a single buffer,
 825  * this will communicate to the server the number of slice parameters
 826  * that are valid in the buffer.
 827  */
 828 VAStatus vaBufferSetNumElements (
 829     VADisplay dpy,
 830     VABufferID buf_id,  /* in */
 831     unsigned int num_elements /* in */
 832 );
 833
 834 /*
 835  * Map data store of the buffer into the client's address space
 836  * vaBufferData() needs to be called with "data" set to NULL before
 837  * calling vaMapBuffer()
 838  */
 839 VAStatus vaMapBuffer (
 840     VADisplay dpy,
 841     VABufferID buf_id,  /* in */
 842     void **pbuf         /* out */
 843 );
 844
 845 /*
 846  * After client making changes to a mapped data store, it needs to
 847  * "Unmap" it to let the server know that the data is ready to be
 848  * consumed by the server
 849  */
 850 VAStatus vaUnmapBuffer (
 851     VADisplay dpy,
 852     VABufferID buf_id   /* in */
 853 );
 854
 855 /*
 856  * After this call, the buffer is deleted and this buffer_id is no longer valid
 857  */
 858 VAStatus vaDestroyBuffer (
 859     VADisplay dpy,
 860     VABufferID buffer_id
 861 );
 862
 863 /*
 864 Render (Decode) Pictures
 865
 866 A picture represents either a frame or a field.
 867
 868 The Begin/Render/End sequence sends the decode buffers to the server
 869 */
 870
 871 /*
 872  * Get ready to decode a picture to a target surface
 873  */
 874 VAStatus vaBeginPicture (
 875     VADisplay dpy,
 876     VAContext *context,
 877     VASurface *render_target
 878 );
 879
 880 /*
 881  * Send decode buffers to the server.
 882  */
 883 VAStatus vaRenderPicture (
 884     VADisplay dpy,
 885     VAContext *context,
 886     VABufferID *buffers,
 887     int num_buffers
 888 );
 889
 890 /*
 891  * Make the end of rendering for a picture.
 892  * The server should start processing all pending operations for this
 893  * surface. This call is non-blocking. The client can start another
 894  * Begin/Render/End sequence on a different render target.
 895  */
 896 VAStatus vaEndPicture (
 897     VADisplay dpy,
 898     VAContext *context
 899 );
 900
 901 /*
 902
 903 Synchronization
 904
 905 */
 906
 907 /*
 908  * This function blocks until all pending operations on the render target
 909  * have been completed.  Upon return it is safe to use the render target for a
 910  * different picture.
 911  */
 912 VAStatus vaSyncSurface (
 913     VADisplay dpy,
 914     VAContext *context,
 915     VASurface *render_target
 916 );
 917
 918 typedef enum
 919 {
 920     VASurfaceRendering  = 0,
 921     VASurfaceReady      = 1,
 922 } VASurfaceStatus;
 923
 924 /*
 925  * Find out any pending ops on the render target
 926  */
 927 VAStatus vaQuerySurfaceStatus (
 928     VADisplay dpy,
 929     VAContext *context,
 930     VASurface *render_target,
 931     VASurfaceStatus *status     /* out */
 932 );
 933
 934 /*
 935  * Copies the surface to a buffer
 936  * The stride of the surface will be stored in *stride
 937  * Caller should free the returned buffer with free() when done.
 938  */
 939 VAStatus vaDbgCopySurfaceToBuffer(VADisplay dpy,
 940     VASurface *surface,
 941     void **buffer, /* out */
 942     unsigned int *stride /* out */
 943 );
 944
 945 #ifdef __cplusplus
 946 }
 947 #endif
 948
 949 #endif /* _VA_H_ */
 950
 951 #if 0
 952 /*****************************************************************************/
 953
 954 Sample Program (w/ pseudo code)
 955
 956 Mostly to demonstrate program flow with no error handling ...
 957
 958 /*****************************************************************************/
 959
 960         /* MPEG-2 VLD decode for a 720x480 frame */
 961
 962         int major_ver, minor_ver;
 963         vaInitialize(dpy, &major_ver, &minor_ver);
 964
 965         int max_num_profiles, max_num_entrypoints, max_num_attribs;
 966         max_num_profiles = vaMaxNumProfiles(dpy);
 967         max_num_entrypoints = vaMaxNumProfiles(dpy);
 968         max_num_attribs = vaMaxNumProfiles(dpy);
 969
 970         /* find out whether MPEG2 MP is supported */
 971         VAProfile *profiles = malloc(sizeof(VAProfile)*max_num_profiles);
 972         int num_profiles;
 973         vaQueryConfigProfiles(dpy, profiles, &profiles);
 974         /*
 975          * traverse "profiles" to locate the one that matches VAProfileMPEG2Main
 976          */
 977
 978         /* now get the available entrypoints for MPEG2 MP */
 979         VAEntrypoint *entrypoints = malloc(sizeof(VAEntrypoint)*max_num_entrypoints);
 980         int num_entrypoints;
 981         vaQueryConfigEntrypoints(dpy, VAProfileMPEG2Main, entrypoints, &num_entrypoints);
 982
 983         /* traverse "entrypoints" to see whether VLD is there */
 984
 985         /* Assuming finding VLD, find out the format for the render target */
 986         VAConfigAttrib attrib;
 987         attrib.type = VAConfigAttribRTFormat;
 988         vaQueryConfigAttributes(dpy, VAProfileMPEG2Main, VAEntrypointVLD,
 989                                 &attrib, 1);
 990
 991         if (attrib.value & VA_RT_FORMAT_YUV420)
 992                 /* Found desired RT format, keep going */
 993
 994         VAConfigID config_id;
 995         vaCreateConfig(dpy, VAProfileMPEG2Main, VAEntrypointVLD, &attrib, 1,
 996                        &config_id);
 997
 998         /*
 999          * create surfaces for the current target as well as reference frames
1000          * we can get by with 4 surfaces for MPEG-2
1001          */
1002         VASurface surfaces[4];
1003         vaCreateSurfaces(dpy, 720, 480, VA_RT_FORMAT_YUV420, 4, surfaces);
1004
1005         /*
1006          * Create a context for this decode pipe
1007          */
1008         VAContext context;
1009         vaCreateContext(dpy, config_id, 720, 480, VA_PROGRESSIVE, surfaces,
1010                         4, &context);
1011
1012         /* Create a picture parameter buffer for this frame */
1013         VABufferID picture_buf;
1014         VAPictureParameterBufferMPEG2 *picture_param;
1015         vaCreateBuffer(dpy, VAPictureParameterBufferType, &picture_buf);
1016         vaBufferData(dpy, picture_buf, sizeof(VAPictureParameterBufferMPEG2), NULL);
1017         vaMapBuffer(dpy, picture_buf, &picture_param);
1018         picture_param->horizontal_size = 720;
1019         picture_param->vertical_size = 480;
1020         picture_param->picture_coding_type = 1; /* I-frame */
1021         /* fill in picture_coding_extension fields here */
1022         vaUnmapBuffer(dpy, picture_buf);
1023
1024
1025         /* Create an IQ matrix buffer for this frame */
1026         VABufferID iq_buf;
1027         VAIQMatrixBufferMPEG2 *iq_matrix;
1028         vaCreateBuffer(dpy, VAIQMatrixBufferType, &iq_buf);
1029         vaBufferData(dpy, iq_buf, sizeof(VAIQMatrixBufferMPEG2), NULL);
1030         vaMapBuffer(dpy, iq_buf, &iq_matrix);
1031         /* fill values for IQ_matrix here */
1032         vaUnmapBuffer(dpy, iq_buf);
1033
1034         /* send the picture and IQ matrix buffers to the server */
1035         vaBeginPicture(dpy, context, &surfaces[0]);
1036
1037         vaRenderPicture(dpy, context, &picture_buf, 1);
1038         vaRenderPicture(dpy, context, &iq_buf, 1);
1039
1040         /*
1041          * Send slices in this frame to the server.
1042          * For MPEG-2, each slice is one row of macroblocks, and
1043          * we have 30 slices for a 720x480 frame
1044          */
1045         for (int i = 1; i <= 30; i++) {
1046
1047                 /* Create a slice parameter buffer */
1048                 VABufferID slice_param_buf;
1049                 VASliceParameterBufferMPEG2 *slice_param;
1050                 vaCreateBuffer(dpy, VASliceParameterBufferType, &slice_param_buf);
1051                 vaBufferData(dpy, slice_param_buf, sizeof(VASliceParameterBufferMPEG2), NULL);
1052                 vaMapBuffer(dpy, slice_param_buf, &slice_param);
1053                 slice_param->slice_data_offset = 0;
1054                 /* Let's say all slices in this bit-stream has 64-bit header */
1055                 slice_param->macroblock_offset = 64;
1056                 slice_param->vertical_position = i;
1057                 /* set up the rest based on what is in the slice header ... */
1058                 vaUnmapBuffer(dpy, slice_param_buf);
1059
1060                 /* send the slice parameter buffer */
1061                 vaRenderPicture(dpy, context, &slice_param_buf, 1);
1062
1063                 /* Create a slice data buffer */
1064                 unsigned char *slice_data;
1065                 VABufferID slice_data_buf;
1066                 vaCreateBuffer(dpy, VASliceDataBufferType, slice_data_buf);
1067                 vaBufferData(dpy, slice_data_buf, x /* decoder figure out how big */, NULL);
1068                 vaMapBuffer(dpy, slice_data_buf, &slice_data);
1069                 /* decoder fill in slice_data */
1070                 vaUnmapBuffer(dpy, slice_data_buf);
1071
1072                 /* send the slice data buffer */
1073                 vaRenderPicture(dpy, context, &slice_data_buf, 1);
1074         }
1075
1076         /* all slices have been sent, mark the end for this frame */
1077         vaEndPicture(dpy, context);
1078 #endif