xv-protocol-v2.txt

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10                           X Video Extension
  11                          Protocol Description
  12
  13                               Version 2
  14
  15                               25-JUL-91
  16
  17                              David Carver
  18
  19                     Digital Equipment Corporation
  20                 Workstation Engineering/Project Athena
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  45   Copyright 1991 by Digital Equipment Corporation, Maynard, Massachusetts,
  46   and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
  47
  48                         All Rights Reserved
  49
  50   Permission to use, copy, modify, and distribute this software and its
  51   documentation for any purpose and without fee is hereby granted, provided
  52   that the above copyright notice appear in all copies and that both that
  53   copyright notice and this permission notice appear in supporting
  54   documentation, and that the names of Digital or MIT not be used in
  55   advertising or publicity pertaining to distribution of the software
  56   without specific, written prior permission.
  57
  58   DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  59   ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
  60   DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
  61   ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
  62   IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
  63   OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  64   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  65
  66 \f
  67
  68   Preface
  69   -------
  70
  71     The following is an outline for an X video extension protocol.  It
  72     is preliminary and subject to change.  My goal in writing this was
  73     to fix some the shortcomings of existing overly simplistic
  74     extensions while avoiding pitfalls in an overly complex extension.
  75
  76     Your feedback is desired, and since the major design directions
  77     have been stable for some time, feel free to hammer on the details
  78     of the protocol.
  79
  80     When you receive a revision of the document, refer to the changes
  81     and issues sections to guide your review and analysis.
  82
  83
  84   Acknowledgements
  85   ---------------
  86
  87     The following people have made major contributions to the design of
  88     the Xv protocol:
  89
  90       Branko Gerovac (DEC/Corporate Research)
  91       Russ Sasnett (GTE/Project Athena)
  92       Ralph Swick (DEC/Project Athena)
  93
  94     Many ideas and approaches in Xv were the product of discussions
  95     with several groups, including
  96
  97       Project Athena's Visual Computing Group
  98       The MIT X Consortium
  99       The MIT Media Lab's Interactive Cinema Group
 100
 101
 102   \f
 103   Changes
 104   -------
 105
 106     From version 1.3 to 2.0
 107
 108     -- Changed SetPortControl and GetPortControl to GetPortAttribute
 109        and SetPortAttribute.
 110
 111     -- Changed QueryBestSize
 112
 113     -- Simplified SelectVideoNotify and SelectPortNotify requests.
 114
 115     -- Changed the way SetPortControl and GetPortControl works.
 116
 117     -- Added a QueryExtension request to return the version and
 118        revision information of the extension.
 119
 120     -- Changed the name of the QueryVideo request to QueryAdaptors;
 121        Removed the list of encodings from QueryVideo and added a
 122        QueryEncodings request.
 123
 124     -- Added a PortNotify event that notifies interested clients that
 125        a port control has been changed.
 126
 127     -- Added SelectPortNotify request to select for PortNotify events.
 128
 129     -- The XvInterruped reason has been replaced by two new reasons:
 130        one for when video is preempted by another video request and
 131        one for when video is terminated because of hard transmission
 132        or reception errors.
 133
 134     -- Changed the wording of the QueryBestSize request.  Added issue
 135        about whether or not returned sizes should maintain the
 136        requested aspect ratio.
 137
 138 \f
 139
 140   Introduction
 141   ------------
 142
 143     Video technology is moving very quickly.  Standards for processing
 144     high resolution video are currently a hot topic of discussion
 145     internationally, and it will soon be possible to process video
 146     entirely within the digital domain.  The Xv extension, however,
 147     does not attempt to address issues of digital video.  Its purpose
 148     is to provide a mechanism for support of current and near term
 149     interactive video technology.
 150
 151     It is somewhat ironic that Xv contains nothing particularly
 152     innovative.  It takes a minimalistic approach, and without a doubt
 153     it could have been defined years ago, and with several revisions.
 154     So, the life expectancy of Xv is not long.  Nevertheless, it may
 155     undergo further revision and experimentation that will help our
 156     progress towards digital video systems.
 157
 158     One premise of the Xv extension is that the X server is not alone.
 159     A separate video server is often used to manage other aspects of
 160     video processing, though the partition between what the X server
 161     does and what a video server does is a matter of great debate.
 162
 163
 164   Model
 165   -----
 166
 167     This extension models video monitor capabilities in the X Window
 168     System.  Some advanced monitors support the simultaneous display
 169     of multiple video signals (into separate windows), and that is
 170     prepresented here through the ability to display video from
 171     multiple video input adaptors into X drawables.
 172
 173     Some monitors support multiple video encodings (mostly for
 174     internationalization purposes) either through switches or
 175     automatic detection, thus each video adaptor specifies the set of
 176     encodings it supports.
 177
 178     The requests to display video from an adaptor into a drawable are
 179     modeled after the core PutImage request, though extended to
 180     support scaling and source clipping.
 181
 182     Video output is also supported and is symmetric with the video
 183     input function, though fewer GC components are used.
 184
 185
 186   Mechanism
 187   ---------
 188
 189     The Xv extension does the following:
 190
 191       --  lists available video adaptors
 192       --  identifies the number of ports each adaptor supports
 193       --  describes what drawable formats each adaptor supports
 194       --  describes what video encodings each adaptor supports
 195       --  displays video from a port to a drawable
 196       --  captures video from a drawable to a port
 197       --  grabs and ungrabs ports
 198       --  sets and gets port attributes
 199       --  delivers event notification
 200
 201 \f
 202
 203   Adaptors
 204   --------
 205
 206     A display may have multiple video input and output adaptors.  An
 207     adaptor may support multiple simultaneously active ports, and in
 208     some cases the number of ports has no fixed limit.
 209
 210     An input port receives encoded video data and converts it to a
 211     stream of data used to update a drawable.  An output port samples
 212     data from a drawable and produces a stream of encoded video data.
 213
 214     The ADAPTORINFO structure is used to describe a video adaptor.
 215
 216     ADAPTORINFO:
 217         [base-id: PORT
 218          num-ports: CARD16
 219          type: SETofADAPTORTYPE
 220          formats: LISTofFORMAT
 221          name: STRING]
 222
 223     ADAPTORTYPE: {Input, Output}
 224
 225     FORMAT:
 226         [depth: CARD8
 227          visual: VISUALID]
 228
 229     The base-id field specifies the XID of the first port of the
 230     adaptor.  The `num-ports' field specifies how many ports the
 231     adaptor supports.  The ports of the adaptor have XIDs in the range
 232     [base-id..base-id + num-ports - 1]
 233
 234     The type attribute determines if the adaptor can process video
 235     input, output, or input and output.  The if the adaptor can
 236     process input then Input is asserted, if the adaptor can process
 237     output then Output is asserted.
 238
 239     The drawable depths and visual types supported by the adaptor are
 240     listed in `formats'.  Note: that when video is being processed for
 241     pixmaps the visual format is taken to be the visual of the first
 242     pair that matches the depth of the pixmap.
 243
 244     The name field contains an a vendor specific string that
 245     identifies the adaptor.
 246
 247     It should be noted that the existence of separate adaptors doesn't
 248     necessarily imply that simultaneous operation is supported.
 249
 250 \f
 251
 252   Errors
 253   ------
 254
 255     Port
 256
 257     A Port error is returned if any request names a PORT that does not
 258     exist.
 259
 260
 261     Encoding
 262
 263     An Encoding error is returned if any request names an ENCODINGID
 264     that does not exist.
 265
 266
 267 \f
 268
 269   Query Requests
 270   -------------------
 271
 272     QueryExtension
 273     ==>
 274       version: CARD16
 275       revision: CARD16
 276
 277     The QueryExtension request returns the extension version and
 278     revision numbers.
 279
 280
 281     QueryAdaptors
 282       win: WINDOW
 283     ==>
 284       adaptors: LISTofADAPTORINFO
 285
 286     The QueryAdaptors request returns the video adaptor information for
 287     the screen of the specified window.
 288
 289     Errors: {Window}
 290
 291
 292     QueryEncodings
 293       port: PORT
 294     ==>
 295       encodings: LISTofENCODINGINFO
 296
 297     The QueryEncodings request returns the list of encodings supported
 298     by the port adaptor.  Use the SetPortAttribute request to set
 299     which encoding a port is to process.  The ENCODINGINFO record
 300     describes an encoding:
 301
 302     ENCODINGINFO:
 303         [encoding: ENCODINGID
 304          name: STRING
 305          width, height: CARD16
 306          rate: FRACTION]
 307
 308     The `encoding' field identifies an encoding supported by a port.
 309     Its value is unique for a screen.  Width and height specify the
 310     size of the video image and rate specifies the rate at which
 311     fields of image information are encoded.
 312
 313     An encoding is identified by a string that names the encoding.
 314     Encoding naming conventions need to be established (i.e.,
 315     something along the lines of font naming, but simpler)
 316
 317     FRACTION
 318           [numerator, denominator: INT32]
 319
 320     The FRACTION structure is used to specify a fractional number.
 321
 322     Errors: {Port}
 323
 324 \f
 325
 326   Put Video Requests
 327   ------------------
 328
 329     PutVideo
 330       port: PORT
 331       drawable: DRAWABLE
 332       gc: GCONTEXT
 333       vid-x, vid-y: INT16
 334       vid-w, vid-h: CARD16
 335       drw-x, drw-y: INT16
 336       drw-w, drw-h: CARD16
 337
 338     The PutVideo request writes video into a drawable.  The position
 339     and size of the source rectangle is specified by vid-x, vid-y,
 340     vid-w, and vid-h.  The position and size of the destination
 341     rectangle is specified by drw-x, drw-y, drw-w, drw-h.
 342
 343     Video data is clipped to the bounds of the video encoding, scaled
 344     to the requested drawable region size (or the closest size
 345     supported), and clipped to the bounds of the drawable.
 346
 347     If video is successfully initiated, a VideoNotify event with
 348     detail Started is generated for the drawable.  If the port is
 349     already in use, its video is preempted, and if the new drawable is
 350     different than the old, a VideoNotify event with detail Preempted
 351     is generated for the old drawable.  If the port is grabbed by
 352     another client, this request is ignored, and a VideoNotify event
 353     with detail Busy is generated for the drawable.  If the port is
 354     not receiving a valid video signal or if the video signal is
 355     interrupted while video is active a VideoNotify event with detail
 356     HardError is generated for the drawable.
 357
 358     GC components: subwindow-mode, clip-x-origin, clip-y-origin, clip-mask.
 359
 360     Errors: {Match, Value, GContext, Port, Alloc}
 361
 362
 363     PutStill
 364       port: PORT
 365       drawable: DRAWABLE
 366       gc: GCONTEXT
 367       vid-x, vid-y: INT16
 368       vid-w, vid-h: CARD16
 369       drw-x, drw-y: INT16
 370       drw-w, drw-h: CARD16
 371
 372     The PutStill request writes a single frame of video into a
 373     drawable.  The position and size of the source rectangle is
 374     specified by vid-x, vid-y, vid-w, and vid-h.  The position and
 375     size of the destination rectangle is specified by drw-x, drw-y,
 376     drw-w, drw-h.
 377
 378     Video data is clipped to the bounds of the video encoding, scaled
 379     to the requested drawable region size (or the closest size
 380     supported) and clipped to the bounds of the drawable.
 381
 382     If the port is grabbed by another client, this request is ignored,
 383     and a VideoNotify event with detail Busy is generated for the
 384     drawable.  If the port is not receiving a valid video signal a
 385     VideoNotify event with detail HardError is generated for the
 386     drawable.
 387
 388     GC components: subwindow-mode, clip-x-origin, clip-y-origin, clip-mask.
 389
 390     Errors: {Match, Value, GContext, Port, Alloc}
 391
 392   \f
 393
 394   Get Video Requests
 395   ------------------
 396
 397     GetVideo
 398       port: PORT
 399       drawable: DRAWABLE
 400       gc: GCONTEXT
 401       vid-x, vid-y: INT16
 402       vid-w, vid-h: CARD16
 403       drw-x, drw-y: INT16
 404       drw-w, drw-h: CARD16
 405
 406     The GetVideo request outputs video from a drawable.  The position
 407     and size of the destination rectangle is specified by vid-x,
 408     vid-y, vid-w, and vid-h.  The position and size of the source
 409     rectangle is specified by drw-x, drw-y, drw-w, and drw-h.
 410
 411     Drawable data is clipped to the bounds of the drawable, scaled to
 412     the requested video region size (or the closest size supported)
 413     and clipped to the bounds of the video encoding.  The contents of
 414     any region not updated with drawable data is undefined.
 415
 416     If video is successfully initiated, a VideoNotify event with
 417     detail Started is generated for the drawable.  If the port is
 418     already in use, its video is preempted, and if the new drawable is
 419     different than the old, a VideoNotify event with detail Preempted
 420     is generated for the old drawable.  If the port is grabbed by
 421     another client, this request is ignored, and a VideoNotify event
 422     with detail Busy is generated for the drawable.
 423
 424     GC components: subwindow-mode, clip-x-origin, clip-y-origin,
 425     clip-mask.
 426
 427     Errors: {Match, Value, GContext, Port, Alloc}
 428
 429
 430     GetStill
 431       port: PORT
 432       drawable: DRAWABLE
 433       gc: GCONTEXT
 434       vid-x, vid-y: INT16
 435       vid-w, vid-h: CARD16
 436       drw-x, drw-y: INT16
 437       drw-w, drw-h: CARD16
 438
 439     The GetStill request outputs video from a drawable.  The position
 440     and size of the destination rectangle is specified by vid-x,
 441     vid-y, vid-w, and vid-h.  The position and size of the source
 442     rectangle is specified by drw-x, drw-y, drw-w, and drw-h.
 443
 444     Drawable data is clipped to the bounds of the drawable, scaled to
 445     the requested video region size (or the closest size supported)
 446     and clipped to the bounds of the video encoding.  The contents of
 447     any region not updated with drawable data is undefined.
 448
 449     If the still is successfully captured a VideoNotify event with
 450     detail Still is generated for the drawable.  If the port is
 451     grabbed by another client, this request is ignored, and a
 452     VideoNotify event with detail Busy is generated for the drawable.
 453
 454     GC components: subwindow-mode, clip-x-origin, clip-y-origin,
 455     clip-mask.
 456
 457     Errors: {Match, Value, GContext, Port, Alloc}
 458
 459
 460   \f
 461
 462   Grab Requests
 463   -------------
 464
 465     GrabPort
 466       port: PORT
 467       timestamp: {TIMESTAMP, CurrentTime}
 468     ==>
 469       status: {Success, AlreadyGrabbed, InvalidTime}
 470
 471     The GrabPort request grabs a port.  While a port is grabbed, only
 472     video requests from the grabbing client are permitted.
 473
 474     If timestamp specifies a time older than the current port time, a
 475     status of InvalidTime is returned.  If the port is already grabbed
 476     by another client, a status of AlreadyGrabbed is returned.
 477     Otherwise a status of Success is returned. The port time is
 478     updated when the following requests are processed: GrabPort,
 479     UngrabPort, PutVideo, PutStill, GetVideo, GetStill
 480
 481     If the port is actively processing video for another client, the
 482     video is preempted, and an VideoNotify event with detail Preempted
 483     is generated for its drawable.
 484
 485     Errors: {Port}
 486
 487
 488     UngrabPort
 489       port: PORT
 490       timestamp: {TIMESTAMP, CurrentTime}
 491
 492     The UngrabPort request ungrabs a port.  If timestamp specifies a
 493     time before the last connection request time of this port, the
 494     request is ignored.
 495
 496     Errors: {Port}
 497
 498 \f
 499
 500   Other Requests
 501   --------------
 502
 503     StopVideo
 504       port: PORT
 505       drawable: DRAWABLE
 506
 507     The StopVideo request stops active video for the specified port
 508     and drawable.  If the port isn't processing video, or if it is
 509     processing video in a different drawable, the request is ignored.
 510     When video is stopped a VideoNotify event with detail Stopped is
 511     generated for the associated drawable.
 512
 513     Errors: {Drawable, Port}
 514
 515
 516     SelectVideoNotify
 517       drawable: DRAWABLE
 518       onoff: BOOL
 519
 520     The SelectVideoNotify request enables or disables VideoNotify
 521     event delivery to the requesting client.  VideoNotify events are
 522     generated when video starts and stops.
 523
 524     Errors: {Drawable}
 525
 526
 527     SelectPortNotify
 528       port: PORT
 529       onoff: BOOL
 530
 531     The SelectPortNotify request enables or disables PortNotify event
 532     delivery to the requesting client.  PortNotify events are
 533     generated when port attributes are changed using SetPortAttribute.
 534
 535     Errors: {Port}
 536
 537
 538     QueryBestSize
 539       port: PORT
 540       motion: BOOL
 541       vid-w, vid-h: CARD16
 542       drw-w, drw-h: CARD16
 543     ==>
 544       actual-width, actual-height: CARD16
 545
 546     The QueryBestSize request returns, for the given source size and
 547     desired destination size, the closest destination size that the
 548     port adaptor supports.  The returned size will be equal
 549     or smaller than the requested size if one is supported.  If motion
 550     is True then the requested size is intended for use with full
 551     motion video.  If motion is False, the requested size is intended
 552     for use with stills only.
 553
 554     The retuned size is also chosen to maintain the requested aspect ratio
 555     if possible.
 556
 557     Errors: {Port}
 558
 559 \f
 560
 561     SetPortAttribute
 562       port: PORT
 563       attribute: ATOM
 564       value: INT32
 565
 566     The SetPortAttribute request sets the value of a port attribute.
 567     The port attribute is identified by the attribute atom.  The
 568     following strings are guaranteed to generate valid atoms using the
 569     InternAtom request.
 570
 571     String                Type
 572     -----------------------------------------------------------------
 573
 574     "XV_ENCODING"         ENCODINGID
 575     "XV_HUE"              [-1000..1000]
 576     "XV_SATURATION"       [-1000..1000]
 577     "XV_BRIGHTNESS"       [-1000..1000]
 578     "XV_CONTRAST"         [-1000..1000]
 579
 580
 581     If the given attribute doesn't match an attribute supported by the
 582     port adaptor a Match error is generated.  The supplied encoding
 583     must be one of the encodings listed for the adaptor, otherwise an
 584     Encoding error is generated.
 585
 586     If the adaptor doesn't support the exact hue, saturation,
 587     brightness, and contrast levels supplied, the closest levels
 588     supported are assumed.  The GetPortAttribute request can be used
 589     to query the resulting levels.
 590
 591     When a SetPortAttribute request is processed a PortNotify event is
 592     generated for all clients that have requested port change
 593     notification using SelectPortNotify.
 594
 595     Errors: {Port, Match, Value}
 596
 597
 598     GetPortAttribute
 599       port: PORT
 600       attribute: ATOM
 601     ==>
 602       value: INT32
 603
 604
 605     The GetPortAttribute request returns the current value of the
 606     attribute identified by the given atom.  If the given atom
 607     doesn't match an attribute supported by the adaptor a Match
 608     error is generated.
 609
 610     Errors: {Port, Match}
 611
 612 \f
 613
 614   Events
 615   ------
 616
 617     VideoNotify
 618       drawable: DRAWABLE
 619       port: PORT
 620       reason: REASON
 621       time: TIMESTAMP
 622
 623     REASON: {Started, Still, Stopped, Busy, Preempted, HardError}
 624
 625     A VideoNotify event is generated when video activity is started,
 626     stopped, or unable to proceed in a drawable.
 627
 628     A Started reason is generated when video starts in a drawable.
 629
 630     A Stopped reason is generated when video is stopped in a
 631     drawable upon request.
 632
 633     A Busy reason is generated when a put or get request cannot
 634     proceed because the port is grabbed by another client.
 635
 636     A Preempted reason is generated when video is stopped by a
 637     conflicting request.
 638
 639     A HardError reason is generated when the video port cannot
 640     initiate or continue processing a video request because of an
 641     underlying transmission or reception error.
 642
 643
 644     PortNotify
 645       port: PORT
 646       attribute: ATOM
 647       value: INT32
 648       time: TIMESTAMP
 649
 650     The PortNotify event is generated when a SetPortAttribute request
 651     is processed.  The event is delivered to all clients that have
 652     performed a SelectPortNotify request for the port.  The event
 653     contains the atom identifying the attribute that changed, and the
 654     new value of that attribute.