DRAW(3)                                                   DRAW(3)

     NAME
          draw - screen graphics

     SYNOPSIS
          bind -a #i /dev

          /dev/draw/new

          /dev/draw/n/ctl
          /dev/draw/n/data
          /dev/draw/n/colormap
          /dev/draw/n/refresh

          #include <u.h>
          #include <draw.h>

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

     DESCRIPTION
          The draw device serves a three-level file system providing
          an interface to the graphics facilities of the system.  Each
          client of the device connects by opening /dev/draw/new and
          reading 12 strings, each 11 characters wide followed by a
          blank: the connection number (n), the image id (q.v.)  of
          the display image (always zero), the channel format of the
          image, the replicate bit, the min.x, min.y, max.x, and max.y
          of the display image, and the min.x, min.y, max.x, and max.y
          of the clipping rectangle. The channel format string is
          described in image(6), and the other fields are decimal num-
          bers.

          The client can then open the directory /dev/draw/n/ to
          access the ctl, data, colormap, and refresh files associated
          with the connection.

          Via the ctl and data files, the draw device provides access
          to images and font caches in its private storage, as
          described in graphics(2). Each image is identified by a 4-
          byte integer, its id.

          Reading the ctl file yields 12 strings formatted as in
          /dev/draw/new, but for the current image rather than the
          display image.  The current image may be set by writing a
          binary image id to the ctl file.

          A process can write messages to data to allocate and free
          images, fonts, and subfonts; read or write portions of the

     Page 1                       Plan 9             (printed 3/19/24)

     DRAW(3)                                                   DRAW(3)

          images; and draw line segments and character strings in the
          images.  All graphics requests are clipped to their images.
          Some messages return a response to be recovered by reading
          the data file.

          The format of messages written to data is a single letter
          followed by binary parameters; multibyte integers are trans-
          mitted with the low order byte first.  The BPSHORT and
          BPLONG macros place correctly formatted two- and four-byte
          integers into a character buffer.  BGSHORT and BGLONG
          retrieve values from a character buffer.  Points are two
          four-byte numbers: x, y. Rectangles are four four-byte num-
          bers: min x, min y, max x, and max y. Images, screens, and
          fonts have 32-bit identifiers.  In the discussion of the
          protocol below, the distinction between identifier and
          actual image, screen, or font is not made, so that ``the
          object id'' should be interpreted as ``the object with iden-
          tifier id''. The definitions of constants used in the
          description below can be found in draw.h.

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

          A id[4] imageid[4] fillid[4] public[1]
               Allocate a new Screen (see window(2)) with screen iden-
               tifier id using backing store image imageid, filling it
               initially with data from image fillid. If the public
               byte is non-zero, the screen can be accessed from other
               processes using the publicscreen interface.

          b id[4] screenid[4] refresh[1] chan[4] repl[1] r[4*4]
               clipr[4*4] color[4]
               Allocate an image with a given id on the screen named
               by screenid. The image will have rectangle r and clip-
               ping rectangle clipr. If repl is non-zero, the image's
               replicate bit will be set (see draw(2)).

               Refresh specifies the method to be used to draw the
               window when it is uncovered.  Refbackup causes the
               server to maintain a backing store, Refnone does not
               refresh the image, and Refmesg causes a message to be
               sent via the refresh file (q.v.).

               The image format is described by chan, a binary version
               of the channel format string.  Specifically, the image
               format is the catenation of up to four 8-bit numbers,
               each describing a particular image channel.  Each of
               these 8-bit numbers contains a channel type in its high
               nibble and a bit count in its low nibble.  The channel
               type is one of CRed, CGreen, CBlue, CGrey, CAlpha,
               CMap, and CIgnore.  See image(6).

     Page 2                       Plan 9             (printed 3/19/24)

     DRAW(3)                                                   DRAW(3)

               Color is the catenation of four 8-bit numbers specify-
               ing the red, green, blue, and alpha channels of the
               color that the new image should be initially filled
               with.  The red channel is in the highest 8 bits, and
               the alpha in the lowest.  Note that color is always in
               this format, independent of the image format.

          c dstid[4] repl[1] clipr[4*4]
               Change the replicate bit and clipping rectangle of the
               image dstid. This overrides whatever settings were
               specified in the allocate message.

          d dstid[4] srcid[4] maskid[4] dstr[4*4] srcp[2*4] maskp[2*4]
               Use the draw operator to combine the rectangle dstr of
               image dstid with a rectangle of image srcid, using a
               rectangle of image maskid as an alpha mask to further
               control blending.  The three rectangles are congruent
               and aligned such that the upper left corner dstr in
               image dstid corresponds to the point srcp in image
               srcid and the point maskp in image maskid. See draw(2).

          D debugon[1]
               If debugon is non-zero, enable debugging output.  If
               zero, disable it.  The meaning of ``debugging output''
               is implementation dependent.

          e dstid[4] srcid[4] c[2*4] a[4] b[4] thick[4] sp[2*4]
               alpha[4] phi[4]
               Draw an ellipse in image dst centered on the point c
               with horizontal and vertical semiaxes a and b. The
               ellipse is drawn using the image src, with the point sp
               in src aligned with c in dst. The ellipse is drawn with
               thickness 1+2×thick.

               If the high bit of alpha is set, only the arc of the
               ellipse from degree angles alpha to phi is drawn.  For
               the purposes of drawing the arc, alpha is treated as a
               signed 31-bit number by ignoring its high bit.

          E dstid[4] srcid[4] center[2*4] a[4] b[4] thick[4] sp[2*4]
               alpha[4] phi[4]
               Draws an ellipse or arc as the e message, but rather
               than outlining it, fills the corresponding sector using
               the image srcid. The thick field is ignored, but must
               be non-negative.

          f id[4]
               Free the resources associated with the image id.

          F id[4]
               Free the screen with the specified id. Windows on the
               screen must be freed separately.

     Page 3                       Plan 9             (printed 3/19/24)

     DRAW(3)                                                   DRAW(3)

          i id[4] n[4] ascent[1]
               Treat the image id as a font cache of n character
               cells, each with ascent ascent.

          l cacheid[4] srcid[4] index[2] r[4*4] sp[2*4] left[1]
               width[1]
               Load a character into the font cache associated with
               image cacheid at cache position index. The character
               data is drawn in rectangle r of the font cache image
               and is fetched from the congruent rectangle in image
               srcid with upper left corner sp. Width specifies the
               width of the character-the spacing from this character
               to the next-while left specifies the horizontal dis-
               tance from the left side of the character to the left
               side of the cache image.  The dimensions of the image
               of the character are defined by r.

          L dstid[4] p0[2*4] p1[2*4] end0[4] end1[4] thick[4] srcid[4]
               sp[2*4]
               Draw a line of thickness 1+2×thick in image dstid from
               point p0 to p1. The line is drawn using the image
               srcid, translated so that point sp in srcid aligns with
               p0 in dstid. The end0 and end1 fields specify whether
               the corresponding line end should be a square, a disc,
               or an arrow head.  See line in draw(2) for more
               details.

          N id[4] in[1] j[1] name[j]
               If in is non-zero, associate the image id with the
               string name. If in is zero and name already corresponds
               to the image id, the association is deleted.

          n id[4] j[1] name[j]
               Introduce the identifier id to correspond to the image
               named by the string name.

          o id[4] r.min[2*4] scr[2*4]
               Position the window (layer) id so that its upper left
               corner is at the point scr on its screen.  Simultane-
               ously change its internal (logical) coordinate system
               so that the point r.min corresponds to the upper left
               corner of the window, see memlorigin(2).

          O op[1]
               Set the compositing operator to op for the next draw
               operation.  (The default is SoverD).

          p dstid[4] n[2] end0[4] end1[4] thick[4] srcid[4] sp[2*4]
               dp[2*2*(n+1)]
               Draw a polygon of thickness 1+2×thick.  It is conceptu-
               ally equivalent to a series of n line-drawing messages
               (see L above) joining adjacent points in the list of

     Page 4                       Plan 9             (printed 3/19/24)

     DRAW(3)                                                   DRAW(3)

               points dp. The source image srcid is translated so that
               the point sp in srcid aligns with the first point in
               the list dp. The polygon need not be closed: end0 and
               end1 specify the line endings for the first and last
               point on the polygon.  All interior lines have rounded
               ends to make smooth joins.

          P dstid[4] n[2] wind[4] ignore[2*4] srcid[4] sp[2*4]
               dp[2*2*(n+1)]
               Draw a polygon as the p message, but fill it rather
               than outlining it.  The winding rule parameter wind
               resolves ambiguities about what to fill if the polygon
               is self-intersecting.  If wind is ~0, a pixel is inside
               the polygon if the polygon's winding number about the
               point is non-zero.  If wind is 1, a pixel is inside if
               the winding number is odd.  Complementary values (0 or
               ~1) cause outside pixels to be filled.  The meaning of
               other values is undefined.  The polygon is closed with
               a line if necessary.

          r id[4] r[4*4]
               Cause the next read of the data file to return the
               image pixel data corresponding to the rectangle r in
               image id.

          s dstid[4] srcid[4] fontid[4] dp[2*4] clipr[4*4] sp[2*4]
               n[2] n*(index[2])
               Draw in the image dstid the text string specified by
               the n cache indices into font fontid, starting with the
               upper left corner at point p in image dstid. The image
               drawn is taken from image srcid, translated to align sp
               in srcid with dp in dstid. All drawing is confined to
               the clipping rectangle clipr in dstid.

          x dstid[4] srcid[4] fontid[4] dp[2*4] clipr[4*4] sp[2*4]
               n[2] bgid[4] bp[2*4] n*(index[2])
               Like the string drawing s command, but fill the back-
               ground of each character with pixels from image bgid.
               The image bgid is translated so that the point bp
               aligns with the point dp in dstid.

          S id[4] chan[4] Attach to the public screen with the speci-
               fied id. It is an error if the screen does not exist,
               is not public, or does not have the channel descriptor
               chan for its associated image.

          t top[1] n[2] n*id[4]
               Send n windows to the top (if t is non-zero) or bottom
               (if t is zero) of the window stack.  The window is
               specified by the list of n image ids are moved as a
               group, maintaining their own order within the stack.

     Page 5                       Plan 9             (printed 3/19/24)

     DRAW(3)                                                   DRAW(3)

          v
               Flush changes from a soft screen, if any, to the dis-
               play buffer.

          y id[4] r[4*4] buf[x*1]
          Y id[4] r[4*4] buf[x*1]
               Replace the rectangle r of pixels in image id with the
               pixel data in buf. The pixel data must be in the format
               dictated by id's image channel descriptor (see
               image(6)). The y message uses uncompressed data, while
               the Y message uses compressed data. In either case, it
               is an error to include more data than necessary.

          Reading the colormap returns the system color map used on
          8-bit displays.  Each color map entry consists of a single
          line containing four space-separated decimal strings.  The
          first is an index into the map, and the remaining three are
          the red, green, and blue values associated with that index.
          The color map can be changed by writing entries in the above
          format to the colormap file.  Note that changing the system
          color map does not change the color map used for calcula-
          tions involving m8 images, which is immutable.

          The refresh file is read-only.  As windows owned by the
          client are uncovered, if they cannot be refreshed by the
          server (such as when they have refresh functions associated
          with them), a message is made available on the refresh file
          reporting what needs to be repainted by the client.  The
          message has five decimal integers formatted as in the ctl
          message: the image id of the window and the coordinates of
          the rectangle that should be refreshed.

     SOURCE
          /sys/src/9/port/devdraw.c
          /sys/src/libmemdraw

     DIAGNOSTICS
          Most messages to draw 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
          The Refmesg refresh method is not fully implemented.
          The colormap files only reference the system color map, and
          as such should be called /dev/colormap rather than
          /dev/draw/n/colormap.

     Page 6                       Plan 9             (printed 3/19/24)