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

FreeBSD Manual Pages

  
 
  

home | help
vgagl(7)		      Svgalib User Manual		      vgagl(7)

NAME
       vgagl - a fast framebuffer-level	graphics library based on svgalib

TABLE OF CONTENTS
       0. Introduction
       1. How to use vgagl
       2. Description of vgagl functions
       3. Macros defined in vgagl.h

0. INTRODUCTION
       This  is	 a  fast framebuffer-level graphics library for	linear 1, 2, 3
       and 4 byte-per-pixel modes (256-color, hicolor, truecolor). It  uses  a
       limited	number	of functions from svgalib (libvga) for low-level hard-
       ware communication (the library is included in the svgalib  shared  im-
       age).

       In  particular,	svgalib(7)  maps  the 64K VGA frame buffer window, and
       this library directly addresses the buffer. For	SVGA  modes  that  use
       more than 64K of	screen memory, SVGA paging is required when writing to
       the physical screen; this is done automatically for most	functions  (at
       a certain cost).

       Alternatively, any number of virtual screens of any type	in system mem-
       ory can be used,	which can then be copied to the	physical screen. There
       is also support for 4 bytes per pixel framebuffers (and copying them to
       a 3 bytes per pixel context), and limited planar	256 color mode support
       (copyscreen, aligned putbox).

       The planar 256 color modes (available on	all VGA	cards) can now be used
       with a virtual screen, which is copied to the physical screen (with op-
       tional page-flipping).

       Bitmaps	are  raw,  with	one (or	more) bytes per	pixel (like pixmaps in
       X), stored in row-major order. They are usually	manipulated  with  the
       getbox and putbox functions.

       vgagl  does  also  make	use of the graphic cards accelerator (if it is
       supported) in some situations.

       A graphics context is just a structure that holds the size of the asso-
       ciated  graphics	 screen, how it	is organized, clipping status etc. You
       can define a custom virtual (system memory)  graphics  context  of  any
       size  with  the	setcontextvirtual function. All	operations work	on the
       current context.

       Any questions, bug-reports, additions, suggestions etc. are welcome.

1. HOW TO USE VGAGL
       Programs	that use vgagl must #include <vgagl.h>.	 Linking must be  done
       with -lvgagl -lvga.

       Functions  in  the  vgagl  library have the prefix gl_*.	 To initialize
       vgagl, the graphics context must	be set.	Example:

	      vga_setmode(G320x200x256);
	      gl_setcontextvga(G320x200x256);

       In this example,	the context is set to the physical screen. The context
       can  be saved (only the screen type, not	the contents) into a variable,
       e.g.

	      GraphicsContext physicalscreen;
	      gl_getcontext(&physicalscreen).

       To define a virtual screen in system memory,  use  gl_setcontextvgavir-
       tual(3):

	      gl_setcontextvgavirtual(G320x200x256)

       which  allocates	 space	for a screen identical to 320x200x256 graphics
       mode, and makes this virtual screen the current graphics	context.

       The virtual screen can now be copied to the physical screen as follows:

	      gl_copyscreen(&physicalscreen);

       Note that with a	virtual	screen in system memory, it is possible	to add
       fast  X-Window  support	to  a program, using MITSHM to copy the	frame-
       buffer to the screen window.

2. DESCRIPTION OF VGAGL	FUNCTIONS
   Context management
       gl_getcontext(3), currentcontext(3)
	      get the current graphics contents..
       gl_setcontext(3)
	      set a previously saved context.
       gl_setcontextvga(3)
	      set the context to the physical screen.
       gl_setcontextvgavirtual(3)
	      set the context to a virtual mode.
       gl_setcontextvirtual(3)
	      define a virtual context.
       gl_allocatecontext(3)
	      allocate a graphics context.
       gl_freecontext(3)
	      free a virtual screen.
       gl_setcontextwidth(3), gl_setcontextheight(3)
	      set the dimension	of a context.

   Drawing primitives
       gl_clearscreen(3)
	      clear the	screen.
       gl_rgbcolor(3)
	      return pixel value corresponding to an rgb color.
       gl_setpixel(3), gl_setpixelrgb(3)
	      draw a pixel.
       gl_getpixel(3)
	      return the color of a pixel.
       gl_getpixelrgb(3)
	      store color components of	a pixel.
       gl_hline(3)
	      draw a horizontal	line.
       gl_line(3)
	      draw a line.
       gl_circle(3)
	      draw a circle.
       gl_fillbox(3)
	      fill a rectangular area.

   Copying of screen buffers and page flipping
       gl_copyscreen(3)
	      copy the screen contents of contexts.
       gl_setscreenoffset(3)
	      set a memory offset for copyscreen.
       gl_setdisplaystart(3)
	      set the start of the screen are displayed.
       gl_enablepageflipping(3)
	      enables automatic	page flipping.

   Clipping
       gl_disableclipping(3)
	      disables clipping.
       gl_enableclipping(3)
	      enables clipping.
       gl_setclippingwindow(3)
	      set the clipping window.

   Text	drawing	primitives
       gl_setfont(3)
	      set the text font	to be used.
       gl_setfontcolors(3)
	      set the font colors.
       gl_expandfont(3)
	      expand a packed pixel font.
       gl_colorfont(3)
	      change the color of a font.
       gl_setwritemode(3)
	      set the font writemode flags.
       gl_write(3), gl_writen(3)
	      write a text string.
       gl_printf(3)
	      formatted	output to the graphics screen.
       gl_font8x8(3)
	      a	packed 8x8 pixel font.

   Pix-	and Bitmap drawing
       gl_getbox(3)
	      copy a rectangular pixmap	from the screen	to a buffer.
       gl_copybox(3)
	      copy a rectangular screen	area.
       gl_copyboxfromcontext(3)
	      copy rectangular area from another context.
       gl_copyboxtocontext(3)
	      copy a rectangular area to another context.
       gl_putbox(3)
	      copy a pixmap to a rectangular area.
       gl_putboxpart(3)
	      copy a partial pixmap to a rectangular area.
       gl_putboxmask(3)
	      copy a masked  pixmap to a rectangular area.
       gl_putboxmaskcompiled(3)
	      copy a compiled masked pixmap to a rectangular area.
       gl_compileboxmask(3)
	      compress a masked	bitmap.
       gl_compiledboxmasksize(3)
	      compute the size of a compiled masked box.
       gl_scalebox(3)
	      scale a pixmap.

   Palette handling
       gl_getpalettecolor(3), gl_getpalettecolors(3), gl_getpalette(3)
	      read the color palette.
       gl_setpalettecolor(3), gl_setpalettecolors(3), gl_setpalette(3)
	      set the color palette.
       gl_setrgbpalette(3)
	      set a 256-color RGB palette.

   Triangle primitives from threeDkit
       gl_striangle(3)
	      draw a solid colored triangle.
       gl_triangle(3)
	      draw a triangle with interpolated	colors.
       gl_swtriangle(3)
	      draw a solid pixmap mapped on a triangle.
       gl_wtriangle(3)
	      draw a shadowed pixmap mapped on a triangle.
       gl_trisetcolorlookup(3),	gl_trigetcolorlookup(3)
	      manages a	color lookup table for shadowing.
       gl_trisetdrawpoint(3)
	      set a triangle drawing function.

3. MACROS DEFINED IN VGAGL.H:
       WIDTH  The width	in pixels of the current graphics context.

       HEIGHT Height in	pixels.

       BYTESPERPIXEL
	      Number of	bytes per pixel	(1, 2, 3 or 4).

       BYTEWIDTH
	      Width of a scanline in bytes.

       COLORS Number of	colors.

       BITSPERPIXEL
	      Number of	significant color bits.

       VBUF   Address of the framebuffer.

       __clip Clipping flag.

       __clipx1
       __clipy1
	      Top-left corner of clipping window.

       __clipx2
       __clipy2
	      Bottom-right corner of clipping window.

BUGS
       For three bytes per pixel (true color) modes, it	is possible that  pix-
       els  cross  a  SVGA  segment  boundary.	This  should be	correctly han-
       dled   by most functions, but you never know. It	can be avoided by  us-
       ing  a  logical	scanline length	that is	a divisor of 65536 (a power of
       2), like	1024 (as opposed to 960)  for  320x200	and  2048  (1920)  for
       640x480.	 For  800x600,	this  is  impractical (4096 as opposed to 2400
       doesn't fit in 2MB). Alternatively, avoid those functions  by  using  a
       virtual screen.

SEE ALSO
       svgalib(7),   libvga.config(5),	testgl(6),  threedkit(7),  currentcon-
       text(3),	  gl_allocatecontext(3),   gl_circle(3),    gl_clearscreen(3),
       gl_colorfont(3),	   gl_compileboxmask(3),    gl_compiledboxmasksize(3),
       gl_copybox(3),	 gl_copyboxfromcontext(3),     gl_copyboxtocontext(3),
       gl_copyscreen(3),  gl_disableclipping(3),  gl_enableclipping(3),	gl_en-
       ablepageflipping(3),  gl_expandfont(3),	gl_fillbox(3),	gl_font8x8(3),
       gl_freecontext(3),  gl_getbox(3),  gl_getcontext(3),  gl_getpalette(3),
       gl_getpalettecolor(3), gl_getpalettecolors(3), gl_getpixel(3),  gl_get-
       pixelrgb(3),  gl_hline(3),  gl_line(3), gl_putbox(3), gl_putboxmask(3),
       gl_putboxmaskcompiled(3), gl_putboxpart(3),  gl_rgbcolor(3),  gl_scale-
       box(3),	  gl_setclippingwindow(3),   gl_setcontext(3),	 gl_setcontex-
       theight(3), gl_setcontextvga(3),	gl_setcontextvgavirtual(3), gl_setcon-
       textvirtual(3),	gl_setcontextwidth(3),	gl_setdisplaystart(3), gl_set-
       font(3),	gl_setfontcolors(3), gl_setpalette(3),	gl_setpalettecolor(3),
       gl_setpalettecolors(3),	gl_setpixel(3),	 gl_setpixelrgb(3), gl_setrgb-
       palette(3), gl_setscreenoffset(3), gl_setwritemode(3), gl_striangle(3),
       gl_swtriangle(3),  gl_triangle(3),  gl_trigetcolorlookup(3), gl_triset-
       colorlookup(3),	 gl_trisetdrawpoint(3),	  gl_write(3),	 gl_writen(3),
       gl_wtriangle(3).

AUTHOR
       There  are  many	 authors  of  svgalib. This page was edited by Michael
       Weller <eowmob@exp-math.uni-essen.de>.  The original documentation  and
       most  of	 vgagl was done	by Harm	Hanemaayer <H.Hanemaayer@inter.nl.net>
       though.

Svgalib	(>= 1.2.11)		  2 Aug	1997			      vgagl(7)

NAME | TABLE OF CONTENTS | 0. INTRODUCTION | 1. HOW TO USE VGAGL | 2. DESCRIPTION OF VGAGL FUNCTIONS | 3. MACROS DEFINED IN VGAGL.H: | BUGS | SEE ALSO | AUTHOR

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

home | help