src/va.h

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