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