src/va.h

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