unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (plan9)
Page:
Section:
Apropos / Subsearch:
optional field

BIT(3)                     Library Functions Manual                     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  exclu-
       sive use.

       The  bit  device  provides, through the bitblt file, access to bitmaps,
       fonts, and subfonts in its private  storage,  as  described  in  graph-
       ics(2).  Each object is identified by a short, its id.  The bitmap with
       id zero is special: it represents 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 cur-
       rent mouse position.  A process can write messages to bitblt  to  allo-
       cate  and  free bitmaps, fonts, and subfonts, read or write portions of
       the bitmaps, and draw line segments, textures, and character strings in
       the bitmaps.  All graphics requests are clipped to their bitmaps.  Some
       messages 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 integers are transmitted with
       the low order byte first.  The BPSHORT and  BPLONG  macros  place  cor-
       rectly  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.

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

       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 bit-
            map is returned on a subsequent read from  bitblt,  returning  the
            three bytes: 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 identi-
            fied by srcid to a congruent rectangle at Point dstpt in the  bit-
            map  identified  by  dstid.  The rectangle is clipped against both
            source and destination bitmaps. See bitblt(2).

       c [ pt[8] clr[32] set[32] ]
            Switch mouse cursor.  See the description  of  Cursors  in  graph-
            ics(2)  for the meaning of the pt (the offset), set, and clr argu-
            ments.  If only 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  hold-
            ing 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  subfont  identi-
            fied  by  id, including its bitmap.  If the subfont is cached, the
            associated data may be recoverable 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 information about the dis-
            play:
                 I ldepth[1] rect[16] cliprect[16].

            If the read count is large enough, the above information  is  fol-
            lowed  by the header and character information of the default Sub-
            font, 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  subfal-
            loc(2), with info in external subfont file format.  Bitmapid iden-
            tifies 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:  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 destination 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: followed by the id.   The  initial  cache  associated
            with the font will have ncache character entries of zero width.

       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 specified 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 sub-
            sequent read of bitblt will return the requested rows  of  pixels.
            Note:  in  this  case, the response does not begin with an to sim-
            plify 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 can-
            not 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 sub-
            font subfontid into slot cacheindex 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  position  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 bitmap, 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  inclu-
              sive.

              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, subfonts are lim-
       ited to about 1300 characters.
       Can only change the color map of bitmap 0.



                                                                        BIT(3)