draw man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

DRAW(3)								       DRAW(3)

       draw - screen graphics

       bind -a #i /dev



       #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)

       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 char‐
       acters 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 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 numbers.

       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 draw 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 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  transmitted with the low
       order byte first.  The BPSHORT and BPLONG macros place  correctly  for‐
       matted  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 numbers: min x,
       min y, max x, and max y.	 Images, screens, and fonts have 32-bit	 iden‐
       tifiers.	  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 parameters.

       A id[4] imageid[4] fillid[4] public[1]
	    Allocate a new Screen (see window(2)) with	screen	identifier  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]
	    Allocate an image with a given id on the screen named by screenid.
	    The	 image will have rectangle r and clipping rectangle clipr.  If
	    repl is non-zero, the image's  replicate  bit  will	 be  set  (see

	    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 particu‐
	    lar 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).

	    Color is the catenation of four 8-bit numbers specifying 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	 high‐
	    est	 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  rectan‐
	    gles  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	depen‐

       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 horizon‐
	    tal 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]
	    Draws an ellipse or arc as the e message, but rather than  outlin‐
	    ing 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 the screen with the specified id.	Windows on the	screen
	    must be freed separately.

       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  rec‐
	    tangle  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 distance 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

       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  id  so that its upper left corner is at the
	    point scr on its screen.  Simultaneously change its internal (log‐
	    ical)  coordinate  system so that the point log corresponds to the
	    upper left corner of the window.

       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 conceptually equiva‐
	    lent to a series of n line-drawing messages (see L above)  joining
	    adjacent  points in the list of 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

       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 unde‐
	    fined.  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]	  p[2*4]   clipr[4*4]	sp[2*4]	  n[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 background of each
	    character  with  pixels from image bgid.  The image bgid is trans‐
	    lated so that the point bp aligns with the point dp in dstid.

       S id[4] chan[4] Attach to the public screen with the specified 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.

	    Flush changes from a soft screen, if any, to the display 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 dis‐
       plays.  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 calculations 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	avail‐
       able  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 rectan‐
       gle that should be refreshed.


       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.

       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.

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net