vgagl(7)               Svgalib User Manual               vgagl(7)

NAME
       vgagl  -  a  fast framebuffer-level graphics library based
       ion 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 lin-
       ear  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 communication
       (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 optional 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 associated graphics screen, how  it  is  organized,
       clipping status etc. You can define a custom virtual (sys-
       tem memory) graphics context of any size with the  setcon-
       textvirtual  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. Exam-
       ple:

              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_set-
       contextvgavirtual(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_get-
              palette(3)
              read the color palette.
       gl_setpalettecolor(3), gl_setpalettecolors(3), gl_set-
              palette(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  con-
              text.

       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 possi-
       ble 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 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(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_copyboxfrom-
       context(3),    gl_copyboxtocontext(3),   gl_copyscreen(3),
       gl_disableclipping(3),               gl_enableclipping(3),
       gl_enablepageflipping(3), gl_expandfont(3), gl_fillbox(3),
       gl_font8x8(3), gl_freecontext(3), gl_getbox(3), gl_getcon-
       text(3),  gl_getpalette(3), gl_getpalettecolor(3), gl_get-
       palettecolors(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_rgb-
       color(3), gl_scalebox(3), gl_setclippingwindow(3), gl_set-
       context(3),  gl_setcontextheight(3),  gl_setcontextvga(3),
       gl_setcontextvgavirtual(3),       gl_setcontextvirtual(3),
       gl_setcontextwidth(3),   gl_setdisplaystart(3),    gl_set-
       font(3),  gl_setfontcolors(3),  gl_setpalette(3),  gl_set-
       palettecolor(3),  gl_setpalettecolors(3),  gl_setpixel(3),
       gl_setpixelrgb(3),  gl_setrgbpalette(3),  gl_setscreenoff-
       set(3), gl_setwritemode(3),  gl_striangle(3),  gl_swtrian-
       gle(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>  who  cur-
       rently  maintains svgalib.  The original documentation and
       most  of  vgagl  was  done  by  Harm  Hanemaayer  <H.Hane-
       maayer@inter.nl.net> though.

Svgalib (>= 1.2.11)         2 Aug 1997                          1