----------------------------------------------------------------------------
WordUp Graphics Toolkit 5.1 - VESA 2.0 Extension Library
January 4, 1997

Copyright 1997 Egerter Software
Written by Chris Egerter
----------------------------------------------------------------------------


Introduction
------------
This library replaces the old WGT VESA library and adds VESA 2.0 support
for linear frame buffers.  It also uses a new API which provides the same
commands for both VESA versions.

The main improvements you can get with this library are:
1. Linear frame buffer access (opposed to bank switched)
2. Faster SVGA commands
3. Flicker free page flipping
4. All WGT graphics commands work with the linear frame buffers


To use VESA 2.0, your card must support it natively or you can try
Scitech Software's Display Doctor (formerly UNIVBE).  Visit their web site
at http://www.scitechsoft.com for free trial versions.




Getting Started
---------------

Before you start using this library, you must have WGT 5.1.  You can get
the full uncrippled version from our web site, http://www.egerter.com,
or FTP it from x2ftp.oulu.fi /pub/msdos/programming/wgt
or any of the SimTel mirrors.

The WGTSVGA.LIB library is meant to completely replace the old wvesa_wc.lib.
You should not try to use any of your old VESA code.



The Basics
----------

The first thing you have to do is detect which VESA version is available.

  vesa_version = wvesa_detect ();

This will return:
   0 meaning no VESA is available.
   VESA_1 meaning VESA 1.2 is available
   VESA_2 meaning VESA 2.0 is available


The second step is to find the available modes by calling:

  wvesa_findmodeinfo ();

This will fill in the array of video mode attributes called VESAmodes.
It is defined as follows:

typedef struct {
  int mode_number;
  int width;
  int height;

  unsigned char bits;
  unsigned char linear;
  unsigned char available;
  unsigned char pages;
 } MODE_DESC;
MODE_DESC VESAmodes[256];

You can enable or disable a mode by setting the available field to 1 or 0.


Once you have the list of modes initialized, you can actually set the
video mode.  If your application allows for multiple resolutions you could
let the user choose one of the available video modes through a menu.
To set the mode, use:

  result = wvesa_setmode (width, height, bits, linear);

Linear is either 0 or 1, depending if a linear frame buffer is to be used.

If you try a mode using a linear frame buffer and the result is 0,
you can try initializing it without the linear buffer.



Once the video mode is initialized, you can use any graphics command
from WGT on the linear buffer.  You will have two screens to draw on,
called SVGA_FRONTBUFFER and SVGA_BACKBUFFER.  To set the active drawing
screen, use wvesa_setscreen.

When using a mode with a linear frame buffer under VESA 2.0, both screens
will be in video memory and page flipping is used to switch between them.

When using a mode without a linear frame buffer under VESA 1.2 or VESA 2.0,
the back buffer will be a large block allocated in system memory, and the
front buffer will be the actual video memory.  This video memory requires
bank switching and is accessed through the segment A000.  For this reason
not all WGT commands will work on the front buffer.  A number of basic
routines with the prefix "wvesa_" will work on the front buffer.  These
are provided for special applications save as graphical user interfaces
which require small portions of the screen to be updated quickly.

The page flipping/copying method is suited for applications where the frame
buffer is completely redrawn each frame, such as scrolling or 3D rendering.


Below is a listing of the new functions:




void wvesa_bar (int x, int y, int x2, int y2);
/* -----------------------------------------------------------------------
   Function:   wvesa_bar
   Purpose:    Draws a solid rectangle
   Parameters: x,y,x2,y2 - Rectangular region to fill
   Return:     None
   ----------------------------------------------------------------------- */


void wvesa_clip (int x, int y, int x2, int y2);
/* -----------------------------------------------------------------------
   Function:   wvesa_clip
   Purpose:    Sets the clipping region
   Parameters: x,y,x2,y2 - Rectangular clipping region
   Return:     None
   ----------------------------------------------------------------------- */


void wvesa_cls (short color);
/* -----------------------------------------------------------------------
   Function:   wvesa_cls
   Purpose:    Clears the entire screen
   Parameters: color - Color index
   Return:     None
   ----------------------------------------------------------------------- */


void wvesa_copyscreen (int x0, int y0, int x1, int y1, block src, 
                       int dx, int dy);
/* -----------------------------------------------------------------------
   Function:   wvesa_copyscreen
   Purpose:    Copies a section of the source block to the current screen.
   Parameters: x0,y0,x1,y1 - Rectangular region of source
               src - Pointer to the source block
               dx,dy - Top left corner of destination
   Return:     None
   ----------------------------------------------------------------------- */


int wvesa_detect (void);
/* -----------------------------------------------------------------------
   Function:   wvesa_detect
   Purpose:    Detects which version of VESA is installed 
   Parameters: None
   Return:     0, VESA_1, VESA_2
   ----------------------------------------------------------------------- */


void wvesa_findmodeinfo (void);
/* -----------------------------------------------------------------------
   Function:   wvesa_findmodeinfo
   Purpose:    Stores the information for the available video modes
               in the VESAmodes array
   Parameters: None
   Return:     None
   ----------------------------------------------------------------------- */


void wvesa_flip (int retrace);
/* -----------------------------------------------------------------------
   Function:   wvesa_flip
   Purpose:    Flips the display and active drawing pages 
   Parameters: retrace - Number of times to wait for the vertical retrace
   Return:     None
   ----------------------------------------------------------------------- */


unsigned char wvesa_getpixel (int x, int y);
/* -----------------------------------------------------------------------
   Function:   wvesa_getpixel
   Purpose:    Gets the color index of a single pixel
   Parameters: x,y - Coordinate of pixel
   Return:     Color index of pixel
   ----------------------------------------------------------------------- */


void wvesa_hline (int x, int x2, int y);
/* -----------------------------------------------------------------------
   Function:   wvesa_hline
   Purpose:    Draws a horizontal line
   Parameters: x,x2,y - Coordinates of line
   Return:     None
   ----------------------------------------------------------------------- */


void wvesa_line (int x, int y, int x2, int y2);
/* -----------------------------------------------------------------------
   Function:   wvesa_line
   Purpose:    Draws a diagonal line
   Parameters: x,y,x2,y2 - Endpoints of line
   Return:     None
   ----------------------------------------------------------------------- */


block wvesa_newblock (int x0, int y0, int x1, int y1);
/* -----------------------------------------------------------------------
   Function:   wvesa_newblock
   Purpose:    Copies a section of the screen to a new block
   Parameters: x0,y0,x1,y1 - Rectangular region of screen
   Return:     Pointer to the new block
   ----------------------------------------------------------------------- */


void wvesa_outtextxy (int x, int y, wgtfont fnt, char *printit);
/* -----------------------------------------------------------------------
   Function:   wvesa_outtextxy
   Purpose:    Prints a string with the given font
   Parameters: x,y - Top left corner of text
               fnt - Pointer to the font
               printit - Pointer to the string
   Return:     None
   ----------------------------------------------------------------------- */


void wvesa_printf (int x, int y, wgtfont font, char *fmt, ...);
/* -----------------------------------------------------------------------
   Function:   wvesa_printf
   Purpose:    Prints formatted text
   Parameters: x,y - Top left corner of text
               font - Pointer to the font
               fmt - Format string
               ... - parameters for format string
   Return:     None
   ----------------------------------------------------------------------- */


void wvesa_putblock (int x0, int y0, block src, int method);
/* -----------------------------------------------------------------------
   Function:   wvesa_putblock
   Purpose:    Pastes a block to the current screen
   Parameters: x0,y0 - Top left corner of the block on the destination screen
               src - Pointer to the source block
               method - NORMAL or XRAY
   Return:     None
   ----------------------------------------------------------------------- */


void wvesa_putpixel (int x, int y);
/* -----------------------------------------------------------------------
   Function:   wvesa_putpixel
   Purpose:    Draws a single pixel
   Parameters: x,y - Coordinate of pixel
   Return:     None
   ----------------------------------------------------------------------- */


void wvesa_rectangle (int x, int y, int x2, int y2);
/* -----------------------------------------------------------------------
   Function:   wvesa_rectangle
   Purpose:    Draws a hollow rectangle
   Parameters: x,y,x2,y2 - Rectangular region 
   Return:     None
   ----------------------------------------------------------------------- */


int wvesa_setpan (int x,int y, int waitVRT);
/* -----------------------------------------------------------------------
   Function:   wvesa_setpan
   Purpose:    Sets the top left corner of the display start address 
   Parameters: x,y - Position of top left corner of display
               waitVRT - 1 if wait for the vertical retrace, 0 otherwise
   Return:     1 if successful, 0 failed
   ----------------------------------------------------------------------- */


int wvesa_setmode (int width, int height, int bits, int linear);
/* -----------------------------------------------------------------------
   Function:   wvesa_setmode
   Purpose:    Finds the video mode and attempts to initialize it 
   Parameters: width  - Width of screen
               height - Height of screen
               bits   - bits per pixel
               linear - 1 if linear frame buffer is to be used, 0 otherwise
   Return:     1 if successful, 0 failed
   ----------------------------------------------------------------------- */


void wvesa_setscreen (int page);
/* -----------------------------------------------------------------------
   Function:   wvesa_setscreen
   Purpose:    Sets the active drawing page for linear frame buffers 
   Parameters: page - SVGA_FRONTBUFFER or SVGA_BACKBUFFER
   Return:     None
   ----------------------------------------------------------------------- */
