BIT(3)                                                     BIT(3)

     NAME
          bit - screen graphics, mouse

     SYNOPSIS
          bind -a #b /dev

          /dev/bitblt
          /dev/mouse
          /dev/mousectl
          /dev/screen

          #include <u.h>
          #include <libg.h>

          ushort BGSHORT(uchar *p)
          ulong  BGLONG(uchar *p)
          void   BPSHORT(uchar *p, ushort v)
          void   BPLONG(uchar *p, ulong v)

     DESCRIPTION
          The bit device provides the files bitblt, mouse, mousectl,
          and screen on machines with a bitmapped screen and a mouse.
          The device is exclusive use.

          The bit device provides, through the bitblt file, access to
          bitmaps, fonts, and subfonts in its private storage, as
          described in graphics(2). Each object is identified by a
          short, its id. The bitmap with id zero is special: it repre-
          sents the visible display.  The subfont with id zero is also
          special: it is initialized to a default subfont that is
          always available.  There is no default font.  There is also
          a cursor associated with the screen; it is always displayed
          at the current mouse position.  A process can write messages
          to bitblt to allocate and free bitmaps, fonts, and subfonts,
          read or write portions of the bitmaps, and draw line seg-
          ments, textures, and character strings in the bitmaps.  All
          graphics requests are clipped to their bitmaps.  Some mes-
          sages return a response to be recovered by reading bitblt.

          The format of messages written to bitblt is a single lower
          case letter followed by binary parameters; multibyte inte-
          gers are transmitted with the low order byte first.  The
          BPSHORT and BPLONG macros place correctly formatted two- and
          four-byte integers into a character buffer.  Some messages
          return a response formatted the same way; it usually starts
          with the upper case version of the request character.
          BGSHORT and BGLONG retrieve values from a character buffer.
          Points are two four-byte numbers: x, y. Rectangles are four
          four-byte numbers: min x, min y, max x, and max y.

     BIT(3)                                                     BIT(3)

          The following requests are accepted by the bitblt file.  The
          numbers in brackets give the length in bytes of the parame-
          ters.

          a ldepth[1] rect[16]
               Allocate a bitmap.  Ldepth is the log base 2 of the
               number of bits per pixel.  Rect is a Rectangle giving
               the extent of the bitmap.  The bitmap is cleared to all
               zeros.  The id of the allocated bitmap is returned on a
               subsequent read from bitblt, returning the three bytes:
               `A' followed by the id.

          b dstid[2] dstpt[8] srcid[2] srcrect[16] code[2]
               Bit-block transfer (bitblt) from a rectangle in the
               bitmap identified by srcid to a congruent rectangle at
               Point dstpt in the bitmap identified by dstid. The
               rectangle is clipped against both source and destina-
               tion bitmaps. See bitblt(2).

          c [ pt[8] clr[32] set[32] ]
               Switch mouse cursor.  See the description of Cursors in
               graphics(2) for the meaning of the pt (the offset),
               set, and clr arguments.  If only `c' is provided - that
               is, if the message is one byte long - the cursor
               changes to the default, typically an arrow.

          e id[2] pt[8] value[1] code[2] n[2] pts[n*2]
               Join the n+1 points pt and pts with n segments, exactly
               as for the l operator.  The pts are specified by pairs
               of signed bytes holding offsets from the previous point
               in the list.

          f id[2]
               Free the resources associated with the allocated bitmap
               identified by id.

          g id[2]
               Free the resources associated with the allocated sub-
               font identified by id, including its bitmap.  If the
               subfont is cached, the associated data may be recover-
               able even after it has been freed; see below.

          h id[2]
               Free the resources associated with the allocated font
               identified by id.

          i
               Initialize the device.  The next operation on bitblt
               should be a read(2). A read of length 34 returns infor-
               mation about the display:
                    I ldepth[1] rect[16] cliprect[16].

     BIT(3)                                                     BIT(3)

               If the read count is large enough, the above informa-
               tion is followed by the header and character informa-
               tion of the default Subfont, in the format expected by
               rdsubfontfile (see subfalloc(2) and font(6)). `Large
               enough' is 36 + 6n, where n is the number of characters
               in the subfont.  The ids of the screen bitmap and
               default subfont are both zero.

          j q0[4] q1[4]
               Check to see whether a subfont with tags q0 and q1 is
               in the cache.  If it is not, the write of the j message
               will draw an error.  If it is, the next read of bitblt
               will return
                    J id[2]

               followed by the subfont information in the same format
               as returned by an init message; the subfont will then
               be available for use.

          k n[2] height[1] ascent[1] bitmapid[2] q0[4] q1[4]
               info[6*(n+1)]
               Allocate subfont.  The parameters are as described in
               subfalloc(2), with info in external subfont file for-
               mat.  Bitmapid identifies a previously allocated bitmap
               containing the character images.  Q0 and q1 are used as
               labels for the subfont in the cache; if all ones, the
               subfont will not be cached and hence shared with other
               applications.  The id of the allocated subfont is
               recovered by reading from bitblt the three bytes: `K'
               followed by the id.  Henceforth, the bitmap with id
               bitmapid is unavailable to the application; in effect,
               it has been freed.

          l id[2] pt1[8] pt2[8] value[1] code[2]
               Draw a line segment from Point pt1 to Point pt2, using
               code for the drawing function, and value as the source
               pixel. See segment in bitblt(2). Id identifies the des-
               tination bitmap.

          m id[2]
               Read the colormap associated with the bitmap with the
               specified id. The next read of bitblt will return
               12*2^n bytes of colormap data where n is the number of
               bits per pixel in the bitmap.

          n height[1] ascent[1] ldepth[2] ncache[2]
               Allocate a font with the given height, ascent, and
               ldepth. The id of the allocated font is recovered by
               reading from bitblt the three bytes: `N' followed by
               the id.  The initial cache associated with the font
               will have ncache character entries of zero width.

     BIT(3)                                                     BIT(3)

          p id[2] pt[8] value[1] code[2]
               Change the pixel at Point pt using code for the drawing
               function, and value as the source pixel. See point in
               bitblt(2).

          q id[2] rect[16]
               Set the clipping rectangle for the bitmap with speci-
               fied id to the given rectangle, which will itself be
               clipped to the bitmap's image rectangle.

          r id[2] miny[4] maxy[4]
               Read rows ymin, ymin+1, ... ymax-1 of the bitmap with
               the given bitmap id.  See the description of rdbitmap
               in balloc(2). A subsequent read of bitblt will return
               the requested rows of pixels.  Note: in this case, the
               response does not begin with an `R', to simplify the
               reading of large bitmaps.  Also, the reply may be too
               large to fit in a single 9P message (see read(5)), so
               multiple reads may be necessary; each read will return
               only complete rows.

          s id[2] pt[8] fontid[2] code[2] n[2] indices[2*n]
               Draw using code code in the bitmap identified by id the
               text string specified by the n cache indices in font
               fontid, starting with the upper left corner at pt.

          t dstid[2] rect[16] srcid[2] code[2]
               Texture the given rectangle in the bitmap identified by
               dstid by overlaying a tiling of the bitmap identified
               by srcid (aligning (0,0) in the two bitmaps), and using
               code as a drawing code for bitblt; see texture in
               bitblt(2).

          v id[2] ncache[2] width[2]
               Reset, resize, and clear the cache for font id; the
               maximum width of the ncache characters the cache may
               hold is set to width. Must be done before the first
               load of a cache slot.  If the cache cannot be resized,
               the write of this message will fail but the cache will
               be unaffected.

          w id[2] miny[4] maxy[4] data[n]
               Replace rows ymin, ymin+1, ... ymax-1 of the bitmap
               with the given bitmap id with the values in data. See
               the description of wrbitmap in balloc(2).

          x x[4] y[4]
               Move the cursor so its origin is at (x,y).

          y id[2] cacheindex[2] subfontid[2] subfontindex[2]
               Load the description and image of character
               subfontindex in subfont subfontid into slot cacheindex

     BIT(3)                                                     BIT(3)

               of font id.

          z id[2] map[m]
               Replace the colormap associated with bitmap id with
               map, which contains m=12*2^n bytes of colormap data
               (see rgbpix(2) for the format).

          A read of the mouse file returns the mouse status: its posi-
          tion and button state.  The read blocks until the state has
          changed since the last read.  The read returns 14 bytes:
               m buttons[1] x[4] y[4] msec[4]
          where x and y are the mouse coordinates in the screen bit-
          map, msec is a time stamp, in units of milliseconds, and
          buttons has set the 1, 2, and 4 bits when the mouse's left,
          middle, and right buttons, respectively, are down.

          Writing to the mousectl file configures and controls the
          mouse.  The messages are:

               serial n sets serial port n to be the mouse port.

               ps2 sets the PS2 port to be the mouse port.

               accelerated turns on mouse acceleration.

               linear turns off mouse acceleration

               res n sets mouse resolution to a setting between 0 and
               3 inclusive.

               swap swaps the left and right buttons on the mouse.
               Which messages are implemented is machine-dependent.

          The screen file contains the screen bitmap in the format
          described in bitmap(6).

     SOURCE
          /sys/src/9/port/devbit.c

     DIAGNOSTICS
          Most messages to bitblt can return errors; these can be
          detected by a system call error on the write(see read(2)) of
          the data containing the erroneous message.  The most common
          error is a failure to allocate because of insufficient free
          resources.  Most other errors occur only when the protocol
          is mishandled by the application.  Errstr(2) will report
          details.

     BUGS
          Because each message must fit in a single 9P message, sub-
          fonts are limited to about 1300 characters.
          Can only change the color map of bitmap 0.