Convert documentation from xv-library-v2.2.txt into man pages

Signed-off-by: Alan Coopersmith <alan.coopersmith@sun.com>

11 files changed, 403 insertions, 12 deletions

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 <X11/extensions/Xvlib.h>
+.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 <X11/extensions/Xvlib.h>
+.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 <X11/extensions/Xvlib.h>
+.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 <X11/extensions/Xvlib.h>
+.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__