2 X-Video Motion Compensation - API specification v. 1.0
4 Mark Vojkovich <markv@xfree86.org>
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
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.
23 /* acknowledgements */
25 Thanks to Matthew J. Sottek from Intel for lots of input.
27 /********************************************************************/
31 /********************************************************************/
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.
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.
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).
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.
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.
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.
81 /********************************************************************/
83 QUERYING THE EXTENSION
85 /********************************************************************/
88 #define XvMCBadContext 0
89 #define XvMCBadSurface 1
90 #define XvMCBadSubpicture 2
92 Bool XvMCQueryExtension (Display *display, int *eventBase, int *errBase)
94 Returns True if the extension exists, False otherwise. Also returns
95 the error and event bases.
97 display - The connection to the server.
100 errBase - The returned event and error bases. Currently there
101 are no events defined.
103 Status XvMCQueryVersion (Display *display, int *major, int *minor)
105 Query the major and minor version numbers of the extension.
107 display - The connection to the server.
110 minor - The returned major and minor version numbers.
112 /********************************************************************/
114 QUERYING SURFACE TYPES
116 /********************************************************************/
119 #define XVMC_CHROMA_FORMAT_420 0x00000001
120 #define XVMC_CHROMA_FORMAT_422 0x00000002
121 #define XVMC_CHROMA_FORMAT_444 0x00000003
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
129 /* Motion Compensation types */
130 #define XVMC_MOCOMP 0x00000000
131 #define XVMC_IDCT 0x00010000
133 #define XVMC_MPEG_1 0x00000001
134 #define XVMC_MPEG_2 0x00000002
135 #define XVMC_H263 0x00000003
136 #define XVMC_MPEG_4 0x00000004
142 unsigned short max_width;
143 unsigned short max_height;
144 unsigned short subpicture_max_width;
145 unsigned short subpicture_max_height;
150 surface_type_id - Unique descriptor for this surface type.
152 chroma_format - Chroma format of this surface (eg. XVMC_CHROMA_FORMAT_420,
153 XVMC_CHROMA_FORMAT_422, XVMC_CHROMA_FORMAT_444).
156 max_height - Maximum dimensions of the luma data in pixels.
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
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:
168 XVMC_MOCOMP - Acceleration starts at the motion compensation
171 XVMC_IDCT - Acceleration starts at the IDCT level.
173 flags - Any combination of the following may be OR'd together.
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.
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.
185 XVMC_SUBPICTURE_INDEPENDENT_SCALING - The subpicture can be scaled
186 independently of the video
187 surface. See the section on
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.
196 XvMCSurfaceInfo * XvMCListSurfaceTypes(Display *dpy, XvPortID port, int *num)
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().
202 dpy - The connection to the server.
204 port - The port we want to get the XvMCSurfaceInfo array for.
206 num - The number of elements returned in the array.
210 XvBadPort - The requested port does not exist.
212 BadAlloc - There are insufficient resources to complete this request.
215 /********************************************************************/
219 /********************************************************************/
221 /* XvMCContext flags */
222 #define XVMC_DIRECT 0x00000001
227 unsigned short width;
228 unsigned short height;
231 void * privData; /* private to the library */
234 context_id - An XID associated with the context.
236 surface_type_id - This refers to the XvMCSurfaceInfo that describes
237 the surface characteristics.
240 height - The dimensions (of the luma data) this context supports.
242 port - The port that this context supports.
244 flags - Any combination may be OR'd together.
246 XVMC_DIRECT - This context is direct rendered.
249 Status XvMCCreateContext (
256 XvMCContext * context
259 This creates a context by filling out the XvMCContext structure passed
260 to it and returning Success.
262 display - Specifies the connection to the server.
264 port - Specifies the port to create the context for.
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).
274 flags - Any of the following may by OR'd together:
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
281 context - Pointer to the pre-allocated XvMCContext structure.
287 XvBadPort - The requested port does not exist.
289 BadValue - The dimensions requested are not supported by the
292 BadMatch - The surface_type_id is not supported by the port.
294 BadAlloc - There are not sufficient resources to fulfill this
298 Status XvMCDestroyContext (Display display, XvMCContext * context)
300 Destroys the specified context.
302 display - Specifies the connection to the server.
304 context - The context to be destroyed.
308 XvMCBadContext - The XvMCContext is not valid.
311 /*********************************************************************/
315 /*********************************************************************/
321 unsigned short width;
322 unsigned short height;
323 void *privData; /* private to the library */
326 surface_id - An XID associated with the surface.
328 context_id - The XID of the context for which the surface was created.
330 surface_type_id - Derived from the context_id, it specifies the
331 XvMCSurfaceInfo describing the surface.
334 height - The width and height of the luma data.
340 XvMCContext * context;
341 XvMCSurface * surface;
344 Creates a surface (Frame) for use with the specified context.
345 The surface structure is filled out and Success is returned if no
348 context - pointer to a valid context. The context implies
349 the surface type to be created, and its dimensions.
351 surface - pointer to a pre-allocated XvMCSurface structure.
355 XvMCBadContext - the context is not valid.
357 BadAlloc - there are insufficient resources to complete
360 Status XvMCDestroySurface(Display *display, XvMCSurface *surface);
362 Destroys the given surface.
364 display - Specifies the connection to the server.
366 surface - The surface to be destroyed.
370 XvMCBadSurface - The XvMCSurface is not valid.
374 /*********************************************************************/
378 /*********************************************************************/
382 unsigned int num_blocks;
384 void *privData; /* private to the library */
387 num_blocks - Number of 64 element blocks in the blocks array.
389 context_id - XID of the context these blocks were allocated for.
391 blocks - Pointer to an array of (64 * num_blocks) shorts.
393 Status XvMCCreateBlocks (
395 XvMCContext *context,
396 unsigned int num_blocks,
397 XvMCBlockArray * block
400 This allocates an array of DCT blocks in the XvMCBlockArray
401 structure passed to it. Success is returned if no error occured.
403 display - The connection to the server.
405 context - The context the block array is being created for.
407 num_blocks - The number of 64 element short blocks to be allocated.
408 This number must be non-zero.
410 block - A pointer to a pre-allocated XvMCBlockArray structure.
414 XvMCBadContext - the context is invalid.
416 BadAlloc - There are insufficient resources to complete the
419 BadValue - num_blocks was zero.
421 Status XvMCDestroyBlocks (Display *display, XvMCBlockArray * block)
423 Frees the given array.
425 display - The connection to the server.
427 block - The block array to be freed.
430 ----------------------------------------------------------
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
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
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
448 #define XVMC_DCT_TYPE_FRAME 0x00
449 #define XVMC_DCT_TYPE_FIELD 0x01
454 unsigned char macroblock_type;
455 unsigned char motion_type;
456 unsigned char motion_vertical_field_select;
457 unsigned char dct_type;
460 unsigned short coded_block_pattern;
464 x, y - location of the macroblock on the surface in units of macroblocks.
466 macroblock_type - can be any of the following flags OR'd together:
468 XVMC_MB_TYPE_MOTION_FORWARD - Forward motion prediction should
469 be done. This flag is ignored for
472 XVMC_MB_TYPE_MOTION_BACKWARD - Backward motion prediction should
473 be done. This flag is ignored when
474 the frame is not bidirectionally
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.
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
490 motion_type - If the surface is a field, the following are valid:
491 XVMC_PREDICTION_FIELD
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
499 motion_vertical_field_select - The following flags may be OR'd together
501 XVMC_SELECT_FIRST_FORWARD
502 XVMC_SELECT_FIRST_BACKWARD
503 XVMC_SELECT_SECOND_FORWARD
504 XVMC_SELECT_SECOND_BACKWARD
506 If the bit is set the bottom field is indicated.
507 If the bit is clear the top field is indicated.
510 ------- | | | |_ First vector forward
511 | | | |___ First vector backward
512 unused | |_____ Second vector forward
513 |_______ Second vector backward
515 PMV - The motion vector(s)
519 a - This holds the vector. 0 = horizontal, 1 = vertical.
520 b - 0 = forward, 1 = backward.
521 c - 0 = first vector, 1 = second vector.
523 The motion vectors are used only when XVMC_MB_TYPE_MOTION_FORWARD
524 or XVMC_MB_TYPE_MOTION_BACKWARD are set.
526 DualPrime vectors must be fully decoded and placed in the PMV
531 PMV[0][0][1:0] from same parity
532 PMV[0][1][1:0] from opposite parity
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
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.
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
554 dct_type - This field indicates whether frame pictures are frame DCT
555 coded or field DCT coded. ie XVMC_DCT_TYPE_FIELD or
560 unsigned int num_blocks;
562 XvMCMacroBlock *macro_blocks;
563 void *privData; /* private to the library */
564 } XvMCMacroBlockArray;
567 num_blocks - Number of XvMCMacroBlocks in the macro_blocks array.
569 context_id - XID of the context these macroblocks were allocated for.
571 macro_blocks - Pointer to an array of num_blocks XvMCMacroBlocks.
574 Status XvMCCreateMacroBlocks (
576 XvMCContext *context,
577 unsigned int num_blocks,
578 XvMCMacroBlockArray * blocks
581 This allocates an array of XvMCMacroBlocks in the XvMCMacroBlockArray
582 structure passed to it. Success is returned if no error occured.
584 display - The connection to the server.
586 context - The context the macroblock array is being created for.
588 num_blocks - The number of XvMCMacroBlocks to be allocated.
589 This number must be non-zero.
591 blocks - A pointer to a pre-allocated XvMCMacroBlockArray structure.
595 XvMCBadContext - the context is invalid.
597 BadAlloc - There are insufficient resources to complete the
600 BadValue - num_blocks was zero.
602 Status XvMCDestroyMacroBlocks (Display *display, XvMCMacroBlockArray * block)
604 Frees the given array.
606 display - The connection to the server.
608 block - The macro block array to be freed.
611 ------------------------------------------------------------
613 #define XVMC_TOP_FIELD 0x00000001
614 #define XVMC_BOTTOM_FIELD 0x00000002
615 #define XVMC_FRAME_PICTURE (XVMC_TOP_FIELD | XVMC_BOTTOM_FIELD)
617 #define XVMC_SECOND_FIELD 0x00000004
619 Status XvMCRenderSurface(
621 XvMCContext *context,
622 unsigned int picture_structure,
623 Surface *target_surface,
624 Surface *past_surface,
625 Surface *future_surface,
627 unsigned int num_macroblocks,
628 unsigned int first_macroblock,
629 XvMCMacroBlockArray *macroblock_array,
630 XvMCBlockArray *blocks
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.
639 display - The connection to the server.
641 context - The context used to render.
647 The target_surface is required. If the future and past
648 surfaces are NULL, the target_surface is an "Intra" frame.
650 If the past surface is provided but not the future surface,
651 the target_surface is a "Predicted Inter" frame.
653 If both past and future surfaces are provided, the
654 target_surface is a "Bidirectionally-predicted Inter" frame.
656 Specifying a future surface without a past surface results
659 All surfaces must belong to the same context.
661 picture_structure - XVMC_TOP_FIELD, XVMC_BOTTOM_FIELD or
665 flags - Flags may include:
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.
671 num_macroblocks - The number of XvMCMacroBlock structures to execute in
672 the macroblock_array.
674 first_macroblock - The index of the first XvMCMacroBlock to process in the
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
686 XvMCBadContext - The context is not valid.
688 XvMCBadSurface - Any of the surfaces are not valid.
690 BadMatch - Any of the surfaces do not belong to the specified
691 context or a future surface was specified without
694 BadValue - Unrecognized data for the picture_structure.
697 /***********************************************************************/
699 DISPLAYING THE SURFACE
701 /***********************************************************************/
707 XvMCSurface *surface,
715 unsigned short destw,
716 unsigned short desth,
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
727 display - The connection to the server.
729 surface - The surface to copy/overlay from.
731 draw - The drawable to copy/overlay the video on.
736 srch - The rectangle in the source area from the surface that is
742 desth - The rectangle in the destination drawable where the scaled
743 source rectangle should be displayed.
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).
751 XvMCBadSurface - The surface is not valid.
753 BadDrawable - The drawable does not exist.
756 Status XvMCHideSurface(Display *display, XvMCSurface *surface)
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
762 display - The connection to the server.
764 surface - The surface to be hidden.
768 XvMCBadSurface - The surface is not valid.
771 /***********************************************************************/
773 COMPOSITING THE SUBPICTURE
775 /***********************************************************************/
778 XvImageFormatValues * XvMCListSubpictureTypes (
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().
789 display - Specifies the connection to the X-server.
791 port - Specifies the port we are interested in.
793 surface_type_id - Specifies the surface type for which we want to
794 query the supported subpicture types.
796 count_return - the size of the returned array.
800 BadPort - The port doesn't exist.
802 BadAlloc - There are insufficient resources to complete this request.
804 BadMatch - The surface type is not supported on that port.
811 unsigned short width;
812 unsigned short height;
813 int num_palette_entries;
815 char component_order[4];
816 void *privData; /* private to the library */
820 subpicture_id - An XID associated with this subpicture.
822 context_id - The XID of the context this subpicture was created for.
824 xvimage_id - The id descriptor of the XvImage format that may be used
825 with this subpicture.
828 height - The dimensions of the subpicture.
830 num_palette_entries - For paletted formats only. This is the number
831 of palette entries. It is zero for XvImages
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.
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.
844 XvMCCreateSubpicture (
846 XvMCContext *context,
847 XvMCSubpicture *subpicture,
848 unsigned short width,
849 unsigned short height,
853 This creates a subpicture by filling out the XvMCSubpicture structure
854 passed to it and returning Success.
856 display - Specifies the connection to the X-Server.
858 context - The context to create the subpicture for.
860 subpicture - Pre-allocated XvMCSubpicture structure to be filled
861 out by this function.
864 height - The dimensions of the subpicture.
866 xvimage_id - The id describing the XvImage format.
871 BadAlloc - There are insufficient resources to complete this request.
873 XvMCBadContext - The specified context does not exist.
875 BadMatch - The XvImage format id specified is not supported by
878 BadValue - If the size requested is larger than the max size reported
879 in the XvMCSurfaceInfo.
883 XvMCClearSubpicture (
885 XvMCSubpicture *subpicture,
888 unsigned short width,
889 unsigned short height,
893 Clear the area of the given subpicture to "color".
895 display - The connection to the server.
897 subpicture - The subpicture to clear.
902 height - The rectangle in the subpicture to be cleared.
904 color - The data to fill the rectangle with.
908 XvMCBadSubpicture - The subpicture is invalid.
911 XvMCCompositeSubpicture (
913 XvMCSubpicture *subpicture,
917 unsigned short width,
918 unsigned short height,
923 Copies the XvImage to the XvMCSubpicture.
925 display - The connection to the server.
927 subpicture - The subpicture used as the destination of the copy.
929 image - The XvImage to be used as the source of the copy.
930 XvImages should be of the shared memory variety for
936 height - The rectangle from the image to be composited.
939 dsty - The location in the subpicture where the source rectangle
940 should be composited.
944 XvMCBadSubpicture - The subpicture is invalid.
946 BadMatch - The subpicture does not support the type of XvImage
947 passed to this function.
950 XvMCDestroySubpicture (Display *display, XvMCSubpicture *subpicture)
952 Destroys the specified subpicture.
954 display - Specifies the connection to the X-server.
956 subpicture - The subpicture to be destroyed.
960 XvMCBadSubpicture - The subpicture specified does not exist.
964 XvMCSetSubpicturePalette (
966 XvMCSubpicture *subpicture,
967 unsigned char *palette
970 Set the subpicture's palette. This applies to paletted subpictures
973 display - The connection to the server.
975 subpicture - The subpicture on which to change the palette.
977 palette - A pointer to an array holding the palette data. The
978 size of this array is
980 num_palette_entries * entry_bytes
982 in size. The order of the components in the palette
983 is described by the component_order in the XvMCSubpicture
988 XvMCBadSubpicture - The subpicture specified does not exist.
990 BadMatch - The specified subpicture does not use palettes.
994 XvMCBlendSubpicture (
996 XvMCSurface *target_surface,
997 XvMCSubpicture *subpicture,
1000 unsigned short subw,
1001 unsigned short subh,
1004 unsigned short surfw,
1005 unsigned short surfh
1009 XvMCBlendSubpicture2 (
1011 XvMCSurface *source_surface,
1012 XvMCSurface *target_surface,
1013 XvMCSubpicture *subpicture,
1016 unsigned short subw,
1017 unsigned short subh,
1020 unsigned short surfw,
1021 unsigned short surfh
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.
1027 XVMC_BACKEND_SUBPICTURE set:
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.
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.
1048 XVMC_BACKEND_SUBPICTURE not set ("frontend" behavior):
1050 XvMCBlendSubpicture is a no-op in this case.
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.
1058 display - The connection to the server.
1060 subpicture - The subpicture to be blended into the video.
1062 target_surface - The surface to be displayed with the blended subpicture.
1064 source_surface - Source surface prior to blending.
1069 subh - The rectangle from the subpicture to be blended.
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.
1081 XvMCBadSurface - Any of the surfaces are invalid.
1083 XvMCBadSubpicture - The subpicture is invalid.
1085 BadMatch - The subpicture or any of the surfaces do not belong to the
1088 BadValue - XVMC_SUBPICTURE_INDEPENDENT_SCALING is set and the source
1089 and destination rectangles are different sizes.
1092 /***********************************************************************/
1094 SURFACE SYNCHRONIZATION
1096 /***********************************************************************/
1099 #define XVMC_RENDERING 0x00000001
1100 #define XVMC_DISPLAYING 0x00000002
1103 XvMCSyncSurface (Display *display, XvMCSurface *surface)
1105 This function blocks until all rendering requests on the surface
1106 have been completed.
1108 display - The connection to the server.
1110 surface - The surface to synchronize.
1114 XvMCBadSurface - The surface is not valid.
1118 XvMCFlushSurface (Display *display, XvMCSurface *surface)
1120 This function commits pending rendering requests to ensure that
1121 they will be completed in a finite amount of time.
1123 display - The connnection to the server.
1125 surface - The surface whos rendering requests should be flushed.
1129 XvMCBadSurface - The surface is not valid.
1133 XvMCGetSurfaceStatus (Display *display, XvMCSurface *surface, int *stat)
1135 display - The connection to the server.
1137 surface - The surface whos status is being queried.
1139 stat - May be any of the following OR'd together:
1141 XVMC_RENDERING - The last XvMCRenderSurface request has not completed
1144 XVMC_DISPLAYING - The surface is currently being displayed or a
1145 display is pending (ie. it is not safe to render
1150 XvMCBadSurface - The surface is not valid.
1153 /***********************************************************************/
1155 SUBPICTURE SYNCHRONIZATION
1157 /***********************************************************************/
1162 XvMCSyncSubpicture (Display *display, XvMCSubpicture *subpicture)
1164 This function blocks until all composite/clear requests on the supicture
1165 have been completed.
1167 display - The connection to the server.
1169 subpicture - The subpicture to synchronize.
1173 XvMCBadSubpicture - The subpicture is not valid.
1177 XvMCFlushSubpicture (Display *display, XvMCSubpicture *subpicture)
1179 This function commits pending composite/clear requests to ensure that
1180 they will be completed in a finite amount of time.
1182 display - The connection to the server.
1184 subpicture - The subpicture whos compositing should be flushed.
1188 XvMCBadSubpicture - The surface is not valid.
1192 XvMCGetSubpictureStatus (Display *display, XvMCSubpicture *subpic, int *stat)
1194 display - The connection to the server.
1196 subpic - The subpicture whos status is being queried.
1198 stat - may be any of the following OR'd together:
1200 XVMC_RENDERING - The last XvMCCompositeSubpicture or XvMCClearSubpicture
1201 request has not completed yet.
1203 XVMC_DISPLAYING - The subpicture is currently being displayed or a
1204 display is pending (ie. it is not safe to render
1209 XvMCBadSubpicture - The surface is not valid.
1211 /********************************************************************/
1215 /********************************************************************/
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.
1222 XvMCQueryAttributes (
1224 XvMCContext *context,
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().
1232 display - The connection to the server.
1234 context - The context whos attributes we are querying.
1236 number - The returned number of recognized atoms.
1240 XvMCBadContext - The context is invalid.
1245 XvMCContext *context,
1250 This function sets a context-specific attribute and returns Success
1251 if no error has occurred.
1253 display - The connection to the server.
1255 context - The context for which the attribute change is to go into effect.
1257 attribute - The X Atom of the attribute to be changed.
1259 value - The new value of the attribute.
1263 XvMCBadContext - The context is not valid.
1265 BadValue - An invalid value was specified.
1267 BadMatch - This attribute is not defined for this context.
1272 XvMCContext *context,
1277 This function queries a context-specific attribute and return
1278 Success and the value if no error has occurred.
1280 display - The connection to the server.
1282 context - The context whos attribute we are querying.
1284 attribute - The X Atom of the attribute to be retrieved.
1286 value - The returned attribute value.
1290 XvMCBadContext - The context is not valid.
1292 BadMatch - This attribute is not defined for this context.