src/va.h

   1 /*
   2  * Copyright (c) 2007 Intel Corporation. All Rights Reserved.
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a
   5  * copy of this software and associated documentation files (the
   6  * "Software"), to deal in the Software without restriction, including
   7  * without limitation the rights to use, copy, modify, merge, publish,
   8  * distribute, sub license, and/or sell copies of the Software, and to
   9  * permit persons to whom the Software is furnished to do so, subject to
  10  * the following conditions:
  11  *
  12  * The above copyright notice and this permission notice (including the
  13  * next paragraph) shall be included in all copies or substantial portions
  14  * of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  17  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  19  * IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
  20  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  21  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  22  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23  */
  24 /*
  25  * Video Decode Acceleration API Specification
  26  *
  27  * Rev. 0.24
  28  * <jonathan.bian@intel.com>
  29  *
  30  * Revision History:
  31  * rev 0.10 (12/10/2006 Jonathan Bian) - Initial draft
  32  * rev 0.11 (12/15/2006 Jonathan Bian) - Fixed some errors
  33  * rev 0.12 (02/05/2007 Jonathan Bian) - Added VC-1 data structures for slice level decode
  34  * rev 0.13 (02/28/2007 Jonathan Bian) - Added GetDisplay()
  35  * rev 0.14 (04/13/2007 Jonathan Bian) - Fixed MPEG-2 PictureParameter structure, cleaned up a few funcs.
  36  * rev 0.15 (04/20/2007 Jonathan Bian) - Overhauled buffer management
  37  * rev 0.16 (05/02/2007 Jonathan Bian) - Added error codes and fixed some issues with configuration
  38  * rev 0.17 (05/07/2007 Jonathan Bian) - Added H.264/AVC data structures for slice level decode.
  39  * rev 0.18 (05/14/2007 Jonathan Bian) - Added data structures for MPEG-4 slice level decode
  40  *                                       and MPEG-2 motion compensation.
  41  * rev 0.19 (08/06/2007 Jonathan Bian) - Removed extra type for bitplane data.
  42  * rev 0.20 (08/08/2007 Jonathan Bian) - Added missing fields to VC-1 PictureParameter structure.
  43  * rev 0.21 (08/20/2007 Jonathan Bian) - Added image and subpicture support.
  44  * rev 0.22 (08/27/2007 Jonathan Bian) - Added support for chroma-keying and global alpha.
  45  * rev 0.23 (09/07/2007 Jonathan Bian) - Fixed some issues with images and subpictures.
  46  * rev 0.24 (09/18/2007 Jonathan Bian) - Added display attributes.
  47  *
  48  * Acknowledgements:
  49  *  Some concepts borrowed from XvMC and XvImage.
  50  *  Thanks to Waldo Bastian for many valuable feedbacks.
  51  */
  52 #ifndef _VA_H_
  53 #define _VA_H_
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 /*
  60 Overview
  61
  62 This is currently a decode only interface (with some rendering support).
  63
  64 The basic operation steps are:
  65
  66 - Negotiate a mutually acceptable configuration with the server to lock
  67   down profile, entrypoints, and other attributes that will not change on
  68   a frame-by-frame basis.
  69 - Create a decode context which represents a "virtualized" hardware decode
  70   device
  71 - Get and fill decode buffers with picture level, slice level and macroblock
  72   level data (depending on entrypoints)
  73 - Pass the decode buffers to the server to decode the current frame
  74
  75 Initialization & Configuration Management
  76
  77 - Find out supported profiles
  78 - Find out entrypoints for a given profile
  79 - Find out configuration attributes for a given profile/entrypoint pair
  80 - Create a configuration for use by the decoder
  81
  82 */
  83
  84 typedef void* VADisplay;        /* window system dependent */
  85
  86 typedef int VAStatus;   /* Return status type from functions */
  87 /* Values for the return status */
  88 #define VA_STATUS_SUCCESS                       0x00000000
  89 #define VA_STATUS_ERROR_ALLOCATION_FAILED       0x00000001
  90 #define VA_STATUS_ERROR_INVALID_CONFIG          0x00000002
  91 #define VA_STATUS_ERROR_INVALID_CONTEXT         0x00000003
  92 #define VA_STATUS_ERROR_INVALID_SURFACE         0x00000004
  93 #define VA_STATUS_ERROR_INVALID_BUFFER          0x00000005
  94 #define VA_STATUS_ERROR_ATTR_NOT_SUPPORTED      0x00000006
  95 #define VA_STATUS_ERROR_MAX_NUM_EXCEEDED        0x00000007
  96 #define VA_STATUS_ERROR_UNSUPPORTED_PROFILE             0x00000008
  97 #define VA_STATUS_ERROR_UNSUPPORTED_ENTRYPOINT  0x00000009
  98 #define VA_STATUS_ERROR_UNSUPPORTED_RT_FORMAT   0x0000000a
  99 #define VA_STATUS_ERROR_UNSUPPORTED_BUFFERTYPE  0x0000000b
 100 #define VA_STATUS_ERROR_UNKNOWN                 0xFFFFFFFF
 101
 102 /*
 103  * Returns a short english description of error_status
 104  */
 105 const char *vaErrorStr(VAStatus error_status);
 106
 107 /*
 108  * Initialization:
 109  * A display must be obtained by calling vaGetDisplay() before calling
 110  * vaInitialize() and other functions. This connects the API to the
 111  * native window system.
 112  * For X Windows, native_dpy would be from XOpenDisplay()
 113  */
 114 typedef void* NativeDisplay;    /* window system dependent */
 115
 116 VADisplay vaGetDisplay (
 117     NativeDisplay native_dpy    /* implementation specific */
 118 );
 119
 120 VAStatus vaInitialize (
 121     VADisplay dpy,
 122     int *major_version,  /* out */
 123     int *minor_version   /* out */
 124 );
 125
 126 /*
 127  * After this call, all library internal resources will be cleaned up
 128  */
 129 VAStatus vaTerminate (
 130     VADisplay dpy
 131 );
 132
 133 /* Currently defined profiles */
 134 typedef enum
 135 {
 136     VAProfileMPEG2Simple                = 0,
 137     VAProfileMPEG2Main                  = 1,
 138     VAProfileMPEG4Simple                = 2,
 139     VAProfileMPEG4AdvancedSimple        = 3,
 140     VAProfileMPEG4Main                  = 4,
 141     VAProfileH264Baseline               = 5,
 142     VAProfileH264Main                   = 6,
 143     VAProfileH264High                   = 7,
 144     VAProfileVC1Simple                  = 8,
 145     VAProfileVC1Main                    = 9,
 146     VAProfileVC1Advanced                = 10,
 147 } VAProfile;
 148
 149 /*
 150  *  Currently defined entrypoints
 151  */
 152 typedef enum
 153 {
 154     VAEntrypointVLD             = 1,
 155     VAEntrypointIZZ             = 2,
 156     VAEntrypointIDCT            = 3,
 157     VAEntrypointMoComp          = 4,
 158     VAEntrypointDeblocking      = 5,
 159 } VAEntrypoint;
 160
 161 /* Currently defined configuration attribute types */
 162 typedef enum
 163 {
 164     VAConfigAttribRTFormat              = 0,
 165     VAConfigAttribSpatialResidual       = 1,
 166     VAConfigAttribSpatialClipping       = 2,
 167     VAConfigAttribIntraResidual         = 3,
 168     VAConfigAttribEncryption            = 4,
 169 } VAConfigAttribType;
 170
 171 /*
 172  * Configuration attributes
 173  * If there is more than one value for an attribute, a default
 174  * value will be assigned to the attribute if the client does not
 175  * specify the attribute when creating a configuration
 176  */
 177 typedef struct _VAConfigAttrib {
 178     VAConfigAttribType type;
 179     unsigned int value; /* OR'd flags (bits) for this attribute */
 180 } VAConfigAttrib;
 181
 182 /* attribute value for VAConfigAttribRTFormat */
 183 #define VA_RT_FORMAT_YUV420     0x00000001
 184 #define VA_RT_FORMAT_YUV422     0x00000002
 185 #define VA_RT_FORMAT_YUV444     0x00000004
 186
 187 /*
 188  * if an attribute is not applicable for a given
 189  * profile/entrypoint pair, then set the value to the following
 190  */
 191 #define VA_ATTRIB_NOT_SUPPORTED 0x80000000
 192
 193 /* Get maximum number of profiles supported by the implementation */
 194 int vaMaxNumProfiles (
 195     VADisplay dpy
 196 );
 197
 198 /* Get maximum number of entrypoints supported by the implementation */
 199 int vaMaxNumEntrypoints (
 200     VADisplay dpy
 201 );
 202
 203 /* Get maximum number of attributs supported by the implementation */
 204 int vaMaxNumConfigAttributes (
 205     VADisplay dpy
 206 );
 207
 208 /*
 209  * Query supported profiles
 210  * The caller must provide a "profile_list" array that can hold at
 211  * least vaMaxNumProfile() entries. The actual number of profiles
 212  * returned in "profile_list" is returned in "num_profile".
 213  */
 214 VAStatus vaQueryConfigProfiles (
 215     VADisplay dpy,
 216     VAProfile *profile_list,    /* out */
 217     int *num_profiles           /* out */
 218 );
 219
 220 /*
 221  * Query supported entrypoints for a given profile
 222  * The caller must provide an "entrypoint_list" array that can hold at
 223  * least vaMaxNumEntrypoints() entries. The actual number of entrypoints
 224  * returned in "entrypoint_list" is returned in "num_entrypoints".
 225  */
 226 VAStatus vaQueryConfigEntrypoints (
 227     VADisplay dpy,
 228     VAProfile profile,
 229     VAEntrypoint *entrypoint_list,      /* out */
 230     int *num_entrypoints                /* out */
 231 );
 232
 233 /*
 234  * Get attributes for a given profile/entrypoint pair
 235  * The caller must provide an \93attrib_list\94 with all attributes to be
 236  * queried.  Upon return, the attributes in \93attrib_list\94 have been
 237  * updated with their value.  Unknown attributes or attributes that are
 238  * not supported for the given profile/entrypoint pair will have their
 239  * value set to VA_ATTRIB_NOT_SUPPORTED
 240  */
 241 VAStatus vaGetConfigAttributes (
 242     VADisplay dpy,
 243     VAProfile profile,
 244     VAEntrypoint entrypoint,
 245     VAConfigAttrib *attrib_list, /* in/out */
 246     int num_attribs
 247 );
 248
 249 /* Generic ID type, can be re-typed for specific implementation */
 250 typedef unsigned int VAGenericID;
 251
 252 typedef VAGenericID VAConfigID;
 253
 254 /*
 255  * Create a configuration for the decode pipeline
 256  * it passes in the attribute list that specifies the attributes it cares
 257  * about, with the rest taking default values.
 258  */
 259 VAStatus vaCreateConfig (
 260     VADisplay dpy,
 261     VAProfile profile,
 262     VAEntrypoint entrypoint,
 263     VAConfigAttrib *attrib_list,
 264     int num_attribs,
 265     VAConfigID *config_id /* out */
 266 );
 267
 268 /*
 269  * Free resources associdated with a given config
 270  */
 271 VAStatus vaDestroyConfig (
 272     VADisplay dpy,
 273     VAConfigID config_id
 274 );
 275
 276 /*
 277  * Query all attributes for a given configuration
 278  * The profile of the configuration is returned in \93profile\94
 279  * The entrypoint of the configuration is returned in \93entrypoint\94
 280  * The caller must provide an \93attrib_list\94 array that can hold at least
 281  * vaMaxNumConfigAttributes() entries. The actual number of attributes
 282  * returned in \93attrib_list\94 is returned in \93num_attribs\94
 283  */
 284 VAStatus vaQueryConfigAttributes (
 285     VADisplay dpy,
 286     VAConfigID config_id,
 287     VAProfile *profile,         /* out */
 288     VAEntrypoint *entrypoint,   /* out */
 289     VAConfigAttrib *attrib_list,/* out */
 290     int *num_attribs            /* out */
 291 );
 292
 293
 294 /*
 295  * Context
 296  *
 297  * Context represents a "virtual" video decode pipeline
 298  */
 299
 300 typedef VAGenericID VAContextID;
 301
 302 typedef VAGenericID VASurfaceID;
 303
 304 #define VA_INVALID_SURFACE      -1
 305
 306 typedef struct _VAContext
 307 {
 308     VAContextID         context_id; /* to identify this context */
 309     VAConfigID          config_id;
 310     unsigned short      picture_width;
 311     unsigned short      picture_height;
 312     VASurfaceID         *render_targets;
 313     int                 num_render_targets;
 314     int                 flags;
 315     void                *privData;
 316 } VAContext;
 317
 318 /*
 319     flags - Any combination of the following:
 320       VA_PROGRESSIVE (only progressive frame pictures in the sequence when set)
 321 */
 322 #define VA_PROGRESSIVE  0x1
 323
 324 /*
 325
 326 Surface Management
 327
 328 Surfaces are render targets for a given context. The data in the surfaces
 329 are not accessible to the client and the internal data format of
 330 the surface is implementatin specific.
 331
 332 Question: Is there a need to know the data format (fourcc) or just
 333 differentiate between 420/422/444 is sufficient?
 334
 335 */
 336
 337 typedef struct _VASurface
 338 {
 339     VASurfaceID         surface_id; /* uniquely identify this surface */
 340     VAContextID         context_id; /* which context does this surface belong */
 341     unsigned short      width;
 342     unsigned short      height;
 343     int                 format; /* 420/422/444 */
 344     void                *privData; /* private to the library */
 345 } VASurface;
 346
 347 /*
 348  * Surfaces will be bound to a context when the context is created. Once
 349  * a surface is bound to a given context, it can not be used to create
 350  * another context. The association is removed when the context is destroyed
 351  */
 352
 353 /* Surface Functions */
 354 VAStatus vaCreateSurfaces (
 355     VADisplay dpy,
 356     int width,
 357     int height,
 358     int format,
 359     int num_surfaces,
 360     VASurface *surfaces /* out */
 361 );
 362
 363 /*
 364  * surfaces can only be destroyed after the context associated has been
 365  * destroyed
 366  */
 367 VAStatus vaDestroySurface (
 368     VADisplay dpy,
 369     VASurface *surface_list,
 370     int num_surfaces
 371 );
 372
 373 VAStatus vaCreateContext (
 374     VADisplay dpy,
 375     VAConfigID config_id,
 376     int picture_width,
 377     int picture_height,
 378     int flag,
 379     VASurface *render_targets,
 380     int num_render_targets,
 381     VAContext *context          /* out */
 382 );
 383
 384 VAStatus vaDestroyContext (
 385     VADisplay dpy,
 386     VAContext *context
 387 );
 388
 389 /*
 390  *
 391  *      Buffers
 392  *      Buffers are used to pass various types of data from the
 393  *      client to the server. The server maintains a data store
 394  *      for each buffer created, and the client idenfies a buffer
 395  *      through a unique buffer id assigned by the server.
 396  *
 397  */
 398
 399 typedef VAGenericID VABufferID;
 400
 401 typedef enum
 402 {
 403     VAPictureParameterBufferType        = 0,
 404     VAIQMatrixBufferType                = 1,
 405     VABitPlaneBufferType                = 2,
 406     VASliceGroupMapBufferType           = 3,
 407     VASliceParameterBufferType          = 4,
 408     VASliceDataBufferType               = 5,
 409     VAMacroblockParameterBufferType     = 6,
 410     VAResidualDataBufferType            = 7,
 411     VADeblockingParameterBufferType     = 8,
 412     VAImageBufferType                   = 9
 413 } VABufferType;
 414
 415 /****************************
 416  * MPEG-2 data structures
 417  ****************************/
 418
 419 /* MPEG-2 Picture Parameter Buffer */
 420 /*
 421  * For each frame or field, and before any slice data, a single
 422  * picture parameter buffer must be send.
 423  */
 424 typedef struct _VAPictureParameterBufferMPEG2
 425 {
 426     unsigned short horizontal_size;
 427     unsigned short vertical_size;
 428     VASurfaceID forward_reference_picture;
 429     VASurfaceID backward_reference_picture;
 430     /* meanings of the following fields are the same as in the standard */
 431     int picture_coding_type;
 432     int f_code; /* pack all four fcode into this */
 433     union {
 434         struct {
 435             unsigned char intra_dc_precision            : 2;
 436             unsigned char picture_structure             : 2;
 437             unsigned char top_field_first               : 1;
 438             unsigned char frame_pred_frame_dct          : 1;
 439             unsigned char concealment_motion_vectors    : 1;
 440             unsigned char q_scale_type                  : 1;
 441             unsigned char intra_vlc_format              : 1;
 442             unsigned char alternate_scan                : 1;
 443             unsigned char repeat_first_field            : 1;
 444             unsigned char progressive_frame             : 1;
 445             unsigned char is_first_field                : 1; /* indicate whether the current field
 446                                                               * is the first field for field picture
 447                                                               */
 448         };
 449         unsigned int picture_coding_extension;
 450     };
 451 } VAPictureParameterBufferMPEG2;
 452
 453 /* MPEG-2 Inverse Quantization Matrix Buffer */
 454 typedef struct _VAIQMatrixBufferMPEG2
 455 {
 456     int load_intra_quantiser_matrix;
 457     int load_non_intra_quantiser_matrix;
 458     int load_chroma_intra_quantiser_matrix;
 459     int load_chroma_non_intra_quantiser_matrix;
 460     unsigned char intra_quantiser_matrix[64];
 461     unsigned char non_intra_quantiser_matrix[64];
 462     unsigned char chroma_intra_quantiser_matrix[64];
 463     unsigned char chroma_non_intra_quantiser_matrix[64];
 464 } VAIQMatrixBufferMPEG2;
 465
 466 /*
 467  * There will be cases where the bitstream buffer will not have enough room to hold
 468  * the data for the entire slice, and the following flags will be used in the slice
 469  * parameter to signal to the server for the possible cases.
 470  * If a slice parameter buffer and slice data buffer pair is sent to the server with
 471  * the slice data partially in the slice data buffer (BEGIN and MIDDLE cases below),
 472  * then a slice parameter and data buffer needs to be sent again to complete this slice.
 473  */
 474 #define VA_SLICE_DATA_FLAG_ALL          0x00    /* whole slice is in the buffer */
 475 #define VA_SLICE_DATA_FLAG_BEGIN        0x01    /* The beginning of the slice is in the buffer but the end if not */
 476 #define VA_SLICE_DATA_FLAG_MIDDLE       0x02    /* Neither beginning nor end of the slice is in the buffer */
 477 #define VA_SLICE_DATA_FLAG_END          0x04    /* end of the slice is in the buffer */
 478
 479 /* MPEG-2 Slice Parameter Buffer */
 480 typedef struct _VASliceParameterBufferMPEG2
 481 {
 482     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 483     unsigned int slice_data_offset;/* the offset to the first byte of slice data */
 484     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 485     unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
 486     unsigned int slice_vertical_position;
 487     int quantiser_scale_code;
 488     int intra_slice_flag;
 489 } VASliceParameterBufferMPEG2;
 490
 491 /* MPEG-2 Macroblock Parameter Buffer */
 492 typedef struct _VAMacroblockParameterBufferMPEG2
 493 {
 494     unsigned short macroblock_address;
 495     /*
 496      * macroblock_address (in raster scan order)
 497      * top-left: 0
 498      * bottom-right: picture-height-in-mb*picture-width-in-mb - 1
 499      */
 500     unsigned char macroblock_type;  /* see definition below */
 501     union {
 502         struct {
 503             unsigned char frame_motion_type             : 2;
 504             unsigned char field_motion_type             : 2;
 505             unsigned char dct_type                      : 1;
 506         };
 507         unsigned char macroblock_modes;
 508     };
 509     unsigned char motion_vertical_field_select;
 510     /*
 511      * motion_vertical_field_select:
 512      * see section 6.3.17.2 in the spec
 513      * only the lower 4 bits are used
 514      * bit 0: first vector forward
 515      * bit 1: first vector backward
 516      * bit 2: second vector forward
 517      * bit 3: second vector backward
 518      */
 519     short PMV[2][2][2]; /* see Table 7-7 in the spec */
 520     unsigned short coded_block_pattern;
 521     /*
 522      * The bitplanes for coded_block_pattern are described
 523      * in Figure 6.10-12 in the spec
 524      */
 525
 526     /* Number of skipped macroblocks after this macroblock */
 527     unsigned short num_skipped_macroblocks;
 528 } VAMacroblockParameterBufferMPEG2;
 529
 530 /*
 531  * OR'd flags for macroblock_type (section 6.3.17.1 in the spec)
 532  */
 533 #define VA_MB_TYPE_MOTION_FORWARD       0x02
 534 #define VA_MB_TYPE_MOTION_BACKWARD      0x04
 535 #define VA_MB_TYPE_MOTION_PATTERN       0x08
 536 #define VA_MB_TYPE_MOTION_INTRA         0x10
 537
 538 /*
 539  * MPEG-2 Residual Data Buffer
 540  * For each macroblock, there wil be 64 shorts (16-bit) in the
 541  * residual data buffer
 542  */
 543
 544 /****************************
 545  * MPEG-4 Part 2 data structures
 546  ****************************/
 547
 548 /* MPEG-4 Picture Parameter Buffer */
 549 /*
 550  * For each frame or field, and before any slice data, a single
 551  * picture parameter buffer must be send.
 552  */
 553 typedef struct _VAPictureParameterBufferMPEG4
 554 {
 555     unsigned short vop_width;
 556     unsigned short vop_height;
 557     VASurfaceID forward_reference_picture;
 558     VASurfaceID backward_reference_picture;
 559     union {
 560         struct {
 561             unsigned char short_video_header            : 1;
 562             unsigned char chroma_format                 : 2;
 563             unsigned char interlaced                    : 1;
 564             unsigned char obmc_disable                  : 1;
 565             unsigned char sprite_enable                 : 2;
 566             unsigned char sprite_warping_accuracy       : 2;
 567             unsigned char quant_type                    : 1;
 568             unsigned char quarter_sample                : 1;
 569             unsigned char data_partitioned              : 1;
 570             unsigned char reversible_vlc                : 1;
 571         };
 572         unsigned short vol_fields;
 573     };
 574     unsigned char no_of_sprite_warping_points;
 575     short sprite_trajectory_du[3];
 576     short sprite_trajectory_dv[3];
 577     unsigned char quant_precision;
 578     union {
 579         struct {
 580             unsigned char vop_coding_type               : 2;
 581             unsigned char backward_reference_vop_coding_type    : 2;
 582             unsigned char vop_rounding_type             : 1;
 583             unsigned char intra_dc_vlc_thr              : 3;
 584             unsigned char top_field_first               : 1;
 585             unsigned char alternate_vertical_scan_flag  : 1;
 586         };
 587         unsigned short vop_fields;
 588     };
 589     unsigned char vop_fcode_forward;
 590     unsigned char vop_fcode_backward;
 591     /* short header related */
 592     unsigned char num_gobs_in_vop;
 593     unsigned char num_macroblocks_in_gob;
 594     /* for direct mode prediction */
 595     short TRB;
 596     short TRD;
 597 } VAPictureParameterBufferMPEG4;
 598
 599 /* MPEG-4 Inverse Quantization Matrix Buffer */
 600 typedef struct _VAIQMatrixBufferMPEG4
 601 {
 602     int load_intra_quant_mat;
 603     int load_non_intra_quant_mat;
 604     unsigned char intra_quant_mat[64];
 605     unsigned char non_intra_quant_mat[64];
 606 } VAIQMatrixBufferMPEG4;
 607
 608 /* MPEG-4 Slice Parameter Buffer */
 609 typedef struct _VASliceParameterBufferMPEG4
 610 {
 611     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 612     unsigned int slice_data_offset;/* the offset to the first byte of slice data */
 613     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 614     unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
 615     unsigned int macroblock_number;
 616     int quant_scale;
 617 } VASliceParameterBufferMPEG4;
 618
 619 /*
 620  VC-1 data structures
 621 */
 622
 623 /* VC-1 Picture Parameter Buffer */
 624 /*
 625  * For each picture, and before any slice data, a picture parameter
 626  * buffer must be send. Multiple picture parameter buffers may be
 627  * sent for a single picture. In that case picture parameters will
 628  * apply to all slice data that follow it until a new picture
 629  * parameter buffer is sent.
 630  *
 631  * Notes:
 632  *   pic_quantizer_type should be set to the applicable quantizer
 633  *   type as defined by QUANTIZER (J.1.19) and either
 634  *   PQUANTIZER (7.1.1.8) or PQINDEX (7.1.1.6)
 635  */
 636 typedef struct _VAPictureParameterBufferVC1
 637 {
 638     VASurfaceID forward_reference_picture;
 639     VASurfaceID backward_reference_picture;
 640     /* if out-of-loop post-processing is done on the render
 641        target, then we need to keep the in-loop decoded
 642        picture as a reference picture */
 643     VASurfaceID inloop_decoded_picture;
 644
 645     /* sequence layer for AP or meta data for SP and MP */
 646     union {
 647         struct {
 648             unsigned char interlace     : 1; /* SEQUENCE_LAYER::INTERLACE */
 649             unsigned char syncmarker    : 1;/* METADATA::SYNCMARKER */
 650             unsigned char overlap       : 1;/* METADATA::OVERLAP */
 651         };
 652         unsigned char sequence_fields;
 653     };
 654
 655     unsigned short coded_width;         /* ENTRY_POINT_LAYER::CODED_WIDTH */
 656     unsigned short coded_height;        /* ENTRY_POINT_LAYER::CODED_HEIGHT */
 657     unsigned char closed_entry;         /* ENTRY_POINT_LAYER::CLOSED_ENTRY */
 658     unsigned char broken_link;          /* ENTRY_POINT_LAYER::BROKEN_LINK */
 659     unsigned char loopfilter;           /* ENTRY_POINT_LAYER::LOOPFILTER */
 660     unsigned char conditional_overlap_flag; /* ENTRY_POINT_LAYER::CONDOVER */
 661     unsigned char fast_uvmc_flag;       /* ENTRY_POINT_LAYER::FASTUVMC */
 662     union {
 663         struct {
 664             unsigned char range_mapping_luma_flag:      1; /* ENTRY_POINT_LAYER::RANGE_MAPY_FLAG */
 665             unsigned char range_mapping_luma:           3; /* ENTRY_POINT_LAYER::RANGE_MAPY */
 666             unsigned char range_mapping_chroma_flag:    1; /* ENTRY_POINT_LAYER::RANGE_MAPUV_FLAG */
 667             unsigned char range_mapping_chroma:         3; /* ENTRY_POINT_LAYER::RANGE_MAPUV */
 668         };
 669         unsigned char range_mapping_fields;
 670     };
 671
 672     unsigned char b_picture_fraction;   /* PICTURE_LAYER::BFRACTION */
 673     unsigned char cbp_table;            /* PICTURE_LAYER::CBPTAB/ICBPTAB */
 674     unsigned char mb_mode_table;        /* PICTURE_LAYER::MBMODETAB */
 675     unsigned char range_reduction_frame;/* PICTURE_LAYER::RANGEREDFRM */
 676     unsigned char rounding_control;     /* PICTURE_LAYER::RNDCTRL */
 677     unsigned char post_processing;      /* PICTURE_LAYER::POSTPROC */
 678     unsigned char picture_resolution_index;     /* PICTURE_LAYER::RESPIC */
 679     unsigned char luma_scale;           /* PICTURE_LAYER::LUMSCALE */
 680     unsigned char luma_shift;           /* PICTURE_LAYER::LUMSHIFT */
 681     union {
 682         struct {
 683             unsigned char picture_type  : 2;    /* PICTURE_LAYER::PTYPE */
 684             unsigned char frame_coding_mode     : 3;/* PICTURE_LAYER::FCM */
 685             unsigned char top_field_first       : 1;/* PICTURE_LAYER::TFF */
 686             unsigned char is_first_field        : 1; /* set to 1 if it is the first field */
 687             unsigned char intensity_compensation: 1;/* PICTURE_LAYER::INTCOMP */
 688         };
 689         unsigned char picture_fields;
 690     };
 691     union {
 692        struct {
 693             unsigned char mv_type_mb    : 1;    /* PICTURE::MVTYPEMB */
 694             unsigned char direct_mb     : 1;    /* PICTURE::DIRECTMB */
 695             unsigned char skip_mb       : 1;    /* PICTURE::SKIPMB */
 696             unsigned char field_tx      : 1;    /* PICTURE::FIELDTX */
 697             unsigned char foward_mb     : 1;    /* PICTURE::FORWARDMB */
 698             unsigned char ac_pred       : 1;    /* PICTURE::ACPRED */
 699             unsigned char overflags     : 1;    /* PICTURE::OVERFLAGS */
 700         };
 701         unsigned char raw_coding_flag;
 702     };
 703     union {
 704         struct {
 705             unsigned char reference_distance_flag : 1;/* PICTURE_LAYER::REFDIST_FLAG */
 706             unsigned char reference_distance    : 1;/* PICTURE_LAYER::REFDIST */
 707             unsigned char num_reference_pictures: 1;/* PICTURE_LAYER::NUMREF */
 708             unsigned char reference_field_pic_indicator : 1;/* PICTURE_LAYER::REFFIELD */
 709         };
 710         unsigned short reference_fields;
 711     };
 712     union {
 713         struct {
 714             unsigned char mv_mode       : 2;    /* PICTURE_LAYER::MVMODE */
 715             unsigned char mv_mode2      : 2;    /* PICTURE_LAYER::MVMODE2 */
 716             unsigned char mv_table      : 3;/* PICTURE_LAYER::MVTAB/IMVTAB */
 717             unsigned char two_mv_block_pattern_table: 2;/* PICTURE_LAYER::2MVBPTAB */
 718             unsigned char four_mv_switch: 1;    /* PICTURE_LAYER::4MVSWITCH */
 719             unsigned char four_mv_block_pattern_table : 2;/* PICTURE_LAYER::4MVBPTAB */
 720             unsigned char extended_mv_flag: 1;/* ENTRY_POINT_LAYER::EXTENDED_MV */
 721             unsigned char extended_mv_range : 2;/* PICTURE_LAYER::MVRANGE */
 722             unsigned char extended_dmv_flag : 1;/* ENTRY_POINT_LAYER::EXTENDED_DMV */
 723             unsigned char extended_dmv_range : 2;/* PICTURE_LAYER::DMVRANGE */
 724         };
 725         unsigned int mv_fields;
 726     };
 727     union {
 728         struct {
 729             unsigned char dquant        : 2;    /* ENTRY_POINT_LAYER::DQUANT */
 730             unsigned char half_qp       : 1;    /* PICTURE_LAYER::HALFQP */
 731             unsigned char pic_quantizer_scale : 5;/* PICTURE_LAYER::PQUANT */
 732             unsigned char pic_quantizer_type : 1;/* PICTURE_LAYER::PQUANTIZER */
 733             unsigned char dq_frame      : 1;    /* VOPDQUANT::DQUANTFRM */
 734             unsigned char dq_profile    : 2;    /* VOPDQUANT::DQPROFILE */
 735             unsigned char dq_sb_edge    : 2;    /* VOPDQUANT::DQSBEDGE */
 736             unsigned char dq_db_edge    : 2;    /* VOPDQUANT::DQDBEDGE */
 737             unsigned char dq_binary_level : 1;  /* VOPDQUANT::DQBILEVEL */
 738             unsigned char alt_pic_quantizer : 5;/* VOPDQUANT::ALTPQUANT */
 739         };
 740         unsigned long pic_quantizer_fields;
 741     };
 742     union {
 743         struct {
 744             unsigned char variable_sized_transform_flag : 1;/* ENTRY_POINT_LAYER::VSTRANSFORM */
 745             unsigned char mb_level_transform_type_flag  : 1;/* PICTURE_LAYER::TTMBF */
 746             unsigned char frame_level_transform_type    : 2;/* PICTURE_LAYER::TTFRM */
 747             unsigned char transform_ac_codingset_idx1   : 2;/* PICTURE_LAYER::TRANSACFRM */
 748             unsigned char transform_ac_codingset_idx2   : 2;/* PICTURE_LAYER::TRANSACFRM2 */
 749             unsigned char intra_transform_dc_table      : 1;/* PICTURE_LAYER::TRANSDCTAB */
 750         };
 751         unsigned short transform_fields;
 752     };
 753 } VAPictureParameterBufferVC1;
 754
 755 /* VC-1 Bitplane Buffer
 756 There will be at most three bitplanes coded in any picture header. To send
 757 the bitplane data more efficiently, each byte is divided in two nibbles, with
 758 each nibble carrying three bitplanes for one macroblock.  The following table
 759 shows the bitplane data arrangement within each nibble based on the picture
 760 type.
 761
 762 Picture Type    Bit3            Bit2            Bit1            Bit0
 763 I or BI                         OVERFLAGS       ACPRED          FIELDTX
 764 P                               MYTYPEMB        SKIPMB          DIRECTMB
 765 B                               FORWARDMB       SKIPMB          DIRECTMB
 766
 767 Within each byte, the lower nibble is for the first MB and the upper nibble is
 768 for the second MB.  E.g. the lower nibble of the first byte in the bitplane
 769 buffer is for Macroblock #1 and the upper nibble of the first byte is for
 770 Macroblock #2 in the first row.
 771 */
 772
 773 /* VC-1 Slice Parameter Buffer */
 774 typedef struct _VASliceParameterBufferVC1
 775 {
 776     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 777     unsigned int slice_data_offset;/* the offset to the first byte of slice data */
 778     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 779     unsigned int macroblock_offset;/* the offset to the first bit of MB from the first byte of slice data */
 780     unsigned int slice_vertical_position;
 781 } VASliceParameterBufferVC1;
 782
 783 /* VC-1 Slice Data Buffer */
 784 /*
 785 This is simplely a buffer containing raw bit-stream bytes
 786 */
 787
 788 /****************************
 789  * H.264/AVC data structures
 790  ****************************/
 791
 792 typedef struct _VAPictureH264
 793 {
 794     VASurfaceID picture_id;
 795     unsigned int flags;
 796     unsigned int TopFieldOrderCnt;
 797     unsigned int BottomFieldOrderCnt;
 798 } VAPictureH264;
 799 /* flags in VAPictureH264 could be OR of the following */
 800 #define VA_PICTURE_H264_INVALID                 0x00000001
 801 #define VA_PICTURE_H264_TOP_FIELD               0x00000002
 802 #define VA_PICTURE_H264_BOTTOM_FIELD            0x00000004
 803 #define VA_PICTURE_H264_SHORT_TERM_REFERENCE    0x00000008
 804 #define VA_PICTURE_H264_LONG_TERM_REFERENCE     0x00000010
 805
 806 /* H.264 Picture Parameter Buffer */
 807 /*
 808  * For each picture, and before any slice data, a single
 809  * picture parameter buffer must be send.
 810  */
 811 typedef struct _VAPictureParameterBufferH264
 812 {
 813     VAPictureH264 CurrPic;
 814     VAPictureH264 ReferenceFrames[16];  /* in DPB */
 815     unsigned short picture_width_in_mbs_minus1;
 816     unsigned short picture_height_in_mbs_minus1;
 817     unsigned char bit_depth_luma_minus8;
 818     unsigned char bit_depth_chroma_minus8;
 819     unsigned char num_ref_frames;
 820     union {
 821         struct {
 822             unsigned char chroma_format_idc                     : 2;
 823             unsigned char residual_colour_transform_flag        : 1;
 824             unsigned char frame_mbs_only_flag                   : 1;
 825             unsigned char mb_adaptive_frame_field_flag          : 1;
 826             unsigned char direct_8x8_inference_flag             : 1;
 827             unsigned char MinLumaBiPredSize8x8                  : 1; /* see A.3.3.2 */
 828         };
 829         unsigned char seq_fields;
 830     };
 831     unsigned char num_slice_groups_minus1;
 832     unsigned char slice_group_map_type;
 833     signed char pic_init_qp_minus26;
 834     signed char chroma_qp_index_offset;
 835     signed char second_chroma_qp_index_offset;
 836     union {
 837         struct {
 838             unsigned char entropy_coding_mode_flag      : 1;
 839             unsigned char weighted_pred_flag            : 1;
 840             unsigned char weighted_bipred_idc           : 2;
 841             unsigned char transform_8x8_mode_flag       : 1;
 842             unsigned char field_pic_flag                : 1;
 843             unsigned char constrained_intra_pred_flag   : 1;
 844         };
 845         unsigned char pic_fields;
 846     };
 847     unsigned short frame_num;
 848 } VAPictureParameterBufferH264;
 849
 850 /* H.264 Inverse Quantization Matrix Buffer */
 851 typedef struct _VAIQMatrixBufferH264
 852 {
 853     unsigned char ScalingList4x4[6][16];
 854     unsigned char ScalingList8x8[2][64];
 855 } VAIQMatrixBufferH264;
 856
 857 /*
 858  * H.264 Slice Group Map Buffer
 859  * When VAPictureParameterBufferH264::num_slice_group_minus1 is not equal to 0,
 860  * A slice group map buffer should be sent for each picture if required. The buffer
 861  * is sent only when there is a change in the mapping values.
 862  * The slice group map buffer map "map units" to slice groups as specified in
 863  * section 8.2.2 of the H.264 spec. The buffer will contain one byte for each macroblock
 864  * in raster scan order
 865  */
 866
 867 /* H.264 Slice Parameter Buffer */
 868 typedef struct _VASliceParameterBufferH264
 869 {
 870     unsigned int slice_data_size;/* number of bytes in the slice data buffer for this slice */
 871     unsigned int slice_data_offset;/* the offset to first byte of slice data */
 872     unsigned int slice_data_flag; /* see VA_SLICE_DATA_FLAG_XXX defintions */
 873     unsigned short slice_data_bit_offset; /* bit offset in the first byte of valid data */
 874     unsigned short first_mb_in_slice;
 875     unsigned char slice_type;
 876     unsigned char direct_spatial_mv_pred_flag;
 877     unsigned char num_ref_idx_l0_active_minus1;
 878     unsigned char num_ref_idx_l1_active_minus1;
 879     unsigned char cabac_init_idc;
 880     char slice_qp_delta;
 881     unsigned char disable_deblocking_filter_idc;
 882     char slice_alpha_c0_offset_div2;
 883     char slice_beta_offset_div2;
 884     VAPictureH264 RefPicList0[32];      /* See 8.2.4.2 */
 885     VAPictureH264 RefPicList1[32];      /* See 8.2.4.2 */
 886     unsigned char luma_log2_weight_denom;
 887     unsigned char chroma_log2_weight_denom;
 888     unsigned char luma_weight_l0_flag;
 889     short luma_weight_l0[32];
 890     short luma_offset_l0[32];
 891     unsigned char chroma_weight_l0_flag;
 892     short chroma_weight_l0[32][2];
 893     short chroma_offset_l0[32][2];
 894     unsigned char luma_weight_l1_flag;
 895     short luma_weight_l1[32];
 896     short luma_offset_l1[32];
 897     unsigned char chroma_weight_l1_flag;
 898     short chroma_weight_l1[32][2];
 899     short chroma_offset_l1[32][2];
 900 } VASliceParameterBufferH264;
 901
 902 /* Buffer functions */
 903
 904 /*
 905  * Creates a buffer for storing a certain type of data, no data store allocated
 906  */
 907 VAStatus vaCreateBuffer (
 908     VADisplay dpy,
 909     VABufferType type,  /* in */
 910     VABufferID *buf_id  /* out */
 911 );
 912
 913 /*
 914  * Create data store for the buffer and initalize with "data".
 915  * if "data" is null, then the contents of the buffer data store
 916  * are undefined.
 917  * Basically there are two ways to get buffer data to the server side. One is
 918  * to call vaBufferData() with a non-null "data", which results the data being
 919  * copied to the data store on the server side.  A different method that
 920  * eliminates this copy is to pass null as "data" when calling vaBufferData(),
 921  * and then use vaMapBuffer() to map the data store from the server side to the
 922  * client address space for access.
 923  */
 924 VAStatus vaBufferData (
 925     VADisplay dpy,
 926     VABufferID buf_id,  /* in */
 927     unsigned int size,  /* in */
 928     unsigned int num_elements, /* in */
 929     void *data          /* in */
 930 );
 931
 932 /*
 933  * Convey to the server how many valid elements are in the buffer.
 934  * e.g. if multiple slice parameters are being held in a single buffer,
 935  * this will communicate to the server the number of slice parameters
 936  * that are valid in the buffer.
 937  */
 938 VAStatus vaBufferSetNumElements (
 939     VADisplay dpy,
 940     VABufferID buf_id,  /* in */
 941     unsigned int num_elements /* in */
 942 );
 943
 944 /*
 945  * Map data store of the buffer into the client's address space
 946  * vaBufferData() needs to be called with "data" set to NULL before
 947  * calling vaMapBuffer()
 948  */
 949 VAStatus vaMapBuffer (
 950     VADisplay dpy,
 951     VABufferID buf_id,  /* in */
 952     void **pbuf         /* out */
 953 );
 954
 955 /*
 956  * After client making changes to a mapped data store, it needs to
 957  * "Unmap" it to let the server know that the data is ready to be
 958  * consumed by the server
 959  */
 960 VAStatus vaUnmapBuffer (
 961     VADisplay dpy,
 962     VABufferID buf_id   /* in */
 963 );
 964
 965 /*
 966  * After this call, the buffer is deleted and this buffer_id is no longer valid
 967  */
 968 VAStatus vaDestroyBuffer (
 969     VADisplay dpy,
 970     VABufferID buffer_id
 971 );
 972
 973 /*
 974 Render (Decode) Pictures
 975
 976 A picture represents either a frame or a field.
 977
 978 The Begin/Render/End sequence sends the decode buffers to the server
 979 */
 980
 981 /*
 982  * Get ready to decode a picture to a target surface
 983  */
 984 VAStatus vaBeginPicture (
 985     VADisplay dpy,
 986     VAContext *context,
 987     VASurface *render_target
 988 );
 989
 990 /*
 991  * Send decode buffers to the server.
 992  */
 993 VAStatus vaRenderPicture (
 994     VADisplay dpy,
 995     VAContext *context,
 996     VABufferID *buffers,
 997     int num_buffers
 998 );
 999
1000 /*
1001  * Make the end of rendering for a picture.
1002  * The server should start processing all pending operations for this
1003  * surface. This call is non-blocking. The client can start another
1004  * Begin/Render/End sequence on a different render target.
1005  */
1006 VAStatus vaEndPicture (
1007     VADisplay dpy,
1008     VAContext *context
1009 );
1010
1011 /*
1012
1013 Synchronization
1014
1015 */
1016
1017 /*
1018  * This function blocks until all pending operations on the render target
1019  * have been completed.  Upon return it is safe to use the render target for a
1020  * different picture.
1021  */
1022 VAStatus vaSyncSurface (
1023     VADisplay dpy,
1024     VAContext *context,
1025     VASurface *render_target
1026 );
1027
1028 typedef enum
1029 {
1030     VASurfaceRendering  = 0, /* Rendering in progress */
1031     VASurfaceDisplaying = 1, /* Displaying in progress (not safe to render into it) */
1032                              /* this status is useful if surface is used as the source */
1033                              /* of an overlay */
1034     VASurfaceReady      = 2  /* not being rendered or displayed */
1035 } VASurfaceStatus;
1036
1037 /*
1038  * Find out any pending ops on the render target
1039  */
1040 VAStatus vaQuerySurfaceStatus (
1041     VADisplay dpy,
1042     VAContext *context,
1043     VASurface *render_target,
1044     VASurfaceStatus *status     /* out */
1045 );
1046
1047
1048 /*
1049  * Copies the surface to a buffer
1050  * The stride of the surface will be stored in *stride
1051  * Caller should free the returned buffer with free() when done.
1052  */
1053 VAStatus vaDbgCopySurfaceToBuffer(VADisplay dpy,
1054     VASurface *surface,
1055     void **buffer, /* out */
1056     unsigned int *stride /* out */
1057 );
1058
1059 /*
1060  * Images and Subpictures
1061  * VAImage is used to either get the surface data to client memory, or
1062  * to copy image data in client memory to a surface.
1063  * Both images, subpictures and surfaces follow the same 2D coordinate system where origin
1064  * is at the upper left corner with positive X to the right and positive Y down
1065  */
1066 #define MAKEFOURCC(ch0, ch1, ch2, ch3) \
1067     ((unsigned long)(unsigned char) (ch0) | ((unsigned long)(unsigned char) (ch1) << 8) | \
1068     ((unsigned long)(unsigned char) (ch2) << 16) | ((unsigned long)(unsigned char) (ch3) << 24 ))
1069
1070 /* a few common FourCCs */
1071 #define VA_FOURCC_NV12          0x3231564E
1072 #define VA_FOURCC_AI44          0x34344149
1073 #define VA_FOURCC_RGBA          0x41424752
1074
1075 typedef struct _VAImageFormat
1076 {
1077     unsigned int        fourcc;
1078     unsigned int        byte_order; /* VA_LSB_FIRST, VA_MSB_FIRST */
1079     unsigned int        bits_per_pixel;
1080     /* for RGB formats */
1081     unsigned int        depth; /* significant bits per pixel */
1082     unsigned int        red_mask;
1083     unsigned int        green_mask;
1084     unsigned int        blue_mask;
1085     unsigned int        alpha_mask;
1086 } VAImageFormat;
1087
1088 typedef VAGenericID VAImageID;
1089
1090 typedef struct _VAImage
1091 {
1092     VAImageID           image_id; /* uniquely identify this image */
1093     VAImageFormat       format;
1094     VABufferID          buf;    /* image data buffer */
1095     /*
1096      * Image data will be stored in a buffer of type VAImageBufferType to facilitate
1097      * data store on the server side for optimal performance.
1098      * It is expected that the client will first call vaCreateImage which returns a VAImage
1099      * structure with the following fields filled by the library. It will then
1100      * create the "buf" with vaBufferCreate. For PutImage, then client will call
1101      * vaBufferData() with the image data before calling PutImage, and for GetImage
1102      * the client will call vaBufferData() with a NULL data pointer, and then call GetImage.
1103      * After that the client can use the Map/Unmap buffer functions to access the image data.
1104      */
1105     unsigned short      width;
1106     unsigned short      height;
1107     unsigned int        data_size;
1108     unsigned int        num_planes;
1109     /*
1110      * An array of size num_planes indicating the scanline pitch in bytes.
1111      * Each plane may have a different pitch.
1112      */
1113     unsigned int        *pitches;
1114     /*
1115      * An array of size num_planes indicating the byte offset from
1116      * the beginning of the image data to the start of each plane.
1117      */
1118     unsigned int        *offsets;
1119 } VAImage;
1120
1121 /* Get maximum number of image formats supported by the implementation */
1122 int vaMaxNumImageFormats (
1123     VADisplay dpy
1124 );
1125
1126 /*
1127  * Query supported image formats
1128  * The caller must provide a "format_list" array that can hold at
1129  * least vaMaxNumImageFormats() entries. The actual number of formats
1130  * returned in "format_list" is returned in "num_formats".
1131  */
1132 VAStatus vaQueryImageFormats (
1133     VADisplay dpy,
1134     VAImageFormat *format_list, /* out */
1135     int *num_formats            /* out */
1136 );
1137
1138 /*
1139  * Create a VAImage structure
1140  * The width and height fields returned in the VAImage structure may get
1141  * enlarged for some YUV formats. The size of the data buffer that needs
1142  * to be allocated will be given in the "data_size" field in VAImage.
1143  * Image data is not allocated by this function.  The client should
1144  * allocate the memory required for the data and fill in the data field after
1145  * looking at "data_size" returned from this call.
1146  */
1147 VAStatus vaCreateImage (
1148     VADisplay dpy,
1149     VAImageFormat *format,
1150     int width,
1151     int height,
1152     VAImage *image      /* out */
1153 );
1154
1155 /*
1156  * Should call DestroyImage before destroying the surface it is bound to
1157  */
1158 VAStatus vaDestroyImage (
1159     VADisplay dpy,
1160     VAImage *image
1161 );
1162
1163 /*
1164  * Retrive surface data into a VAImage
1165  * Image must be in a format supported by the implementation
1166  */
1167 VAStatus vaGetImage (
1168     VADisplay dpy,
1169     VASurface *surface,
1170     int x,      /* coordinates of the upper left source pixel */
1171     int y,
1172     unsigned int width, /* width and height of the region */
1173     unsigned int height,
1174     VAImage *image
1175 );
1176
1177 /*
1178  * Copy data from a VAImage to a surface
1179  * Image must be in a format supported by the implementation
1180  */
1181 VAStatus vaPutImage (
1182     VADisplay dpy,
1183     VASurface *surface,
1184     VAImage *image,
1185     int src_x,
1186     int src_y,
1187     unsigned int width,
1188     unsigned int height,
1189     int dest_x,
1190     int dest_y
1191 );
1192
1193 /*
1194  * Subpictures
1195  * Subpicture is a special type of image that can be blended
1196  * with a surface during vaPutSurface(). Subpicture can be used to render
1197  * DVD sub-titles or closed captioning text etc.
1198  */
1199
1200 typedef VAGenericID VASubpictureID;
1201
1202 typedef struct _VASubpicture
1203 {
1204     VASubpictureID      subpicture_id; /* uniquely identify this subpicture */
1205     VASurfaceID         surface_id; /* which surface does this subpicture associate with */
1206     VAImageID           image_id;
1207     /* The following fields are set by the library */
1208     int num_palette_entries; /* paletted formats only. set to zero for image without palettes */
1209     /*
1210      * Each component is one byte and entry_bytes indicates the number of components in
1211      * each entry (eg. 3 for YUV palette entries). set to zero for image without palettes
1212      */
1213     int entry_bytes;
1214     /*
1215      * An array of ascii characters describing teh order of the components within the bytes.
1216      * Only entry_bytes characters of the string are used.
1217      */
1218     char component_order[4];
1219
1220     /* chromakey range */
1221     unsigned int chromakey_min;
1222     unsigned int chromakey_max;
1223
1224     /* global alpha */
1225     unsigned int global_alpha;
1226
1227     /* flags */
1228     unsigned int flags; /* see below */
1229 } VASubpicture;
1230
1231 /* flags for subpictures */
1232 #define VA_SUBPICTURE_CHROMA_KEYING     0x0001
1233 #define VA_SUBPICTURE_GLOBAL_ALPHA      0x0002
1234
1235 /* Get maximum number of subpicture formats supported by the implementation */
1236 int vaMaxNumSubpictureFormats (
1237     VADisplay dpy
1238 );
1239
1240 /*
1241  * Query supported subpicture formats
1242  * The caller must provide a "format_list" array that can hold at
1243  * least vaMaxNumSubpictureFormats() entries. The flags arrary holds the flag
1244  * for each format to indicate additional capabilities for that format. The actual
1245  * number of formats returned in "format_list" is returned in "num_formats".
1246  */
1247 VAStatus vaQuerySubpictureFormats (
1248     VADisplay dpy,
1249     VAImageFormat *format_list, /* out */
1250     unsigned int *flags,        /* out */
1251     unsigned int *num_formats   /* out */
1252 );
1253
1254 /*
1255  * Subpictures are created with an image associated.
1256  */
1257 VAStatus vaCreateSubpicture (
1258     VADisplay dpy,
1259     VAImage *image,
1260     VASubpicture *subpicture    /* out */
1261 );
1262
1263 /*
1264  * Destroy the subpicture before destroying the image it is assocated to
1265  */
1266 VAStatus vaDestroySubpicture (
1267     VADisplay dpy,
1268     VASubpicture *subpicture
1269 );
1270
1271 /*
1272  * Bind an image to the subpicture. This image will now be associated with
1273  * the subpicture instead of the one at creation.
1274  */
1275 VAStatus vaSetSubpictureImage (
1276     VADisplay dpy,
1277     VASubpicture *subpicture,
1278     VAImage *image
1279 );
1280
1281 VAStatus vaSetSubpicturePalette (
1282     VADisplay dpy,
1283     VASubpicture *subpicture,
1284     /*
1285      * pointer to an array holding the palette data.  The size of the array is
1286      * num_palette_entries * entry_bytes in size.  The order of the components
1287      * in the palette is described by the component_order in VASubpicture struct
1288      */
1289     unsigned char *palette
1290 );
1291
1292 /*
1293  * If chromakey is enabled, then the area where the source value falls within
1294  * the chromakey [min, max] range is transparent
1295  */
1296 VAStatus vaSetSubpictureChromakey (
1297     VADisplay dpy,
1298     VASubpicture *subpicture,
1299     unsigned int chromakey_min,
1300     unsigned int chromakey_max
1301 );
1302
1303 /*
1304  * Global alpha value is between 0 and 1. A value of 1 means fully opaque and
1305  * a value of 0 means fully transparent. If per-pixel alpha is also specified then
1306  * the overall alpha is per-pixel alpha multiplied by the global alpha
1307  */
1308 VAStatus vaSetSubpictureGlobalAlpha (
1309     VADisplay dpy,
1310     VASubpicture *subpicture,
1311     float global_alpha
1312 );
1313
1314 /*
1315   vaAssociateSubpicture associates the subpicture with the target_surface.
1316   It defines the region mapping between the subpicture and the target
1317   surface through source and destination rectangles (with the same width and height).
1318   Both will be displayed at the next call to vaPutSurface.  Additional
1319   associations before the call to vaPutSurface simply overrides the association.
1320 */
1321 VAStatus vaAssociateSubpicture (
1322     VADisplay dpy,
1323     VASurface *target_surface,
1324     VASubpicture *subpicture,
1325     short src_x, /* upper left offset in subpicture */
1326     short src_y,
1327     short dest_x, /* upper left offset in surface */
1328     short dest_y,
1329     unsigned short width,
1330     unsigned short height,
1331     /*
1332      * whether to enable chroma-keying or global-alpha
1333      * see VA_SUBPICTURE_XXX values
1334      */
1335     unsigned int flags
1336 );
1337
1338 typedef struct _VARectangle
1339 {
1340     short x;
1341     short y;
1342     unsigned short width;
1343     unsigned short height;
1344 } VARectangle;
1345
1346 /*
1347  * Display attributes
1348  * Display attributes are used to control things such as contrast, hue, saturation,
1349  * brightness etc. in the rendering process.  The application can query what
1350  * attributes are supported by the driver, and then set the appropriate attributes
1351  * before calling vaPutSurface()
1352  */
1353
1354 /* Currently defined display attribute types */
1355 typedef enum
1356 {
1357     VADisplayAttribBrightness           = 0,
1358     VADisplayAttribContrast             = 1,
1359     VADisplayAttribHue                  = 2,
1360     VADisplayAttribSaturation           = 3,
1361 } VADisplayAttribType;
1362
1363 /* flags for VADisplayAttribute */
1364 #define VA_DISPLAY_ATTRIB_NOT_SUPPORTED 0x0000
1365 #define VA_DISPLAY_ATTRIB_GETTABLE      0x0001
1366 #define VA_DISPLAY_ATTRIB_SETTABLE      0x0002
1367
1368 typedef struct _VADisplayAttribute
1369 {
1370     VADisplayAttribType type;
1371     int min_value;
1372     int max_value;
1373     int value;  /* used by the set/get attribute functions */
1374 /* flags can be VA_DISPLAY_ATTRIB_GETTABLE or VA_DISPLAY_ATTRIB_SETTABLE or OR'd together */
1375     unsigned int flags;
1376 } VADisplayAttribute;
1377
1378 /* Get maximum number of display attributs supported by the implementation */
1379 int vaMaxNumDisplayAttributes (
1380     VADisplay dpy
1381 );
1382
1383 /*
1384  * Query display attributes
1385  * The caller must provide a "attr_list" array that can hold at
1386  * least vaMaxNumDisplayAttributes() entries. The actual number of attributes
1387  * returned in "attr_list" is returned in "num_attributes".
1388  */
1389 VAStatus vaQueryDisplayAttributes (
1390     VADisplay dpy,
1391     VADisplayAttribute *attr_list,      /* out */
1392     int *num_attributes                 /* out */
1393 );
1394
1395 /*
1396  * Get display attributes
1397  * This function returns the current attribute values in "attr_list".
1398  * Only attributes returned with VA_DISPLAY_ATTRIB_GETTABLE set in the "flags" field
1399  * from vaQueryDisplayAttributes() can have their values retrieved.
1400  */
1401 VAStatus vaGetDisplayAttributes (
1402     VADisplay dpy,
1403     VADisplayAttribute *attr_list,      /* in/out */
1404     int num_attributes
1405 );
1406
1407 /*
1408  * Set display attributes
1409  * Only attributes returned with VA_DISPLAY_ATTRIB_SETTABLE set in the "flags" field
1410  * from vaQueryDisplayAttributes() can be set.  If the attribute is not settable or
1411  * the value is out of range, the function returns VA_STATUS_ERROR_ATTR_NOT_SUPPORTED
1412  */
1413 VAStatus vaSetDisplayAttributes (
1414     VADisplay dpy,
1415     VADisplayAttribute *attr_list,
1416     int num_attributes
1417 );
1418
1419 #ifdef __cplusplus
1420 }
1421 #endif
1422
1423 #endif /* _VA_H_ */
1424
1425 #if 0
1426 /*****************************************************************************/
1427
1428 Sample Program (w/ pseudo code)
1429
1430 Mostly to demonstrate program flow with no error handling ...
1431
1432 /*****************************************************************************/
1433
1434         /* MPEG-2 VLD decode for a 720x480 frame */
1435
1436         int major_ver, minor_ver;
1437         vaInitialize(dpy, &major_ver, &minor_ver);
1438
1439         int max_num_profiles, max_num_entrypoints, max_num_attribs;
1440         max_num_profiles = vaMaxNumProfiles(dpy);
1441         max_num_entrypoints = vaMaxNumProfiles(dpy);
1442         max_num_attribs = vaMaxNumProfiles(dpy);
1443
1444         /* find out whether MPEG2 MP is supported */
1445         VAProfile *profiles = malloc(sizeof(VAProfile)*max_num_profiles);
1446         int num_profiles;
1447         vaQueryConfigProfiles(dpy, profiles, &profiles);
1448         /*
1449          * traverse "profiles" to locate the one that matches VAProfileMPEG2Main
1450          */
1451
1452         /* now get the available entrypoints for MPEG2 MP */
1453         VAEntrypoint *entrypoints = malloc(sizeof(VAEntrypoint)*max_num_entrypoints);
1454         int num_entrypoints;
1455         vaQueryConfigEntrypoints(dpy, VAProfileMPEG2Main, entrypoints, &num_entrypoints);
1456
1457         /* traverse "entrypoints" to see whether VLD is there */
1458
1459         /* Assuming finding VLD, find out the format for the render target */
1460         VAConfigAttrib attrib;
1461         attrib.type = VAConfigAttribRTFormat;
1462         vaGetConfigAttributes(dpy, VAProfileMPEG2Main, VAEntrypointVLD,
1463                                 &attrib, 1);
1464
1465         if (attrib.value & VA_RT_FORMAT_YUV420)
1466                 /* Found desired RT format, keep going */
1467
1468         VAConfigID config_id;
1469         vaCreateConfig(dpy, VAProfileMPEG2Main, VAEntrypointVLD, &attrib, 1,
1470                        &config_id);
1471
1472         /*
1473          * create surfaces for the current target as well as reference frames
1474          * we can get by with 4 surfaces for MPEG-2
1475          */
1476         VASurface surfaces[4];
1477         vaCreateSurfaces(dpy, 720, 480, VA_RT_FORMAT_YUV420, 4, surfaces);
1478
1479         /*
1480          * Create a context for this decode pipe
1481          */
1482         VAContext context;
1483         vaCreateContext(dpy, config_id, 720, 480, VA_PROGRESSIVE, surfaces,
1484                         4, &context);
1485
1486         /* Create a picture parameter buffer for this frame */
1487         VABufferID picture_buf;
1488         VAPictureParameterBufferMPEG2 *picture_param;
1489         vaCreateBuffer(dpy, VAPictureParameterBufferType, &picture_buf);
1490         vaBufferData(dpy, picture_buf, sizeof(VAPictureParameterBufferMPEG2), NULL);
1491         vaMapBuffer(dpy, picture_buf, &picture_param);
1492         picture_param->horizontal_size = 720;
1493         picture_param->vertical_size = 480;
1494         picture_param->picture_coding_type = 1; /* I-frame */
1495         /* fill in picture_coding_extension fields here */
1496         vaUnmapBuffer(dpy, picture_buf);
1497
1498
1499         /* Create an IQ matrix buffer for this frame */
1500         VABufferID iq_buf;
1501         VAIQMatrixBufferMPEG2 *iq_matrix;
1502         vaCreateBuffer(dpy, VAIQMatrixBufferType, &iq_buf);
1503         vaBufferData(dpy, iq_buf, sizeof(VAIQMatrixBufferMPEG2), NULL);
1504         vaMapBuffer(dpy, iq_buf, &iq_matrix);
1505         /* fill values for IQ_matrix here */
1506         vaUnmapBuffer(dpy, iq_buf);
1507
1508         /* send the picture and IQ matrix buffers to the server */
1509         vaBeginPicture(dpy, context, &surfaces[0]);
1510
1511         vaRenderPicture(dpy, context, &picture_buf, 1);
1512         vaRenderPicture(dpy, context, &iq_buf, 1);
1513
1514         /*
1515          * Send slices in this frame to the server.
1516          * For MPEG-2, each slice is one row of macroblocks, and
1517          * we have 30 slices for a 720x480 frame
1518          */
1519         for (int i = 1; i <= 30; i++) {
1520
1521                 /* Create a slice parameter buffer */
1522                 VABufferID slice_param_buf;
1523                 VASliceParameterBufferMPEG2 *slice_param;
1524                 vaCreateBuffer(dpy, VASliceParameterBufferType, &slice_param_buf);
1525                 vaBufferData(dpy, slice_param_buf, sizeof(VASliceParameterBufferMPEG2), NULL);
1526                 vaMapBuffer(dpy, slice_param_buf, &slice_param);
1527                 slice_param->slice_data_offset = 0;
1528                 /* Let's say all slices in this bit-stream has 64-bit header */
1529                 slice_param->macroblock_offset = 64;
1530                 slice_param->vertical_position = i;
1531                 /* set up the rest based on what is in the slice header ... */
1532                 vaUnmapBuffer(dpy, slice_param_buf);
1533
1534                 /* send the slice parameter buffer */
1535                 vaRenderPicture(dpy, context, &slice_param_buf, 1);
1536
1537                 /* Create a slice data buffer */
1538                 unsigned char *slice_data;
1539                 VABufferID slice_data_buf;
1540                 vaCreateBuffer(dpy, VASliceDataBufferType, slice_data_buf);
1541                 vaBufferData(dpy, slice_data_buf, x /* decoder figure out how big */, NULL);
1542                 vaMapBuffer(dpy, slice_data_buf, &slice_data);
1543                 /* decoder fill in slice_data */
1544                 vaUnmapBuffer(dpy, slice_data_buf);
1545
1546                 /* send the slice data buffer */
1547                 vaRenderPicture(dpy, context, &slice_data_buf, 1);
1548         }
1549
1550         /* all slices have been sent, mark the end for this frame */
1551         vaEndPicture(dpy, context);
1552
1553         /* The following code demonstrates rendering a sub-title with the target surface */
1554         /* Find out supported Subpicture formats */
1555         VAImageFormat sub_formats[4];
1556         int num_formats;
1557         vaQuerySubpictureFormats(dpy, sub_formats, &num_formats);
1558         /* Assume that we find AI44 as a subpicture format in sub_formats[0] */
1559         VAImage sub_image;
1560         VASubpicture subpicture;
1561         unsigned char sub_data[128][16];
1562         /* create an image for the subtitle */
1563         vaCreateImage(dpy, sub_formats, 128, 16, &sub_image);
1564         vaCreateBuffer(dpy, VAImageBufferType, &sub_image->buf);
1565         /* fill the image data */
1566         vaBufferData(dpy, sub_image->buf, sub_image->data_size, sub_data);
1567         vaCreateSubpicture(dpy, &sub_image, &subpicture);
1568         unsigned char palette[3][16];
1569         /* fill the palette data */
1570         vaSetSubpicturePalette(dpy, &subpicture, palette);
1571         vaAssociateSubpicture(dpy, surfaces, &subpicture, 0, 0, 296, 400, 128, 16);
1572         vaPutSurface(dpy, surfaces, win, 0, 0, 720, 480, 100, 100, 640, 480, NULL, 0, 0);
1573 #endif