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