draw man page on Inferno

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

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/refresh

DESCRIPTION
       The draw device serves a three-level file system providing an interface
       to the graphics facilities of the system.  The Limbo Draw  module  (see
       draw-intro(2)) implements its functions using this device.  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 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  rectan‐
       gle.  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, 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	draw-intro(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  draw  device  provides  three types of graphical resource: Images,
       Screens and Fonts.  Resource instances have an  identification  number.
       Screen identifiers are global to the device.  All other identifiers are
       local to each client.

       Image is the fundamental resource type on which all drawing  primitives
       are  performed.	 At  client  connection the physical display is repre‐
       sented by Image 0.

       A Screen manages a set of (overlapping) Images,	handling  Z-order  and
       position	 manipulation  and the refreshing of regions uncovered by such
       operations.  When a Screen is created it is associated with an Image on
       which  to  render  itself.   New images can be associated with a screen
       when they are created; they are then treated as windows on that screen.
       Screens	can be marked as public, meaning that other clients can import
       their ID and create new windows on them.

       A Font is an image with associated character data.  The Font image pro‐
       vides  the bitmap of all the characters in the Font; the character data
       is used by the string command to render characters from the image.

   Command messages
       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.  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 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 inter‐
       preted  as  ``the object with identifier id''.  The definitions of con‐
       stants used in the description below can be found in /module/draw.m  or
       /include/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 draw-display(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]
	    color[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
	    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 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-image(2).

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

       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]
	    phi[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-image(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 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.

       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
	    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 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]
	    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 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.

       v
	    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.

       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.

SOURCE
       /emu/port/devdraw.c
       /emu/*/win.c
       /os/port/devdraw.c
       /os/*/screen.c
       /libmemdraw

SEE ALSO
       draw-intro(2), colour(6), image(6), font(6)

DIAGNOSTICS
       Most  messages  to  draw	 can return errors; these can be detected by a
       system call error on the write(see sys-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.  The error string
       (see sys-intro(2)) will report details.

BUGS
       The Refmesg refresh method is not fully implemented.

								       DRAW(3)
[top]

List of man pages available for Inferno

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]
Tweet
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