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 typedef struct _VAContext
 263 {
 264     VAContextID         context_id; /* to identify this context */
 265     VAConfigID          config_id;
 266     unsigned short      picture_width;
 267     unsigned short      picture_height;
 268     VASurfaceID         *render_targets;
 269     int                 num_render_targets;
 270     int                 flags;
 271     void                *privData;
 272 } VAContext;
 273
 274 /*
 275     flags - Any combination of the following:
 276       VA_PROGRESSIVE (only progressive frame pictures in the sequence when set)
 277 */
 278 #define VA_PROGRESSIVE  0x1
 279
 280 /*
 281
 282 Surface Management
 283
 284 Surfaces are render targets for a given context. The data in the surfaces
 285 are not accessible to the client and the internal data format of
 286 the surface is implementatin specific.
 287
 288 Question: Is there a need to know the data format (fourcc) or just
 289 differentiate between 420/422/444 is sufficient?
 290
 291 */
 292
 293 typedef struct _VASurface
 294 {
 295     VASurfaceID         surface_id; /* uniquely identify this surface */
 296     VAContextID         context_id; /* which context does this surface belong */
 297     unsigned short      width;
 298     unsigned short      height;
 299     int                 format; /* 420/422/444 */
 300     void                *privData; /* private to the library */
 301 } VASurface;
 302
 303 /*
 304  * Surfaces will be bound to a context when the context is created. Once
 305  * a surface is bound to a given context, it can not be used to create
 306  * another context. The association is removed when the context is destroyed
 307  */
 308
 309 /* Surface Functions */
 310 VAStatus vaCreateSurfaces (
 311     VADisplay dpy,
 312     int width,
 313     int height,
 314     int format,
 315     int num_surfaces,
 316     VASurface *surfaces /* out */
 317 );
 318
 319 /*
 320  * surfaces can only be destroyed after the context associated has been
 321  * destroyed
 322  */
 323 VAStatus vaDestroySurface (
 324     VADisplay dpy,
 325     VASurface *surface_list,
 326     int num_surfaces
 327 );
 328
 329 VAStatus vaCreateContext (
 330     VADisplay dpy,
 331     VAConfigID config_id,
 332     int picture_width,
 333     int picture_height,
 334     int flag,
 335     VASurface *render_targets,
 336     int num_render_targets,
 337     VAContext *context          /* out */
 338 );
 339
 340 VAStatus vaDestroyContext (
 341     VADisplay dpy,
 342     VAContext *context
 343 );
 344
 345 /*
 346  *
 347  *      Buffers
 348  *      Buffers are used to pass various types of data from the
 349  *      client to the server. The server maintains a data store
 350  *      for each buffer created, and the client idenfies a buffer
 351  *      through a unique buffer id assigned by the server.
 352  *
 353  */
 354
 355 typedef int VABufferID;
 356
 357 typedef enum
 358 {
 359     VAPictureParameterBufferType        = 0,
 360     VAPictureBitPlaneBufferType         = 1,
 361     VAIQMatrixBufferType                = 2,
 362     VABitPlaneBufferType                = 3,
 363     VASliceGroupMapBufferType           = 4,
 364     VASliceParameterBufferType          = 5,
 365     VASliceDataBufferType               = 6,
 366     VAMacroblockParameterBufferType     = 7,
 367     VAResidualDataBufferType            = 8,
 368     VADeblockingParameterBufferType     = 9,
 369 } VABufferType;
 370
 371 /****************************
 372  * MPEG-2 data structures
 373  ****************************/
 374
 375 /* MPEG-2 Picture Parameter Buffer */
 376 typedef struct _VAPictureParameterBufferMPEG2
 377 {
 378     unsigned short horizontal_size;
 379     unsigned short vertical_size;
 380     VASurfaceID forward_reference_picture;
 381     VASurfaceID backward_reference_picture;
 382     /* meanings of the following fields are the same as in the standard */
 383     int picture_coding_type;
 384     int f_code; /* pack all four fcode into this */
 385     union {
 386         struct {
 387             unsigned char intra_dc_precision            : 2;
 388             unsigned char picture_structure             : 2;
 389             unsigned char top_field_first               : 1;
 390             unsigned char frame_pred_frame_dct          : 1;
 391             unsigned char concealment_motion_vectors    : 1;
 392             unsigned char q_scale_type                  : 1;
 393             unsigned char intra_vlc_format              : 1;
 394             unsigned char alternate_scan                : 1;
 395             unsigned char repeat_first_field            : 1;
 396             unsigned char progressive_frame             : 1;
 397         };
 398         unsigned int picture_coding_extension;
 399     };
 400 } VAPictureParameterBufferMPEG2;
 401
 402 /* MPEG-2 Inverse Quantization Matrix Buffer */
 403 typedef struct _VAIQMatrixBufferMPEG2
 404 {
 405     int load_intra_quantiser_matrix;
 406     int load_non_intra_quantiser_matrix;
 407     int load_chroma_intra_quantiser_matrix;
 408     int load_chroma_non_intra_quantiser_matrix;
 409     unsigned char intra_quantiser_matrix[64];
 410     unsigned char non_intra_quantiser_matrix[64];
 411     unsigned char chroma_intra_quantiser_matrix[64];
 412     unsigned char chroma_non_intra_quantiser_matrix[64];
 413 } VAIQMatrixBufferMPEG2;
 414
 415 /*
 416  * There will be cases where the bitstream buffer will not have enough room to hold
 417  * the data for the entire slice, and the following flags will be used in the slice
 418  * parameter to signal to the server for the possible cases.
 419  * If a slice parameter buffer and slice data buffer pair is sent to the server with
 420  * the slice data partially in the slice data buffer (BEGIN and MIDDLE cases below),
 421  * then a slice parameter and data buffer needs to be sent again to complete this slice.
 422  */
 423 #define VA_SLICE_DATA_FLAG_ALL          0x00    /* whole slice is in the buffer */
 424 #define VA_SLICE_DATA_FLAG_BEGIN        0x01    /* The beginning of the slice is in the buffer but the end if not */
 425 #define VA_SLICE_DATA_FLAG_MIDDLE       0x02    /* Neither beginning nor end of the slice is in the buffer */
 426 #define VA_SLICE_DATA_FLAG_END          0x04    /* end of the slice is in the buffer */
 427
 428 /* MPEG-2 Slice Parameter Buffer */
 429 typedef struct _VASliceParameterBufferMPEG2
 430 {
 431     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 432     unsigned int slice_data_offset;/* the offset to the first byte of slice data */
 433     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 434     unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
 435     unsigned int slice_vertical_position;
 436     int quantiser_scale_code;
 437     int intra_slice_flag;
 438 } VASliceParameterBufferMPEG2;
 439
 440 /* MPEG-2 Macroblock Parameter Buffer */
 441 typedef struct _VAMacroblockParameterBufferMPEG2
 442 {
 443     unsigned short macroblock_address;
 444     /*
 445      * macroblock_address (in raster scan order)
 446      * top-left: 0
 447      * bottom-right: picture-height-in-mb*picture-width-in-mb - 1
 448      */
 449     unsigned char macroblock_type;  /* see definition below */
 450     union {
 451         struct {
 452             unsigned char frame_motion_type             : 2;
 453             unsigned char field_motion_type             : 2;
 454             unsigned char dct_type                      : 1;
 455         };
 456         unsigned char macroblock_modes;
 457     };
 458     unsigned char motion_vertical_field_select;
 459     /*
 460      * motion_vertical_field_select:
 461      * see section 6.3.17.2 in the spec
 462      * only the lower 4 bits are used
 463      * bit 0: first vector forward
 464      * bit 1: first vector backward
 465      * bit 2: second vector forward
 466      * bit 3: second vector backward
 467      */
 468     short PMV[2][2][2]; /* see Table 7-7 in the spec */
 469     unsigned short coded_block_pattern;
 470     /*
 471      * The bitplanes for coded_block_pattern are described
 472      * in Figure 6.10-12 in the spec
 473      */
 474 } VAMacroblockParameterBufferMPEG2;
 475
 476 /*
 477  * OR'd flags for macroblock_type (section 6.3.17.1 in the spec)
 478  */
 479 #define VA_MB_TYPE_MOTION_FORWARD       0x02
 480 #define VA_MB_TYPE_MOTION_BACKWARD      0x04
 481 #define VA_MB_TYPE_MOTION_PATTERN       0x08
 482 #define VA_MB_TYPE_MOTION_INTRA         0x10
 483
 484 /*
 485  * MPEG-2 Residual Data Buffer
 486  * For each macroblock, there wil be 64 shorts (16-bit) in the
 487  * residual data buffer
 488  */
 489
 490 /****************************
 491  * MPEG-4 Part 2 data structures
 492  ****************************/
 493
 494 /* MPEG-4 Picture Parameter Buffer */
 495 typedef struct _VAPictureParameterBufferMPEG4
 496 {
 497     unsigned short vop_width;
 498     unsigned short vop_height;
 499     VASurfaceID forward_reference_picture;
 500     VASurfaceID backward_reference_picture;
 501     union {
 502         struct {
 503             unsigned char short_video_header            : 1;
 504             unsigned char chroma_format                 : 2;
 505             unsigned char interlaced                    : 1;
 506             unsigned char obmc_disable                  : 1;
 507             unsigned char sprite_enable                 : 2;
 508             unsigned char sprite_warping_accuracy       : 2;
 509             unsigned char quant_type                    : 1;
 510             unsigned char quarter_sample                : 1;
 511             unsigned char data_partitioned              : 1;
 512             unsigned char reversible_vlc                : 1;
 513         };
 514         unsigned short vol_fields;
 515     };
 516     unsigned char no_of_sprite_warping_points;
 517     short sprite_trajectory_du[3];
 518     short sprite_trajectory_dv[3];
 519     unsigned char quant_precision;
 520     union {
 521         struct {
 522             unsigned char vop_coding_type               : 2;
 523             unsigned char backward_reference_vop_coding_type    : 2;
 524             unsigned char vop_rounding_type             : 1;
 525             unsigned char intra_dc_vlc_thr              : 3;
 526             unsigned char top_field_first               : 1;
 527             unsigned char alternate_vertical_scan_flag  : 1;
 528         };
 529         unsigned short vop_fields;
 530     };
 531     unsigned char vop_fcode_forward;
 532     unsigned char vop_fcode_backward;
 533     /* short header related */
 534     unsigned char num_gobs_in_vop;
 535     unsigned char num_macroblocks_in_gob;
 536     /* for direct mode prediction */
 537     short TRB;
 538     short TRD;
 539 } VAPictureParameterBufferMPEG4;
 540
 541 /* MPEG-4 Inverse Quantization Matrix Buffer */
 542 typedef struct _VAIQMatrixBufferMPEG4
 543 {
 544     int load_intra_quant_mat;
 545     int load_non_intra_quant_mat;
 546     unsigned char intra_quant_mat[64];
 547     unsigned char non_intra_quant_mat[64];
 548 } VAIQMatrixBufferMPEG4;
 549
 550 /* MPEG-4 Slice Parameter Buffer */
 551 typedef struct _VASliceParameterBufferMPEG4
 552 {
 553     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 554     unsigned int slice_data_offset;/* the offset to the first byte of slice data */
 555     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 556     unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
 557     unsigned int macroblock_number;
 558     int quant_scale;
 559 } VASliceParameterBufferMPEG4;
 560
 561 /*
 562  VC-1 data structures
 563 */
 564
 565 /* VC-1 Picture Parameter Buffer */
 566 typedef struct _VAPictureParameterBufferVC1
 567 {
 568     VASurfaceID forward_reference_picture;
 569     VASurfaceID backward_reference_picture;
 570     /* if out-of-loop post-processing is done on the render
 571        target, then we need to keep the in-loop decoded
 572        picture as a reference picture */
 573     VASurfaceID inloop_decoded_picture;
 574
 575     unsigned short coded_width;         /* ENTRY_POINT_LAYER::CODED_WIDTH */
 576     unsigned short coded_height;        /* ENTRY_POINT_LAYER::CODED_HEIGHT */
 577     unsigned char closed_entry;         /* ENTRY_POINT_LAYER::CLOSED_ENTRY */
 578     unsigned char broken_link;          /* ENTRY_POINT_LAYER::BROKEN_LINK */
 579     unsigned char conditional_overlap_flag; /* ENTRY_POINT_LAYER::CONDOVER */
 580     unsigned char fast_uvmc_flag;       /* ENTRY_POINT_LAYER::FASTUVMC */
 581     unsigned char b_picture_fraction;   /* PICTURE_LAYER::BFRACTION */
 582     unsigned char cbp_table;            /* PICTURE_LAYER::CBPTAB/ICBPTAB */
 583     unsigned char mb_mode_table;        /* PICTURE_LAYER::MBMODETAB */
 584     unsigned char range_reduction_frame;/* PICTURE_LAYER::RNDCTRL */
 585     unsigned char rounding_control;     /* PICTURE_LAYER::RNDCTRL */
 586     unsigned char post_processing;      /* PICTURE_LAYER::POSTPROC */
 587     unsigned char picture_resolution_index;     /* PICTURE_LAYER::RESPIC */
 588     unsigned char luma_scale;           /* PICTURE_LAYER::LUMSCALE */
 589     unsigned char luma_shift;           /* PICTURE_LAYER::LUMSHIFT */
 590     union {
 591         struct {
 592             unsigned char picture_type  : 2;    /* PICTURE_LAYER::PTYPE */
 593             unsigned char frame_coding_mode     : 3;/* PICTURE_LAYER::FCM */
 594             unsigned char top_field_first       : 1;/* PICTURE_LAYER::TFF */
 595         };
 596         unsigned char picture_fields;
 597     };
 598     union {
 599        struct {
 600             unsigned char mv_type_mb    : 1;    /* PICTURE::MVTYPEMB */
 601             unsigned char direct_mb     : 1;    /* PICTURE::DIRECTMB */
 602             unsigned char skip_mb       : 1;    /* PICTURE::SKIPMB */
 603             unsigned char field_tx      : 1;    /* PICTURE::FIELDTX */
 604             unsigned char foward_mb     : 1;    /* PICTURE::FORWARDMB */
 605             unsigned char ac_pred       : 1;    /* PICTURE::ACPRED */
 606             unsigned char overflags     : 1;    /* PICTURE::OVERFLAGS */
 607         };
 608         unsigned char raw_coding_flag;
 609     };
 610     union {
 611         struct {
 612             unsigned char reference_distance_flag : 1;/* PICTURE_LAYER::REFDIST_FLAG */
 613             unsigned char reference_distance    : 1;/* PICTURE_LAYER::REFDIST */
 614             unsigned char num_reference_pictures: 1;/* PICTURE_LAYER::NUMREF */
 615             unsigned char reference_field_pic_indicator : 1;/* PICTURE_LAYER::REFFIELD */
 616         };
 617         unsigned short reference_fields;
 618     };
 619     union {
 620         struct {
 621             unsigned char mv_mode       : 2;    /* PICTURE_LAYER::MVMODE */
 622             unsigned char mv_mode2      : 2;    /* PICTURE_LAYER::MVMODE2 */
 623             unsigned char mv_table      : 3;/* PICTURE_LAYER::MVTAB/IMVTAB */
 624             unsigned char two_mv_block_pattern_table: 2;/* PICTURE_LAYER::2MVBPTAB */
 625             unsigned char four_mv_switch: 1;    /* PICTURE_LAYER::4MVSWITCH */
 626             unsigned char four_mv_block_pattern_table : 2;/* PICTURE_LAYER::4MVBPTAB */
 627             unsigned char extended_mv_flag: 1;/* ENTRY_POINT_LAYER::EXTENDED_MV */
 628             unsigned char extended_mv_range : 2;/* PICTURE_LAYER::MVRANGE */
 629             unsigned char extended_dmv_flag : 1;/* ENTRY_POINT_LAYER::EXTENDED_DMV */
 630             unsigned char extended_dmv_range : 2;/* PICTURE_LAYER::DMVRANGE */
 631         };
 632         unsigned int mv_fields;
 633     };
 634     union {
 635         struct {
 636             unsigned char dquant        : 2;    /* ENTRY_POINT_LAYER::DQUANT */
 637             unsigned char half_qp       : 1;    /* PICTURE_LAYER::HALFQP */
 638             unsigned char pic_quantizer_scale : 1;/* PICTURE_LAYER::PQUANT */
 639             unsigned char pic_quantizer_type : 1;/* PICTURE_LAYER::PQUANTIZER */
 640             unsigned char dq_frame      : 1;    /* VOPDQUANT::DQUANTFRM */
 641             unsigned char dq_profile    : 1;    /* VOPDQUANT::DQPROFILE */
 642             unsigned char dq_binary_level : 1;  /* VOPDQUANT::DQBILEVEL */
 643             unsigned char alt_pic_quantizer : 5;/* VOPDQUANT::ALTPQUANT */
 644         };
 645         unsigned short pic_quantizer_fields;
 646     };
 647     union {
 648         struct {
 649             unsigned char variable_sized_transform_flag : 1;/* ENTRY_POINT_LAYER::VSTRANSFORM */
 650             unsigned char mb_level_transform_type_flag  : 1;/* PICTURE_LAYER::TTMBF */
 651             unsigned char frame_level_transform_type    : 2;/* PICTURE_LAYER::TTFRM */
 652             unsigned char transform_ac_codingset_idx1   : 2;/* PICTURE_LAYER::TRANSACFRM */
 653             unsigned char transform_ac_codingset_idx2   : 2;/* PICTURE_LAYER::TRANSACFRM2 */
 654             unsigned char intra_transform_dc_table      : 1;/* PICTURE_LAYER::TRANSDCTAB */
 655         };
 656         unsigned short transform_fields;
 657     };
 658 } VAPictureParameterBufferVC1;
 659
 660 /* VC-1 Bitplane Buffer
 661 There will be at most three bitplanes coded in any picture header. To send
 662 the bitplane data more efficiently, each byte is divided in two nibbles, with
 663 each nibble carrying three bitplanes for one macroblock.  The following table
 664 shows the bitplane data arrangement within each nibble based on the picture
 665 type.
 666
 667 Picture Type    Bit3            Bit2            Bit1            Bit0
 668 I or BI                         OVERFLAGS       ACPRED          FIELDTX
 669 P                               MYTYPEMB        SKIPMB          DIRECTMB
 670 B                               FORWARDMB       SKIPMB          DIRECTMB
 671
 672 Within each byte, the lower nibble is for the first MB and the upper nibble is
 673 for the second MB.  E.g. the lower nibble of the first byte in the bitplane
 674 buffer is for Macroblock #1 and the upper nibble of the first byte is for
 675 Macroblock #2 in the first row.
 676 */
 677
 678 /* VC-1 Slice Parameter Buffer */
 679 typedef struct _VASliceParameterBufferVC1
 680 {
 681     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 682     unsigned int slice_data_offset;/* the offset to the first byte of slice data */
 683     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 684     unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
 685     unsigned int slice_vertical_position;
 686 } VASliceParameterBufferVC1;
 687
 688 /* VC-1 Slice Data Buffer */
 689 /*
 690 This is simplely a buffer containing raw bit-stream bytes
 691 */
 692
 693 /****************************
 694  * H.264/AVC data structures
 695  ****************************/
 696
 697 typedef struct _VAPictureH264
 698 {
 699     VASurfaceID picture_id;
 700     unsigned int flags;
 701     unsigned int TopFieldOrderCnt;
 702     unsigned int BottomFieldOrderCnt;
 703 } VAPictureH264;
 704 /* flags in VAPictureH264 could be OR of the following */
 705 #define VA_PICTURE_H264_INVALID                 0x00000001
 706 #define VA_PICTURE_H264_TOP_FIELD               0x00000002
 707 #define VA_PICTURE_H264_BOTTOM_FIELD            0x00000004
 708 #define VA_PICTURE_H264_SHORT_TERM_REFERENCE    0x00000008
 709 #define VA_PICTURE_H264_LONG_TERM_REFERENCE     0x00000010
 710 #define VA_PICTURE_H264_USED_AS_REFERENCE       0x00000020
 711
 712 /* H.264 Picture Parameter Buffer */
 713 typedef struct _VAPictureParameterBufferH264
 714 {
 715     VAPictureH264 CurrPic;
 716     VAPictureH264 ReferenceFrames[16];  /* in DPB */
 717     unsigned short picture_width_in_mbs_minus1;
 718     unsigned short picture_height_in_mbs_minus1;
 719     unsigned char bit_depth_luma_minus8;
 720     unsigned char bit_depth_chroma_minus8;
 721     unsigned char num_ref_frames;
 722     union {
 723         struct {
 724             unsigned char chroma_format_idc                     : 2;
 725             unsigned char residual_colour_transform_flag        : 1;
 726             unsigned char frame_mbs_only_flag                   : 1;
 727             unsigned char mb_adaptive_frame_field_flag          : 1;
 728             unsigned char direct_8x8_inference_flag             : 1;
 729         };
 730         unsigned char seq_fields;
 731     };
 732     unsigned char num_slice_groups_minus1;
 733     unsigned char slice_group_map_type;
 734     unsigned char pic_init_qp_minus26;
 735     unsigned char chroma_qp_index_offset;
 736     unsigned char second_chroma_qp_index_offset;
 737     union {
 738         struct {
 739             unsigned char entropy_coding_mode_flag      : 1;
 740             unsigned char weighted_pred_flag            : 1;
 741             unsigned char weighted_bipred_idc           : 1;
 742             unsigned char transform_8x8_mode_flag       : 1;
 743             unsigned char field_pic_flag                : 1;
 744         };
 745         unsigned char pic_fields;
 746     };
 747     unsigned short frame_num;
 748 } VAPictureParameterBufferH264;
 749
 750 /* H.264 Inverse Quantization Matrix Buffer */
 751 typedef struct _VAIQMatrixBufferH264
 752 {
 753     unsigned char ScalingList4x4[6][16];
 754     unsigned char ScalingList8x8[2][64];
 755 } VAIQMatrixBufferH264;
 756
 757 /*
 758  * H.264 Slice Group Map Buffer
 759  * When VAPictureParameterBufferH264::num_slice_group_minus1 is not equal to 0,
 760  * A slice group map buffer should be sent for each picture if required. The buffer
 761  * is sent only when there is a change in the mapping values.
 762  * The slice group map buffer map "map units" to slice groups as specified in
 763  * section 8.2.2 of the H.264 spec. The buffer will contain one byte for each macroblock
 764  * in raster scan order
 765  */
 766
 767 /* H.264 Slice Parameter Buffer */
 768 typedef struct _VASliceParameterBufferH264
 769 {
 770     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 771     unsigned int slice_data_offset;/* the offset to first byte of slice data */
 772     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 773     unsigned short slice_data_bit_offset; /* bit offset in the first byte of valid data */
 774     unsigned short first_mb_in_slice;
 775     unsigned char slice_type;
 776     unsigned char direct_spatial_mv_pred_flag;
 777     unsigned char num_ref_idx_10_active_minus1;
 778     unsigned char num_ref_idx_11_active_minus1;
 779     unsigned char cabac_init_idc;
 780     char slice_qp_delta;
 781     unsigned char disable_deblocking_filter_idc;
 782     char slice_alpha_c0_offset_div2;
 783     char slice_beta_offset_div2;
 784     VAPictureH264 RefPicList0[32];      /* See 8.2.4.2 */
 785     VAPictureH264 RefPicList1[32];      /* See 8.2.4.2 */
 786     unsigned char luma_log2_weight_denom;
 787     unsigned char chroma_log2_weight_denom;
 788 } VASliceParameterBufferH264;
 789
 790 /* Buffer functions */
 791
 792 /*
 793  * Creates a buffer for storing a certain type of data, no data store allocated
 794  */
 795 VAStatus vaCreateBuffer (
 796     VADisplay dpy,
 797     VABufferType type,  /* in */
 798     VABufferID *buf_id  /* out */
 799 );
 800
 801 /*
 802  * Create data store for the buffer and initalize with "data".
 803  * if "data" is null, then the contents of the buffer data store
 804  * are undefined.
 805  * Basically there are two ways to get buffer data to the server side. One is
 806  * to call vaBufferData() with a non-null "data", which results the data being
 807  * copied to the data store on the server side.  A different method that
 808  * eliminates this copy is to pass null as "data" when calling vaBufferData(),
 809  * and then use vaMapBuffer() to map the data store from the server side to the
 810  * client address space for access.
 811  */
 812 VAStatus vaBufferData (
 813     VADisplay dpy,
 814     VABufferID buf_id,  /* in */
 815     unsigned int size,  /* in */
 816     unsigned int num_elements, /* in */
 817     void *data          /* in */
 818 );
 819
 820 /*
 821  * Convey to the server how many valid elements are in the buffer.
 822  * e.g. if multiple slice parameters are being held in a single buffer,
 823  * this will communicate to the server the number of slice parameters
 824  * that are valid in the buffer.
 825  */
 826 VAStatus vaBufferSetNumElements (
 827     VADisplay dpy,
 828     VABufferID buf_id,  /* in */
 829     unsigned int num_elements /* in */
 830 );
 831
 832 /*
 833  * Map data store of the buffer into the client's address space
 834  * vaBufferData() needs to be called with "data" set to NULL before
 835  * calling vaMapBuffer()
 836  */
 837 VAStatus vaMapBuffer (
 838     VADisplay dpy,
 839     VABufferID buf_id,  /* in */
 840     void **pbuf         /* out */
 841 );
 842
 843 /*
 844  * After client making changes to a mapped data store, it needs to
 845  * "Unmap" it to let the server know that the data is ready to be
 846  * consumed by the server
 847  */
 848 VAStatus vaUnmapBuffer (
 849     VADisplay dpy,
 850     VABufferID buf_id   /* in */
 851 );
 852
 853 /*
 854  * After this call, the buffer is deleted and this buffer_id is no longer valid
 855  */
 856 VAStatus vaDestroyBuffer (
 857     VADisplay dpy,
 858     VABufferID buffer_id
 859 );
 860
 861 /*
 862 Render (Decode) Pictures
 863
 864 A picture represents either a frame or a field.
 865
 866 The Begin/Render/End sequence sends the decode buffers to the server
 867 */
 868
 869 /*
 870  * Get ready to decode a picture to a target surface
 871  */
 872 VAStatus vaBeginPicture (
 873     VADisplay dpy,
 874     VAContext *context,
 875     VASurface *render_target
 876 );
 877
 878 /*
 879  * Send decode buffers to the server.
 880  */
 881 VAStatus vaRenderPicture (
 882     VADisplay dpy,
 883     VAContext *context,
 884     VABufferID *buffers,
 885     int num_buffers
 886 );
 887
 888 /*
 889  * Make the end of rendering for a picture.
 890  * The server should start processing all pending operations for this
 891  * surface. This call is non-blocking. The client can start another
 892  * Begin/Render/End sequence on a different render target.
 893  */
 894 VAStatus vaEndPicture (
 895     VADisplay dpy,
 896     VAContext *context
 897 );
 898
 899 /*
 900
 901 Synchronization
 902
 903 */
 904
 905 /*
 906  * This function blocks until all pending operations on the render target
 907  * have been completed.  Upon return it is safe to use the render target for a
 908  * different picture.
 909  */
 910 VAStatus vaSyncSurface (
 911     VADisplay dpy,
 912     VAContext *context,
 913     VASurface *render_target
 914 );
 915
 916 typedef enum
 917 {
 918     VASurfaceRendering  = 0,
 919     VASurfaceReady      = 1,
 920 } VASurfaceStatus;
 921
 922 /*
 923  * Find out any pending ops on the render target
 924  */
 925 VAStatus vaQuerySurfaceStatus (
 926     VADisplay dpy,
 927     VAContext *context,
 928     VASurface *render_target,
 929     VASurfaceStatus *status     /* out */
 930 );
 931
 932 /*
 933  * Copies the surface to a buffer
 934  * The stride of the surface will be stored in *stride
 935  * Caller should free the returned buffer with free() when done.
 936  */
 937 VAStatus vaDbgCopySurfaceToBuffer(VADisplay dpy,
 938     VASurface *surface,
 939     void **buffer, /* out */
 940     unsigned int *stride /* out */
 941 );
 942
 943 #ifdef __cplusplus
 944 }
 945 #endif
 946
 947 #endif /* _VA_H_ */
 948
 949 #if 0
 950 /*****************************************************************************/
 951
 952 Sample Program (w/ pseudo code)
 953
 954 Mostly to demonstrate program flow with no error handling ...
 955
 956 /*****************************************************************************/
 957
 958         /* MPEG-2 VLD decode for a 720x480 frame */
 959
 960         int major_ver, minor_ver;
 961         vaInitialize(dpy, &major_ver, &minor_ver);
 962
 963         int max_num_profiles, max_num_entrypoints, max_num_attribs;
 964         max_num_profiles = vaMaxNumProfiles(dpy);
 965         max_num_entrypoints = vaMaxNumProfiles(dpy);
 966         max_num_attribs = vaMaxNumProfiles(dpy);
 967
 968         /* find out whether MPEG2 MP is supported */
 969         VAProfile *profiles = malloc(sizeof(VAProfile)*max_num_profiles);
 970         int num_profiles;
 971         vaQueryConfigProfiles(dpy, profiles, &profiles);
 972         /*
 973          * traverse "profiles" to locate the one that matches VAProfileMPEG2Main
 974          */
 975
 976         /* now get the available entrypoints for MPEG2 MP */
 977         VAEntrypoint *entrypoints = malloc(sizeof(VAEntrypoint)*max_num_entrypoints);
 978         int num_entrypoints;
 979         vaQueryConfigEntrypoints(dpy, VAProfileMPEG2Main, entrypoints, &num_entrypoints);
 980
 981         /* traverse "entrypoints" to see whether VLD is there */
 982
 983         /* Assuming finding VLD, find out the format for the render target */
 984         VAConfigAttrib attrib;
 985         attrib.type = VAConfigAttribRTFormat;
 986         vaQueryConfigAttributes(dpy, VAProfileMPEG2Main, VAEntrypointVLD,
 987                                 &attrib, 1);
 988
 989         if (attrib.value & VA_RT_FORMAT_YUV420)
 990                 /* Found desired RT format, keep going */
 991
 992         VAConfigID config_id;
 993         vaCreateConfig(dpy, VAProfileMPEG2Main, VAEntrypointVLD, &attrib, 1,
 994                        &config_id);
 995
 996         /*
 997          * create surfaces for the current target as well as reference frames
 998          * we can get by with 4 surfaces for MPEG-2
 999          */
1000         VASurface surfaces[4];
1001         vaCreateSurfaces(dpy, 720, 480, VA_RT_FORMAT_YUV420, 4, surfaces);
1002
1003         /*
1004          * Create a context for this decode pipe
1005          */
1006         VAContext context;
1007         vaCreateContext(dpy, config_id, 720, 480, VA_PROGRESSIVE, surfaces,
1008                         4, &context);
1009
1010         /* Create a picture parameter buffer for this frame */
1011         VABufferID picture_buf;
1012         VAPictureParameterBufferMPEG2 *picture_param;
1013         vaCreateBuffer(dpy, VAPictureParameterBufferType, &picture_buf);
1014         vaBufferData(dpy, picture_buf, sizeof(VAPictureParameterBufferMPEG2), NULL);
1015         vaMapBuffer(dpy, picture_buf, &picture_param);
1016         picture_param->horizontal_size = 720;
1017         picture_param->vertical_size = 480;
1018         picture_param->picture_coding_type = 1; /* I-frame */
1019         /* fill in picture_coding_extension fields here */
1020         vaUnmapBuffer(dpy, picture_buf);
1021
1022
1023         /* Create an IQ matrix buffer for this frame */
1024         VABufferID iq_buf;
1025         VAIQMatrixBufferMPEG2 *iq_matrix;
1026         vaCreateBuffer(dpy, VAIQMatrixBufferType, &iq_buf);
1027         vaBufferData(dpy, iq_buf, sizeof(VAIQMatrixBufferMPEG2), NULL);
1028         vaMapBuffer(dpy, iq_buf, &iq_matrix);
1029         /* fill values for IQ_matrix here */
1030         vaUnmapBuffer(dpy, iq_buf);
1031
1032         /* send the picture and IQ matrix buffers to the server */
1033         vaBeginPicture(dpy, context, &surfaces[0]);
1034
1035         vaRenderPicture(dpy, context, &picture_buf, 1);
1036         vaRenderPicture(dpy, context, &iq_buf, 1);
1037
1038         /*
1039          * Send slices in this frame to the server.
1040          * For MPEG-2, each slice is one row of macroblocks, and
1041          * we have 30 slices for a 720x480 frame
1042          */
1043         for (int i = 1; i <= 30; i++) {
1044
1045                 /* Create a slice parameter buffer */
1046                 VABufferID slice_param_buf;
1047                 VASliceParameterBufferMPEG2 *slice_param;
1048                 vaCreateBuffer(dpy, VASliceParameterBufferType, &slice_param_buf);
1049                 vaBufferData(dpy, slice_param_buf, sizeof(VASliceParameterBufferMPEG2), NULL);
1050                 vaMapBuffer(dpy, slice_param_buf, &slice_param);
1051                 slice_param->slice_data_offset = 0;
1052                 /* Let's say all slices in this bit-stream has 64-bit header */
1053                 slice_param->macroblock_offset = 64;
1054                 slice_param->vertical_position = i;
1055                 /* set up the rest based on what is in the slice header ... */
1056                 vaUnmapBuffer(dpy, slice_param_buf);
1057
1058                 /* send the slice parameter buffer */
1059                 vaRenderPicture(dpy, context, &slice_param_buf, 1);
1060
1061                 /* Create a slice data buffer */
1062                 unsigned char *slice_data;
1063                 VABufferID slice_data_buf;
1064                 vaCreateBuffer(dpy, VASliceDataBufferType, slice_data_buf);
1065                 vaBufferData(dpy, slice_data_buf, x /* decoder figure out how big */, NULL);
1066                 vaMapBuffer(dpy, slice_data_buf, &slice_data);
1067                 /* decoder fill in slice_data */
1068                 vaUnmapBuffer(dpy, slice_data_buf);
1069
1070                 /* send the slice data buffer */
1071                 vaRenderPicture(dpy, context, &slice_data_buf, 1);
1072         }
1073
1074         /* all slices have been sent, mark the end for this frame */
1075         vaEndPicture(dpy, context);
1076 #endif