changelog shortlog tags branches changeset files file revisions raw help

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

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