XvMC_API.txt

   1
   2    X-Video Motion Compensation - API specification v. 1.0
   3
   4    Mark Vojkovich <markv@xfree86.org>
   5
   6
   7 /* history */
   8
   9    first draft (9/6/00)
  10    second draft (10/31/00) - Changed to allow acceleration at both
  11       the motion compensation and IDCT level.
  12    third draft (1/21/01) - Some refinements and subpicture support.
  13    fourth draft (5/2/01) - Dual Prime clarification, add
  14       XvMCSetAttribute.
  15    fifth draft (6/26/01) - Change definition of XvMCCompositeSubpicture
  16       plus some clarifications and fixed typographical errors.
  17    sixth draft (9/24/01) - Added XVMC_SECOND_FIELD and removed
  18       XVMC_PROGRESSIVE_FRAME and XVMC_TOP_FIELD_FIRST flags.
  19    seventh draft (10/26/01) - Added XVMC_INTRA_UNSIGNED option.
  20    eighth draft (11/13/02) - Removed IQ level acceleration and
  21       changed some structures to remove unused fields.
  22
  23 /* acknowledgements */
  24
  25    Thanks to Matthew J. Sottek from Intel for lots of input.
  26
  27 /********************************************************************/
  28
  29       OVERVIEW
  30
  31 /********************************************************************/
  32
  33      XvMC extends the X-Video extension (Xv) and makes use of the
  34   familar concept of the XvPort.  Ports have attributes that can be set
  35   and queried through Xv.  In XvMC ports can also have hardware motion
  36   compensation contexts created for use with them.  Ports which support
  37   XvImages (ie. they have an "XV_IMAGE" port encoding as described in
  38   the Xv version 2.2 API addendum) can be queried for the list of XvMCSurface
  39   types they support.  If they support any XvMCSurface types an
  40   XvMCContext can be created for that port.
  41
  42      An XvMCContext describes the state of the motion compensation
  43   pipeline.  An individual XvMCContext can be created for use with
  44   a single port, surface type, motion compensation type, width and
  45   height combination.  For example, a context might be created for a
  46   particular port that does MPEG-2 motion compensation on 720 x 480
  47   4:2:0 surfaces.  Once the context is created, referencing it implies
  48   the port, surface type, size and the motion compensation type.  Contexts
  49   may be "direct" or "indirect".  For indirect contexts the X server
  50   renders all video using the data passed to it by the client.  For
  51   direct contexts the client libraries render the video with little
  52   or no interaction with the X server.
  53
  54      XvMCSurfaces are buffers into which the motion compensation
  55   hardware can render.  The data in the buffers themselves are not client
  56   accessible and may be stored in a hardware-specific format.  Any
  57   number of buffers can be created for use with a particular context
  58   (resources permitting).
  59
  60      XvMC provides video acceleration starting at one of two places
  61   in the video pipeline.  Acceleration starting at the first point,
  62   which we shall call the "Motion Compensation" level, begins after the
  63   the inverse quantization and IDCT at the place where motion compensation
  64   is to be applied.  The second point, which we shall call the "IDCT"
  65   level, begins before the IDCT just after the inverse quantization.
  66
  67      Rendering is done by presenting the library with a target XvMCSurface
  68   and up to two reference XvMCSurfaces for the motion compensation, a
  69   buffer of 8x8 blocks and a command buffer which describes how to
  70   use the 8x8 blocks along with motion compensation vectors to construct
  71   the data in the target XvMCSurface.  When the pipeline starts at the
  72   IDCT level, Xv will perform the IDCT on the blocks before performing
  73   the motion compensation. A function is provided to copy/overlay a
  74   portion of the XvMCSurface to a drawable with arbitrary scaling.
  75
  76     XvMCSubpictures are separate surfaces that may be blended with the
  77   target surface.  Any number of XvMCSubpictures may be created for use
  78   with a context (resources permitting).  Both "backend" and "frontend"
  79   subpicture behavior are supported.
  80
  81 /********************************************************************/
  82
  83           QUERYING THE EXTENSION
  84
  85 /********************************************************************/
  86
  87 /* Errors */
  88 #define XvMCBadContext          0
  89 #define XvMCBadSurface          1
  90 #define XvMCBadSubpicture       2
  91
  92 Bool XvMCQueryExtension (Display *display, int *eventBase, int *errBase)
  93
  94    Returns True if the extension exists, False otherwise.  Also returns
  95  the error and event bases.
  96
  97    display - The connection to the server.
  98
  99    eventBase -
 100    errBase -  The returned event and error bases.  Currently there
 101               are no events defined.
 102
 103 Status XvMCQueryVersion (Display *display, int *major, int *minor)
 104
 105    Query the major and minor version numbers of the extension.
 106
 107    display - The connection to the server.
 108
 109    major -
 110    minor -  The returned major and minor version numbers.
 111
 112 /********************************************************************/
 113
 114           QUERYING SURFACE TYPES
 115
 116 /********************************************************************/
 117
 118 /* Chroma formats */
 119 #define XVMC_CHROMA_FORMAT_420          0x00000001
 120 #define XVMC_CHROMA_FORMAT_422          0x00000002
 121 #define XVMC_CHROMA_FORMAT_444          0x00000003
 122
 123 /* XvMCSurfaceInfo Flags */
 124 #define XVMC_OVERLAID_SURFACE                   0x00000001
 125 #define XVMC_BACKEND_SUBPICTURE                 0x00000002
 126 #define XVMC_SUBPICTURE_INDEPENDENT_SCALING     0x00000004
 127 #define XVMC_INTRA_UNSIGNED                     0x00000008
 128
 129 /* Motion Compensation types */
 130 #define XVMC_MOCOMP                     0x00000000
 131 #define XVMC_IDCT                       0x00010000
 132
 133 #define XVMC_MPEG_1                     0x00000001
 134 #define XVMC_MPEG_2                     0x00000002
 135 #define XVMC_H263                       0x00000003
 136 #define XVMC_MPEG_4                     0x00000004
 137
 138
 139 typedef struct {
 140    int surface_type_id;
 141    int chroma_format;
 142    unsigned short max_width;
 143    unsigned short max_height;
 144    unsigned short subpicture_max_width;
 145    unsigned short subpicture_max_height;
 146    int mc_type;
 147    int flags;
 148 } XvMCSurfaceInfo;
 149
 150    surface_type_id - Unique descriptor for this surface type.
 151
 152    chroma_format - Chroma format of this surface (eg. XVMC_CHROMA_FORMAT_420,
 153                 XVMC_CHROMA_FORMAT_422, XVMC_CHROMA_FORMAT_444).
 154
 155    max_width -
 156    max_height -  Maximum dimensions of the luma data in pixels.
 157
 158    subpicture_max_width -
 159    subpicture_max_height -  The Maximum dimensions of the subpicture
 160                             that can be created for use with this surface
 161                             Both fields are zero if subpictures are not
 162                             supported.
 163
 164    mc_type -  The type of motion compensation available for this
 165               surface.  This consists of XVMC_MPEG_1, XVMC_MPEG_2, XVMC_H263
 166               or XVMC_MPEG_4 OR'd together with any of the following:
 167
 168                  XVMC_MOCOMP - Acceleration starts at the motion compensation
 169                                level;
 170
 171                  XVMC_IDCT - Acceleration starts at the IDCT level.
 172
 173    flags -  Any combination of the following may be OR'd together.
 174
 175         XVMC_OVERLAID_SURFACE - Displayed data is overlaid and not
 176                                 physically in the visible framebuffer.
 177                                 When this is set the client is responsible
 178                                 for painting the colorkey.
 179
 180         XVMC_BACKEND_SUBPICTURE - The supicture is of the "backend"
 181                                   variety.  It is "frontend" otherwise.
 182                                   There is more information on this in the
 183                                   section on subpictures below.
 184
 185         XVMC_SUBPICTURE_INDEPENDENT_SCALING - The subpicture can be scaled
 186                                               independently of the video
 187                                               surface.  See the section on
 188                                               subpictures below.
 189
 190         XVMC_INTRA_UNSIGNED - When this flag is set, the motion compenstation
 191                               level Intra macroblock data should be in an
 192                               unsigned format rather than the signed format
 193                               present in the mpeg stream.  This flag applies
 194                               only to motion compensation level acceleration.
 195
 196 XvMCSurfaceInfo * XvMCListSurfaceTypes(Display *dpy, XvPortID port, int *num)
 197
 198    Returns the number of surface types supported by the XvPort and an array
 199    of XvMCSurfaceInfo describing each surface type.  The returned array
 200    should be freed with XFree().
 201
 202    dpy -  The connection to the server.
 203
 204    port - The port we want to get the XvMCSurfaceInfo array for.
 205
 206    num  - The number of elements returned in the array.
 207
 208    Errors:
 209
 210       XvBadPort -  The requested port does not exist.
 211
 212       BadAlloc - There are insufficient resources to complete this request.
 213
 214
 215 /********************************************************************/
 216
 217           CREATING A CONTEXT
 218
 219 /********************************************************************/
 220
 221 /* XvMCContext flags */
 222 #define XVMC_DIRECT                     0x00000001
 223
 224 typedef struct {
 225    XID context_id;
 226    int surface_type_id;
 227    unsigned short width;
 228    unsigned short height;
 229    XVPortID port;
 230    int flags;
 231    void * privData;  /* private to the library */
 232 } XvMCContext;
 233
 234    context_id - An XID associated with the context.
 235
 236    surface_type_id - This refers to the XvMCSurfaceInfo that describes
 237                      the surface characteristics.
 238
 239    width -
 240    height -  The dimensions (of the luma data) this context supports.
 241
 242    port -  The port that this context supports.
 243
 244    flags -  Any combination may be OR'd together.
 245
 246         XVMC_DIRECT -  This context is direct rendered.
 247
 248
 249 Status XvMCCreateContext (
 250    Display display,
 251    XVPortID port,
 252    int surface_type_id,
 253    int width,
 254    int height,
 255    int flags,
 256    XvMCContext * context
 257 );
 258
 259    This creates a context by filling out the XvMCContext structure passed
 260    to it and returning Success.
 261
 262    display -  Specifies the connection to the server.
 263
 264    port -  Specifies the port to create the context for.
 265
 266    surface_type_id -
 267    width -
 268    height -  Specifies the surface type and dimensions that this
 269              context will be used for.  The surface_type_id corresponds
 270              to the surface_type_id referenced by the XvMCSurfaceInfo.
 271              The surface returned may be larger than the surface requested
 272              (usually the next larger multiple of 16x16 pixels).
 273
 274    flags -  Any of the following may by OR'd together:
 275
 276          XVMC_DIRECT -  A direct context is requested.
 277                         If a direct context cannot be created the request
 278                         will not fail, rather, an indirect context will
 279                         be created instead.
 280
 281    context - Pointer to the pre-allocated XvMCContext structure.
 282
 283
 284
 285    Errors:
 286
 287       XvBadPort -  The requested port does not exist.
 288
 289       BadValue -  The dimensions requested are not supported by the
 290                   surface type.
 291
 292       BadMatch -  The surface_type_id is not supported by the port.
 293
 294       BadAlloc -  There are not sufficient resources to fulfill this
 295                   request.
 296
 297
 298 Status XvMCDestroyContext (Display display, XvMCContext * context)
 299
 300      Destroys the specified context.
 301
 302       display - Specifies the connection to the server.
 303
 304       context - The context to be destroyed.
 305
 306      Errors:
 307
 308        XvMCBadContext - The XvMCContext is not valid.
 309
 310
 311 /*********************************************************************/
 312
 313           SURFACE CREATION
 314
 315 /*********************************************************************/
 316
 317 typedef struct {
 318   XID surface_id;
 319   XID context_id;
 320   int surface_type_id;
 321   unsigned short width;
 322   unsigned short height;
 323   void *privData;  /* private to the library */
 324 } XvMCSurface;
 325
 326   surface_id -  An XID associated with the surface.
 327
 328   context_id -  The XID of the context for which the surface was created.
 329
 330   surface_type_id - Derived from the context_id, it specifies the
 331                     XvMCSurfaceInfo describing the surface.
 332
 333   width -
 334   height -  The width and height of the luma data.
 335
 336
 337 Status
 338 XvMCCreateSurface(
 339   Display *display,
 340   XvMCContext * context;
 341   XvMCSurface * surface;
 342 );
 343
 344      Creates a surface (Frame) for use with the specified context.
 345    The surface structure is filled out and Success is returned if no
 346    error occured.
 347
 348    context - pointer to a valid context.  The context implies
 349              the surface type to be created, and its dimensions.
 350
 351    surface - pointer to a pre-allocated XvMCSurface structure.
 352
 353    Errors:
 354
 355         XvMCBadContext - the context is not valid.
 356
 357         BadAlloc - there are insufficient resources to complete
 358                    this operation.
 359
 360 Status XvMCDestroySurface(Display *display, XvMCSurface *surface);
 361
 362    Destroys the given surface.
 363
 364     display - Specifies the connection to the server.
 365
 366     surface - The surface to be destroyed.
 367
 368     Errors:
 369
 370        XvMCBadSurface - The XvMCSurface is not valid.
 371
 372
 373
 374 /*********************************************************************/
 375
 376     RENDERING A FRAME
 377
 378 /*********************************************************************/
 379
 380 typedef struct {
 381   XID context_id;
 382   unsigned int num_blocks;
 383   short *blocks;
 384   void *privData;       /* private to the library */
 385 } XvMCBlockArray;
 386
 387    num_blocks - Number of 64 element blocks in the blocks array.
 388
 389    context_id - XID of the context these blocks were allocated for.
 390
 391    blocks -  Pointer to an array of (64 * num_blocks) shorts.
 392
 393 Status XvMCCreateBlocks (
 394     Display *display,
 395     XvMCContext *context,
 396     unsigned int num_blocks,
 397     XvMCBlockArray * block
 398 );
 399
 400    This allocates an array of DCT blocks in the XvMCBlockArray
 401    structure passed to it.  Success is returned if no error occured.
 402
 403     display - The connection to the server.
 404
 405     context -  The context the block array is being created for.
 406
 407     num_blocks - The number of 64 element short blocks to be allocated.
 408                  This number must be non-zero.
 409
 410     block -  A pointer to a pre-allocated XvMCBlockArray structure.
 411
 412       Errors:
 413
 414           XvMCBadContext - the context is invalid.
 415
 416           BadAlloc -  There are insufficient resources to complete the
 417                       operation.
 418
 419           BadValue -  num_blocks was zero.
 420
 421 Status XvMCDestroyBlocks (Display *display, XvMCBlockArray * block)
 422
 423    Frees the given array.
 424
 425      display -  The connection to the server.
 426
 427      block - The block array to be freed.
 428
 429
 430    ----------------------------------------------------------
 431
 432 #define XVMC_MB_TYPE_MOTION_FORWARD     0x02
 433 #define XVMC_MB_TYPE_MOTION_BACKWARD    0x04
 434 #define XVMC_MB_TYPE_PATTERN            0x08
 435 #define XVMC_MB_TYPE_INTRA              0x10
 436
 437 #define XVMC_PREDICTION_FIELD           0x01
 438 #define XVMC_PREDICTION_FRAME           0x02
 439 #define XVMC_PREDICTION_DUAL_PRIME      0x03
 440 #define XVMC_PREDICTION_16x8            0x02
 441 #define XVMC_PREDICTION_4MV             0x04
 442
 443 #define XVMC_SELECT_FIRST_FORWARD       0x01
 444 #define XVMC_SELECT_FIRST_BACKWARD      0x02
 445 #define XVMC_SELECT_SECOND_FORWARD      0x04
 446 #define XVMC_SELECT_SECOND_BACKWARD     0x08
 447
 448 #define XVMC_DCT_TYPE_FRAME             0x00
 449 #define XVMC_DCT_TYPE_FIELD             0x01
 450
 451 typedef struct {
 452    unsigned short x;
 453    unsigned short y;
 454    unsigned char macroblock_type;
 455    unsigned char motion_type;
 456    unsigned char motion_vertical_field_select;
 457    unsigned char dct_type;
 458    short PMV[2][2][2];
 459    unsigned int index;
 460    unsigned short coded_block_pattern;
 461    unsigned short pad0;
 462 } XvMCMacroBlock;
 463
 464     x, y -  location of the macroblock on the surface in units of macroblocks.
 465
 466     macroblock_type - can be any of the following flags OR'd together:
 467
 468         XVMC_MB_TYPE_MOTION_FORWARD - Forward motion prediction should
 469                                       be done.  This flag is ignored for
 470                                       Intra frames.
 471
 472         XVMC_MB_TYPE_MOTION_BACKWARD - Backward motion prediction should
 473                                        be done.  This flag is ignored when
 474                                        the frame is not bidirectionally
 475                                        predicted.
 476
 477         XVMC_MB_TYPE_PATTERN -  Blocks are referenced and they contain
 478                                 differentials.  The coded_block_pattern will
 479                                 indicate the number of blocks and index will
 480                                 note their locations in the block array.
 481
 482         XVMC_MB_TYPE_INTRA -  Blocks are referenced and they are intra blocks.
 483                               The coded_block_pattern will indicate the number
 484                               of blocks and index will note their locations in
 485                               the block array.  XVMC_MB_TYPE_PATTERN and
 486                               XVMC_MB_TYPE_INTRA are mutually exclusive.  If
 487                               both are specified, XVMC_MB_TYPE_INTRA takes
 488                               precedence.
 489
 490     motion_type -  If the surface is a field, the following are valid:
 491                         XVMC_PREDICTION_FIELD
 492                         XVMC_PREDICTION_16x8
 493                         XVMC_PREDICTION_DUAL_PRIME
 494                    If the surface is a frame, the following are valid:
 495                         XVMC_PREDICTION_FIELD
 496                         XVMC_PREDICTION_FRAME
 497                         XVMC_PREDICTION_DUAL_PRIME
 498
 499     motion_vertical_field_select - The following flags may be OR'd together
 500
 501                 XVMC_SELECT_FIRST_FORWARD
 502                 XVMC_SELECT_FIRST_BACKWARD
 503                 XVMC_SELECT_SECOND_FORWARD
 504                 XVMC_SELECT_SECOND_BACKWARD
 505
 506               If the bit is set the bottom field is indicated.
 507               If the bit is clear the top field is indicated.
 508
 509               X X X X D C B A
 510               ------- | | | |_  First vector forward
 511                 |     | | |___  First vector backward
 512               unused  | |_____ Second vector forward
 513                       |_______ Second vector backward
 514
 515     PMV -  The motion vector(s)
 516
 517                PMV[c][b][a]
 518
 519                   a - This holds the vector. 0 = horizontal, 1 = vertical.
 520                   b - 0 = forward, 1 = backward.
 521                   c - 0 = first vector, 1 = second vector.
 522
 523             The motion vectors are used only when XVMC_MB_TYPE_MOTION_FORWARD
 524             or XVMC_MB_TYPE_MOTION_BACKWARD are set.
 525
 526             DualPrime vectors must be fully decoded and placed in the PMV
 527             array as follows.
 528
 529             Field structure:
 530
 531                 PMV[0][0][1:0]  from same parity
 532                 PMV[0][1][1:0]  from opposite parity
 533
 534             Frame structure:
 535
 536                 PMV[0][0][1:0]  top from top
 537                 PMV[0][1][1:0]  bottom from bottom
 538                 PMV[1][0][1:0]  top from bottom
 539                 PMV[1][1][1:0]  bottom from top
 540
 541
 542     index -  The offset in units of (64 * sizeof(short)) from the start of
 543              the block array where this macroblock's DCT blocks, as indicated
 544              by the coded_block_pattern, are stored.
 545
 546     coded_block_pattern - Indicates the blocks to be updated.  The bitplanes
 547                           are specific to the mc_type of the surface.  This
 548                           field is valid only if XVMC_MB_TYPE_PATTERN or
 549                           XVMC_MB_TYPE_INTRA are set.  In that case the blocks
 550                           are differential or intra blocks respectively.
 551                           The bitplanes are described in ISO/IEC 13818-2
 552                           Figures 6.10-12.
 553
 554     dct_type -  This field indicates whether frame pictures are frame DCT
 555                 coded or field DCT coded. ie XVMC_DCT_TYPE_FIELD or
 556                 XVMC_DCT_TYPE_FRAME.
 557
 558
 559 typedef struct {
 560   unsigned int num_blocks;
 561   XID context_id;
 562   XvMCMacroBlock *macro_blocks;
 563   void *privData;       /* private to the library */
 564 } XvMCMacroBlockArray;
 565
 566
 567    num_blocks - Number of XvMCMacroBlocks in the macro_blocks array.
 568
 569    context_id - XID of the context these macroblocks were allocated for.
 570
 571    macro_blocks -  Pointer to an array of num_blocks XvMCMacroBlocks.
 572
 573
 574 Status XvMCCreateMacroBlocks (
 575     Display *display,
 576     XvMCContext *context,
 577     unsigned int num_blocks,
 578     XvMCMacroBlockArray * blocks
 579 );
 580
 581    This allocates an array of XvMCMacroBlocks in the XvMCMacroBlockArray
 582    structure passed to it.  Success is returned if no error occured.
 583
 584     display - The connection to the server.
 585
 586     context -  The context the macroblock array is being created for.
 587
 588     num_blocks - The number of XvMCMacroBlocks to be allocated.
 589                  This number must be non-zero.
 590
 591     blocks -  A pointer to a pre-allocated XvMCMacroBlockArray structure.
 592
 593       Errors:
 594
 595           XvMCBadContext - the context is invalid.
 596
 597           BadAlloc -  There are insufficient resources to complete the
 598                       operation.
 599
 600           BadValue -  num_blocks was zero.
 601
 602 Status XvMCDestroyMacroBlocks (Display *display, XvMCMacroBlockArray * block)
 603
 604    Frees the given array.
 605
 606     display - The connection to the server.
 607
 608     block -  The macro block array to be freed.
 609
 610
 611     ------------------------------------------------------------
 612
 613 #define XVMC_TOP_FIELD          0x00000001
 614 #define XVMC_BOTTOM_FIELD       0x00000002
 615 #define XVMC_FRAME_PICTURE      (XVMC_TOP_FIELD | XVMC_BOTTOM_FIELD)
 616
 617 #define XVMC_SECOND_FIELD       0x00000004
 618
 619 Status XvMCRenderSurface(
 620     Display *display,
 621     XvMCContext *context,
 622     unsigned int picture_structure,
 623     Surface *target_surface,
 624     Surface *past_surface,
 625     Surface *future_surface,
 626     unsigned int flags,
 627     unsigned int num_macroblocks,
 628     unsigned int first_macroblock,
 629     XvMCMacroBlockArray *macroblock_array,
 630     XvMCBlockArray *blocks
 631 );
 632
 633     This function renders the macroblocks passed to it.  It will not
 634     return until it has read all of the macroblocks, however, rendering
 635     will usually not be completed by that time.  The return of this
 636     function means it is safe to touch the blocks and macroblock_array.
 637     To synchronize rendering see the section on sychronization below.
 638
 639     display - The connection to the server.
 640
 641     context - The context used to render.
 642
 643     target_surface -
 644     past_surface -
 645     furture_surface -
 646
 647         The target_surface is required.  If the future and past
 648       surfaces are NULL, the target_surface is an "Intra" frame.
 649
 650         If the past surface is provided but not the future surface,
 651       the target_surface is a "Predicted Inter" frame.
 652
 653         If both past and future surfaces are provided, the
 654       target_surface is a "Bidirectionally-predicted Inter" frame.
 655
 656         Specifying a future surface without a past surface results
 657       in a BadMatch.
 658
 659       All surfaces must belong to the same context.
 660
 661     picture_structure - XVMC_TOP_FIELD, XVMC_BOTTOM_FIELD or
 662                         XVMC_FRAME_PICTURE.
 663
 664
 665     flags -  Flags may include:
 666
 667             XVMC_SECOND_FIELD - For field pictures this indicates whether
 668                                 the current field (top or bottom) is first
 669                                 or second in the sequence.
 670
 671     num_macroblocks -  The number of XvMCMacroBlock structures to execute in
 672                        the macroblock_array.
 673
 674     first_macroblock - The index of the first XvMCMacroBlock to process in the
 675                        macroblock_array.
 676
 677     blocks - The array of XvMCBlocks to be referenced by the XvMCMacroBlocks.
 678              The data in the individual blocks are in raster scan order and
 679              should be clamped to the limits specific to the acceleration
 680              level.  For motion compensation level acceleration this is 8
 681              bits for Intra and 9 bits for non-Intra data.  At the IDCT level
 682              this is 12 bits.
 683
 684   Errors:
 685
 686         XvMCBadContext - The context is not valid.
 687
 688         XvMCBadSurface - Any of the surfaces are not valid.
 689
 690         BadMatch - Any of the surfaces do not belong to the specified
 691                    context or a future surface was specified without
 692                    a past surface.
 693
 694         BadValue - Unrecognized data for the picture_structure.
 695
 696
 697 /***********************************************************************/
 698
 699      DISPLAYING THE SURFACE
 700
 701 /***********************************************************************/
 702
 703
 704 Status
 705 XvMCPutSurface(
 706   Display *display,
 707   XvMCSurface *surface,
 708   Drawable draw,
 709   short srcx,
 710   short srcy,
 711   unsigned short srcw,
 712   unsigned short srch,
 713   short destx,
 714   short desty,
 715   unsigned short destw,
 716   unsigned short desth,
 717   int flags
 718 );
 719
 720    Display the rectangle from the source defined by srcx/y/w/h scaled
 721  to destw by desth and placed at (destx, desty) on the given drawable.
 722  This function is not guaranteed to be pipelined with previous rendering
 723  commands and may display the surface immediately.  Therefore, the client
 724  must query that the surface has finished rendering before calling this
 725  function.
 726
 727     display - The connection to the server.
 728
 729     surface - The surface to copy/overlay from.
 730
 731     draw - The drawable to copy/overlay the video on.
 732
 733     srcx -
 734     srcy -
 735     srcw -
 736     srch -  The rectangle in the source area from the surface that is
 737             to be displayed.
 738
 739     destx -
 740     desty -
 741     destw -
 742     desth -  The rectangle in the destination drawable where the scaled
 743              source rectangle should be displayed.
 744
 745     flags - this indicates the field to be displayed and can be XVMC_TOP_FIELD,
 746             XVMC_BOTTOM_FIELD or XVMC_FRAME_PICTURE.  XVMC_FRAME_PICTURE
 747             displays both fields (weave).
 748
 749    Errors:
 750
 751        XvMCBadSurface - The surface is not valid.
 752
 753        BadDrawable -  The drawable does not exist.
 754
 755
 756 Status XvMCHideSurface(Display *display, XvMCSurface *surface)
 757
 758    Stops display of a surface.  This is only needed if the surface is an
 759    overlaid surface as indicated in the XvMCSurfaceInfo - it is a no-op
 760    otherwise.
 761
 762      display - The connection to the server.
 763
 764      surface - The surface to be hidden.
 765
 766       Errors:
 767
 768           XvMCBadSurface - The surface is not valid.
 769
 770
 771 /***********************************************************************/
 772
 773      COMPOSITING THE SUBPICTURE
 774
 775 /***********************************************************************/
 776
 777
 778 XvImageFormatValues * XvMCListSubpictureTypes (
 779   Display * display,
 780   XvPortID port,
 781   int surface_type_id,
 782   int *count_return
 783 )
 784
 785   Returns an array of XvImageFormatValues supported by the surface_type_id
 786   describing the surface. The surface_type_id is acquired from the
 787   XvMCSurfaceInfo.  This list should be freed with XFree().
 788
 789    display - Specifies the connection to the X-server.
 790
 791    port - Specifies the port we are interested in.
 792
 793    surface_type_id - Specifies the surface type for which we want to
 794                      query the supported subpicture types.
 795
 796    count_return - the size of the returned array.
 797
 798    Errors:
 799
 800       BadPort -  The port doesn't exist.
 801
 802       BadAlloc - There are insufficient resources to complete this request.
 803
 804       BadMatch - The surface type is not supported on that port.
 805
 806
 807 typedef struct {
 808   XID subpicture_id;
 809   XID context_id;
 810   int xvimage_id;
 811   unsigned short width;
 812   unsigned short height;
 813   int num_palette_entries;
 814   int entry_bytes;
 815   char component_order[4];
 816   void *privData;    /* private to the library */
 817 } XvMCSubpicture;
 818
 819
 820    subpicture_id - An XID associated with this subpicture.
 821
 822    context_id - The XID of the context this subpicture was created for.
 823
 824    xvimage_id - The id descriptor of the XvImage format that may be used
 825                 with this subpicture.
 826
 827    width -
 828    height - The dimensions of the subpicture.
 829
 830    num_palette_entries - For paletted formats only.  This is the number
 831                          of palette entries.  It is zero for XvImages
 832                          without palettes.
 833
 834    entry_bytes -  Each component is one byte and entry_bytes indicates
 835                   the number of components in each entry (eg. 3 for
 836                   YUV palette entries).  This field is zero when
 837                   palettes are not used.
 838
 839    component_order - Is an array of ascii characters describing the order
 840                      of the components within the bytes.  Only entry_bytes
 841                      characters of the string are used.
 842
 843 Status
 844 XvMCCreateSubpicture (
 845    Display *display,
 846    XvMCContext *context,
 847    XvMCSubpicture *subpicture,
 848    unsigned short width,
 849    unsigned short height,
 850    int xvimage_id
 851 )
 852
 853    This creates a subpicture by filling out the XvMCSubpicture structure
 854    passed to it and returning Success.
 855
 856     display -  Specifies the connection to the X-Server.
 857
 858     context -  The context to create the subpicture for.
 859
 860     subpicture - Pre-allocated XvMCSubpicture structure to be filled
 861                  out by this function.
 862
 863     width -
 864     height -  The dimensions of the subpicture.
 865
 866     xvimage_id - The id describing the XvImage format.
 867
 868
 869     Errors:
 870
 871       BadAlloc - There are insufficient resources to complete this request.
 872
 873       XvMCBadContext - The specified context does not exist.
 874
 875       BadMatch - The XvImage format id specified is not supported by
 876                  the context.
 877
 878       BadValue - If the size requested is larger than the max size reported
 879                  in the XvMCSurfaceInfo.
 880
 881
 882 Status
 883 XvMCClearSubpicture (
 884   Display *display,
 885   XvMCSubpicture *subpicture,
 886   short x,
 887   short y,
 888   unsigned short width,
 889   unsigned short height,
 890   unsigned int color
 891 )
 892
 893     Clear the area of the given subpicture to "color".
 894
 895     display - The connection to the server.
 896
 897     subpicture - The subpicture to clear.
 898
 899     x -
 900     y -
 901     width -
 902     height -  The rectangle in the subpicture to be cleared.
 903
 904     color -  The data to fill the rectangle with.
 905
 906     Errors:
 907
 908        XvMCBadSubpicture - The subpicture is invalid.
 909
 910 Status
 911 XvMCCompositeSubpicture (
 912    Display *display,
 913    XvMCSubpicture *subpicture,
 914    XvImage *image,
 915    short srcx,
 916    short srcy,
 917    unsigned short width,
 918    unsigned short height,
 919    short dstx,
 920    short dsty
 921 )
 922
 923     Copies the XvImage to the XvMCSubpicture.
 924
 925     display -  The connection to the server.
 926
 927     subpicture -  The subpicture used as the destination of the copy.
 928
 929     image -  The XvImage to be used as the source of the copy.
 930              XvImages should be of the shared memory variety for
 931              indirect contexts.
 932
 933     srcx -
 934     srcy -
 935     width -
 936     height -  The rectangle from the image to be composited.
 937
 938     dstx -
 939     dsty -  The location in the subpicture where the source rectangle
 940             should be composited.
 941
 942     Errors:
 943
 944        XvMCBadSubpicture - The subpicture is invalid.
 945
 946        BadMatch -  The subpicture does not support the type of XvImage
 947                    passed to this function.
 948
 949 Status
 950 XvMCDestroySubpicture (Display *display, XvMCSubpicture *subpicture)
 951
 952    Destroys the specified subpicture.
 953
 954    display - Specifies the connection to the X-server.
 955
 956    subpicture - The subpicture to be destroyed.
 957
 958    Errors:
 959
 960       XvMCBadSubpicture -  The subpicture specified does not exist.
 961
 962
 963 Status
 964 XvMCSetSubpicturePalette (
 965   Display *display,
 966   XvMCSubpicture *subpicture,
 967   unsigned char *palette
 968 )
 969
 970    Set the subpicture's palette.  This applies to paletted subpictures
 971    only.
 972
 973     display -  The connection to the server.
 974
 975     subpicture - The subpicture on which to change the palette.
 976
 977     palette -  A pointer to an array holding the palette data.  The
 978                size of this array is
 979
 980                    num_palette_entries * entry_bytes
 981
 982                in size.  The order of the components in the palette
 983                is described by the component_order in the XvMCSubpicture
 984                structure.
 985
 986     Errors:
 987
 988       XvMCBadSubpicture -  The subpicture specified does not exist.
 989
 990       BadMatch -  The specified subpicture does not use palettes.
 991
 992
 993 Status
 994 XvMCBlendSubpicture (
 995    Display *display,
 996    XvMCSurface *target_surface,
 997    XvMCSubpicture *subpicture,
 998    short subx,
 999    short suby,
1000    unsigned short subw,
1001    unsigned short subh,
1002    short surfx,
1003    short surfy,
1004    unsigned short surfw,
1005    unsigned short surfh
1006 )
1007
1008 Status
1009 XvMCBlendSubpicture2 (
1010    Display *display,
1011    XvMCSurface *source_surface,
1012    XvMCSurface *target_surface,
1013    XvMCSubpicture *subpicture,
1014    short subx,
1015    short suby,
1016    unsigned short subw,
1017    unsigned short subh,
1018    short surfx,
1019    short surfy,
1020    unsigned short surfw,
1021    unsigned short surfh
1022 )
1023
1024    The behavior of these two functions is different depending on whether
1025 or not the XVMC_BACKEND_SUBPICTURE flag is set in the XvMCSurfaceInfo.
1026
1027  XVMC_BACKEND_SUBPICTURE set:
1028
1029     XvMCBlendSubpicture associates the subpicture with the target_surface.
1030   Both will be displayed at the next call to XvMCPutSurface.  Additional
1031   blends before the call to XvMCPutSurface simply overrides the association.
1032   Both the target_surface and subpicture will query XVMC_DISPLAYING from
1033   the call to XvMCPutSurface until they are no longer displaying.  It is
1034   safe to associate the subpicture and target_surface before rendering has
1035   completed (while they still query XVMC_RENDERING) but it is not safe to
1036   call XvMCPutSurface at that time.
1037
1038     XvMCBlendSubpicture2 copies the source_surface to the target_surface
1039   and associates the subpicture with the target_surface.  This essentially
1040   calls XvMCBlendSubpicture on the target_surface after the copy.  Both
1041   the subpicture and target_surface will query XVMC_DISPLAYING from the
1042   call to XvMCPutSurface until they are no longer displaying.  The
1043   source_surface will not query XVMC_DISPLAYING as a result of this function.
1044   The copy is pipelined with the rendering and will cause XVMC_RENDERING
1045   to be queried until the copy is done.
1046
1047
1048  XVMC_BACKEND_SUBPICTURE not set ("frontend" behavior):
1049
1050     XvMCBlendSubpicture is a no-op in this case.
1051
1052     XvMCBlendSubpicture2 blends the source_surface and subpicture and
1053   puts it in the target_surface.  This does not effect the status of
1054   the source surface but will cause the target_surface to query
1055   XVMC_RENDERING until the blend is completed.
1056
1057
1058   display - The connection to the server.
1059
1060   subpicture - The subpicture to be blended into the video.
1061
1062   target_surface - The surface to be displayed with the blended subpicture.
1063
1064   source_surface - Source surface prior to blending.
1065
1066   subx -
1067   suby -
1068   subw -
1069   subh -  The rectangle from the subpicture to be blended.
1070
1071   surfx -
1072   surfy -
1073   surfw -
1074   surfh - The rectangle in the XvMCSurface to blend the subpicture rectangle
1075           into.  If XVMC_SUBPICTURE_INDEPENDENT_SCALING is not set in the
1076           XvMCSurfaceInfo subw must be equal to surfw and subh must be
1077           equal to surfh height or else a BadValue error occurs.
1078
1079    Errors:
1080
1081     XvMCBadSurface - Any of the surfaces are invalid.
1082
1083     XvMCBadSubpicture - The subpicture is invalid.
1084
1085     BadMatch - The subpicture or any of the surfaces do not belong to the
1086                same context.
1087
1088     BadValue - XVMC_SUBPICTURE_INDEPENDENT_SCALING is set and the source
1089                and destination rectangles are different sizes.
1090
1091
1092 /***********************************************************************/
1093
1094      SURFACE SYNCHRONIZATION
1095
1096 /***********************************************************************/
1097
1098
1099 #define XVMC_RENDERING          0x00000001
1100 #define XVMC_DISPLAYING         0x00000002
1101
1102 Status
1103 XvMCSyncSurface (Display *display, XvMCSurface *surface)
1104
1105    This function blocks until all rendering requests on the surface
1106   have been completed.
1107
1108      display - The connection to the server.
1109
1110      surface - The surface to synchronize.
1111
1112      Errors:
1113
1114          XvMCBadSurface - The surface is not valid.
1115
1116
1117 Status
1118 XvMCFlushSurface (Display *display, XvMCSurface *surface)
1119
1120    This function commits pending rendering requests to ensure that
1121   they will be completed in a finite amount of time.
1122
1123     display -  The connnection to the server.
1124
1125     surface -  The surface whos rendering requests should be flushed.
1126
1127      Errors:
1128
1129          XvMCBadSurface - The surface is not valid.
1130
1131
1132 Status
1133 XvMCGetSurfaceStatus (Display *display, XvMCSurface *surface, int *stat)
1134
1135    display -  The connection to the server.
1136
1137    surface -  The surface whos status is being queried.
1138
1139    stat -  May be any of the following OR'd together:
1140
1141    XVMC_RENDERING - The last XvMCRenderSurface request has not completed
1142                     yet.
1143
1144    XVMC_DISPLAYING - The surface is currently being displayed or a
1145                      display is pending (ie. it is not safe to render
1146                      to it).
1147
1148     Errors:
1149
1150          XvMCBadSurface - The surface is not valid.
1151
1152
1153 /***********************************************************************/
1154
1155      SUBPICTURE SYNCHRONIZATION
1156
1157 /***********************************************************************/
1158
1159
1160
1161 Status
1162 XvMCSyncSubpicture (Display *display, XvMCSubpicture *subpicture)
1163
1164    This function blocks until all composite/clear requests on the supicture
1165   have been completed.
1166
1167      display - The connection to the server.
1168
1169      subpicture -  The subpicture to synchronize.
1170
1171      Errors:
1172
1173          XvMCBadSubpicture - The subpicture is not valid.
1174
1175
1176 Status
1177 XvMCFlushSubpicture (Display *display, XvMCSubpicture *subpicture)
1178
1179    This function commits pending composite/clear requests to ensure that
1180   they will be completed in a finite amount of time.
1181
1182     display - The connection to the server.
1183
1184     subpicture - The subpicture whos compositing should be flushed.
1185
1186      Errors:
1187
1188          XvMCBadSubpicture - The surface is not valid.
1189
1190
1191 Status
1192 XvMCGetSubpictureStatus (Display *display, XvMCSubpicture *subpic, int *stat)
1193
1194     display - The connection to the server.
1195
1196     subpic - The subpicture whos status is being queried.
1197
1198     stat - may be any of the following OR'd together:
1199
1200    XVMC_RENDERING - The last XvMCCompositeSubpicture or XvMCClearSubpicture
1201                     request has not completed yet.
1202
1203    XVMC_DISPLAYING - The subpicture is currently being displayed or a
1204                      display is pending (ie. it is not safe to render
1205                      to it).
1206
1207      Errors:
1208
1209          XvMCBadSubpicture - The surface is not valid.
1210
1211 /********************************************************************/
1212
1213      ATTRIBUTES
1214
1215 /********************************************************************/
1216
1217    Context specific attribute functions are provided.  These are
1218 similar to their Xv Counterparts XvQueryPortAttributes, XvSetPortAttribute
1219 and XvGetPortAttribute but their state is specific to the context.
1220
1221 XvAttribute *
1222 XvMCQueryAttributes (
1223     Display *display,
1224     XvMCContext *context,
1225     int *number
1226 )
1227
1228     An array of XvAttributes of size "number" is returned by this function.
1229   If there are no attributes, NULL is returned and number is set to 0.
1230   The array may be freed with XFree().
1231
1232     display - The connection to the server.
1233
1234     context - The context whos attributes we are querying.
1235
1236     number - The returned number of recognized atoms.
1237
1238     Errors:
1239
1240         XvMCBadContext - The context is invalid.
1241
1242 Status
1243 XvMCSetAttribute (
1244     Display *display,
1245     XvMCContext *context,
1246     Atom attribute,
1247     int value
1248 )
1249
1250     This function sets a context-specific attribute and returns Success
1251   if no error has occurred.
1252
1253     display - The connection to the server.
1254
1255     context - The context for which the attribute change is to go into effect.
1256
1257     attribute - The X Atom of the attribute to be changed.
1258
1259     value -  The new value of the attribute.
1260
1261     Errors:
1262
1263         XvMCBadContext - The context is not valid.
1264
1265         BadValue - An invalid value was specified.
1266
1267         BadMatch - This attribute is not defined for this context.
1268
1269 Status
1270 XvMCGetAttribute (
1271     Display *display,
1272     XvMCContext *context,
1273     Atom attribute,
1274     int *value
1275 )
1276
1277     This function queries a context-specific attribute and return
1278   Success and the value if no error has occurred.
1279
1280     display - The connection to the server.
1281
1282     context - The context whos attribute we are querying.
1283
1284     attribute - The X Atom of the attribute to be retrieved.
1285
1286     value -  The returned attribute value.
1287
1288     Errors:
1289
1290         XvMCBadContext - The context is not valid.
1291
1292         BadMatch - This attribute is not defined for this context.
1293