diff options
Diffstat (limited to 'xv-protocol-v2.txt')
| -rw-r--r-- | xv-protocol-v2.txt | 654 |
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. |