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