XvMC_API.txt revision 98af18c5 
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
92Bool 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
103Status 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
139typedef 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
196XvMCSurfaceInfo * 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
224typedef 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
249Status 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
298Status 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
317typedef 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
337Status 
338XvMCCreateSurface(
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
360Status 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
380typedef 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
393Status 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
421Status 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
451typedef 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
559typedef 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
574Status 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
602Status 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
619Status 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
704Status
705XvMCPutSurface(
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
756Status 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
778XvImageFormatValues * 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
807typedef 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
843Status
844XvMCCreateSubpicture (
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
882Status
883XvMCClearSubpicture (
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
910Status
911XvMCCompositeSubpicture (
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
949Status
950XvMCDestroySubpicture (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
963Status
964XvMCSetSubpicturePalette (
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
993Status
994XvMCBlendSubpicture (
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
1008Status
1009XvMCBlendSubpicture2 (
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
1025or 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
1102Status
1103XvMCSyncSurface (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
1117Status
1118XvMCFlushSurface (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
1132Status
1133XvMCGetSurfaceStatus (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
1161Status
1162XvMCSyncSubpicture (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
1176Status
1177XvMCFlushSubpicture (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
1191Status
1192XvMCGetSubpictureStatus (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
1218similar to their Xv Counterparts XvQueryPortAttributes, XvSetPortAttribute 
1219and XvGetPortAttribute but their state is specific to the context.
1220
1221XvAttribute *
1222XvMCQueryAttributes (
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
1242Status
1243XvMCSetAttribute (
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
1269Status
1270XvMCGetAttribute (
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
1294