va/va.h

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