diff options
| -rw-r--r-- | Makefile.am | 3 | ||||
| -rw-r--r-- | XvMC_API.txt | 1293 |
2 files changed, 1296 insertions, 0 deletions
diff --git a/Makefile.am b/Makefile.am index bbca204..56dffbd 100644 --- a/Makefile.am +++ b/Makefile.am @@ -24,6 +24,9 @@ SUBDIRS = src include pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = xvmc.pc +xvmcdocdir = $(datadir)/doc/$(PACKAGE) +dist_xvmcdoc_DATA = XvMC_API.txt + EXTRA_DIST = xvmc.pc.in ChangeLog .PHONY: ChangeLog diff --git a/XvMC_API.txt b/XvMC_API.txt new file mode 100644 index 0000000..9aded3a --- /dev/null +++ b/XvMC_API.txt @@ -0,0 +1,1293 @@ + + X-Video Motion Compensation - API specification v. 1.0 + + Mark Vojkovich <markv@xfree86.org> + + +/* history */ + + first draft (9/6/00) + second draft (10/31/00) - Changed to allow acceleration at both + the motion compensation and IDCT level. + third draft (1/21/01) - Some refinements and subpicture support. + fourth draft (5/2/01) - Dual Prime clarification, add + XvMCSetAttribute. + fifth draft (6/26/01) - Change definition of XvMCCompositeSubpicture + plus some clarifications and fixed typographical errors. + sixth draft (9/24/01) - Added XVMC_SECOND_FIELD and removed + XVMC_PROGRESSIVE_FRAME and XVMC_TOP_FIELD_FIRST flags. + seventh draft (10/26/01) - Added XVMC_INTRA_UNSIGNED option. + eighth draft (11/13/02) - Removed IQ level acceleration and + changed some structures to remove unused fields. + +/* acknowledgements */ + + Thanks to Matthew J. Sottek from Intel for lots of input. + +/********************************************************************/ + + OVERVIEW + +/********************************************************************/ + + XvMC extends the X-Video extension (Xv) and makes use of the + familar concept of the XvPort. Ports have attributes that can be set + and queried through Xv. In XvMC ports can also have hardware motion + compensation contexts created for use with them. Ports which support + XvImages (ie. they have an "XV_IMAGE" port encoding as described in + the Xv version 2.2 API addendum) can be queried for the list of XvMCSurface + types they support. If they support any XvMCSurface types an + XvMCContext can be created for that port. + + An XvMCContext describes the state of the motion compensation + pipeline. An individual XvMCContext can be created for use with + a single port, surface type, motion compensation type, width and + height combination. For example, a context might be created for a + particular port that does MPEG-2 motion compensation on 720 x 480 + 4:2:0 surfaces. Once the context is created, referencing it implies + the port, surface type, size and the motion compensation type. Contexts + may be "direct" or "indirect". For indirect contexts the X server + renders all video using the data passed to it by the client. For + direct contexts the client libraries render the video with little + or no interaction with the X server. + + XvMCSurfaces are buffers into which the motion compensation + hardware can render. The data in the buffers themselves are not client + accessible and may be stored in a hardware-specific format. Any + number of buffers can be created for use with a particular context + (resources permitting). + + XvMC provides video acceleration starting at one of two places + in the video pipeline. Acceleration starting at the first point, + which we shall call the "Motion Compensation" level, begins after the + the inverse quantization and IDCT at the place where motion compensation + is to be applied. The second point, which we shall call the "IDCT" + level, begins before the IDCT just after the inverse quantization. + + Rendering is done by presenting the library with a target XvMCSurface + and up to two reference XvMCSurfaces for the motion compensation, a + buffer of 8x8 blocks and a command buffer which describes how to + use the 8x8 blocks along with motion compensation vectors to construct + the data in the target XvMCSurface. When the pipeline starts at the + IDCT level, Xv will perform the IDCT on the blocks before performing + the motion compensation. A function is provided to copy/overlay a + portion of the XvMCSurface to a drawable with arbitrary scaling. + + XvMCSubpictures are separate surfaces that may be blended with the + target surface. Any number of XvMCSubpictures may be created for use + with a context (resources permitting). Both "backend" and "frontend" + subpicture behavior are supported. + +/********************************************************************/ + + QUERYING THE EXTENSION + +/********************************************************************/ + +/* Errors */ +#define XvMCBadContext 0 +#define XvMCBadSurface 1 +#define XvMCBadSubpicture 2 + +Bool XvMCQueryExtension (Display *display, int *eventBase, int *errBase) + + Returns True if the extension exists, False otherwise. Also returns + the error and event bases. + + display - The connection to the server. + + eventBase - + errBase - The returned event and error bases. Currently there + are no events defined. + +Status XvMCQueryVersion (Display *display, int *major, int *minor) + + Query the major and minor version numbers of the extension. + + display - The connection to the server. + + major - + minor - The returned major and minor version numbers. + +/********************************************************************/ + + QUERYING SURFACE TYPES + +/********************************************************************/ + +/* Chroma formats */ +#define XVMC_CHROMA_FORMAT_420 0x00000001 +#define XVMC_CHROMA_FORMAT_422 0x00000002 +#define XVMC_CHROMA_FORMAT_444 0x00000003 + +/* XvMCSurfaceInfo Flags */ +#define XVMC_OVERLAID_SURFACE 0x00000001 +#define XVMC_BACKEND_SUBPICTURE 0x00000002 +#define XVMC_SUBPICTURE_INDEPENDENT_SCALING 0x00000004 +#define XVMC_INTRA_UNSIGNED 0x00000008 + +/* Motion Compensation types */ +#define XVMC_MOCOMP 0x00000000 +#define XVMC_IDCT 0x00010000 + +#define XVMC_MPEG_1 0x00000001 +#define XVMC_MPEG_2 0x00000002 +#define XVMC_H263 0x00000003 +#define XVMC_MPEG_4 0x00000004 + + +typedef struct { + int surface_type_id; + int chroma_format; + unsigned short max_width; + unsigned short max_height; + unsigned short subpicture_max_width; + unsigned short subpicture_max_height; + int mc_type; + int flags; +} XvMCSurfaceInfo; + + surface_type_id - Unique descriptor for this surface type. + + chroma_format - Chroma format of this surface (eg. XVMC_CHROMA_FORMAT_420, + XVMC_CHROMA_FORMAT_422, XVMC_CHROMA_FORMAT_444). + + max_width - + max_height - Maximum dimensions of the luma data in pixels. + + subpicture_max_width - + subpicture_max_height - The Maximum dimensions of the subpicture + that can be created for use with this surface + Both fields are zero if subpictures are not + supported. + + mc_type - The type of motion compensation available for this + surface. This consists of XVMC_MPEG_1, XVMC_MPEG_2, XVMC_H263 + or XVMC_MPEG_4 OR'd together with any of the following: + + XVMC_MOCOMP - Acceleration starts at the motion compensation + level; + + XVMC_IDCT - Acceleration starts at the IDCT level. + + flags - Any combination of the following may be OR'd together. + + XVMC_OVERLAID_SURFACE - Displayed data is overlaid and not + physically in the visible framebuffer. + When this is set the client is responsible + for painting the colorkey. + + XVMC_BACKEND_SUBPICTURE - The supicture is of the "backend" + variety. It is "frontend" otherwise. + There is more information on this in the + section on subpictures below. + + XVMC_SUBPICTURE_INDEPENDENT_SCALING - The subpicture can be scaled + independently of the video + surface. See the section on + subpictures below. + + XVMC_INTRA_UNSIGNED - When this flag is set, the motion compenstation + level Intra macroblock data should be in an + unsigned format rather than the signed format + present in the mpeg stream. This flag applies + only to motion compensation level acceleration. + +XvMCSurfaceInfo * XvMCListSurfaceTypes(Display *dpy, XvPortID port, int *num) + + Returns the number of surface types supported by the XvPort and an array + of XvMCSurfaceInfo describing each surface type. The returned array + should be freed with XFree(). + + dpy - The connection to the server. + + port - The port we want to get the XvMCSurfaceInfo array for. + + num - The number of elements returned in the array. + + Errors: + + XvBadPort - The requested port does not exist. + + BadAlloc - There are insufficient resources to complete this request. + + +/********************************************************************/ + + CREATING A CONTEXT + +/********************************************************************/ + +/* XvMCContext flags */ +#define XVMC_DIRECT 0x00000001 + +typedef struct { + XID context_id; + int surface_type_id; + unsigned short width; + unsigned short height; + XVPortID port; + int flags; + void * privData; /* private to the library */ +} XvMCContext; + + context_id - An XID associated with the context. + + surface_type_id - This refers to the XvMCSurfaceInfo that describes + the surface characteristics. + + width - + height - The dimensions (of the luma data) this context supports. + + port - The port that this context supports. + + flags - Any combination may be OR'd together. + + XVMC_DIRECT - This context is direct rendered. + + +Status XvMCCreateContext ( + Display display, + XVPortID port, + int surface_type_id, + int width, + int height, + int flags, + XvMCContext * context +); + + This creates a context by filling out the XvMCContext structure passed + to it and returning Success. + + display - Specifies the connection to the server. + + port - Specifies the port to create the context for. + + surface_type_id - + width - + height - Specifies the surface type and dimensions that this + context will be used for. The surface_type_id corresponds + to the surface_type_id referenced by the XvMCSurfaceInfo. + The surface returned may be larger than the surface requested + (usually the next larger multiple of 16x16 pixels). + + flags - Any of the following may by OR'd together: + + XVMC_DIRECT - A direct context is requested. + If a direct context cannot be created the request + will not fail, rather, an indirect context will + be created instead. + + context - Pointer to the pre-allocated XvMCContext structure. + + + + Errors: + + XvBadPort - The requested port does not exist. + + BadValue - The dimensions requested are not supported by the + surface type. + + BadMatch - The surface_type_id is not supported by the port. + + BadAlloc - There are not sufficient resources to fulfill this + request. + + +Status XvMCDestroyContext (Display display, XvMCContext * context) + + Destroys the specified context. + + display - Specifies the connection to the server. + + context - The context to be destroyed. + + Errors: + + XvMCBadContext - The XvMCContext is not valid. + + +/*********************************************************************/ + + SURFACE CREATION + +/*********************************************************************/ + +typedef struct { + XID surface_id; + XID context_id; + int surface_type_id; + unsigned short width; + unsigned short height; + void *privData; /* private to the library */ +} XvMCSurface; + + surface_id - An XID associated with the surface. + + context_id - The XID of the context for which the surface was created. + + surface_type_id - Derived from the context_id, it specifies the + XvMCSurfaceInfo describing the surface. + + width - + height - The width and height of the luma data. + + +Status +XvMCCreateSurface( + Display *display, + XvMCContext * context; + XvMCSurface * surface; +); + + Creates a surface (Frame) for use with the specified context. + The surface structure is filled out and Success is returned if no + error occured. + + context - pointer to a valid context. The context implies + the surface type to be created, and its dimensions. + + surface - pointer to a pre-allocated XvMCSurface structure. + + Errors: + + XvMCBadContext - the context is not valid. + + BadAlloc - there are insufficient resources to complete + this operation. + +Status XvMCDestroySurface(Display *display, XvMCSurface *surface); + + Destroys the given surface. + + display - Specifies the connection to the server. + + surface - The surface to be destroyed. + + Errors: + + XvMCBadSurface - The XvMCSurface is not valid. + + + +/*********************************************************************/ + + RENDERING A FRAME + +/*********************************************************************/ + +typedef struct { + XID context_id; + unsigned int num_blocks; + short *blocks; + void *privData; /* private to the library */ +} XvMCBlockArray; + + num_blocks - Number of 64 element blocks in the blocks array. + + context_id - XID of the context these blocks were allocated for. + + blocks - Pointer to an array of (64 * num_blocks) shorts. + +Status XvMCCreateBlocks ( + Display *display, + XvMCContext *context, + unsigned int num_blocks, + XvMCBlockArray * block +); + + This allocates an array of DCT blocks in the XvMCBlockArray + structure passed to it. Success is returned if no error occured. + + display - The connection to the server. + + context - The context the block array is being created for. + + num_blocks - The number of 64 element short blocks to be allocated. + This number must be non-zero. + + block - A pointer to a pre-allocated XvMCBlockArray structure. + + Errors: + + XvMCBadContext - the context is invalid. + + BadAlloc - There are insufficient resources to complete the + operation. + + BadValue - num_blocks was zero. + +Status XvMCDestroyBlocks (Display *display, XvMCBlockArray * block) + + Frees the given array. + + display - The connection to the server. + + block - The block array to be freed. + + + ---------------------------------------------------------- + +#define XVMC_MB_TYPE_MOTION_FORWARD 0x02 +#define XVMC_MB_TYPE_MOTION_BACKWARD 0x04 +#define XVMC_MB_TYPE_PATTERN 0x08 +#define XVMC_MB_TYPE_INTRA 0x10 + +#define XVMC_PREDICTION_FIELD 0x01 +#define XVMC_PREDICTION_FRAME 0x02 +#define XVMC_PREDICTION_DUAL_PRIME 0x03 +#define XVMC_PREDICTION_16x8 0x02 +#define XVMC_PREDICTION_4MV 0x04 + +#define XVMC_SELECT_FIRST_FORWARD 0x01 +#define XVMC_SELECT_FIRST_BACKWARD 0x02 +#define XVMC_SELECT_SECOND_FORWARD 0x04 +#define XVMC_SELECT_SECOND_BACKWARD 0x08 + +#define XVMC_DCT_TYPE_FRAME 0x00 +#define XVMC_DCT_TYPE_FIELD 0x01 + +typedef struct { + unsigned short x; + unsigned short y; + unsigned char macroblock_type; + unsigned char motion_type; + unsigned char motion_vertical_field_select; + unsigned char dct_type; + short PMV[2][2][2]; + unsigned int index; + unsigned short coded_block_pattern; + unsigned short pad0; +} XvMCMacroBlock; + + x, y - location of the macroblock on the surface in units of macroblocks. + + macroblock_type - can be any of the following flags OR'd together: + + XVMC_MB_TYPE_MOTION_FORWARD - Forward motion prediction should + be done. This flag is ignored for + Intra frames. + + XVMC_MB_TYPE_MOTION_BACKWARD - Backward motion prediction should + be done. This flag is ignored when + the frame is not bidirectionally + predicted. + + XVMC_MB_TYPE_PATTERN - Blocks are referenced and they contain + differentials. The coded_block_pattern will + indicate the number of blocks and index will + note their locations in the block array. + + XVMC_MB_TYPE_INTRA - Blocks are referenced and they are intra blocks. + The coded_block_pattern will indicate the number + of blocks and index will note their locations in + the block array. XVMC_MB_TYPE_PATTERN and + XVMC_MB_TYPE_INTRA are mutually exclusive. If + both are specified, XVMC_MB_TYPE_INTRA takes + precedence. + + motion_type - If the surface is a field, the following are valid: + XVMC_PREDICTION_FIELD + XVMC_PREDICTION_16x8 + XVMC_PREDICTION_DUAL_PRIME + If the surface is a frame, the following are valid: + XVMC_PREDICTION_FIELD + XVMC_PREDICTION_FRAME + XVMC_PREDICTION_DUAL_PRIME + + motion_vertical_field_select - The following flags may be OR'd together + + XVMC_SELECT_FIRST_FORWARD + XVMC_SELECT_FIRST_BACKWARD + XVMC_SELECT_SECOND_FORWARD + XVMC_SELECT_SECOND_BACKWARD + + If the bit is set the bottom field is indicated. + If the bit is clear the top field is indicated. + + X X X X D C B A + ------- | | | |_ First vector forward + | | | |___ First vector backward + unused | |_____ Second vector forward + |_______ Second vector backward + + PMV - The motion vector(s) + + PMV[c][b][a] + + a - This holds the vector. 0 = horizontal, 1 = vertical. + b - 0 = forward, 1 = backward. + c - 0 = first vector, 1 = second vector. + + The motion vectors are used only when XVMC_MB_TYPE_MOTION_FORWARD + or XVMC_MB_TYPE_MOTION_BACKWARD are set. + + DualPrime vectors must be fully decoded and placed in the PMV + array as follows. + + Field structure: + + PMV[0][0][1:0] from same parity + PMV[0][1][1:0] from opposite parity + + Frame structure: + + PMV[0][0][1:0] top from top + PMV[0][1][1:0] bottom from bottom + PMV[1][0][1:0] top from bottom + PMV[1][1][1:0] bottom from top + + + index - The offset in units of (64 * sizeof(short)) from the start of + the block array where this macroblock's DCT blocks, as indicated + by the coded_block_pattern, are stored. + + coded_block_pattern - Indicates the blocks to be updated. The bitplanes + are specific to the mc_type of the surface. This + field is valid only if XVMC_MB_TYPE_PATTERN or + XVMC_MB_TYPE_INTRA are set. In that case the blocks + are differential or intra blocks respectively. + The bitplanes are described in ISO/IEC 13818-2 + Figures 6.10-12. + + dct_type - This field indicates whether frame pictures are frame DCT + coded or field DCT coded. ie XVMC_DCT_TYPE_FIELD or + XVMC_DCT_TYPE_FRAME. + + +typedef struct { + unsigned int num_blocks; + XID context_id; + XvMCMacroBlock *macro_blocks; + void *privData; /* private to the library */ +} XvMCMacroBlockArray; + + + num_blocks - Number of XvMCMacroBlocks in the macro_blocks array. + + context_id - XID of the context these macroblocks were allocated for. + + macro_blocks - Pointer to an array of num_blocks XvMCMacroBlocks. + + +Status XvMCCreateMacroBlocks ( + Display *display, + XvMCContext *context, + unsigned int num_blocks, + XvMCMacroBlockArray * blocks +); + + This allocates an array of XvMCMacroBlocks in the XvMCMacroBlockArray + structure passed to it. Success is returned if no error occured. + + display - The connection to the server. + + context - The context the macroblock array is being created for. + + num_blocks - The number of XvMCMacroBlocks to be allocated. + This number must be non-zero. + + blocks - A pointer to a pre-allocated XvMCMacroBlockArray structure. + + Errors: + + XvMCBadContext - the context is invalid. + + BadAlloc - There are insufficient resources to complete the + operation. + + BadValue - num_blocks was zero. + +Status XvMCDestroyMacroBlocks (Display *display, XvMCMacroBlockArray * block) + + Frees the given array. + + display - The connection to the server. + + block - The macro block array to be freed. + + + ------------------------------------------------------------ + +#define XVMC_TOP_FIELD 0x00000001 +#define XVMC_BOTTOM_FIELD 0x00000002 +#define XVMC_FRAME_PICTURE (XVMC_TOP_FIELD | XVMC_BOTTOM_FIELD) + +#define XVMC_SECOND_FIELD 0x00000004 + +Status XvMCRenderSurface( + Display *display, + XvMCContext *context, + unsigned int picture_structure, + Surface *target_surface, + Surface *past_surface, + Surface *future_surface, + unsigned int flags, + unsigned int num_macroblocks, + unsigned int first_macroblock, + XvMCMacroBlockArray *macroblock_array, + XvMCBlockArray *blocks +); + + This function renders the macroblocks passed to it. It will not + return until it has read all of the macroblocks, however, rendering + will usually not be completed by that time. The return of this + function means it is safe to touch the blocks and macroblock_array. + To synchronize rendering see the section on sychronization below. + + display - The connection to the server. + + context - The context used to render. + + target_surface - + past_surface - + furture_surface - + + The target_surface is required. If the future and past + surfaces are NULL, the target_surface is an "Intra" frame. + + If the past surface is provided but not the future surface, + the target_surface is a "Predicted Inter" frame. + + If both past and future surfaces are provided, the + target_surface is a "Bidirectionally-predicted Inter" frame. + + Specifying a future surface without a past surface results + in a BadMatch. + + All surfaces must belong to the same context. + + picture_structure - XVMC_TOP_FIELD, XVMC_BOTTOM_FIELD or + XVMC_FRAME_PICTURE. + + + flags - Flags may include: + + XVMC_SECOND_FIELD - For field pictures this indicates whether + the current field (top or bottom) is first + or second in the sequence. + + num_macroblocks - The number of XvMCMacroBlock structures to execute in + the macroblock_array. + + first_macroblock - The index of the first XvMCMacroBlock to process in the + macroblock_array. + + blocks - The array of XvMCBlocks to be referenced by the XvMCMacroBlocks. + The data in the individual blocks are in raster scan order and + should be clamped to the limits specific to the acceleration + level. For motion compensation level acceleration this is 8 + bits for Intra and 9 bits for non-Intra data. At the IDCT level + this is 12 bits. + + Errors: + + XvMCBadContext - The context is not valid. + + XvMCBadSurface - Any of the surfaces are not valid. + + BadMatch - Any of the surfaces do not belong to the specified + context or a future surface was specified without + a past surface. + + BadValue - Unrecognized data for the picture_structure. + + +/***********************************************************************/ + + DISPLAYING THE SURFACE + +/***********************************************************************/ + + +Status +XvMCPutSurface( + Display *display, + XvMCSurface *surface, + Drawable draw, + short srcx, + short srcy, + unsigned short srcw, + unsigned short srch, + short destx, + short desty, + unsigned short destw, + unsigned short desth, + int flags +); + + Display the rectangle from the source defined by srcx/y/w/h scaled + to destw by desth and placed at (destx, desty) on the given drawable. + This function is not guaranteed to be pipelined with previous rendering + commands and may display the surface immediately. Therefore, the client + must query that the surface has finished rendering before calling this + function. + + display - The connection to the server. + + surface - The surface to copy/overlay from. + + draw - The drawable to copy/overlay the video on. + + srcx - + srcy - + srcw - + srch - The rectangle in the source area from the surface that is + to be displayed. + + destx - + desty - + destw - + desth - The rectangle in the destination drawable where the scaled + source rectangle should be displayed. + + flags - this indicates the field to be displayed and can be XVMC_TOP_FIELD, + XVMC_BOTTOM_FIELD or XVMC_FRAME_PICTURE. XVMC_FRAME_PICTURE + displays both fields (weave). + + Errors: + + XvMCBadSurface - The surface is not valid. + + BadDrawable - The drawable does not exist. + + +Status XvMCHideSurface(Display *display, XvMCSurface *surface) + + Stops display of a surface. This is only needed if the surface is an + overlaid surface as indicated in the XvMCSurfaceInfo - it is a no-op + otherwise. + + display - The connection to the server. + + surface - The surface to be hidden. + + Errors: + + XvMCBadSurface - The surface is not valid. + + +/***********************************************************************/ + + COMPOSITING THE SUBPICTURE + +/***********************************************************************/ + + +XvImageFormatValues * XvMCListSubpictureTypes ( + Display * display, + XvPortID port, + int surface_type_id, + int *count_return +) + + Returns an array of XvImageFormatValues supported by the surface_type_id + describing the surface. The surface_type_id is acquired from the + XvMCSurfaceInfo. This list should be freed with XFree(). + + display - Specifies the connection to the X-server. + + port - Specifies the port we are interested in. + + surface_type_id - Specifies the surface type for which we want to + query the supported subpicture types. + + count_return - the size of the returned array. + + Errors: + + BadPort - The port doesn't exist. + + BadAlloc - There are insufficient resources to complete this request. + + BadMatch - The surface type is not supported on that port. + + +typedef struct { + XID subpicture_id; + XID context_id; + int xvimage_id; + unsigned short width; + unsigned short height; + int num_palette_entries; + int entry_bytes; + char component_order[4]; + void *privData; /* private to the library */ +} XvMCSubpicture; + + + subpicture_id - An XID associated with this subpicture. + + context_id - The XID of the context this subpicture was created for. + + xvimage_id - The id descriptor of the XvImage format that may be used + with this subpicture. + + width - + height - The dimensions of the subpicture. + + num_palette_entries - For paletted formats only. This is the number + of palette entries. It is zero for XvImages + without palettes. + + entry_bytes - Each component is one byte and entry_bytes indicates + the number of components in each entry (eg. 3 for + YUV palette entries). This field is zero when + palettes are not used. + + component_order - Is an array of ascii characters describing the order + of the components within the bytes. Only entry_bytes + characters of the string are used. + +Status +XvMCCreateSubpicture ( + Display *display, + XvMCContext *context, + XvMCSubpicture *subpicture, + unsigned short width, + unsigned short height, + int xvimage_id +) + + This creates a subpicture by filling out the XvMCSubpicture structure + passed to it and returning Success. + + display - Specifies the connection to the X-Server. + + context - The context to create the subpicture for. + + subpicture - Pre-allocated XvMCSubpicture structure to be filled + out by this function. + + width - + height - The dimensions of the subpicture. + + xvimage_id - The id describing the XvImage format. + + + Errors: + + BadAlloc - There are insufficient resources to complete this request. + + XvMCBadContext - The specified context does not exist. + + BadMatch - The XvImage format id specified is not supported by + the context. + + BadValue - If the size requested is larger than the max size reported + in the XvMCSurfaceInfo. + + +Status +XvMCClearSubpicture ( + Display *display, + XvMCSubpicture *subpicture, + short x, + short y, + unsigned short width, + unsigned short height, + unsigned int color +) + + Clear the area of the given subpicture to "color". + + display - The connection to the server. + + subpicture - The subpicture to clear. + + x - + y - + width - + height - The rectangle in the subpicture to be cleared. + + color - The data to fill the rectangle with. + + Errors: + + XvMCBadSubpicture - The subpicture is invalid. + +Status +XvMCCompositeSubpicture ( + Display *display, + XvMCSubpicture *subpicture, + XvImage *image, + short srcx, + short srcy, + unsigned short width, + unsigned short height, + short dstx, + short dsty +) + + Copies the XvImage to the XvMCSubpicture. + + display - The connection to the server. + + subpicture - The subpicture used as the destination of the copy. + + image - The XvImage to be used as the source of the copy. + XvImages should be of the shared memory variety for + indirect contexts. + + srcx - + srcy - + width - + height - The rectangle from the image to be composited. + + dstx - + dsty - The location in the subpicture where the source rectangle + should be composited. + + Errors: + + XvMCBadSubpicture - The subpicture is invalid. + + BadMatch - The subpicture does not support the type of XvImage + passed to this function. + +Status +XvMCDestroySubpicture (Display *display, XvMCSubpicture *subpicture) + + Destroys the specified subpicture. + + display - Specifies the connection to the X-server. + + subpicture - The subpicture to be destroyed. + + Errors: + + XvMCBadSubpicture - The subpicture specified does not exist. + + +Status +XvMCSetSubpicturePalette ( + Display *display, + XvMCSubpicture *subpicture, + unsigned char *palette +) + + Set the subpicture's palette. This applies to paletted subpictures + only. + + display - The connection to the server. + + subpicture - The subpicture on which to change the palette. + + palette - A pointer to an array holding the palette data. The + size of this array is + + num_palette_entries * entry_bytes + + in size. The order of the components in the palette + is described by the component_order in the XvMCSubpicture + structure. + + Errors: + + XvMCBadSubpicture - The subpicture specified does not exist. + + BadMatch - The specified subpicture does not use palettes. + + +Status +XvMCBlendSubpicture ( + Display *display, + XvMCSurface *target_surface, + XvMCSubpicture *subpicture, + short subx, + short suby, + unsigned short subw, + unsigned short subh, + short surfx, + short surfy, + unsigned short surfw, + unsigned short surfh +) + +Status +XvMCBlendSubpicture2 ( + Display *display, + XvMCSurface *source_surface, + XvMCSurface *target_surface, + XvMCSubpicture *subpicture, + short subx, + short suby, + unsigned short subw, + unsigned short subh, + short surfx, + short surfy, + unsigned short surfw, + unsigned short surfh +) + + The behavior of these two functions is different depending on whether +or not the XVMC_BACKEND_SUBPICTURE flag is set in the XvMCSurfaceInfo. + + XVMC_BACKEND_SUBPICTURE set: + + XvMCBlendSubpicture associates the subpicture with the target_surface. + Both will be displayed at the next call to XvMCPutSurface. Additional + blends before the call to XvMCPutSurface simply overrides the association. + Both the target_surface and subpicture will query XVMC_DISPLAYING from + the call to XvMCPutSurface until they are no longer displaying. It is + safe to associate the subpicture and target_surface before rendering has + completed (while they still query XVMC_RENDERING) but it is not safe to + call XvMCPutSurface at that time. + + XvMCBlendSubpicture2 copies the source_surface to the target_surface + and associates the subpicture with the target_surface. This essentially + calls XvMCBlendSubpicture on the target_surface after the copy. Both + the subpicture and target_surface will query XVMC_DISPLAYING from the + call to XvMCPutSurface until they are no longer displaying. The + source_surface will not query XVMC_DISPLAYING as a result of this function. + The copy is pipelined with the rendering and will cause XVMC_RENDERING + to be queried until the copy is done. + + + XVMC_BACKEND_SUBPICTURE not set ("frontend" behavior): + + XvMCBlendSubpicture is a no-op in this case. + + XvMCBlendSubpicture2 blends the source_surface and subpicture and + puts it in the target_surface. This does not effect the status of + the source surface but will cause the target_surface to query + XVMC_RENDERING until the blend is completed. + + + display - The connection to the server. + + subpicture - The subpicture to be blended into the video. + + target_surface - The surface to be displayed with the blended subpicture. + + source_surface - Source surface prior to blending. + + subx - + suby - + subw - + subh - The rectangle from the subpicture to be blended. + + surfx - + surfy - + surfw - + surfh - The rectangle in the XvMCSurface to blend the subpicture rectangle + into. If XVMC_SUBPICTURE_INDEPENDENT_SCALING is not set in the + XvMCSurfaceInfo subw must be equal to surfw and subh must be + equal to surfh height or else a BadValue error occurs. + + Errors: + + XvMCBadSurface - Any of the surfaces are invalid. + + XvMCBadSubpicture - The subpicture is invalid. + + BadMatch - The subpicture or any of the surfaces do not belong to the + same context. + + BadValue - XVMC_SUBPICTURE_INDEPENDENT_SCALING is set and the source + and destination rectangles are different sizes. + + +/***********************************************************************/ + + SURFACE SYNCHRONIZATION + +/***********************************************************************/ + + +#define XVMC_RENDERING 0x00000001 +#define XVMC_DISPLAYING 0x00000002 + +Status +XvMCSyncSurface (Display *display, XvMCSurface *surface) + + This function blocks until all rendering requests on the surface + have been completed. + + display - The connection to the server. + + surface - The surface to synchronize. + + Errors: + + XvMCBadSurface - The surface is not valid. + + +Status +XvMCFlushSurface (Display *display, XvMCSurface *surface) + + This function commits pending rendering requests to ensure that + they will be completed in a finite amount of time. + + display - The connnection to the server. + + surface - The surface whos rendering requests should be flushed. + + Errors: + + XvMCBadSurface - The surface is not valid. + + +Status +XvMCGetSurfaceStatus (Display *display, XvMCSurface *surface, int *stat) + + display - The connection to the server. + + surface - The surface whos status is being queried. + + stat - May be any of the following OR'd together: + + XVMC_RENDERING - The last XvMCRenderSurface request has not completed + yet. + + XVMC_DISPLAYING - The surface is currently being displayed or a + display is pending (ie. it is not safe to render + to it). + + Errors: + + XvMCBadSurface - The surface is not valid. + + +/***********************************************************************/ + + SUBPICTURE SYNCHRONIZATION + +/***********************************************************************/ + + + +Status +XvMCSyncSubpicture (Display *display, XvMCSubpicture *subpicture) + + This function blocks until all composite/clear requests on the supicture + have been completed. + + display - The connection to the server. + + subpicture - The subpicture to synchronize. + + Errors: + + XvMCBadSubpicture - The subpicture is not valid. + + +Status +XvMCFlushSubpicture (Display *display, XvMCSubpicture *subpicture) + + This function commits pending composite/clear requests to ensure that + they will be completed in a finite amount of time. + + display - The connection to the server. + + subpicture - The subpicture whos compositing should be flushed. + + Errors: + + XvMCBadSubpicture - The surface is not valid. + + +Status +XvMCGetSubpictureStatus (Display *display, XvMCSubpicture *subpic, int *stat) + + display - The connection to the server. + + subpic - The subpicture whos status is being queried. + + stat - may be any of the following OR'd together: + + XVMC_RENDERING - The last XvMCCompositeSubpicture or XvMCClearSubpicture + request has not completed yet. + + XVMC_DISPLAYING - The subpicture is currently being displayed or a + display is pending (ie. it is not safe to render + to it). + + Errors: + + XvMCBadSubpicture - The surface is not valid. + +/********************************************************************/ + + ATTRIBUTES + +/********************************************************************/ + + Context specific attribute functions are provided. These are +similar to their Xv Counterparts XvQueryPortAttributes, XvSetPortAttribute +and XvGetPortAttribute but their state is specific to the context. + +XvAttribute * +XvMCQueryAttributes ( + Display *display, + XvMCContext *context, + int *number +) + + An array of XvAttributes of size "number" is returned by this function. + If there are no attributes, NULL is returned and number is set to 0. + The array may be freed with XFree(). + + display - The connection to the server. + + context - The context whos attributes we are querying. + + number - The returned number of recognized atoms. + + Errors: + + XvMCBadContext - The context is invalid. + +Status +XvMCSetAttribute ( + Display *display, + XvMCContext *context, + Atom attribute, + int value +) + + This function sets a context-specific attribute and returns Success + if no error has occurred. + + display - The connection to the server. + + context - The context for which the attribute change is to go into effect. + + attribute - The X Atom of the attribute to be changed. + + value - The new value of the attribute. + + Errors: + + XvMCBadContext - The context is not valid. + + BadValue - An invalid value was specified. + + BadMatch - This attribute is not defined for this context. + +Status +XvMCGetAttribute ( + Display *display, + XvMCContext *context, + Atom attribute, + int *value +) + + This function queries a context-specific attribute and return + Success and the value if no error has occurred. + + display - The connection to the server. + + context - The context whos attribute we are querying. + + attribute - The X Atom of the attribute to be retrieved. + + value - The returned attribute value. + + Errors: + + XvMCBadContext - The context is not valid. + + BadMatch - This attribute is not defined for this context. + |