Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

Plan 9 - man page for graphics (plan9 section 2)

GRAPHICS(2)			       System Calls Manual			      GRAPHICS(2)

NAME
       Point,  Rectangle,  Bitmap,  Cursor,  binit,  bclose,  berror, bscreenrect, bneed, bflush,
       bwrite, bexit, clipr, cursorswitch, cursorset, rdfontfile, ffree, charwidth, Pconv,  Rconv
       - bitmap graphics

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

       void	 binit(void (*errfun)(char *), char *font, char *label)

       void	 bclose(void)

       void	 bexit(void)

       void	 berror(char *msg)

       Rectangle bscreenrect(Rectangle *clipr)

       uchar*	 bneed(int n)

       void	 bflush(void)

       int	 bwrite(void)

       int	 clipr(Bitmap *b, Rectangle cr)

       void	 cursorswitch(Cursor *curs)

       void	 cursorset(Point p)

       Font*	 rdfontfile(char *name, int ldepth)

       void	 ffree(Font *f)

       int	 charwidth(Font *f, Rune r)

       int	 Pconv(void *arg, Fconv*)

       int	 Rconv(void *arg, Fconv*)

       extern Bitmap	screen

       extern Font	*font

DESCRIPTION
       A Point is a location in a bitmap (see below), such as the screen, and is defined as:

	      typedef
	      struct Point {
		    int x;
		    int y;
	      } Point;

       The coordinate system has x increasing to the right and y increasing down.

       A Rectangle is a rectangular area in a bitmap.

	      typedef
	      struct Rectangle {
		    Point min;	    /* upper left */
		    Point max;	    /* lower right */
	      } Rectangle;

       By  definition,	min.x<=max.x  and min.y<=max.y.  By convention, the right (maximum x) and
       bottom (maximum y) edges are excluded from the represented rectangle, so abutting  rectan-
       gles  have  no  points  in  common.  Thus, max contains the coordinates of the first point
       beyond the rectangle.

       A Bitmap holds a rectangular image.

	      typedef
	      struct Bitmap {
		    Rectangle r;       /* rect. in data area, local coords */
		    Rectangle clipr;   /* clipping region */
		    int       ldepth;  /* log base 2 of #bits per pixel */
		    int       id;      /* id as known in /dev/bitblt */
		    Bitmap*   cache;   /* zero; tells bitmap from layer */
	      } Bitmap;

       R.min is the location in the bitmap of the upper-leftmost point in the image.   There  are
       2^ldepth contiguous bits for each pixel of the image; the bits form a binary number giving
       the pixel value.  is the clipping rectangle; typically it is the same as  r  except  in	a
       window,	where it is inset by the width of the border.  Graphical operations on the Bitmap
       will be confined to the clipping rectangle.  The subroutine clipr sets the  clipping  rec-
       tangle  of  b  to  the intersection of cr and b->r.  If cr does not intersect b->r it does
       nothing.  Clipr returns 1 if the clipping region was set, 0 if it was not.

       A Font is a set of character images, indexed by runes (see utf(6)).  The images are  orga-
       nized into Subfonts, each containing the images for a small, contiguous set of runes.  The
       detailed format of these data structures, which are described in detail in  cachechars(2),
       is immaterial for most applications.  Font and Subfont structures contain two interrelated
       fields: the distance from the top of the highest character (actually the top of the bitmap
       holding	all the characters) to the baseline, and the distance from the top of the highest
       character to the bottom of the lowest character (and hence, the interline  spacing).   The
       width  of  any  particular  character  in  a  font is returned by charwidth.  The width is
       defined as the amount to add to the  horizontal	position  after  drawing  the  character.
       Charwidth  calls  the  graphics error function if r is zero (NUL) because string (see bit-
       blt(2)) cannot draw a NUL.  The other fields are used internally by the text-drawing func-
       tions; see cachechars(2) for the details.

       Rdfontfile  reads the font description in file name and returns a pointer that can by used
       by string (see bitblt(2)) to draw characters from the font.  The ldepth argument specifies
       how  characters	will  be  cached; it should usually be the ldepth of the bitmap that will
       most often be the target of string.  Ffree frees a font.  The convention for  naming  font
       files is:

	      /lib/font/bit/name/range.size.font

       where size is approximately the height in pixels of the lower case letters (without ascen-
       ders or descenders).  Range gives some indication of which characters will  be  available:
       for example ascii, latin1, euro, or unicode.  Euro includes most European languages, punc-
       tuation marks, the International Phonetic Alphabet, etc., but no Oriental languages.  Uni-
       code includes every character for which images exist on the system.

       A Cursor is defined:

	      typedef struct
	      Cursor {
		    Point offset;
		    uchar clr[2*16];
		    uchar set[2*16];
	      } Cursor;

       The  arrays  are arranged in rows, two bytes per row, left to right in big-endian order to
       give 16 rows of 16 bits each.  A cursor is displayed on the screen by adding offset to the
       current	mouse  position,  using clr as a mask to zero the pixels where clr is 1, and then
       setting pixels to ones where set is one.

       The function binit must be called before using any graphics operations.	The errfun  argu-
       ment is a function to be called with an error message argument when the graphics functions
       detect a fatal error; such an error function must not return.  A zero for the errfun spec-
       ifies  the  default  berror, which prints the message and exits.  If label is non-null, it
       will be written to /dev/label, so that it can be used to identify the window  when  hidden
       (see  81/2(1)).	Binit sets up the global screen to be a bitmap describing the area of the
       screen that the program can use.  This will be either the whole screen, or some portion of
       it  if  the  program  is running under a window system such as 81/2(1).	Binit also estab-
       lishes a font by reading the named font file.  If font is null, binit reads the file named
       in  the	environment  variable $font; if $font is not set, it imports the default (usually
       minimal) font from the operating system.  The global font will be  set  to  point  to  the
       resulting  Font	structure.   Another effect of binit is that it installs print(2) formats
       Pconv and Rconv as and for printing Points and Rectangles.

       Bclose closes the file descriptor connecting the application to the graphics server, typi-
       cally  for  use	by a child process that needs to disconnect from the graphics server.  It
       does not automatically flush pending output (see bflush, below).  Bclose is not needed  by
       most  programs.	 Bexit	completes  any	pending  graphics.  It is called automatically by
       exits(2).

       The screen.r field is not maintained across `reshape' events; use bscreenrect to  discover
       the current size (see event(2)); a non-null clipr will be filled in with the screen's clip
       rectangle.

       The mouse cursor is always displayed.  The  initial  cursor  is	an  arrow.   Cursorswitch
       causes  the argument cursor to be displayed instead.  A zero argument causes a switch back
       to the arrow cursor.  Cursorset moves the mouse cursor to position p, provided  (if  in	a
       window)	that  the  requesting program is executing in the current window and the mouse is
       within the window boundaries; otherwise cursorset is a no-op.

       The graphics functions described in bitblt(2), balloc(2), cachechars(2), and  subfalloc(2)
       are  implemented by writing commands to /dev/bitblt (see bit(3)); the writes are buffered,
       so the functions may not take effect immediately.  Bflush flushes the  buffer,  doing  all
       pending	graphics  operations.  Binit arranges that bflush will be called on exit, and the
       following functions all cause a flush:  balloc,	bfree,	bscreenrect,  cursorset,  cursor-
       switch,	ecankbd,  ecanmouse, ekbd, emouse, event, rdfontfile, subfalloc, ffree, rdbitmap,
       and wrbitmap.

       The rare program that needs to implement the /dev/bitblt protocol directly can  use  bneed
       and  bwrite.  Bneed returns a pointer to a place in the write buffer, allocating space for
       n bytes.  The buffer will be flushed first if n is zero, or the buffer is too full.  After
       filling	in bytes allocated with bneed, bwrite can be used to write everything in the buf-
       fer and reset the buffer pointer.  Unlike bflush, bwrite  does  not  call  the  registered
       error  function	and  so  can  be used when an error is possible and the error function is
       inappropriate.

FILES
       /lib/font/bit	directory of bitmap fonts

SOURCE
       /sys/src/libg

SEE ALSO
       add(2), balloc(2), cachechars(2), subfalloc(2), bitblt(2), event(2),  frame(2),	print(2),
       bit(3), layer(2), bitmap(6), font(6)

DIAGNOSTICS
       An error function may call errstr(2) for further diagnostics.

										      GRAPHICS(2)


All times are GMT -4. The time now is 12:53 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password