Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DRAW(3)			   Library Functions Manual		       DRAW(3)

NAME
       Image,  draw,  drawop,  gendraw,	 gendrawop,  drawreplxy, drawrepl, re-
       plclipr,	line, lineop,  poly,  polyop,  fillpoly,  fillpolyop,  bezier,
       bezierop,   bezspline,  bezsplineop,  bezsplinepts,  fillbezier,	 fill-
       bezierop, fillbezspline,	fillbezsplineop, ellipse,  ellipseop,  fillel-
       lipse,	fillellipseop,	 arc,	arcop,	fillarc,  fillarcop,  icossin,
       icossin2,  border,  borderop,  string,  stringop,  stringn,  stringnop,
       runestring, runestringop, runestringn, runestringnop, stringbg, string-
       bgop,	stringnbg,    stringnbgop,    runestringbg,    runestringbgop,
       runestringnbg, runestringnbgop, _string,	ARROW, drawsetdebug - graphics
       functions

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

       typedef
       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;

       typedef enum
       {
	    /* Porter-Duff compositing operators */
	    Clear     =	0,
	    SinD = 8,
	    DinS = 4,
	    SoutD     =	2,
	    DoutS     =	1,
	    S	      =	SinD|SoutD,
	    SoverD    =	SinD|SoutD|DoutS,
	    SatopD    =	SinD|DoutS,
	    SxorD     =	SoutD|DoutS,
	    D	      =	DinS|DoutS,
	    DoverS    =	DinS|DoutS|SoutD,
	    DatopS    =	DinS|SoutD,
	    DxorS     =	DoutS|SoutD, /*	== SxorD */
	    Ncomp = 12,
       } Drawop;

       void  draw(Image	*dst, Rectangle	r, Image *src,
		 Image *mask, Point p)
       void  drawop(Image *dst,	Rectangle r, Image *src,
		 Image *mask, Point p, Drawop op)
       void  gendraw(Image *dst, Rectangle r, Image *src, Point	sp,
		 Image *mask, Point mp)
       void  gendrawop(Image *dst, Rectangle r,	Image *src, Point sp,
		 Image *mask, Point mp,	Drawop op)
       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  lineop(Image *dst,	Point p0, Point	p1, int	end0, int end1,
		 int radius, Image *src, Point sp, Drawop op)
       void  poly(Image	*dst, Point *p,	int np,	int end0, int end1,
		 int radius, Image *src, Point sp)
       void  polyop(Image *dst,	Point *p, int np, int end0, int	end1,
		 int radius, Image *src, Point sp, Drawop op)
       void  fillpoly(Image *dst, Point	*p, int	np, int	wind,
		 Image *src, Point sp)
       void  fillpolyop(Image *dst, Point *p, int np, int wind,
		 Image *src, Point sp, Drawop op)
       int   bezier(Image *dst,	Point p0, Point	p1, Point p2, Point p3,
		 int end0, int end1, int radius, Image *src, Point sp)
       int   bezierop(Image *dst, Point	p0, Point p1, Point p2,	Point p3,
		 int end0, int end1, int radius, Image *src, Point sp,
		 Drawop	op)
       int   bezspline(Image *dst, Point *pt, int npt, int end0, int end1,
		 int radius, Image *src, Point sp)
       int   bezsplineop(Image *dst, Point *pt,	int npt, int end0, int end1,
		 int radius, Image *src, Point sp, Drawop op)
       int   bezsplinepts(Point	*pt, int npt, Point **pp)
       int   fillbezier(Image *dst, Point p0, Point p1,	Point p2, Point	p3,
		 int w,	Image *src, Point sp)
       int   fillbezierop(Image	*dst, Point p0,	Point p1, Point	p2, Point p3,
		 int w,	Image *src, Point sp, Drawop op)
       int   fillbezspline(Image *dst, Point *pt, int npt, int w,
		 Image *src, Point sp)
       int   fillbezsplineop(Image *dst, Point *pt, int	npt, int w,
		 Image *src, Point sp, Drawop op)
       void  ellipse(Image *dst, Point c, int a, int b,	int thick,
		 Image *src, Point sp)
       void  ellipseop(Image *dst, Point c, int	a, int b, int thick,
		 Image *src, Point sp, Drawop op)
       void  fillellipse(Image *dst, Point c, int a, int b,
		 Image *src, Point sp)
       void  fillellipseop(Image *dst, Point c,	int a, int b,
		 Image *src, Point sp, Drawop op)
       void  arc(Image *dst, Point c, int a, int b, int	thick,
		 Image *src, Point sp, int alpha, int phi)
       void  arcop(Image *dst, Point c,	int a, int b, int thick,
		 Image *src, Point sp, int alpha, int phi, Drawop op)
       void  fillarc(Image *dst, Point c, int a, int b,	Image *src,
		 Point sp, int alpha, int phi)
       void  fillarcop(Image *dst, Point c, int	a, int b, Image	*src,
		 Point sp, int alpha, int phi, Drawop op)
       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)
       void  borderop(Image *im, Rectangle r, int i, Image *color, Point sp,
		 Drawop	op)
       Point string(Image *dst,	Point p, Image *src, Point sp,
		 Font *f, char *s)
       Point stringop(Image *dst, Point	p, Image *src, Point sp,
		 Font *f, char *s, Drawop op)
       Point stringn(Image *dst, Point p, Image	*src, Point sp,
		 Font *f, char *s, int len)
       Point stringnop(Image *dst, Point p, Image *src,	Point sp,
		 Font *f, char *s, int len, Drawop op)
       Point runestring(Image *dst, Point p, Image *src, Point sp,
		 Font *f, Rune *r)
       Point runestringop(Image	*dst, Point p, Image *src, Point sp,
		 Font *f, Rune *r, Drawop op)
       Point runestringn(Image *dst, Point p, Image *src, Point	sp,
		 Font *f, Rune *r, int len)
       Point runestringnop(Image *dst, Point p,	Image *src, Point sp,
		 Font *f, Rune *r, int len, Drawop op)
       Point stringbg(Image *dst, Point	p, Image *src, Point sp,
		 Font *f, char *s, Image *bg, Point bgp)
       Point stringbgop(Image *dst, Point p, Image *src, Point sp,
		 Font *f, char *s, Image *bg, Point bgp, Drawop	op)
       Point stringnbg(Image *dst, Point p, Image *src,	Point sp,
		 Font *f, char *s, int len, Image *bg, Point bgp)
       Point stringnbgop(Image *dst, Point p, Image *src, Point	sp,
		 Font *f, char *s, int len, Image *bg, Point bgp, Drawop op)
       Point runestringbg(Image	*dst, Point p, Image *src, Point sp,
		 Font *f, Rune *r, Image *bg, Point bgp)
       Point runestringbgop(Image *dst,	Point p, Image *src, Point sp,
		 Font *f, Rune *r, Image *bg, Point bgp, Drawop	op)
       Point runestringnbg(Image *dst, Point p,	Image *src, Point sp,
		 Font *f, Rune *r, int len, Image *bg, Point bgp)
       Point runestringnbgop(Image *dst, Point p, Image	*src, Point sp,
		 Font *f, Rune *r, int len, Image *bg, Point bgp, Drawop op)
       Point _string(Image *dst, Point p, Image	*src,
		 Point sp, Font	*f, char *s, Rune *r, int len,
		 Rectangle clipr, Image	*bg, Point bgp,	Drawop op)
       void  drawsetdebug(int on)

       enum
       {
	     /*	line ends */
	     Endsquare = 0,
	     Enddisc	   = 1,
	     Endarrow  = 2,
	     Endmask	   = 0x1F
       };

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

DESCRIPTION
       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 Im-
       age; 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 im-
		 age 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  dy-
		 namically using replclipr (q.v.).

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

       depth	 The number of bits per	pixel in the picture;  it  is  identi-
		 cally	chantodepth(chan)  (see	 and  is  provided as a	conve-
		 nience.  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	opera-
		 tion.	 If repl is zero, operations are restricted to the in-
		 tersection of r and clipr.  If	repl is	 set,  r  defines  the
		 tile  to  be  replicated and clipr defines the	portion	of the
		 plane covered by the tiling, in other words, r	is  replicated
		 to cover clipr; in such cases r and clipr are independent.

		 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	dynam-
		 ically	using replclipr	(q.v.).

       Most  of	 the drawing functions come in two forms: a basic form,	and an
       extended	form that takes	an extra Drawop	to specify a Porter-Duff  com-
       positing	 operator  to  use.   The  basic  forms	assume the operator is
       SoverD, which suffices for the vast majority of applications.  The  ex-
       tended forms are	named by adding	an -op suffix to the basic form.  Only
       the basic forms are listed below.

       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 implementation):

	      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 r.min.

	      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 corresponding to the mask
		     pixel.  If	the mask has an	explicit  alpha	 channel,  the
		     alpha  value  corresponding  to  the mask pixel is	simply
		     that pixel's alpha	channel.  Otherwise, the  alpha	 value
		     is	the NTSC greyscale equivalent 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.  (In the extended
		     form, ``over'' is replaced	by op).

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

       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
	      simple masks and source images, draw is sufficient, but  gendraw
	      is the general operator and the one all other drawing primitives
	      are built	upon.

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

       drawrepl(r,p)
	      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 height.

       replclipr(i,repl,clipr)
	      Because  the image data is stored	on the server, local modifica-
	      tions 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 modification.

       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  des-
	      tination.	  The  line  touches both p0 and p1, and end0 and end1
	      specify how the ends of the line are  drawn.   Endsquare	termi-
	      nates  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 ar-
	      row.  If all three parameters are	zero, it produces the  default
	      arrowhead, otherwise, 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 distance perpendicular	to the
	      line from	edge of	line to	the tip	of the barb, all in pixels.

	      Line and the other geometrical operators are equivalent to calls
	      to gendraw using a mask produced 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 terminated 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 meaning of other
	      values is	undefined.  The	polygon	is closed with a line if  nec-
	      essary.

       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 determined  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 con-
	      ditions.

       bezsplinepts(pt,	npt, pp)
	      Bezsplinepts  returns  in	pp a list of points making up the open
	      polygon that bezspline would draw.  The  caller  is  responsible
	      for freeing *pp.

       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 quadratic B-spline
	      rather than the polygon outlined by p.   The  spline  is	closed
	      with a line if necessary.

       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 source is aligned so	sp  in
	      src  corresponds	to c in	dst.  The ellipse is drawn with	thick-
	      ness 1+2*thick.

       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 extending through an angle  of  phi.
	      The  angles  are	measured  in degrees counterclockwise from the
	      positive 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 de-
	      grees.  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

       border(dst, r, i, color,	sp)
	      Border draws an outline of rectangle r in	the  specified	color.
	      The outline has width i; if positive, the	border goes inside the
	      rectangle; negative, outside.  The source	is aligned so sp  cor-
	      responds 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 determined by the	character shapes.  The
	      text is positioned with the left of the first character  at  p.x
	      and  the	top  of	 the line of text at p.y.  The source is posi-
	      tioned so	sp in src corresponds to p in dst.  String  returns  a
	      Point  that  is the position 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 (NUL) is	drawn.

	      The  other  string routines are variants of this basic form, and
	      have names that encode their variant behavior.   Routines	 whose
	      names  contain rune accept a string of Runes rather than UTF-en-
	      coded 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	 back-
	      ground  behind  the  characters  in the specified	color (bg) and
	      alignment	(bgp); normally	the text is drawn  leaving  the	 back-
	      ground intact.

	      The routine _string captures all this behavior into a single op-
	      erator.  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  background	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.

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

SOURCE
       /src/libdraw

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

DIAGNOSTICS
       These routines call the graphics	error function on fatal	errors.

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

								       DRAW(3)

NAME | SYNOPSIS | DESCRIPTION | SOURCE | SEE ALSO | DIAGNOSTICS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=draw&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help