Addendum to the Xv Client library documentation =============================================== The following features are new to version 2.2 1) In addition to XvInputMask and XvOutputMask masks in the type field of the XvAdaptorInfo there are 3 new bits defined - XvVideoMask, XvStillMask and XvImageMask indicating that the adaptor is capable of video, still or image primitives respectively. 2) A new function and structure is defined to allow querying port attributes. typedef struct { int flags; int min_value; int max_value; char *name; } XvAttribute; flags - May be XvGettable or XvSettable or both OR'd together indicating the particular attribute is readable, writeable or readable and writeable. min_value, max_value - Indicate the minimun and maximum attribute values which are valid for the driver. name - A string describing the name of the attribute that may be used to retrieve the Atom for the particular attribute. extern XvAttribute* XvQueryPortAttributes( Display* /* display */, XvPortID /* port */, int* /* number */ ); XvQueryPortAttributes returns the number of attributes and an array of XvAttributes valid for the given port. The array may be freed with XFree(). 3) The X Video Extension (Xv) is extended to support client images in alternate colorspaces (XvImages) in the following way. Xv Adaptors which are capable of displaying XvImages will have the XvImageMask field set in the type field of the XvAdaptorInfo. XvImage formats supported by the port may be queried with XvListImageFormats(). XvImages may be created with the help of XvCreateImage() or XvShmCreateImage(); XvImages may be displayed with XvPutImage() or XvShmPutImage(). The Port attributes of the port specified in the Xv(Shm)PutImage command will be valid for the image operation when applicable. There will be a port encoding with the name "XV_IMAGE". The width and height of that encoding will indicate the maximum source image size. typedef struct { int id; /* Unique descriptor for the format */ int type; /* XvRGB, XvYUV */ int byte_order; /* LSBFirst, MSBFirst */ char guid[16]; /* Globally Unique IDentifier */ int bits_per_pixel; int format; /* XvPacked, XvPlanar */ int num_planes; /* for RGB formats */ int depth; unsigned int red_mask; unsigned int green_mask; unsigned int blue_mask; /* for YUV formats */ unsigned int y_sample_bits; unsigned int u_sample_bits; unsigned int v_sample_bits; unsigned int horz_y_period; unsigned int horz_u_period; unsigned int horz_v_period; unsigned int vert_y_period; unsigned int vert_u_period; unsigned int vert_v_period; char component_order[32]; /* eg. UYVY */ int scanline_order; /* XvTopToBottom, XvBottomToTop */ } XvImageFormatValues; id - A unique descriptor for the format. This is often the FOURCC for the format, when applicable. This id is used to describe the format during XvImage creation. type - XvRGB or XvYUV. byte_order - The byte order of the image. It is either LSBFirst or MSBFirst. guid - The Globally Unique IDentifier (also known as Universally Unique IDentifier). When not applicable, all characters are NULL. bits_per_pixel - The bits taken up (but not necessarily used) by each pixel. Note that for some planar formats which have fractional bits per pixel (such as IF09) this number may be rounded _down_. format - XvPacked or XvPlanar. num_planes - The number of planes in planar formats. depth - Significant bits per pixel. red_mask, green_mask, blue_mask - The red, green and blue bitmasks (RGB formats only). ?_sample_bits - The size of each sample in bits (YUV formats only). horz_?_period, vert_?_period - The period (in pixels) on which samples occur in the horizontal and vertical directions (YUV formats only). component_order - Upper case ascii characters representing the order that samples are stored within packed formats. For planar formats this represents the ordering of the planes. scanline_order - XvTopToBottom or XvBottomToTop. Note: Since some formats (particularly some planar YUV formats) may not be completely defined by the parameters above, the guid, when available, should provide the most accurate description of the format. XvImageFormatValues * XvListImageFormats ( Display *display, XvPortID port_id, int *count_return ); Returns the XvImageFormatValues supported by the specified port. This list should be freed with XFree(). typedef struct { int id; int width, height; int data_size; int num_planes; int *pitches; int *offsets; char *data; XPointer obdata; } XvImage; id - XvImageFormatValues id. width, height - The width and height of the image in pixels. int data_size - The size of the data buffer in bytes. num_planes - The number of image planes. pitches - An array of size num_planes indicating the scanline pitch in bytes. Each plane may have a different pitch. offsets - An array of size num_planes indicating the byte offset from "data" to the start of each plane. data - A pointer to the start of the data buffer. obdata - A private field for holding SHM info. This field will be set up by the client libraries so the programmer will generally need not be concerned with this field. XvImage * XvCreateImage ( Display *display, XvPortID port, int id, char *data, int width, int height ); display - Specifies the connection to the Xserver. port - Specifies the port the XvImage will be used with. id - Specifies the format of the image to be created by the XvImageFormatValues id. data - Specifies the image data. width height - Specifies the desired width and height of the image. This function is similar to XCreateImage. The library will allocate the XvImage structure and fill out all fields except for "data". Width and height may be enlarged in some YUV formats. The size of the data buffer that needs to be allocated will be give in the "data_size" field in the XvImage. Image data is not allocated by this function. The client may pass a pointer to the preallocated memory as "data" or may allocate the memory and fill in the XvImage structure's data field after the "data_size" field has been filled out by the server. The XvImage structure may be freed by XFree(); XvImage * XvShmCreateImage ( Display *display, XvPortID port, int id, char* data, int width, int height, XShmSegmentInfo *shminfo ); This function is similar to XShmCreateImage. The library will allocate the XvImage structure and fill out all fields except for "data". Width and height may be enlarged in some YUV formats. The size of the data buffer that needs to be allocated will be give in the "data_size" field in the XvImage. Image data is not allocated by this function. The client may pass a pointer to the preallocated memory as "data" or may allocate the memory and fill in the XvImage structure's data field after the "data_size" field has been filled out by the server. The XvImage structure may be freed by XFree(); XvPutImage ( Display *display, XvPortID id, Drawable d, GC gc, XvImage *image, int src_x, int src_y, unsigned int src_w, unsigned int src_h, int dest_x, int dest_y, unsigned int dest_w, unsigned int dest_h, ); XvShmPutImage ( Display *display, XvPortID id, Drawable d, GC gc, XvImage *image, int src_x, int src_y, unsigned int src_w, unsigned int src_h, int dest_x, int dest_y, unsigned int dest_w, unsigned int dest_h, Bool send_event ); display - The connection to the X-Server. id - The port id of a port on an XvImage capable adaptor. d - The target drawable. gc - the graphics context specifying the clip mask to use, if any. image - A pointer to the XvImage to be displayed. src_? - The portion of the XvImage to be displayed. dest_? - The portion of the destination drawable to be filled by the image. send_event - Indicates whether or not an XShmCompletionEvent should be sent. If sent, the event's major_code and minor_code fields will indicate the Xv extension's major code and XvShmPutImage's minor code. Shared memory segments are attached/detached with XShmAttach/Detach. Some of the possible Errors: BadDrawable - The specified drawable does not exist. BadContext - The specified GC does not exist. BadMatch - Incompatible arguments such as a port that isn't capable of displaying XvImages. XvBadPort - The specified port does not exist. BadAlloc - The server was unable to allocate resources required to complete the operation. BadValue - Some numeric value falls outside the range of the values accepted by the request. BadShmSegCode - An invalid shared memory segment.