Move xv-protocol-v2.txt from xorg-docs to videoproto

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

1 files changed, 654 insertions, 0 deletions

diff --git a/xv-protocol-v2.txt b/xv-protocol-v2.txt
new file mode 100644
index 0000000..31e2013
--- /dev/null
+++ b/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.