va/va.h

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