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,
       replclipr, 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
       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
		 dynamically using replclipr (q.v.).

       chan	 The   pixel   channel	format	descriptor,  as	 described  in
		 image(7).  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 graphics(3)) 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	opera-
		 tion.	If repl	is zero,  operations  are  restricted  to  the
		 intersection  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
       extended	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
	      extant  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
	      arrow.   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  perpen-
	      dicular  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
	      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(3)).

       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-
	      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	 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
	      operator.	 Whether it draws a UTF	string or Rune string  depends
	      on  whether  s  or r is null (the	string length is always	deter-
	      mined 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	 clip-
	      ping rectangles to further limit the extent of the text.

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

SOURCE
       /usr/local/plan9/src/libdraw

SEE ALSO
       graphics(3), stringsize(3), color(7), utf(7), addpt(3)

       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.0-RELEASE+and+Ports>

home | help