man(1) Manual page archive

     DRAW(2)                                                   DRAW(2)

          Image, draw, gendraw, drawreplxy, drawrepl, replclipr, line,
          poly, fillpoly, bezier, bezspline, fillbezier,
          fillbezspline, ellipse, fillellipse, arc, fillarc, icossin,
          icossin2, border, string, stringn, runestring, runestringn,
          stringbg, stringnbg, runestringbg, runestringnbg, _string,
          ARROW, drawsetdebug - graphics functions

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

          struct Image
               Display   *display; /* display holding data */
               int       id;       /* id of system-held Image */
               Rectangle r;        /* rectangle in data area, local coords */
               Rectangle clipr;    /* clipping region */
               ulong     chan;     /* pixel channel format descriptor */
               int       depth;    /* number of bits per pixel */
               int       repl;     /* flag: data replicates to tile clipr */
               Screen    *screen;  /* 0 if not a window */
               Image     *next;    /* next in list of windows */
          } Image;

          void draw(Image *dst, Rectangle r,
                   Image *src, Image *mask, Point p)

          void gendraw(Image *dst, Rectangle r,
                   Image *src, Point sp, Image *mask, Point mp)

          int  drawreplxy(int min, int max, int x)

          Point drawrepl(Rectangle r, Point p)

          void replclipr(Image *i, int repl, Rectangle clipr)

          void line(Image *dst, Point p0, Point p1, int end0, int end1,
                   int radius, Image *src, Point sp)

          void poly(Image *dst, Point *p, int np, int end0, int end1,
                   int radius, Image *src, Point sp)

          void fillpoly(Image *dst, Point *p, int np, int wind,
                   Image *src, Point sp)

          int  bezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
                   int end0, int end1, int radius, Image *src, Point sp)

     DRAW(2)                                                   DRAW(2)

          int  bezspline(Image *dst, Point *pt, int npt, int end0, int end1,
                   int radius, Image *src, Point sp)

          int  fillbezier(Image *dst, Point p0, Point p1, Point p2, Point p3,
                   int w, Image *src, Point sp)

          int  fillbezspline(Image *dst, Point *pt, int npt, int w,
                   Image *src, Point sp)

          void ellipse(Image *dst, Point c, int a, int b, int thick,
                   Image *src, Point sp)

          void fillellipse(Image *dst, Point c, int a, int b,
                   Image *src, Point sp)

          void arc(Image *dst, Point c, int a, int b, int thick,
                   Image *src, Point sp, int alpha, int phi)

          void fillarc(Image *dst, Point c, int a, int b, Image *src,
                   Point sp, int alpha, int phi)

          int  icossin(int deg, int *cosp, int *sinp)

          int  icossin2(int x, int y, int *cosp, int *sinp)

          void border(Image *dst, Rectangle r, int i, Image *color, Point sp)

          Point string(Image *dst, Point p, Image *src, Point sp,
                   Font *f, char *s)

          Point stringn(Image *dst, Point p, Image *src, Point sp,
                   Font *f, char *s, int len)

          Point runestring(Image *dst, Point p, Image *src, Point sp,
                   Font *f, Rune *r)

          Point runestringn(Image *dst, Point p, Image *src, Point sp,
                   Font *f, Rune *r, int len)

          Point stringbg(Image *dst, Point p, Image *src, Point sp,
                   Font *f, char *s, Image *bg, Point bgp)

          Point stringnbg(Image *dst, Point p, Image *src, Point sp,
                   Font *f, char *s, int len, Image *bg, Point bgp)

          Point runestringbg(Image *dst, Point p, Image *src, Point sp,
                   Font *f, Rune *r, Image *bg, Point bgp)

          Point runestringnbg(Image *dst, Point p, Image *src, Point sp,
                   Font *f, Rune *r, int len, Image *bg, Point bgp)

          Point _string(Image *dst, Point p, Image *src,

     DRAW(2)                                                   DRAW(2)

                   Point sp, Font *f, char *s, Rune *r, int len,
                   Rectangle clipr, Image *bg, Point bgp)

          void  drawsetdebug(int on)

                /* line ends */
                Endsquare= 0,
                Enddisc= 1,
                Endarrow= 2,
                Endmask= 0x1F

          #define ARROW(a, b, c) (Endarrow|((a)<<5)|((b)<<14)|((c)<<23))

          The Image type defines rectangular pictures and the methods
          to draw upon them; it is also the building block for higher
          level objects such as windows and fonts.  In particular, a
          window is represented as an Image; no special operators are
          needed to draw on a window.

          r         The coordinates of the rectangle in the plane for
                    which the Image has defined pixel values.  It
                    should not be modified after the image is created.

          clipr     The clipping rectangle: operations that read or
                    write the image will not access pixels outside
                    clipr.  Frequently, clipr is the same as r, but it
                    may differ; see in particular the discussion of
                    repl.  The clipping region may be modified dynami-
                    cally using replclipr (q.v.).

          chan      The pixel channel format descriptor, as described
                    in image(6). The value should not be modified
                    after the image is created.

          depth     The number of bits per pixel in the picture; it is
                    identically chantodepth(chan) (see graphics(2))
                    and is provided as a convenience.  The value
                    should not be modified after the image is created.

          repl      A boolean value specifying whether the image is
                    tiled to cover the plane when used as a source for
                    a drawing operation.  If repl is zero, operations
                    are restricted to the intersection of r and clipr.
                    If repl is set, r defines the tile to be repli-
                    cated and clipr defines the portion of the plane
                    covered by the tiling, in other words, r is repli-
                    cated to cover clipr; in such cases r and clipr
                    are independent.

     DRAW(2)                                                   DRAW(2)

                    For example, a replicated image with r set to
                    ((0, 0), (1, 1)) and clipr set to
                    ((0, 0), (100, 100)), with the single pixel of r
                    set to blue, behaves identically to an image with
                    r and clipr both set to ((0, 0), (100, 100)) and
                    all pixels set to blue.  However, the first image
                    requires far less memory.  The replication flag
                    may be modified dynamically using replclipr

          draw(dst, r, src, mask, p)
                    Draw is the standard drawing function.  Only those
                    pixels within the intersection of dst->r and
                    dst->clipr will be affected; draw ignores
                    dst->repl.  The operation proceeds as follows
                    (this is a description of the behavior, not the

                    1.   If repl is set in src or mask, replicate
                         their contents to fill their clip rectangles.

                    2.   Translate src and mask so p is aligned with

                    3.   Set r to the intersection of r and dst->r.

                    4.   Intersect r with src->clipr.  If src->repl is
                         false, also intersect r with src->r.

                    5.   Intersect r with mask->clipr.  If mask->repl
                         is false, also intersect r with mask->r.

                    6.   For each location in r, combine the dst pixel
                         with the src pixel using the alpha value cor-
                         responding to the mask pixel.  If the mask
                         has an explicit alpha channel, the alpha
                         value corresponding to the mask pixel is sim-
                         ply that pixel's alpha channel.  Otherwise,
                         the alpha value is the NTSC greyscale equiva-
                         lent of the color value, with white meaning
                         opaque and black transparent.  In terms of
                         the Porter-Duff compositing algebra, draw
                         replaces the dst pixels with (src in mask)
                         over dst.

                    The various pixel channel formats involved need
                    not be identical.  If the channels involved are
                    smaller than 8-bits, they will be promoted before
                    the calculation by replicating the extant bits;
                    after the calculation, they will be truncated to
                    their proper sizes.

     DRAW(2)                                                   DRAW(2)

          gendraw(dst, r, src, p0, mask, p1)
                    Similar to draw except that gendraw aligns the
                    source and mask differently: src is aligned so p0
                    corresponds to r.min and mask is aligned so p1
                    corresponds to r.min.  For most purposes with sim-
                    ple masks and source images, draw is sufficient,
                    but gendraw is the general operator and the one
                    all other drawing primitives are built upon.

                    Clips x to be in the half-open interval [min, max)
                    by adding or subtracting a multiple of max-min.

                    Clips the point p to be within the rectangle r by
                    translating the point horizontally by an integer
                    multiple of rectangle width and vertically by the

                    Because the image data is stored on the server,
                    local modifications to the Image data structure
                    itself will have no effect.  Repclipr modifies the
                    local Image data structure's repl and clipr
                    fields, and notifies the server of their modifica-

          line(dst, p0, p1, end0, end1, thick, src, sp)
                    Line draws in dst a line of width 1+2*thick pixels
                    joining points p0 and p1. The line is drawn using
                    pixels from the src image aligned so sp in the
                    source corresponds to p0 in the destination.  The
                    line touches both p0 and p1, and end0 and end1
                    specify how the ends of the line are drawn.
                    Endsquare terminates the line perpendicularly to
                    the direction of the line; a thick line with
                    Endsquare on both ends will be a rectangle.
                    Enddisc terminates the line by drawing a disc of
                    diameter 1+2*thick centered on the end point.
                    Endarrow terminates the line with an arrowhead
                    whose tip touches the endpoint.

                    The macro ARROW permits explicit control of the
                    shape of the arrow.  If all three parameters are
                    zero, it produces the default arrowhead, other-
                    wise, a sets the distance along line from end of
                    the regular line to tip, b sets the distance along
                    line from the barb to the tip, and c sets the dis-
                    tance perpendicular to the line from edge of line
                    to the tip of the barb, all in pixels.

                    Line and the other geometrical operators are

     DRAW(2)                                                   DRAW(2)

                    equivalent to calls to gendraw using a mask pro-
                    duced by the geometric procedure.

          poly(dst, p, np, end0, end1, thick, src, sp)
                    Poly draws a general polygon; it is conceptually
                    equivalent to a series of calls to line joining
                    adjacent points in the array of Points p, which
                    has np elements.  The ends of the polygon are
                    specified as in line; interior lines are termi-
                    nated with Enddisc to make smooth joins.  The
                    source is aligned so sp corresponds to p[0].

          fillpoly(dst, p, np, wind, src, sp)
                    Fillpoly is like poly but fills in the resulting
                    polygon rather than outlining it.  The source is
                    aligned so sp corresponds to p[0].  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 mean-
                    ing of other values is undefined.  The polygon is
                    closed with a line if necessary.

          bezier(dst, a, b, c, d, end0, end1, thick, src, sp)
                    Bezier draws the cubic Bezier curve defined by
                    Points a, b, c, and d. The end styles are deter-
                    mined by end0 and end1; the thickness of the curve
                    is 1+2*thick.  The source is aligned so sp in src
                    corresponds to a in dst.

          bezspline(dst, p, end0, end1, thick, src, sp)
                    Bezspline takes the same arguments as poly but
                    draws a quadratic B-spline (despite its name)
                    rather than a polygon.  If the first and last
                    points in p are equal, the spline has periodic end

          fillbezier(dst, a, b, c, d, wind, src, sp)
                    Fillbezier is to bezier as fillpoly is to poly.

          fillbezspline(dst, p, wind, src, sp)
                    Fillbezspline is like fillpoly but fills the qua-
                    dratic B-spline rather than the polygon outlined
                    by p. The spline is closed with a line if neces-

          ellipse(dst, c, a, b, thick, src, sp)
                    Ellipse draws in dst an ellipse centered on c with
                    horizontal and vertical semiaxes a and b. The

     DRAW(2)                                                   DRAW(2)

                    source is aligned so sp in src corresponds to c in
                    dst. The ellipse is drawn with thickness

          fillellipse(dst, c, a, b, src, sp)
                    Fillellipse is like ellipse but fills the ellipse
                    rather than outlining it.

          arc(dst, c, a, b, thick, src, sp, alpha, phi)
                    Arc is like ellipse, but draws only that portion
                    of the ellipse starting at angle alpha and extend-
                    ing through an angle of phi. The angles are mea-
                    sured in degrees counterclockwise from the posi-
                    tive x axis.

          fillarc(dst, c, a, b, src, sp, alpha, phi)
                    Fillarc is like arc, but fills the sector with the
                    source color.

          icossin(deg, cosp, sinp)
                    Icossin stores in *cosp and *sinp scaled integers
                    representing the cosine and sine of the angle deg,
                    measured in integer degrees.  The values are
                    scaled so cos(0) is 1024.

          icossin2(x, y, cosp, sinp)
                    Icossin2 is analogous to icossin, with the angle
                    represented not in degrees but implicitly by the
                    point (x,y).  It is to icossin what atan2 is to
                    atan (see sin(2)).

          border(dst, r, i, color, sp)
                    Border draws an outline of rectangle r in the
                    specified color. The outline has width i; if posi-
                    tive, the border goes inside the rectangle; nega-
                    tive, outside.  The source is aligned so sp corre-
                    sponds to r.min.

          string(dst, p, src, sp, font, s)
                    String draws in dst characters specified by the
                    string s and font; it is equivalent to a series of
                    calls to gendraw using source src and masks deter-
                    mined by the character shapes.  The text is posi-
                    tioned with the left of the first character at p.x
                    and the top of the line of text at p.y.  The
                    source is positioned so sp in src corresponds to p
                    in dst. String returns a Point that is the posi-
                    tion of the next character that would be drawn if
                    the string were longer.

                    For characters with undefined or zero-width images
                    in the font, the character at font position 0

     DRAW(2)                                                   DRAW(2)

                    (NUL) is drawn.

                    The other string routines are variants of this
                    basic form, and have names that encode their vari-
                    ant behavior.  Routines whose names contain rune
                    accept a string of Runes rather than UTF-encoded
                    bytes.  Routines ending in n accept an argument,
                    n, that defines the number of characters to draw
                    rather than accepting a NUL-terminated string.
                    Routines containing bg draw the background behind
                    the characters in the specified color (bg) and
                    alignment (bgp); normally the text is drawn leav-
                    ing the background intact.

                    The routine _string captures all this behavior
                    into a single operator.  Whether it draws a UTF
                    string or Rune string depends on whether s or r is
                    null (the string length is always determined by
                    len). If bg is non-null, it is used as a back-
                    ground color.  The clipr argument allows further
                    management of clipping when drawing the string; it
                    is intersected with the usual clipping rectangles
                    to further limit the extent of the text.

                    Turns on or off debugging output (usually to a
                    serial line) according to whether on is non-zero.


          graphics(2), stringsize(2), color(6), utf(6), addpt(2)

          T. Porter, T. Duff.  ``Compositing Digital Images'',
          Computer Graphics (Proc. SIGGRAPH), 18:3, pp. 253-259, 1984.

          These routines call the graphics error function on fatal

          Anti-aliased characters can be drawn by defining a font with
          multiple bits per pixel, but there are no anti-aliasing geo-
          metric primitives.