This file is a short documentation of all functions and types contained in
the library. To understand how they work, check out and play arround with 
the sample programs and view the library source files, they contain more
detailed information.


error.cpp + error.h  
  general: A global error handler class is defined. You should call 
           ErrorHandler.Abort(char *) instead of exit(), abort() or similar
           function.
  functions:
    ErrorHandler.Abort(char *) - print all debug strings that are on the
      stack, execute the clean up procedures, and exit(3).
    ErrorHandler.EnterCriticalSection(char *) 
      Push a debug string. All strings on the debug string stack are shown
      if ErrorHandler.Abort() is called. Perhaps you find it useful. 
      (sample in fadeanim.cpp)
    ErrorHandler.LeaveCriticalSection() 
      pop the formerly pushed debug string.
    ErrorHandler.AddCleanUpProc() and .RemoveCleanUpProc()
      similar to standard atexit.

mem.cpp + mem.h
  general: mem allocation with heap checking (debugging help) for "new" 
      and "delete"
  defines: HEAPCHECK - allows heap checking, this slows down your program,
      but it is very useful for debugging. (for instance if a function
      overwrites an array and therefore the heap crashes)
  functions: 
    operator new - checks always if the allocation is successful, 
      if not -> abort
    HeapCheck() - aborts the program if the heap is corrupt.

palette.cpp + palette.h
  general:
    The library uses a type called ColorRef to reference colors.
    A color ref is even an RGB value or a palette index. RGB values are
    global, and palette indexes are only appliable to one palette.
    Palettes are used by bitmaps and by the video driver. Two bitmaps 
    are 'compatible' if they use the same palette. Operations with compatible
    bitmaps are fastest, because no color mapping is necessary.
  functions:
    type ColorRef:
      ColorRef RGB8(int r,int g,int b) -
        create a ColorRef to this 8 bit RGB value (0<=val<=255.
      int ColorRefType(ColorRef) -
        returns the type of this color ref, either CRRGB8 or CRPaletteIndex
      int RGB8Red(ColorRef) - returns the brightness value for red
      int RGB8Green,Blue - the same
    class Palette:
      Palette(ClassID,colors) - constructor, see palette.h for details
      void SetColor(ColorRef PaletteIndex,ColorRef RGBValue) - clear
      ColorRef GetColor(ColorRef PaletteIndex)
      GetPaletteIndex(ColorRef RGB) - return the palette index that is 
        nearest to the given rgb value
bitmap.cpp + bitmap.h
  general: Bitmaps are the base of the graphic library: off screen 
    buffer(s) are bitmaps, images that you load from disk are bitmaps.
    The library supports 2color,256color,HiColor and TrueColor bitmaps.
  functions:
    class Bitmap 
      Bitmap() - creates an invalid bitmap that may be constructed later
        using Construct()
      Bitmap(int w,int h,Bitmap::Class classID) -
        create a bitmap of this size and this class (see bitmap.h) with a 
        standard palette (for bitmaps with <=256 colors color 0 is black,
        the other colors are white)
      operator = - the destination bitmap is first deleted, and then
        reconstructed identically to the source bitmap. Both use the same
        palette.
      Delete() - free the allocated bitmap mem and invalate the bitmap
      UsePalette(Palette &Pal) - use the given Palette. Used to create
        'compatible' palettes. (see all samples)
      SetPixel(int x,y,ColorRef c) - c is the palette index.
      ColorRef GetPixel(x,y) - returns the palette index.
      SetPixelRGB(int x,y,ColorRef c) - c is a RGB value created by 
        RGB8(r,g,b)
      GetPixelRGB(int x,y) - return RGB-value
        = { return Bitmap.Palette().GetColor(Bitmap.GetPixel(x,y)); }
      SetPixelRGB(..)
      int IsValid(),Width(),Height(),Planes(),BitsPerPixel(),
        WidthBytes(),PlaneBytes(),ImageBytes() - clear
      Class ClassID() - return classID, e.g. PackedPixel8
      Palette() - return a reference to the used palette
  (see all samples and bitmap.h)

vesadrv.h + vesadrv.cpp + vesablt.cpp
   general: functions for setting the video mode (VGA+VESA) and for
     copying rectangular part of bitmap (=off screen buffers) onto the
     screen. The driver is automatically (de)installed if vesadrv.cpp is
     included in the project.
   #defines:
     VIDEOSUPPORT_PP8L   - include the function that copies bitmaps to 
                         PackedPixel8 (256 color) Linear Screens (mode 13h)
     VIDEOSUPPORT_PP8W   - support PackedPixel8 Windowing modes (256col SVGA)
     VIDEOSUPPORT_DC1555 - support DirectColor1555 (32k colSVGA)
     VIDEOSUPPORT_DC565  -  " 64k SVGA
     VIDEOSUPPORT_DC888  -  " 16M SVGA
       If you don't include a mode, you can't blit bitmaps into a screen that
       uses this mode, but you save some memory.
   func: 
     int Video.IsVGASupported(),IsVESASupported
     int Video.SupportedModes() - return number of supported modes (vga+vesa)
     int Video.SupportedMode(int index) - 0<=index<SupportedModes() returns
       the index of an available VESAMode
     int Video.IsSupportedMode(int vesamodeid) - return 0 if mode is not 
       supported (vesa mode ids are defined in vesadrv.h)
     int Video.CurrentMode()
     Palette Video.Palette() - return the active palette (e.g. for creating
       compatible bitmaps, or for changing video colors,fading,palette
       cycling ... )
     int Video.Width(),Video.Height() - info
     Bitmap::ClassID Video.ClassID() - return id for creating compatible bitmaps
     Video.BlitToScreen(destx,desty,Bitmap&,Rect &SrcRect) - interface to bitmap
       objects (used to show off screen buffers)

keyboard.cpp + keyboard.h
  general: provides you with functions that tell whether a key is pressed or
    not. The driver is automatically (de)installed  if keyboard.cpp is added 
    to your project. Stdlib getch() is disabled (the system will hang if you 
   call it) because of speed reasons and the nerving beep sound if the key buffer
   is full.
  functions:
    int Keyboard.GetKey() - replaces getch(), the difference is, that it returns
      nil if no key is pressed. Extended keys are returned like described
      in keyboard.h (extended KeyCodes)
    Keyboard.IsPressed(int c) .WasPressed(int c) - 
      c is either a keycode or a scancode, see keyboard.h

mouse.cpp + mouse.h
   general: basic mouse driver with automatic (de)installation if mouse.cpp
     is included. I didn't add a function for showing the mouse pointer,
     because you may want some special behaviour like animated pointers or
     so. Besides you may want to use an off screen buffer, so rather write 
     your own little mouse pointer function. (Use the GetX,GetY interface,
     load a mouse pointer bitmap from a file and show it via a call to
     CopyRectMasked)
   functions:
      int GetX,GetY,SetX,SetY - clear
      int GetButton - combination of LeftButton,RightButton,MidButton
      SetVirtualWindow(int width,height) - sets the max x and y coordinates
        set are to  be returned by GetX and GetY.

blit.h + fillrect.cpp + copyrect.cpp + copyrecm.cpp + copyrecs.cpp +
   copyrecc.cpp (+ rect.h)
   general: functions for filling,copying, stretching,masking,converting rectangular
     parts bitmap.
   functions: see blit.h and the sample source

font.cpp + font.h
  general: 2color text with run length encoded chars (pretty fast)
  functions:
    class Font:
      Load(char *pcxfilename) - fonts are saved as pcx files (makes easy 
        modification possible), watch the sample fonts (256 chars in a row),
        automatic size detection.
      int CharWidth(char),CharHeight(char),StringWidth(char*),StringHeight(*);
    TextOut - see font.h    

imageio.h + pcxload.cpp + pcxsave.cpp
  general: load a pcxfile into a bitmap-object, or save a bitmap-object

fade.h + fade.cpp [+timer.cpp]
  general: timer controlled fading
  functions:
    class PaletteFader
      PaletteFader(Palette &Pal) - create a fader for this palette
      ~PaletteFader() - restores original color values
      int IsRunning() - 0 if the fading process is already done
      int Brightness() - get actual brightness value >=0 <256 (0 is black,
        256 original colors)
      Brightness(int 0<=b<=256) - set brightness level manually
      FadeOut(int millisecs) - start fading from actual state to black
      FadeIn(int millisecs) - start fading from actual state to original state
timer.h + timer.cpp
  general: timer support, automatically (de)installed.
    AlarmTimer class allows you to run scheduled 'threads' (for instance for
    timer controlled fading/scrolling)
  functions:
    long SystemTimer.Time() - get time since the program started in millisecs
    int SystemTimer.TimeVal() - get the millisecs between two interrupts
    SystemTimer.TimeVal(int diff) - set the timer resolution  to so many 
      millisecs. The starting (DOS) resolution is about 13 ticks per second
      = 76 milliseconds. 20 millisecs are recommended (=50 ticks per second)
    class AlarmTimer (see sample fade.cpp/fade.h)
      virtual void TimerHandler(int MissedCalls) - overload.
        This routine is called by the interrupt handler whenever the next
        alarm time index is reached. 
      Start(int SystemTime) - The first interuption occurs at this time index
      Start() - start the first interruption after TimeVal() millisecs 
        from now on
      Stop() 
      int IsRunning() - info flag
      TimeVal(int millisecs) - time between two interrupts
      TimeVal() - info

template.h
  functions:
    Abs,Max,Min,Swap (see there)

dynarray.h + stack.h
  general: template classes for dynamic arrays and stacks
  functions: see there

line.h + line.cpp
  DrawLine

fillpoly.cpp + scanpoly.cpp + blitpoly.h
  FillPoly(Bitmap &Dst,Polygon &Poly,ColorRef Color)





general graphic library #defines (include *.def with the 'force include' 
project option + see the demos for example)
  #define ACCEL_<classID> - includes all accelerated functions for the desired,
                           modeID is a short cut for the Bitmap::Class:
                             PL1    - Planar1 = 1color
                             PP8    - PackedPixel8 = 256col
                             DC1555 - DirectColor 32K col
                             DC565  - DirectColor 64K col
                             DC888  - DirectColor 16M col
                           e.g. ACCEL_PP8 includes 256 color accelerated functions
                           If you don't include this, the slower general functions 
                           are used.
  #define ACCEL_<func_name>_<classID1><classID2>...<classIDn>
                          - include a special accelerated function 
                           <func_name> that is applied to <classID1..n> 
                           bitmaps.
                           e.g. ACCEL_CopyRectMasked_PP8PL1 is the 
                           accelerated function that copies PL1 bitmaps 
                           into PP8 bitmaps. (if not defined,
                           the slow general function is used)
  see the demos and sources for details


Kjell Schubert unbu@rz.uni-karlsruhe.de
