Return to bit CVS log

Up to [Plan 9 NeXT] / lucent / sys / man / 3

Annotation of lucent/sys/man/3/bit, revision 1.1

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.