Move specs/Xv/xv-library-v2.2.txt to libXv module

Remove library spec this time, not the protocol spec.   Oops.

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

3 files changed, 654 insertions, 301 deletions

diff --git a/Makefile.am b/Makefile.am
index e4e52b2..4fffdd6 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -230,7 +230,6 @@ EXTRA_DIST = \
 	specs/Xt/strings.mit \
 	specs/Xt/Xtk.intr.front \
 	specs/XvMC/XvMC_API.txt \
-	specs/Xv/xv-library-v2.2.txt \
 	specs/Xv/xv-protocol-v2.txt \
 	util/block.awk \
 	util/fixindex.awk \
diff --git a/specs/Xv/xv-library-v2.2.txt b/specs/Xv/xv-library-v2.2.txt
deleted file mode 100644
index 41e7cbd..0000000
--- a/specs/Xv/xv-library-v2.2.txt
+++ /dev/null
@@ -1,300 +0,0 @@
-
-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.
diff --git a/specs/Xv/xv-protocol-v2.txt b/specs/Xv/xv-protocol-v2.txt
new file mode 100644
index 0000000..31e2013
--- /dev/null
+++ b/specs/Xv/xv-protocol-v2.txt
@@ -0,0 +1,654 @@
+
+
+
+
+
+
+
+
+
+			  X Video Extension
+			 Protocol Description
+
+			      Version 2
+
+			      25-JUL-91
+
+			     David Carver
+
+		    Digital Equipment Corporation
+		Workstation Engineering/Project Athena
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
+  Copyright 1991 by Digital Equipment Corporation, Maynard, Massachusetts, 
+  and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
+
+                        All Rights Reserved
+
+  Permission to use, copy, modify, and distribute this software and its
+  documentation for any purpose and without fee is hereby granted, provided
+  that the above copyright notice appear in all copies and that both that
+  copyright notice and this permission notice appear in supporting
+  documentation, and that the names of Digital or MIT not be used in
+  advertising or publicity pertaining to distribution of the software
+  without specific, written prior permission.
+
+  DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
+  ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL 
+  DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR 
+  ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER 
+  IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING 
+  OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.  
+  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+
+
+  Preface
+  -------
+  
+    The following is an outline for an X video extension protocol.  It
+    is preliminary and subject to change.  My goal in writing this was
+    to fix some the shortcomings of existing overly simplistic
+    extensions while avoiding pitfalls in an overly complex extension.
+  
+    Your feedback is desired, and since the major design directions
+    have been stable for some time, feel free to hammer on the details
+    of the protocol.
+
+    When you receive a revision of the document, refer to the changes
+    and issues sections to guide your review and analysis.
+
+
+  Acknowledgements
+  ---------------
+
+    The following people have made major contributions to the design of
+    the Xv protocol:
+
+      Branko Gerovac (DEC/Corporate Research)
+      Russ Sasnett (GTE/Project Athena)
+      Ralph Swick (DEC/Project Athena)
+
+    Many ideas and approaches in Xv were the product of discussions
+    with several groups, including
+
+      Project Athena's Visual Computing Group
+      The MIT X Consortium 
+      The MIT Media Lab's Interactive Cinema Group
+      
+  
+  
+  Changes
+  -------
+
+    From version 1.3 to 2.0
+
+    -- Changed SetPortControl and GetPortControl to GetPortAttribute
+       and SetPortAttribute.
+
+    -- Changed QueryBestSize
+
+    -- Simplified SelectVideoNotify and SelectPortNotify requests.
+
+    -- Changed the way SetPortControl and GetPortControl works.
+
+    -- Added a QueryExtension request to return the version and
+       revision information of the extension.
+
+    -- Changed the name of the QueryVideo request to QueryAdaptors;
+       Removed the list of encodings from QueryVideo and added a
+       QueryEncodings request.
+
+    -- Added a PortNotify event that notifies interested clients that
+       a port control has been changed.
+
+    -- Added SelectPortNotify request to select for PortNotify events.
+
+    -- The XvInterruped reason has been replaced by two new reasons:
+       one for when video is preempted by another video request and
+       one for when video is terminated because of hard transmission
+       or reception errors.
+
+    -- Changed the wording of the QueryBestSize request.  Added issue
+       about whether or not returned sizes should maintain the
+       requested aspect ratio.
+
+
+
+  Introduction
+  ------------
+  
+    Video technology is moving very quickly.  Standards for processing
+    high resolution video are currently a hot topic of discussion
+    internationally, and it will soon be possible to process video
+    entirely within the digital domain.  The Xv extension, however,
+    does not attempt to address issues of digital video.  Its purpose
+    is to provide a mechanism for support of current and near term
+    interactive video technology.
+    
+    It is somewhat ironic that Xv contains nothing particularly
+    innovative.  It takes a minimalistic approach, and without a doubt
+    it could have been defined years ago, and with several revisions.
+    So, the life expectancy of Xv is not long.  Nevertheless, it may
+    undergo further revision and experimentation that will help our
+    progress towards digital video systems.
+  
+    One premise of the Xv extension is that the X server is not alone.
+    A separate video server is often used to manage other aspects of
+    video processing, though the partition between what the X server
+    does and what a video server does is a matter of great debate.
+
+  
+  Model
+  -----
+  
+    This extension models video monitor capabilities in the X Window
+    System.  Some advanced monitors support the simultaneous display
+    of multiple video signals (into separate windows), and that is
+    prepresented here through the ability to display video from
+    multiple video input adaptors into X drawables.
+  
+    Some monitors support multiple video encodings (mostly for
+    internationalization purposes) either through switches or
+    automatic detection, thus each video adaptor specifies the set of
+    encodings it supports.
+  
+    The requests to display video from an adaptor into a drawable are
+    modeled after the core PutImage request, though extended to
+    support scaling and source clipping.
+  
+    Video output is also supported and is symmetric with the video
+    input function, though fewer GC components are used.
+  
+  
+  Mechanism
+  ---------
+  
+    The Xv extension does the following:
+  
+      --  lists available video adaptors
+      --  identifies the number of ports each adaptor supports
+      --  describes what drawable formats each adaptor supports
+      --  describes what video encodings each adaptor supports
+      --  displays video from a port to a drawable
+      --  captures video from a drawable to a port
+      --  grabs and ungrabs ports
+      --  sets and gets port attributes
+      --  delivers event notification
+  
+
+  
+  Adaptors
+  --------
+  
+    A display may have multiple video input and output adaptors.  An
+    adaptor may support multiple simultaneously active ports, and in
+    some cases the number of ports has no fixed limit.
+  
+    An input port receives encoded video data and converts it to a
+    stream of data used to update a drawable.  An output port samples
+    data from a drawable and produces a stream of encoded video data.
+  
+    The ADAPTORINFO structure is used to describe a video adaptor.
+    
+    ADAPTORINFO:
+  	[base-id: PORT
+         num-ports: CARD16
+         type: SETofADAPTORTYPE
+         formats: LISTofFORMAT
+         name: STRING]
+  
+    ADAPTORTYPE: {Input, Output}
+
+    FORMAT:
+  	[depth: CARD8
+  	 visual: VISUALID]
+  
+    The base-id field specifies the XID of the first port of the
+    adaptor.  The `num-ports' field specifies how many ports the
+    adaptor supports.  The ports of the adaptor have XIDs in the range
+    [base-id..base-id + num-ports - 1]
+
+    The type attribute determines if the adaptor can process video
+    input, output, or input and output.  The if the adaptor can
+    process input then Input is asserted, if the adaptor can process
+    output then Output is asserted.
+
+    The drawable depths and visual types supported by the adaptor are
+    listed in `formats'.  Note: that when video is being processed for
+    pixmaps the visual format is taken to be the visual of the first
+    pair that matches the depth of the pixmap.
+
+    The name field contains an a vendor specific string that
+    identifies the adaptor.
+
+    It should be noted that the existence of separate adaptors doesn't
+    necessarily imply that simultaneous operation is supported.
+
+
+  
+  Errors
+  ------
+  
+    Port
+  
+    A Port error is returned if any request names a PORT that does not
+    exist.
+
+  
+    Encoding
+  
+    An Encoding error is returned if any request names an ENCODINGID
+    that does not exist.
+
+
+
+  
+  Query Requests
+  -------------------
+
+    QueryExtension
+    ==>
+      version: CARD16
+      revision: CARD16
+
+    The QueryExtension request returns the extension version and
+    revision numbers.
+
+  
+    QueryAdaptors
+      win: WINDOW
+    ==>
+      adaptors: LISTofADAPTORINFO
+  
+    The QueryAdaptors request returns the video adaptor information for
+    the screen of the specified window.
+  
+    Errors: {Window}
+
+
+    QueryEncodings    
+      port: PORT
+    ==>
+      encodings: LISTofENCODINGINFO
+
+    The QueryEncodings request returns the list of encodings supported
+    by the port adaptor.  Use the SetPortAttribute request to set
+    which encoding a port is to process.  The ENCODINGINFO record
+    describes an encoding:
+
+    ENCODINGINFO:
+  	[encoding: ENCODINGID
+  	 name: STRING
+  	 width, height: CARD16
+  	 rate: FRACTION]
+  
+    The `encoding' field identifies an encoding supported by a port.
+    Its value is unique for a screen.  Width and height specify the
+    size of the video image and rate specifies the rate at which
+    fields of image information are encoded.
+  
+    An encoding is identified by a string that names the encoding.
+    Encoding naming conventions need to be established (i.e.,
+    something along the lines of font naming, but simpler)
+  
+    FRACTION
+          [numerator, denominator: INT32]
+  
+    The FRACTION structure is used to specify a fractional number.
+
+    Errors: {Port}
+
+
+  
+  Put Video Requests
+  ------------------
+  
+    PutVideo
+      port: PORT
+      drawable: DRAWABLE
+      gc: GCONTEXT
+      vid-x, vid-y: INT16
+      vid-w, vid-h: CARD16
+      drw-x, drw-y: INT16
+      drw-w, drw-h: CARD16
+  
+    The PutVideo request writes video into a drawable.  The position
+    and size of the source rectangle is specified by vid-x, vid-y,
+    vid-w, and vid-h.  The position and size of the destination
+    rectangle is specified by drw-x, drw-y, drw-w, drw-h.
+  
+    Video data is clipped to the bounds of the video encoding, scaled
+    to the requested drawable region size (or the closest size
+    supported), and clipped to the bounds of the drawable.
+
+    If video is successfully initiated, a VideoNotify event with
+    detail Started is generated for the drawable.  If the port is
+    already in use, its video is preempted, and if the new drawable is
+    different than the old, a VideoNotify event with detail Preempted
+    is generated for the old drawable.  If the port is grabbed by
+    another client, this request is ignored, and a VideoNotify event
+    with detail Busy is generated for the drawable.  If the port is
+    not receiving a valid video signal or if the video signal is
+    interrupted while video is active a VideoNotify event with detail
+    HardError is generated for the drawable.
+
+    GC components: subwindow-mode, clip-x-origin, clip-y-origin, clip-mask.
+  
+    Errors: {Match, Value, GContext, Port, Alloc}
+  
+  
+    PutStill
+      port: PORT
+      drawable: DRAWABLE
+      gc: GCONTEXT
+      vid-x, vid-y: INT16
+      vid-w, vid-h: CARD16
+      drw-x, drw-y: INT16
+      drw-w, drw-h: CARD16
+  
+    The PutStill request writes a single frame of video into a
+    drawable.  The position and size of the source rectangle is
+    specified by vid-x, vid-y, vid-w, and vid-h.  The position and
+    size of the destination rectangle is specified by drw-x, drw-y,
+    drw-w, drw-h.
+  
+    Video data is clipped to the bounds of the video encoding, scaled
+    to the requested drawable region size (or the closest size
+    supported) and clipped to the bounds of the drawable.
+
+    If the port is grabbed by another client, this request is ignored,
+    and a VideoNotify event with detail Busy is generated for the
+    drawable.  If the port is not receiving a valid video signal a
+    VideoNotify event with detail HardError is generated for the
+    drawable.
+
+    GC components: subwindow-mode, clip-x-origin, clip-y-origin, clip-mask.
+  
+    Errors: {Match, Value, GContext, Port, Alloc}
+  
+  
+  
+  Get Video Requests
+  ------------------
+  
+    GetVideo
+      port: PORT
+      drawable: DRAWABLE
+      gc: GCONTEXT
+      vid-x, vid-y: INT16
+      vid-w, vid-h: CARD16
+      drw-x, drw-y: INT16
+      drw-w, drw-h: CARD16
+  
+    The GetVideo request outputs video from a drawable.  The position
+    and size of the destination rectangle is specified by vid-x,
+    vid-y, vid-w, and vid-h.  The position and size of the source
+    rectangle is specified by drw-x, drw-y, drw-w, and drw-h.
+  
+    Drawable data is clipped to the bounds of the drawable, scaled to
+    the requested video region size (or the closest size supported)
+    and clipped to the bounds of the video encoding.  The contents of
+    any region not updated with drawable data is undefined.
+
+    If video is successfully initiated, a VideoNotify event with
+    detail Started is generated for the drawable.  If the port is
+    already in use, its video is preempted, and if the new drawable is
+    different than the old, a VideoNotify event with detail Preempted
+    is generated for the old drawable.  If the port is grabbed by
+    another client, this request is ignored, and a VideoNotify event
+    with detail Busy is generated for the drawable.
+
+    GC components: subwindow-mode, clip-x-origin, clip-y-origin,
+    clip-mask.
+  
+    Errors: {Match, Value, GContext, Port, Alloc}
+  
+  
+    GetStill
+      port: PORT
+      drawable: DRAWABLE
+      gc: GCONTEXT
+      vid-x, vid-y: INT16
+      vid-w, vid-h: CARD16
+      drw-x, drw-y: INT16
+      drw-w, drw-h: CARD16
+  
+    The GetStill request outputs video from a drawable.  The position
+    and size of the destination rectangle is specified by vid-x,
+    vid-y, vid-w, and vid-h.  The position and size of the source
+    rectangle is specified by drw-x, drw-y, drw-w, and drw-h.
+  
+    Drawable data is clipped to the bounds of the drawable, scaled to
+    the requested video region size (or the closest size supported)
+    and clipped to the bounds of the video encoding.  The contents of
+    any region not updated with drawable data is undefined.
+
+    If the still is successfully captured a VideoNotify event with
+    detail Still is generated for the drawable.  If the port is
+    grabbed by another client, this request is ignored, and a
+    VideoNotify event with detail Busy is generated for the drawable.
+
+    GC components: subwindow-mode, clip-x-origin, clip-y-origin,
+    clip-mask.
+  
+    Errors: {Match, Value, GContext, Port, Alloc}
+  
+  
+  
+  
+  Grab Requests
+  -------------
+  
+    GrabPort
+      port: PORT    
+      timestamp: {TIMESTAMP, CurrentTime}
+    ==>
+      status: {Success, AlreadyGrabbed, InvalidTime}
+  
+    The GrabPort request grabs a port.  While a port is grabbed, only
+    video requests from the grabbing client are permitted.
+  
+    If timestamp specifies a time older than the current port time, a
+    status of InvalidTime is returned.  If the port is already grabbed
+    by another client, a status of AlreadyGrabbed is returned.
+    Otherwise a status of Success is returned. The port time is
+    updated when the following requests are processed: GrabPort,
+    UngrabPort, PutVideo, PutStill, GetVideo, GetStill
+  
+    If the port is actively processing video for another client, the
+    video is preempted, and an VideoNotify event with detail Preempted
+    is generated for its drawable.
+
+    Errors: {Port}
+  
+  
+    UngrabPort
+      port: PORT    
+      timestamp: {TIMESTAMP, CurrentTime}
+  
+    The UngrabPort request ungrabs a port.  If timestamp specifies a
+    time before the last connection request time of this port, the
+    request is ignored.
+  
+    Errors: {Port}
+  
+
+
+  Other Requests
+  --------------
+  
+    StopVideo
+      port: PORT
+      drawable: DRAWABLE
+  
+    The StopVideo request stops active video for the specified port
+    and drawable.  If the port isn't processing video, or if it is
+    processing video in a different drawable, the request is ignored.
+    When video is stopped a VideoNotify event with detail Stopped is
+    generated for the associated drawable.
+
+    Errors: {Drawable, Port}  
+
+  
+    SelectVideoNotify
+      drawable: DRAWABLE
+      onoff: BOOL
+  
+    The SelectVideoNotify request enables or disables VideoNotify
+    event delivery to the requesting client.  VideoNotify events are
+    generated when video starts and stops.
+
+    Errors: {Drawable}
+
+
+    SelectPortNotify
+      port: PORT
+      onoff: BOOL
+  
+    The SelectPortNotify request enables or disables PortNotify event
+    delivery to the requesting client.  PortNotify events are
+    generated when port attributes are changed using SetPortAttribute.
+
+    Errors: {Port}
+
+  
+    QueryBestSize
+      port: PORT
+      motion: BOOL
+      vid-w, vid-h: CARD16
+      drw-w, drw-h: CARD16
+    ==>
+      actual-width, actual-height: CARD16
+  
+    The QueryBestSize request returns, for the given source size and
+    desired destination size, the closest destination size that the
+    port adaptor supports.  The returned size will be equal
+    or smaller than the requested size if one is supported.  If motion
+    is True then the requested size is intended for use with full
+    motion video.  If motion is False, the requested size is intended
+    for use with stills only.
+
+    The retuned size is also chosen to maintain the requested aspect ratio
+    if possible.
+  
+    Errors: {Port}
+  
+
+    
+    SetPortAttribute
+      port: PORT
+      attribute: ATOM
+      value: INT32
+  
+    The SetPortAttribute request sets the value of a port attribute.
+    The port attribute is identified by the attribute atom.  The
+    following strings are guaranteed to generate valid atoms using the
+    InternAtom request.
+
+    String                Type          
+    -----------------------------------------------------------------
+  
+    "XV_ENCODING"         ENCODINGID
+    "XV_HUE"	          [-1000..1000] 
+    "XV_SATURATION"       [-1000..1000] 
+    "XV_BRIGHTNESS"       [-1000..1000] 
+    "XV_CONTRAST"         [-1000..1000]
+  
+
+    If the given attribute doesn't match an attribute supported by the
+    port adaptor a Match error is generated.  The supplied encoding
+    must be one of the encodings listed for the adaptor, otherwise an
+    Encoding error is generated.
+
+    If the adaptor doesn't support the exact hue, saturation,
+    brightness, and contrast levels supplied, the closest levels
+    supported are assumed.  The GetPortAttribute request can be used
+    to query the resulting levels.
+
+    When a SetPortAttribute request is processed a PortNotify event is
+    generated for all clients that have requested port change
+    notification using SelectPortNotify.
+
+    Errors: {Port, Match, Value}
+  
+  
+    GetPortAttribute
+      port: PORT
+      attribute: ATOM
+    ==>
+      value: INT32  
+        
+
+    The GetPortAttribute request returns the current value of the
+    attribute identified by the given atom.  If the given atom
+    doesn't match an attribute supported by the adaptor a Match
+    error is generated.
+
+    Errors: {Port, Match}
+
+
+
+  Events
+  ------
+  
+    VideoNotify
+      drawable: DRAWABLE
+      port: PORT
+      reason: REASON
+      time: TIMESTAMP
+
+    REASON: {Started, Still, Stopped, Busy, Preempted, HardError}
+
+    A VideoNotify event is generated when video activity is started,
+    stopped, or unable to proceed in a drawable.
+
+    A Started reason is generated when video starts in a drawable.
+
+    A Stopped reason is generated when video is stopped in a
+    drawable upon request.
+
+    A Busy reason is generated when a put or get request cannot
+    proceed because the port is grabbed by another client.
+
+    A Preempted reason is generated when video is stopped by a
+    conflicting request.
+  
+    A HardError reason is generated when the video port cannot
+    initiate or continue processing a video request because of an
+    underlying transmission or reception error.
+  
+
+    PortNotify
+      port: PORT
+      attribute: ATOM
+      value: INT32
+      time: TIMESTAMP
+  
+    The PortNotify event is generated when a SetPortAttribute request
+    is processed.  The event is delivered to all clients that have
+    performed a SelectPortNotify request for the port.  The event
+    contains the atom identifying the attribute that changed, and the
+    new value of that attribute.