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 hardware communica-
     tion (the library is included in the svgalib shared image).

     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  memory
     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  sup-
     ported) in some situations.

     A	graphics  context is just a structure that holds the size of the associ-
     ated graphics screen, how it is organized, clipping status etc. You can de-
     fine 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 framebuffer 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  pixels
     cross  a  SVGA segment boundary. This should be correctly handled	 by most
     functions, but you never know. It can be avoided by using a  logical  scan-
     line  length  that  is a divisor of 65536 (a power of 2), like 1024 (as op-
     posed 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), currentcontext(3),
     gl_allocatecontext(3),  gl_circle(3),  gl_clearscreen(3),	gl_colorfont(3),
     gl_compileboxmask(3),  gl_compiledboxmasksize(3),	gl_copybox(3),	gl_copy-
     boxfromcontext(3),  gl_copyboxtocontext(3),  gl_copyscreen(3),  gl_disable-
     clipping(3),   gl_enableclipping(3),  gl_enablepageflipping(3),  gl_expand-
     font(3),  gl_fillbox(3),  gl_font8x8(3),  gl_freecontext(3),  gl_getbox(3),
     gl_getcontext(3),	gl_getpalette(3),  gl_getpalettecolor(3), gl_getpalette-
     colors(3),  gl_getpixel(3),  gl_getpixelrgb(3),  gl_hline(3),   gl_line(3),
     gl_putbox(3), gl_putboxmask(3), gl_putboxmaskcompiled(3), gl_putboxpart(3),
     gl_rgbcolor(3),  gl_scalebox(3), gl_setclippingwindow(3), gl_setcontext(3),
     gl_setcontextheight(3),  gl_setcontextvga(3),   gl_setcontextvgavirtual(3),
     gl_setcontextvirtual(3),	 gl_setcontextwidth(3),   gl_setdisplaystart(3),
     gl_setfont(3),   gl_setfontcolors(3),   gl_setpalette(3),	  gl_setpalette-
     color(3),	  gl_setpalettecolors(3),   gl_setpixel(3),   gl_setpixelrgb(3),
     gl_setrgbpalette(3), gl_setscreenoffset(3), gl_setwritemode(3),  gl_strian-
     gle(3),	gl_swtriangle(3),    gl_triangle(3),	gl_trigetcolorlookup(3),
     gl_trisetcolorlookup(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)

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

home | help