Provided by: libsvga1_1.4.3-29_i386 bug

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 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 (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_setcontextvgavirtual(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 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),
       currentcontext(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_enablepageflipping(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_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_setpalettecolor(3),      gl_setpalettecolors(3),     gl_setpixel(3),
       gl_setpixelrgb(3),     gl_setrgbpalette(3),      gl_setscreenoffset(3),
       gl_setwritemode(3),  gl_striangle(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.