From 4d189188c913e6956344689802a582589db04abe Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Sat, 3 Oct 2009 01:31:44 -0700 Subject: Convert documentation from xv-library-v2.2.txt into man pages Signed-off-by: Alan Coopersmith --- man/Makefile.am | 11 ++++- man/Xv.man | 51 ++++++++++++++++---- man/XvCreateImage.man | 103 ++++++++++++++++++++++++++++++++++++++++ man/XvListImageFormats.man | 107 ++++++++++++++++++++++++++++++++++++++++++ man/XvPutImage.man | 77 ++++++++++++++++++++++++++++++ man/XvQueryAdaptors.man | 3 ++ man/XvQueryEncodings.man | 5 +- man/XvQueryPortAttributes.man | 55 ++++++++++++++++++++++ man/XvSetPortAttribute.man | 1 + man/XvShmCreateImage.man | 1 + man/XvShmPutImage.man | 1 + 11 files changed, 403 insertions(+), 12 deletions(-) create mode 100644 man/XvCreateImage.man create mode 100644 man/XvListImageFormats.man create mode 100644 man/XvPutImage.man create mode 100644 man/XvQueryPortAttributes.man create mode 100644 man/XvShmCreateImage.man create mode 100644 man/XvShmPutImage.man diff --git a/man/Makefile.am b/man/Makefile.am index 2651cce..4a3e969 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -28,29 +28,37 @@ libmandir = $(LIB_MAN_DIR) libman_PRE = \ Xv.man \ + XvCreateImage.man \ XvFreeAdaptorInfo.man \ XvFreeEncodingInfo.man \ XvGetPortAttribute.man \ XvGetStill.man \ XvGetVideo.man \ XvGrabPort.man \ + XvListImageFormats.man \ XvPortNotify.man \ + XvPutImage.man \ XvPutStill.man \ XvPutVideo.man \ XvQueryAdaptors.man \ XvQueryBestSize.man \ XvQueryEncodings.man \ XvQueryExtension.man \ + XvQueryPortAttributes.man \ XvSelectPortNotify.man \ XvSelectVideoNotify.man \ XvSetPortAttribute.man \ + XvShmCreateImage.man \ + XvShmPutImage.man \ XvStopVideo.man \ XvUngrabPort.man \ XvVideoNotify.man libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@) -EXTRA_DIST = $(libman_PRE) +LIB_MAN_DIR_SUFFIX = $(LIB_MAN_DIR:@mandir@/man%=%) + +EXTRA_DIST = $(libman_PRE) xv-library-v2.2.txt CLEANFILES = $(libman_DATA) @@ -62,6 +70,7 @@ XORGRELSTRING = @PACKAGE_STRING@ MAN_SUBSTS = \ -e 's/__vendorversion__/"$(XORGRELSTRING)" "$(XORGMANNAME)"/' \ + -e 's/__libmandirsuffix__/$(LIB_MAN_DIR_SUFFIX)/g' \ -e 's/__libmansuffix__/$(LIB_MAN_SUFFIX)/g' SUFFIXES = .$(LIB_MAN_SUFFIX) .man diff --git a/man/Xv.man b/man/Xv.man index 3e41c5e..14abb71 100644 --- a/man/Xv.man +++ b/man/Xv.man @@ -3,10 +3,10 @@ .SH NAME Xv \- X Window System video extension .SH DESCRIPTION -The Xv extension provides support for video adaptors attached to an X -display. It takes the approach that a display may have one or more -video adaptors, each of which has one or more ports through which -independent video streams pass. +The X Video Extension (Xv) extension provides support for video +adaptors attached to an X display. It takes the approach that a +display may have one or more video adaptors, each of which has one or +more ports through which independent video streams pass. .PP An adaptor may be able to display video in a drawable, capture video from a drawable, or both. It translates between video encoding (NTSC, @@ -30,8 +30,30 @@ free to put video into a drawable or get video from a drawable, according the capabilities supported. Clients can select to receive events when video activity changes in a drawable and when port attributes have changed. +.PP +The Xv protocol version 2.2 and later is extended to +support client images in alternate colorspaces (XvImages). +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 +.BR XvListImageFormats (__libmansuffix__). +XvImages may be created with the help of +.BR XvCreateImage (__libmansuffix__) +or +.BR XvShmCreateImage (__libmansuffix__); +XvImages may be displayed with +.BR XvPutImage (__libmansuffix__) +or +.BR XvShmPutImage (__libmansuffix__). +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. .SH SUMMARY OF LIBRARY FUNCTIONS -The following is a summary of Xv library functions: +The following is a summary of Xv library functions and events: +.sp 1l +.BR XvCreateImage (__libmansuffix__) +\- create an XvImage .sp 1l .BR XvGetPortAttribute (__libmansuffix__) \- return current port attribute value @@ -45,9 +67,15 @@ The following is a summary of Xv library functions: .BR XvGrabPort (__libmansuffix__) \- lock port for exclusive use by client .sp 1l +.BR XvListImageFormats (__libmansuffix__) +\- return list of image formats for a port +.sp 1l .BR XvPortNotify (__libmansuffix__) \- event generated when port attributes change .sp 1l +.BR XvPutImage (__libmansuffix__) +\- write a XvImage to a drawable +.sp 1l .BR XvPutStill (__libmansuffix__) \- write a single frame of video to a drawable .sp 1l @@ -66,6 +94,9 @@ The following is a summary of Xv library functions: .BR XvQueryExtension (__libmansuffix__) \- return version and revision of extension .sp 1l +.BR XvQueryPortAttributes (__libmansuffix__) +\- return list of attributes of a port +.sp 1l .BR XvSelectPortNotify (__libmansuffix__) \- enable or disable XvPortNotify events .sp 1l @@ -75,6 +106,12 @@ The following is a summary of Xv library functions: .BR XvSetPortAttribute (__libmansuffix__) \- set an attribute for a port .sp 1l +.BR XvShmCreateImage (__libmansuffix__) +\- create an XvImage in shared memory +.sp 1l +.BR XvShmPutImage (__libmansuffix__) +\- write a XvImage in shared memory to a drawable +.sp 1l .BR XvStopVideo (__libmansuffix__) \- stop active video .sp 1l @@ -85,6 +122,4 @@ The following is a summary of Xv library functions: \- event generated for video processing .sp 1l .PP -Each of these functions is described in its own Xv man page. - - +Each of these functions and events is described in its own Xv man page. diff --git a/man/XvCreateImage.man b/man/XvCreateImage.man new file mode 100644 index 0000000..6cc1558 --- /dev/null +++ b/man/XvCreateImage.man @@ -0,0 +1,103 @@ +.TH XvCreateImage __libmansuffix__ __vendorversion__ "libXv Functions" +.SH NAME +XvCreateImage, XvShmCreateImage \- create an XvImage +.\" +.SH SYNOPSIS +.B #include +.sp +.nf +.BI "XvImage * XvCreateImage (Display *" dpy ", XvPortID " port "," +.BI " int " id ", char *" data "," +.BI " int " width ", int " height ");" +.sp +.BI "XvImage * XvShmCreateImage (Display *" dpy ", XvPortID " port "," +.BI " int " id ", char *" data "," +.BI " int " width ", int " height "," +.BI " XShmSegmentInfo *" shminfo ");" +.fi +.SH ARGUMENTS +.\" +.IP \fIdpy\fR 8 +Specifies the connection to the X server. +.IP \fIport\fR 8 +Specifies the port the XvImage will be used with. +.IP \fIid\fR 8 +Specifies the format of the image to be created by the XvImageFormatValues id. +.IP \fIdata\fR 8 +Specifies the image data. +.IP "\fIwidth\fR, \fIheight\fR" 8 +Specifies the desired width and height of the image. +.\" +.SH DESCRIPTION +.BR XvCreateImage (__libmansuffix__) +is similar to +.BR XCreateImage (__libmansuffix__). +.BR XvShmCreateImage (__libmansuffix__) +is similar to +.BR XShmCreateImage (__libmansuffix__). +The library will allocate the XvImage structure and fill out all +fields except for \fIdata\fR. \fIWidth\fR and \fIheight\fR may be +enlarged in some YUV formats. The size of the data buffer that needs +to be allocated will be given in the \fIdata_size\fR field in the XvImage. +Image data is not allocated by this function. The client may pass a pointer +to the preallocated memory as \fIdata\fR or may allocate the memory and fill in +the XvImage structure's data field after the \fIdata_size\fR field has +been filled out by the server. The XvImage structure may be freed by +.BR XFree (__libmansuffix__). +Shared memory segments are attached/detached with +.BR XShmAttach (__libmansuffix__)/ XShmDetach (__libmansuffix__). +.SH RETURN VALUES +XvImage has the following structure: +.EX + +typedef struct { + int id; + int width, height; + int data_size; + int num_planes; + int *pitches; + int *offsets; + char *data; + XPointer obdata; +} XvImage; + +.EE +.IP \fIid\fR 8 +A descriptor for the format from the XvImageFormatValues structure +returned by +.BR XvListImageFormats (__libmansuffix__). +.IP "\fIwidth, height\fR" 8 +The width and height of the image in pixels. +.IP \fIdata_size\fR 8 +The size of the data buffer in bytes. +.IP \fInum_planes\fR 8 +The number of image planes. +.IP \fIpitches\fR 8 +An array of size \fInum_planes\fR indicating the scanline pitch +in bytes. Each plane may have a different pitch. +.IP \fIoffsets\fR 8 +An array of size \fInum_planes\fR indicating the byte offset +from \fIdata\fR to the start of each plane. +.IP \fIdata\fR 8 +A pointer to the start of the data buffer. +.IP \fIobdata\fR 8 +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. +.\" +.SH DIAGNOSTICS +.IP [XvBadPort] 8 +Generated if the requested port does not exist. +.IP [XvBadAlloc] 8 +Generated if the X server was unable to allocate resources required +to complete the operation. +.IP [BadMatch] 8 +Generated if incompatible arguments were supplied, such as a port that +isn't capable of displaying XvImages. +.\" +.SH SEE ALSO +.BR XvListImageFormats (__libmansuffix__), +.BR XCreateImage (__libmansuffix__), +.BR XShmCreateImage (__libmansuffix__), +.BR XShmAttach (__libmansuffix__), +.BR XShmDetach (__libmansuffix__). diff --git a/man/XvListImageFormats.man b/man/XvListImageFormats.man new file mode 100644 index 0000000..c5159e5 --- /dev/null +++ b/man/XvListImageFormats.man @@ -0,0 +1,107 @@ +.TH XvListImageFormats __libmansuffix__ __vendorversion__ "libXv Functions" +.SH Name +XvListImageFormats \- return list of image formats supported by a video port +.\" +.SH Syntax +.B #include +.sp +.nf +.BI "XvImageFormatValues * XvListImageFormats (Display *" dpy "," +.BI " XvPortID " port ", int *" p_num_formats ");" +.fi +.SH Arguments +.\" +.IP \fIdpy\fR 8 +Specifies the connection to the X server. +.IP \fIport\fR 8 +Specifies the port whose adaptor is to be queried for its list of attributes. +.IP \fIp_num_formats\fR 8 +A pointer to where the number of formats returned in the array is written. +.\" +.SH Description +.BR XvListImageFormats (__libmansuffix__) +returns the XvImageFormatValues supported by the specified port. This list +should be freed with +.BR XFree (__libmansuffix__). +.SH Returned Values +XvImageFormatValues has the following structure: +.EX + + 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; + +.EE +.IP \fIid\fR 8 +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. +.IP \fItype\fR 8 +XvRGB or XvYUV. +.IP \fIbyte_order\fR 8 +The byte order of the image. It is either LSBFirst or MSBFirst. +.IP \fIguid\fR 8 +The Globally Unique IDentifier (also known as Universally Unique +IDentifier). When not applicable, all characters are NULL. +.IP \fIbits_per_pixel\fR 8 +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_. +.IP \fIformat\fR 8 +XvPacked or XvPlanar. +.IP \fInum_planes\fR 8 +The number of planes in planar formats. +.IP \fIdepth\fR 8 +Significant bits per pixel. +.IP "\fIred_mask, green_mask, blue_mask\fR" 8 +The red, green and blue bitmasks (RGB formats only). +.IP \fI?_sample_bits\fR 8 +The size of each sample in bits (YUV formats only). +.IP "\fIhorz_?_period, vert_?_period\fR" 8 +The period (in pixels) on which samples occur in the horizontal and vertical +directions (YUV formats only). +.IP \fIcomponent_order\fR 8 +Upper case ascii characters representing the order that samples are stored +within packed formats. +For planar formats this represents the ordering of the planes. +.IP \fIscanline_order\fR 8 +XvTopToBottom or XvBottomToTop. +.\" +.SH Notes +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. +.\" +.SH Diagnostics +.IP [XvBadPort] 8 +Generated if the requested port does not exist. +.\" +.SH See Also +.BR XvCreateImage (__libmansuffix__), +.BR XvCreateShmImage (__libmansuffix__) diff --git a/man/XvPutImage.man b/man/XvPutImage.man new file mode 100644 index 0000000..ab9b575 --- /dev/null +++ b/man/XvPutImage.man @@ -0,0 +1,77 @@ +.TH XvPutImage __libmansuffix__ __vendorversion__ "libXv Functions" +.SH NAME +XvPutImage, XvShmPutImage \- display an XvImage +.\" +.SH SYNOPSIS +.B #include +.sp +.nf +.BI "int XvPutImage (Display *" dpy ", XvPortID " port "," +.BI " Drawable " d ", GC " gc ", XvImage *" image "," +.BI " int " src_x ", int " src_y "," +.BI " unsigned int " src_w ", unsigned int " src_h "," +.BI " int " dest_x ", int " dest_y "," +.BI " unsigned int " dest_w ", unsigned int " dest_h ");" +.sp +.BI "int XvShmPutImage (Display *" dpy ", XvPortID " port "," +.BI " Drawable " d ", GC " gc ", XvImage *" image "," +.BI " int " src_x ", int " src_y "," +.BI " unsigned int " src_w ", unsigned int " src_h "," +.BI " int " dest_x ", int " dest_y "," +.BI " unsigned int " dest_w ", unsigned int " dest_h "," +.BI " Bool " send_event ");" +.fi +.SH ARGUMENTS +.\" +.IP \fIdpy\fR 8 +Specifies the connection to the X server. +.IP \fIport\fR 8 +The port id of a port on an XvImage capable adaptor. +.IP \fId - The target drawable. +.IP \fIgc\fR 8 +the graphics context specifying the clip mask to use, if any. +.IP \fIimage\fR 8 +A pointer to the XvImage to be displayed. +.IP \fIsrc_?\fR 8 +The portion of the XvImage to be displayed. +.IP \fIdest_?\fR 8 +The portion of the destination drawable to be filled by the image. +.IP \fIsend_event\fR 8 +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. +.\" +.SH DESCRIPTION +.BR XvPutImage (__libmansuffix__) +is similar to +.BR XPutImage (__libmansuffix__). +.BR XvShmPutImage (__libmansuffix__) +is similar to +.BR XShmPutImage (__libmansuffix__). +The library will allocate the XvImage structure and fill out all +fields except for \fIdata\fR. \fIWidth\fR and \fIheight\fR may be +enlarged in some YUV formats. The size of the data buffer that needs +to be allocated will be given in the \fIdata_size\fR field in the XvImage. +Image data is not allocated by this function. The client may pass a pointer +to the preallocated memory as \fIdata\fR or may allocate the memory and fill in +the XvImage structure's data field after the \fIdata_size\fR field has +been filled out by the server. The XvImage structure may be freed by +.BR XFree (__libmansuffix__). +.SH DIAGNOSTICS +.IP [XvBadPort] 8 +Generated if the requested port does not exist. +.IP [XvBadAlloc] 8 +Generated if the X server was unable to allocate resources required +to complete the operation. +.IP [BadMatch] 8 +Generated if incompatible arguments were supplied, such as a port that +isn't capable of displaying XvImages. +.IP [BadShmSegCode] 8 +Generated if an invalid shared memory segment is specified. +.\" +.SH SEE ALSO +.BR XvListImageFormats (__libmansuffix__), +.BR XvCreateImage (__libmansuffix__), +.BR XvShmCreateImage (__libmansuffix__) +.BR XPutImage (__libmansuffix__), +.BR XShmPutImage (__libmansuffix__) diff --git a/man/XvQueryAdaptors.man b/man/XvQueryAdaptors.man index bb52ff5..48eabae 100644 --- a/man/XvQueryAdaptors.man +++ b/man/XvQueryAdaptors.man @@ -50,6 +50,9 @@ The number of ports supported by the adaptor. .IP \fItype\fR 8 A bit mask with the value XvInputMask asserted if the adaptor supports video input, and value XvOutputMask asserted if the adaptor supports video output. +In Xv protocol 2.2 and later, there are 3 new bits defined - XvVideoMask, +XvStillMask and XvImageMask indicating that the adaptor is capable +of video, still or image primitives respectively. .IP \fIname\fR 8 A vendor specific name that identifies the adaptor. .IP \fInum_formats\fR 8 diff --git a/man/XvQueryEncodings.man b/man/XvQueryEncodings.man index 34e55d0..ef24f59 100644 --- a/man/XvQueryEncodings.man +++ b/man/XvQueryEncodings.man @@ -14,9 +14,8 @@ XvQueryEncodings \- return list of encodings for an adaptor .\" .IP \fIdpy\fR 8 Specifies the connection to the X server. -.IP \fIXvPortID\fR 8 -Specifies the port whose adaptor is to be queried for its -list of encodings. +.IP \fIport\fR 8 +Specifies the port whose adaptor is to be queried for its list of encodings. .IP \fIp_num_encodings\fR 8 A pointer to where the number of encodings supported by the adaptor is written. diff --git a/man/XvQueryPortAttributes.man b/man/XvQueryPortAttributes.man new file mode 100644 index 0000000..9fbc507 --- /dev/null +++ b/man/XvQueryPortAttributes.man @@ -0,0 +1,55 @@ +.TH XvQueryPortAttributes __libmansuffix__ __vendorversion__ "libXv Functions" +.SH NAME +XvQueryPortAttributes \- return list of attributes of a video port +.\" +.SH SYNOPSIS +.B #include +.sp +.nf +.BI "XvAttribute* XvQueryPortAttributes(Display *" dpy "," +.BI " XvPortID " port ", int *" p_num_attributes ");" +.fi +.SH ARGUMENTS +.\" +.IP \fIdpy\fR 8 +Specifies the connection to the X server. +.IP \fIport\fR 8 +Specifies the port whose adaptor is to be queried for its list of attributes. +.IP \fIp_num_attributes\fR 8 +A pointer to where the number of attributes returned in the array is written. +.\" +.SH DESCRIPTION +.BR XvQueryPortAttributes (__libmansuffix__) returns the number of attributes +and an array of XvAttributes valid for the given port. The array may be +freed with +.BR XFree (__libmansuffix__). +.SH RETURN VALUES +XvAttribute has the following structure: +.EX + + typedef struct { + int flags; + int min_value; + int max_value; + char *name; + } XvAttribute; + +.EE +.IP \fIflags\fR 8 +May be XvGettable or XvSettable or both OR'd together indicating the +particular attribute is readable, writeable or readable and writeable. +.IP \fImin_value\fR 8 +The minimum attribute values which are valid for the driver. +.IP \fI max_value\fR 8 +The maximum attribute values which are valid for the driver. +.IP \fIname\fR 8 +A string describing the name of the attribute that may be used +to retrieve the Atom for the particular attribute. +.\" +.SH DIAGNOSTICS +.IP [XvBadPort] 8 +Generated if the requested port does not exist. +.\" +.SH SEE ALSO +.BR XvGetPortAttribute (__libmansuffix__), +.BR XvSetPortAttribute (__libmansuffix__) diff --git a/man/XvSetPortAttribute.man b/man/XvSetPortAttribute.man index 74e1f4d..c1f14dc 100644 --- a/man/XvSetPortAttribute.man +++ b/man/XvSetPortAttribute.man @@ -85,5 +85,6 @@ supported by the adaptor. .SH SEE ALSO .\" .BR XvGetPortAttribute (__libmansuffix__), +.BR XvQueryPortAttributes (__libmansuffix__), .BR XvSelectPortNotify (__libmansuffix__), .BR XvPortNotify (__libmansuffix__) diff --git a/man/XvShmCreateImage.man b/man/XvShmCreateImage.man new file mode 100644 index 0000000..f44dd89 --- /dev/null +++ b/man/XvShmCreateImage.man @@ -0,0 +1 @@ +.so man__libmandirsuffix__/XvCreateImage.__libmandirsuffix__ diff --git a/man/XvShmPutImage.man b/man/XvShmPutImage.man new file mode 100644 index 0000000..3f15682 --- /dev/null +++ b/man/XvShmPutImage.man @@ -0,0 +1 @@ +.so man__libmandirsuffix__/XvPutImage.__libmandirsuffix__ -- cgit v1.2.3