summaryrefslogtreecommitdiff
path: root/xv-protocol-v2.txt
blob: 31e2013bb514776a351787bb83cc936330d5f0bc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
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.