changelog shortlog tags branches changeset files revisions annotate raw help

Mercurial > hg > plan9front / sys/man/3/draw

changeset 3558: 0a3625675d6a
parent: 1cf3d5629aa0
child: b0b9d97f9ed8
author: ftrvxmtrx
date: Sat, 26 Apr 2014 01:47:36 +0200
permissions: -rw-r--r--
description: man pages: the the wich
1 .TH DRAW 3
2 .SH NAME
3 draw \- screen graphics
4 .SH SYNOPSIS
5 .nf
6 .B bind -a #i /dev
7 
8 .B /dev/draw/new
9 
10 .BI /dev/draw/ n /ctl
11 .BI /dev/draw/ n /data
12 .BI /dev/draw/ n /colormap
13 .BI /dev/draw/ n /refresh
14 
15 .ft L
16 #include <u.h>
17 #include <draw.h>
18 
19 .ta \w'ushort 'u
20 ushort BGSHORT(uchar *p)
21 ulong BGLONG(uchar *p)
22 void BPSHORT(uchar *p, ushort v)
23 void BPLONG(uchar *p, ulong v)
24 .ft P
25 .fi
26 .SH DESCRIPTION
27 The
28 .I draw
29 device serves a three-level file system
30 providing an interface to the graphics facilities of the system.
31 Each client of the device connects by opening
32 .B /dev/draw/new
33 and reading 12 strings, each 11 characters wide followed by a blank:
34 the connection number
35 .RI ( n ),
36 the image id
37 .RI ( q.v. )
38 of the display image (always zero),
39 the
40 channel format
41 of the image,
42 the
43 replicate bit,
44 the
45 .BR min.x ,
46 .BR min.y ,
47 .BR max.x ,
48 and
49 .B max.y
50 of the display image,
51 and the
52 .BR min.x ,
53 .BR min.y ,
54 .BR max.x ,
55 and
56 .B max.y
57 of the clipping rectangle.
58 The channel format string is described in
59 .IR image (6),
60 and the other fields are decimal numbers.
61 .PP
62 The client can then open the directory
63 .BI /dev/draw/ n /
64 to access the
65 .BR ctl ,
66 .BR data ,
67 .BR colormap ,
68 and
69 .B refresh
70 files associated with the connection.
71 .PP
72 Via the
73 .B ctl
74 and
75 .B data
76 files, the
77 .I draw
78 device provides access to
79 images and font caches
80 in its private storage,
81 as described in
82 .IR graphics (2).
83 Each image is identified by a 4-byte integer, its
84 .IR id .
85 .PP
86 Reading the
87 .B ctl
88 file yields 12 strings formatted as in
89 .BR /dev/draw/new ,
90 but for the current image rather
91 than the display image.
92 The current image may be set by writing a
93 binary image id to the
94 .B ctl
95 file.
96 .PP
97 A process can write messages to
98 .B data
99 to allocate and free images, fonts, and subfonts;
100 read or write portions of the images;
101 and draw line segments and character
102 strings in the images.
103 All graphics requests are clipped to their images.
104 Some messages return a response to be recovered by
105 reading the
106 .B data
107 file.
108 .PP
109 The format of messages written to
110 .B data
111 is a single letter
112 followed by binary parameters;
113 multibyte integers are transmitted with the low order byte first.
114 The
115 .B BPSHORT
116 and
117 .B BPLONG
118 macros place correctly formatted two- and four-byte integers into a character
119 buffer.
120 .B BGSHORT
121 and
122 .B BGLONG
123 retrieve values from a character buffer.
124 Points are two four-byte numbers:
125 .IR x ,
126 .IR y .
127 Rectangles are four four-byte numbers: min
128 .IR x ,
129 min
130 .IR y ,
131 max
132 .IR x ,
133 and max
134 .IR y .
135 Images, screens, and fonts have 32-bit identifiers.
136 In the discussion of the protocol below,
137 the distinction between identifier and actual image, screen, or font
138 is not made, so that
139 ``the object
140 .IR id ''
141 should be interpreted as
142 ``the object with identifier
143 .IR id ''.
144 The definitions of constants used in the description below can be found in
145 .BR draw.h .
146 .PP
147 The following requests are accepted by the
148 .B data
149 file.
150 The numbers in brackets give the length in bytes of the parameters.
151 .HP .5i
152 .B A
153 .IR id [4]
154 .IR imageid [4]
155 .IR fillid [4]
156 .IR public [1]
157 .br
158 Allocate a new
159 .B Screen
160 (see
161 .IR window (2))
162 with
163 screen identifier
164 .I id
165 using
166 backing store image
167 .IR imageid ,
168 filling it initially
169 with data from image
170 .IR fillid .
171 If the
172 .I public
173 byte is non-zero, the screen can
174 be accessed from other processes
175 using the
176 .B publicscreen
177 interface.
178 .HP
179 .B b
180 .IR id [4]
181 .IR screenid [4]
182 .IR refresh [1]
183 .IR chan [4]
184 .IR repl [1]
185 .IR r [4*4]
186 .IR clipr [4*4]
187 .IR color [4]
188 .br
189 Allocate an image with a given
190 .I id
191 on the
192 screen named by
193 .IR screenid .
194 The image will have rectangle
195 .I r
196 and clipping rectangle
197 .IR clipr .
198 If
199 .I repl
200 is non-zero, the image's replicate
201 bit will be set (see
202 .IR draw (2)).
203 .IP
204 .I Refresh
205 specifies the method to be used to draw the window
206 when it is uncovered.
207 .B Refbackup
208 causes the server to maintain a backing store,
209 .B Refnone
210 does not refresh the image,
211 and
212 .B Refmesg
213 causes a message to be sent via
214 the
215 .B refresh
216 file
217 .RI ( q.v. ).
218 .IP
219 The image format is described by
220 .IR chan ,
221 a binary version of the channel format string.
222 Specifically, the image format is the catenation of up to four
223 8-bit numbers, each describing a particular image channel.
224 Each of these 8-bit numbers contains a channel type in its
225 high nibble and a bit count in its low nibble.
226 The channel type is one of
227 .BR CRed ,
228 .BR CGreen ,
229 .BR CBlue ,
230 .BR CGrey ,
231 .BR CAlpha ,
232 .BR CMap ,
233 and
234 .BR CIgnore .
235 See
236 .IR image (6).
237 .IP
238 .I Color
239 is the catenation of four 8-bit numbers
240 specifying the red, green, blue, and alpha
241 channels of the color that the new image should
242 be initially filled with.
243 The red channel is in the highest 8 bits, and
244 the alpha in the lowest.
245 Note that color is always in this format, independent of
246 the image format.
247 .HP
248 .B c
249 .IR dstid [4]
250 .IR repl [1]
251 .IR clipr [4*4]
252 .br
253 Change the replicate bit and clipping rectangle of the
254 image
255 .IR dstid .
256 This overrides whatever settings were specified in
257 the allocate message.
258 .HP
259 .B d
260 .IR dstid [4]
261 .IR srcid [4]
262 .IR maskid [4]
263 .IR dstr [4*4]
264 .IR srcp [2*4]
265 .IR maskp [2*4]
266 .br
267 Use the
268 .B draw
269 operator to combine the rectangle
270 .I dstr
271 of
272 image
273 .I dstid
274 with a
275 rectangle of image
276 .IR srcid ,
277 using a rectangle of image
278 .IR maskid
279 as an alpha mask to further control blending.
280 The three rectangles are congruent and aligned such that
281 the upper left corner
282 .I dstr
283 in image
284 .I dstid
285 corresponds to
286 the point
287 .I srcp
288 in image
289 .I srcid
290 and
291 the point
292 .I maskp
293 in image
294 .IR maskid .
295 See
296 .IR draw (2).
297 .HP
298 .B D
299 .IR debugon [1]
300 .br
301 If
302 .I debugon
303 is non-zero, enable debugging output.
304 If zero, disable it.
305 The meaning of ``debugging output'' is implementation dependent.
306 .HP
307 .B e
308 .IR dstid [4]
309 .IR srcid [4]
310 .IR c [2*4]
311 .IR a [4]
312 .IR b [4]
313 .IR thick [4]
314 .IR sp [2*4]
315 .IR alpha [4]
316 .IR phi [4]
317 .br
318 Draw an ellipse in image
319 .I dst
320 centered on the point
321 .I c
322 with horizontal and vertical semiaxes
323 .I a
324 and
325 .IR b .
326 The ellipse is drawn using the image
327 .IR src ,
328 with
329 the point
330 .I sp
331 in
332 .I src
333 aligned with
334 .I c
335 in
336 .IR dst .
337 The ellipse is drawn with thickness
338 .RI 1+2× thick .
339 .IP
340 If the high bit of
341 .I alpha
342 is set,
343 only the arc of the ellipse from degree angles
344 .I alpha
345 to
346 .I phi
347 is drawn.
348 For the purposes of drawing the arc,
349 .I alpha
350 is treated as a signed 31-bit number
351 by ignoring its high bit.
352 .HP
353 .B E
354 .IR dstid [4]
355 .IR srcid [4]
356 .IR center [2*4]
357 .IR a [4]
358 .IR b [4]
359 .IR thick [4]
360 .IR sp [2*4]
361 .IR alpha [4]
362 .IR phi [4]
363 .br
364 Draws an ellipse or arc as the
365 .B e
366 message, but rather than outlining it, fills
367 the corresponding sector using the image
368 .IR srcid .
369 The
370 .I thick
371 field is ignored, but must be non-negative.
372 .HP
373 .B f
374 .IR id [4]
375 .br
376 Free the resources associated with the image
377 .IR id .
378 .HP
379 .B F
380 .IR id [4]
381 .br
382 Free the screen with the specified
383 .IR id .
384 Windows on the screen must be freed separately.
385 .HP
386 .B i
387 .IR id [4]
388 .IR n [4]
389 .IR ascent [1]
390 .br
391 Treat the image
392 .I id
393 as a font cache of
394 .I n
395 character cells, each with
396 ascent
397 .IR ascent .
398 .HP
399 .B l
400 .IR cacheid [4]
401 .IR srcid [4]
402 .IR index [2]
403 .IR r [4*4]
404 .IR sp [2*4]
405 .IR left [1]
406 .IR width [1]
407 .br
408 Load a character into the font cache associated with image
409 .I cacheid
410 at cache position
411 .IR index .
412 The character data is drawn in rectangle
413 .I r
414 of the font cache image
415 and is fetched from
416 the congruent rectangle in image
417 .I srcid
418 with upper left corner
419 .IR sp .
420 .I Width
421 specifies the width of the character\(emthe spacing from this character to the next\(emwhile
422 .I left
423 specifies
424 the horizontal distance from the left side
425 of the character to the left side of the cache image.
426 The dimensions of the image of the character are defined by
427 .IR r .
428 .HP
429 .B L
430 .IR dstid [4]
431 .IR p0 [2*4]
432 .IR p1 [2*4]
433 .IR end0 [4]
434 .IR end1 [4]
435 .IR thick [4]
436 .IR srcid [4]
437 .IR sp [2*4]
438 .br
439 Draw a line of thickness
440 .RI 1+2× thick
441 in image
442 .I dstid
443 from point
444 .I p0
445 to
446 .IR p1 .
447 The line is drawn using the image
448 .IR srcid ,
449 translated so that point
450 .I sp
451 in
452 .I srcid
453 aligns with
454 .I p0
455 in
456 .IR dstid .
457 The
458 .I end0
459 and
460 .I end1
461 fields specify whether the corresponding
462 line end should be a square, a disc,
463 or an arrow head.
464 See
465 .I line
466 in
467 .IR draw (2)
468 for more details.
469 .HP
470 .B N
471 .IR id [4]
472 .IR in [1]
473 .IR j [1]
474 .IR name [ j ]
475 .br
476 If
477 .I in
478 is non-zero, associate the image
479 .I id
480 with the string
481 .IR name .
482 If
483 .I in
484 is zero and
485 .I name
486 already corresponds to the
487 image
488 .IR id ,
489 the association is deleted.
490 .HP
491 .B n
492 .IR id [4]
493 .IR j [1]
494 .IR name [ j ]
495 .br
496 Introduce the identifier
497 .I id
498 to correspond to the image named
499 by the string
500 .IR name .
501 .HP
502 .B o
503 .IR id [4]
504 .IR r.min [2*4]
505 .IR scr [2*4]
506 .br
507 Position the window
508 .I id
509 so that its upper left corner is at the
510 point
511 .I scr
512 on its screen.
513 Simultaneously change its internal (logical) coordinate system
514 so that the point
515 .I log
516 corresponds to the upper left corner of the window.
517 .HP
518 .B O
519 .IR op [1]
520 .br
521 Set the compositing operator to
522 .I op
523 for the next draw operation.
524 (The default is
525 .BR SoverD ).
526 .HP
527 .B p
528 .IR dstid [4]
529 .IR n [2]
530 .IR end0 [4]
531 .IR end1 [4]
532 .IR thick [4]
533 .IR srcid [4]
534 .IR sp [2*4]
535 .IR dp [2*2*(n+1)]
536 .br
537 Draw a polygon of thickness
538 .RI 1+2× thick .
539 It is conceptually equivalent to a series of
540 .I n
541 line-drawing messages (see
542 .B L
543 above)
544 joining adjacent points in the list of points
545 .IR dp .
546 The source image
547 .I srcid
548 is translated so that the point
549 .I sp
550 in
551 .I srcid
552 aligns with the first point
553 in the list
554 .IR dp .
555 The polygon need not be closed:
556 .I end0
557 and
558 .I end1
559 specify the line endings for the first and
560 last point on the polygon.
561 All interior lines have rounded ends
562 to make smooth joins.
563 .HP
564 .B P
565 .IR dstid [4]
566 .IR n [2]
567 .IR wind [4]
568 .IR ignore [2*4]
569 .IR srcid [4]
570 .IR sp [2*4]
571 .IR dp [2*2*(n+1)]
572 .br
573 Draw a polygon as the
574 .B p
575 message, but
576 fill it rather than outlining it.
577 The winding rule parameter
578 .I wind
579 resolves ambiguities about what to fill if the polygon is self-intersecting.
580 If
581 .I wind
582 is
583 .BR ~0 ,
584 a pixel is inside the polygon if the polygon's winding number about the point
585 is non-zero.
586 If
587 .I wind
588 is
589 .BR 1 ,
590 a pixel is inside if the winding number is odd.
591 Complementary values (0 or ~1) cause outside pixels to be filled.
592 The meaning of other values is undefined.
593 The polygon is closed with a line if necessary.
594 .HP
595 .B r
596 .IR id [4]
597 .IR r [4*4]
598 .br
599 Cause the next read of the
600 .B data
601 file to return the image pixel data corresponding to the
602 rectangle
603 .I r
604 in image
605 .IR id .
606 .HP
607 .B s
608 .IR dstid [4]
609 .IR srcid [4]
610 .IR fontid [4]
611 .IR p [2*4]
612 .IR clipr [4*4]
613 .IR sp [2*4]
614 .IR n [2]
615 .IR n*(index [2])
616 .br
617 Draw in the image
618 .I dstid
619 the text string specified by the
620 .I n
621 cache
622 .I indices
623 into font
624 .IR fontid ,
625 starting with the upper left corner at point
626 .I p
627 in image
628 .IR dstid .
629 The image drawn is taken from image
630 .IR srcid ,
631 translated to align
632 .I sp
633 in
634 .I srcid
635 with
636 .I dp
637 in
638 .IR dstid.
639 All drawing is confined to the clipping rectangle
640 .I clipr
641 in
642 .IR dstid .
643 .HP
644 .B x
645 .IR dstid [4]
646 .IR srcid [4]
647 .IR fontid [4]
648 .IR dp [2*4]
649 .IR clipr [4*4]
650 .IR sp [2*4]
651 .IR n [2]
652 .IR bgid [4]
653 .IR bp [2*4]
654 .IR n*(index [2])
655 .br
656 Like the string drawing
657 .B s
658 command, but fill the background of each character
659 with pixels from image
660 .IR bgid .
661 The image
662 .I bgid
663 is translated so that the point
664 .I bp
665 aligns with the
666 point
667 .I dp
668 in
669 .IR dstid .
670 .HP
671 .B S
672 .IR id [4]
673 .IR chan [4]
674 Attach to the public screen with the specified
675 .IR id .
676 It is an error if the screen does not exist, is not public, or does not
677 have the channel descriptor
678 .I chan
679 for its associated image.
680 .HP
681 .B t
682 .IR top [1]
683 .IR n [2]
684 .IR n*id [4]
685 .br
686 Send
687 .I n
688 windows to the top (if
689 .I t
690 is non-zero) or bottom (if
691 .I t
692 is zero) of the window stack.
693 The window is specified by the list of
694 .I n
695 image
696 .IR id s
697 are moved as a group, maintaining their own order within the stack.
698 .HP
699 .B v
700 .br
701 Flush changes from a soft screen, if any, to the display buffer.
702 .HP
703 .B y
704 .IR id [4]
705 .IR r [4*4]
706 .IR buf [x*1]
707 .br
708 .ti -0.5i
709 .B Y
710 .IR id [4]
711 .IR r [4*4]
712 .IR buf [x*1]
713 .br
714 Replace the rectangle
715 .I r
716 of pixels in image
717 .I id
718 with the pixel data in
719 .IR buf .
720 The pixel data must be in the format dictated by
721 .IR id 's
722 image channel descriptor (see
723 .IR image (6)).
724 The
725 .B y
726 message uses uncompressed data,
727 while the
728 .B Y
729 message uses compressed data.
730 In either case,
731 it is an error to include more data than necessary.
732 .PP
733 Reading the
734 .B colormap
735 returns the system color map used on 8-bit displays.
736 Each color map entry consists of a single line containing
737 four space-separated decimal strings.
738 The first is an index into the map, and the remaining three are
739 the red, green, and blue values associated with that index.
740 The color map can be changed by writing entries in the
741 above format to
742 the
743 .B colormap
744 file.
745 Note that changing the system color map
746 does not change the color map used for
747 calculations involving
748 .B m8
749 images, which is immutable.
750 .PP
751 The
752 .B refresh
753 file is read-only.
754 As windows owned by the client are uncovered,
755 if they cannot be refreshed by the server (such as when they have
756 refresh functions associated with them), a message is made available
757 on the
758 .B refresh
759 file reporting what needs to be repainted by the client.
760 The message has five decimal integers formatted as in the
761 .B ctl
762 message: the image id of the window and the coordinates of the rectangle
763 that should be refreshed.
764 .SH SOURCE
765 .B /sys/src/9/port/devdraw.c
766 .br
767 .B /sys/src/libmemdraw
768 .SH DIAGNOSTICS
769 Most messages to
770 .B draw
771 can return errors;
772 these can be detected by a system call error
773 on the
774 .IR write (see
775 .IR read (2))
776 of the data containing the erroneous message.
777 The most common error is a failure to allocate
778 because of insufficient free resources. Most other errors occur
779 only when the protocol is mishandled by the application.
780 .IR Errstr (2)
781 will report details.
782 .SH BUGS
783 The
784 .B Refmesg
785 refresh method is not fully implemented.
786 .br
787 The
788 .B colormap
789 files only reference the system color map, and as
790 such should be called
791 .B /dev/colormap
792 rather than
793 .BI /dev/draw/ n /colormap\f1.