301 lines
9.4 KiB
Plaintext
301 lines
9.4 KiB
Plaintext
|
|
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.
|