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