![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to bit CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Plan 9 NeXT] / lucent / sys / man / 3|
Return to bit CVS log | Up to [Plan 9 NeXT] / lucent / sys / man / 3 |
1.1 root 1: .TH BIT 3
2: .SH NAME
3: bit \- screen graphics, mouse
4: .SH SYNOPSIS
5: .nf
6: .B bind -a #b /dev
7:
8: .B /dev/bitblt
9: .B /dev/mouse
10: .B /dev/mousectl
11: .B /dev/screen
12:
13: .ft L
14: #include <u.h>
15: #include <libg.h>
16:
17: .ta \w'ushort 'u
18: ushort BGSHORT(uchar *p)
19: ulong BGLONG(uchar *p)
20: void BPSHORT(uchar *p, ushort v)
21: void BPLONG(uchar *p, ulong v)
22: .ft P
23: .fi
24: .SH DESCRIPTION
25: The
26: .I bit
27: device provides the files
28: .BR bitblt ,
29: .BR mouse ,
30: .BR mousectl ,
31: and
32: .B screen
33: on machines with a bitmapped screen
34: and a mouse.
35: The device is exclusive use.
36: .PP
37: The
38: .I bit
39: device provides, through the
40: .B bitblt
41: file, access to
42: .IR bitmaps ,
43: .IR fonts ,
44: and
45: .I subfonts
46: in its private storage,
47: as described in
48: .IR graphics (2).
49: Each object is identified by a short, its
50: .IR id .
51: The bitmap with id zero is special: it represents the visible display.
52: The subfont with id zero is also special: it is initialized to
53: a default subfont that is always available.
54: There is no default font.
55: There is also a cursor associated with the screen;
56: it is always displayed at the current mouse position.
57: A process can write messages to
58: .B bitblt
59: to allocate and free bitmaps, fonts, and subfonts,
60: read or write portions of the bitmaps,
61: and draw line segments,
62: textures, and character strings in the bitmaps.
63: All graphics requests are clipped to their bitmaps.
64: Some messages return a response
65: to be recovered by reading
66: .BR bitblt .
67: .PP
68: The format of
69: messages written to
70: .B bitblt
71: is a single lower case letter
72: followed by binary parameters;
73: multibyte integers are transmitted with the low order byte first.
74: The
75: .B BPSHORT
76: and
77: .B BPLONG
78: macros place correctly formatted two- and four-byte integers into a character
79: buffer.
80: Some messages return a response formatted the same way;
81: it usually starts with the upper case version of the request character.
82: .B BGSHORT
83: and
84: .B BGLONG
85: retrieve values from a character buffer.
86: Points are two four-byte numbers:
87: .IR x ,
88: .IR y .
89: Rectangles are four four-byte numbers: min
90: .IR x ,
91: min
92: .IR y ,
93: max
94: .IR x ,
95: and max
96: .IR y .
97: .PP
98: The following requests are accepted by the
99: .B bitblt
100: file.
101: The numbers in brackets give the length in bytes of the parameters.
102: .HP .5i
103: .B a
104: .IR ldepth [1]
105: .IR rect [16]
106: .br
107: Allocate a bitmap.
108: .I Ldepth
109: is the log base 2 of the number of bits per pixel.
110: .I Rect
111: is a Rectangle giving the extent of the bitmap.
112: The bitmap is cleared to all zeros.
113: The id of the allocated bitmap is returned on a subsequent
114: .I read
115: from
116: .BR bitblt ,
117: returning the three bytes:
118: .L A
119: followed by the id.
120: .HP
121: .B b
122: .IR dstid [2]
123: .IR dstpt [8]
124: .IR srcid [2]
125: .IR srcrect [16]
126: .IR code [2]
127: .br
128: Bit-block transfer
129: .RB ( bitblt )
130: from a rectangle in the bitmap identified by
131: .I srcid
132: to a congruent
133: rectangle at Point
134: .B dstpt
135: in the bitmap identified by
136: .IR dstid .
137: The rectangle is clipped against both
138: source and destination bitmaps. See
139: .IR bitblt (2).
140: .HP
141: .B c
142: [
143: .IR pt [8]
144: .IR clr [32]
145: .IR set [32]
146: ]
147: .br
148: Switch mouse cursor.
149: See the description of
150: .B Cursors
151: in
152: .IR graphics (2)
153: for the meaning of the
154: .I pt
155: (the offset),
156: .IR set ,
157: and
158: .I clr
159: arguments.
160: If only
161: .L c
162: is provided \(em that is, if the message is one byte long \(em
163: the cursor changes to the default, typically an arrow.
164: .HP
165: .B e
166: .IR id [2]
167: .IR pt [8]
168: .IR value [1]
169: .IR code [2]
170: .IR n [2]
171: .IR pts [ n *2]
172: .br
173: Join the
174: .IR n +1
175: points
176: .I pt
177: and
178: .I pts
179: with
180: .I n
181: segments, exactly as for the
182: .I l
183: operator. The
184: .I pts
185: are specified by pairs of signed bytes
186: holding offsets from the previous point in the list.
187: .HP
188: .B f
189: .IR id [2]
190: .br
191: Free the resources associated with the allocated bitmap
192: identified by
193: .IR id .
194: .HP
195: .B g
196: .IR id [2]
197: .br
198: Free the resources associated with the allocated subfont identified by
199: .IR id ,
200: including its bitmap.
201: If the subfont is cached,
202: the associated data may be recoverable even after it has
203: been freed; see below.
204: .HP
205: .B h
206: .IR id [2]
207: .br
208: Free the resources associated with the allocated font identified by
209: .IR id .
210: .HP
211: .B i
212: .br
213: Initialize the device.
214: The next operation on
215: .B bitblt
216: should be a
217: .IR read (2).
218: A read of length 34 returns information about the display:
219: .RS 1i
220: .B I
221: .IR ldepth [1]
222: .IR rect [16]
223: .IR cliprect [16].
224: .RE
225: .IP
226: If the read count is large enough, the above information is followed
227: by the header and character information of the default
228: .BR Subfont ,
229: in the format expected by
230: .I rdsubfontfile
231: (see
232: .IR subfalloc (2)
233: and
234: .IR font (6)).
235: `Large enough' is 36 +
236: .RI 6 n ,
237: where
238: .I n
239: is the number of characters in the subfont.
240: The ids of the screen bitmap and default subfont are both zero.
241: .HP
242: .B j
243: .IR q0 [4]
244: .IR q1 [4]
245: .br
246: Check to see whether a subfont with tags
247: .I q0
248: and
249: .I q1
250: is in the cache.
251: If it is not, the write of the
252: .B j
253: message will draw an error.
254: If it is, the next read of
255: .B bitblt
256: will return
257: .RS 1i
258: .B J
259: .IR id [2]
260: .RE
261: .IP
262: followed by the subfont information in the same format
263: as returned by an init message; the subfont will then be available
264: for use.
265: .HP
266: .B k
267: .IR n [2]
268: .IR height [1]
269: .IR ascent [1]
270: .IR bitmapid [2]
271: .IR q0 [4]
272: .IR q1 [4]
273: .IR info [6*( n +1)]
274: .br
275: Allocate subfont.
276: The parameters are as described in
277: .IR subfalloc (2),
278: with
279: .I info
280: in external subfont file format.
281: .I Bitmapid
282: identifies a previously allocated bitmap containing the character images.
283: .I Q0
284: and
285: .I q1
286: are used as labels for the subfont in the cache; if all ones,
287: the subfont will not be cached and hence shared with other applications.
288: The id of the allocated subfont is recovered by reading
289: from
290: .B bitblt
291: the three bytes:
292: .L K
293: followed by the id.
294: Henceforth, the bitmap with id
295: .I bitmapid
296: is unavailable to the application; in effect, it has been freed.
297: .HP
298: .B l
299: .IR id [2]
300: .IR pt1 [8]
301: .IR pt2 [8]
302: .IR value [1]
303: .IR code [2]
304: .br
305: Draw a line segment from Point
306: .I pt1
307: to Point
308: .IR pt2 ,
309: using
310: .I code
311: for the drawing function, and
312: .I value
313: as the source pixel. See
314: .I segment
315: in
316: .IR bitblt (2).
317: .I Id
318: identifies the destination bitmap.
319: .HP
320: .B m
321: .IR id [2]
322: .br
323: Read the colormap associated with the bitmap with the specified
324: .IR id .
325: The next read of
326: .B bitblt
327: will return
328: .if t 12×2\u\s-2\fIn\fP\s+2\d
329: .if n 12*2^\fIn\fP
330: bytes of colormap data where
331: .I n
332: is the number of bits per pixel in the bitmap.
333: .HP
334: .B n
335: .IR height [1]
336: .IR ascent [1]
337: .IR ldepth [2]
338: .IR ncache [2]
339: .br
340: Allocate a font with the given
341: .IR height ,
342: .IR ascent ,
343: and
344: .IR ldepth .
345: The id of the allocated font is recovered by reading
346: from
347: .B bitblt
348: the three bytes:
349: .L N
350: followed by the id.
351: The initial cache associated with the font will have
352: .I ncache
353: character entries of zero width.
354: .HP
355: .B p
356: .IR id [2]
357: .IR pt [8]
358: .IR value [1]
359: .IR code [2]
360: .br
361: Change the pixel at Point
362: .I pt
363: using
364: .I code
365: for the drawing function, and
366: .I value
367: as the source pixel. See
368: .I point
369: in
370: .IR bitblt (2).
371: .HP
372: .B q
373: .IR id [2]
374: .IR rect [16]
375: .br
376: Set the clipping rectangle for the bitmap with specified
377: .I id
378: to the given rectangle, which will itself be clipped to the
379: bitmap's image rectangle.
380: .HP
381: .B r
382: .IR id [2]
383: .IR miny [4]
384: .IR maxy [4]
385: .br
386: Read rows
387: .IR ymin ,
388: .IR ymin "+1, ..."
389: .IR ymax \-1
390: of the bitmap with the given bitmap id.
391: See the description of
392: .I rdbitmap
393: in
394: .IR balloc (2).
395: A subsequent read of
396: .B bitblt
397: will return the requested rows of pixels.
398: Note: in this case, the response does not begin with an
399: .LR R ,
400: to simplify the reading of large bitmaps.
401: Also, the reply may be too large to fit in a single 9P message (see
402: .IR read (5)),
403: so multiple reads may be necessary; each read will return
404: only complete rows.
405: .HP
406: .B s
407: .IR id [2]
408: .IR pt [8]
409: .IR fontid [2]
410: .IR code [2]
411: .IR n [2]
412: .IR indices [2* n ]
413: .br
414: Draw using code
415: .I code
416: in the bitmap identified by
417: .I id
418: the text string
419: specified by the
420: .I n
421: cache
422: .I indices
423: in font
424: .IR fontid ,
425: starting with the upper left corner at
426: .IR pt .
427: .HP
428: .B t
429: .IR dstid [2]
430: .IR rect [16]
431: .IR srcid [2]
432: .IR code [2]
433: .br
434: Texture the given rectangle in the bitmap
435: identified by
436: .I dstid
437: by overlaying a tiling
438: of the bitmap identified by
439: .I srcid
440: (aligning (0,0) in the two bitmaps), and using
441: .I code
442: as a drawing code for
443: .IR bitblt ;
444: see
445: .I texture
446: in
447: .IR bitblt (2).
448: .HP
449: .B v
450: .IR id [2]
451: .IR ncache [2]
452: .IR width [2]
453: .br
454: Reset, resize, and clear the cache for font
455: .IR id ;
456: the maximum width of the
457: .I ncache
458: characters the cache may hold is set to
459: .IR width .
460: Must be done before the first load of a cache slot.
461: If the cache cannot be resized, the write of this message
462: will fail but the cache will be unaffected.
463: .HP
464: .B w
465: .IR id [2]
466: .IR miny [4]
467: .IR maxy [4]
468: .IR data [ n ]
469: .br
470: Replace rows
471: .IR ymin ,
472: .IR ymin "+1, ..."
473: .IR ymax \-1
474: of the bitmap with the given bitmap
475: .I id
476: with the values in
477: .IR data .
478: See the description of
479: .I wrbitmap
480: in
481: .IR balloc (2).
482: .HP
483: .B x
484: .IR x [4]
485: .IR y [4]
486: .br
487: Move the cursor so its origin is at
488: .RI ( x , y ).
489: .HP
490: .B y
491: .IR id [2]
492: .IR cacheindex [2]
493: .IR subfontid [2]
494: .IR subfontindex [2]
495: .br
496: Load the description and image of character
497: .I subfontindex
498: in subfont
499: .I subfontid
500: into slot
501: .I cacheindex
502: of font
503: .IR id .
504: .HP
505: .B z
506: .IR id [2]
507: .IR map [ m ]
508: .br
509: Replace the colormap associated with bitmap
510: .I id
511: with
512: .IR map ,
513: which contains
514: .if t \fIm\fP=12\(mu2\u\s-2\fIn\fP\s+2\d
515: .if n \fIm\fP=12*2^\fIn\fP
516: bytes of colormap data (see
517: .IR rgbpix (2)
518: for the format).
519: .PP
520: A read of the
521: .B mouse
522: file returns the mouse status: its position and button state.
523: The read blocks until the state has changed since the last read.
524: The read returns 14 bytes:
525: .RS
526: .B m
527: .IR buttons [1]
528: .IR x [4]
529: .IR y [4]
530: .IR msec [4]
531: .RE
532: where
533: .I x
534: and
535: .I y
536: are the mouse coordinates in the screen bitmap,
537: .I msec
538: is a time stamp, in units of milliseconds, and
539: .I buttons
540: has set the 1, 2, and 4 bits when the mouse's left, middle, and right
541: buttons, respectively, are down.
542: .PP
543: Writing to the
544: .B mousectl
545: file configures and controls the mouse.
546: The messages are:
547: .IP
548: .B serial \fIn\fR
549: sets serial port
550: .I n
551: to be the mouse port.
552: .IP
553: .B ps2
554: sets the PS2 port to be the mouse port.
555: .IP
556: .B accelerated
557: turns on mouse acceleration.
558: .IP
559: .B linear
560: turns off mouse acceleration
561: .IP
562: .B res \fIn\fR
563: sets mouse resolution to a setting between 0 and
564: 3 inclusive.
565: .IP
566: .B swap
567: swaps the left and right buttons on the mouse.
568: .br
569: Which messages are implemented is machine-dependent.
570: .PP
571: The
572: .B screen
573: file contains the screen bitmap in the format described in
574: .IR bitmap (6).
575: .SH SOURCE
576: .B /sys/src/9/port/devbit.c
577: .SH DIAGNOSTICS
578: Most messages to
579: .B bitblt
580: can return errors;
581: these can be detected by a system call error
582: on the
583: .IR write (see
584: .IR read (2))
585: of the data containing the erroneous message.
586: The most common error is a failure to allocate
587: because of insufficient free resources. Most other errors occur
588: only when the protocol is mishandled by the application.
589: .IR Errstr (2)
590: will report details.
591: .SH BUGS
592: Because each message must fit in a single 9P message,
593: subfonts are limited to about 1300 characters.
594: .br
595: Can only change the color map of bitmap 0.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.