xv-protocol-v2.txt

			  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
    represented 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.