655 lines
20 KiB
Plaintext
655 lines
20 KiB
Plaintext
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
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.
|