                        SVGAKIT for emx/gcc
                        -------------------

This SVGAKIT for emx/gcc is an extension of the fullscreen graphics library
of emx. All functions contained in the graphic library for emx don't have
changed, so this documention explains only new features of the SVGAKIT. Refer
to emxdev.doc for full reference to the emx graphics library.


1.System Requirements:
----------------------
- emx/gcc
- the emx VESA-package (available from same site as svgakit)
- graphic adapter supported by emx VESA-package or standard vga


2.Supported Video-Modes:
------------------------
All 256, 32k, 64k and 16m-Color modes supported by the emx VESA-package
should work.

16 color modes are not supported.


3.Installation:
---------------

See Installation of the VESA-package for emx first.

Unzip the package. All files should be extracted to \emx\jm\svgakit.n_n,
where n_n is the Version number of SVGAKIT.
Type "make install" to compile and install the library (graph.a) and the
test programs. Note that this will replace \emx\include\graph.h and
\emx\lib\graph.a by svgakit versions.

Run "GRAPH.EXE". Type "graph -h" for help on the parameters.

If your graphics card support Hi/True-Color modes run the small Targa-
Viewer "TGAVIEW.EXE". Type "tgaview -h" for help on the parameters.


4.Running Programs in Background and a Word on Screen Locking (OS/2 only):
--------------------------------------------------------------------------

In contrast to the original graphics library for emx/gcc, it is now possible
to access the display, when your program is executed in background. SVGAKIT
holds the display memory in a virtual display buffer, when the program is in
background.
In addition, SVGAKIT installs its own screen locking functions. If you called
g_lock(), it is not possible to switch to the program or from the program to
another program, unless you call g_unlock().
If you called g_lock() in the original graphics library, the program stopped,
until you switched it into foreground and you could not switch back, unless
you called g_unlock().

Because all functions in this package, that require a locked screen, lock the
screen themselfes, it is not necessary for you to lock the screen.
But if you do so, screen output will become much faster. But, remember, it is
not possible to switch from or to your program, while screen is locked. So
do not lock the screen for more than a few seconds.

If you install a virtual screen using g_virtual(), the physical screen is
automatically unlocked. If you call g_refresh() to update the physical
screen, the physical screen is locked for the time of the update process.
Calling g_real() to remove the virtual screen locks the physical screen,
if you called g_lock() any time before (without calling g_unlock()).


5.Addition to emxdev.doc:
-------------------------

Include the following passage to emxdev.doc:

---cut here---
------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_getpal(char *pal, int first, int n)

         Get palette entries from first to (first + n - 1).

See also: g_setpal

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_getimage(int x0, int y0, int x1, int y1, char *buf)

         Copy contents of specified rectangle on screen to buf.

See also: g_imagesize, g_putimage

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

int g_imagesize(int width, int height)

         Returns how much memory (in bytes) is needed to copy
         a rectangle of specified width and height.

See also: g_getimage, g_putimage

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

int g_init(void)

         Initialize the vesa_emx-Library. This is automatically
         done when first calling a vesa function. However, you
         may want to initialize the library when your programs
         starts or some other time.

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

int g_memsize;

         Minimum buffer size to save graphics screen by g_save.

See also: g_restore, g_save

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_putimage(int x0, int y0, int x1, int y1, char *buf)

         Copy contents of buf to specified rectangle on screen.

See also: g_imagesize, g_getimage

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_real (int copy_buf, int copy_pal);

         Removes the virtual screen (and palette in 256 color modes)
         installed by g_virtual. If copy_buf != 0 then copy the contents
         of the virtual screen to the physical screen. If copy_pal != 0
         copies the virtual palette to the physical palette. All drawing
         commands now act on the physical screen.

See also: g_refresh, g_virtual
------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_refresh (int x0, int y0, int x1, int y1, int x2, int y2, int pal);

         Updates a part of the physical screen with the contents of the
         virtual screen. (x0,y0)-(x1,y1) specify a rectangle in the
         virtual screen to be copied to (x2,y2) in the physical screen.
         If pal != 0 the physical palette is updated with the virtual
         palette.

         Note that this function doesn't take care on clipping.

See also: g_real, g_virtual
------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_restore (void *buf);

         Restore graphics screen from buffer.

See also: g_save, g_memsize

------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_save (void *buf);

         Save graphics screen to buffer. Buffer has to be large enough
         to hold all graphics information (minimum buffer size is stored
         in g_memsize).

See also: g_restore, g_memsize
------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

void g_virtual (int copy_buf, int copy_pal);

         Install a virtual screen (and palette in 256 color modes).
         If copy_buf != 0 then copy the contents of the physical screen
         to the virtual screen. If copy_pal != 0 then copy the physical
         palette to the virtual palette. All drawing commands now act
         on the virtual screen until g_real or g_mode is called.

See also: g_real, g_refresh
---cut here---

Change the reference for g_mode(), g_unlock() and g_unlockall() in libref.doc:
---cut here---
------------------------------------------------------------------------------
#include <graph.h>                                                       [emx]

int g_mode (int mode);

    Select graphics mode. mode is the VESA mode number of the graphics
    mode to select. In "graph.h" there are defined several aliases for
    the common VESA mode numbers. Because the supported graphic modes
    differ between the different graphic adapters you should let the
    user choose a graphic mode via command line switch.

    If switching to text mode, always 0 is returned. If switching to
    graphics mode, 1 is returned on success else 0.

    The global variables g_xsize, g_ysize, g_colors and g_memsize are
    set.  The clipping rectangle is set to the entire screen.

    General information about the graphics library: Programs using the
    graphics library work both under DOS and in OS/2 full-screen
    sessions.  The coordinates of the screen are (0,0) (upper left)
    through (g_xsize-1,g_ysize-1) (lower right).  You have to link
    with libgraph (use the -lgraph option) and libvesa (use the -lvesa
    option).
    Under DOS, emx option acim is required, see `Using emx options'.

    Example: /emx/test/graph.c

    See also: g_clip(), g_modeset(), g_colors, g_xsize, g_ysize
------------------------------------------------------------------------------
void g_unlock (int modified);
void g_unlockall (int modified);

    Unlock the screen.  g_unlock() undoes one invocation of g_lock()
    by decrementing the counter incremented by g_lock().  If the
    counter reaches zero, the screen is unlocked.  If the counter
    already was zero, the counter is not changed.  g_unlockall()
    undoes all invocations of g_lock() by resetting the counter to
    zero and unlocking the screen if the counter was non-zero.

    Set modified to 1, if you modified the contents of your screen since
    the last call to g_lock(), else set modified to 0.

    See also: g_lock()

------------------------------------------------------------------------------
---cut here---


6.History:
----------
Version 1.0:
  - initial release
Version 1.1 (04/03/1993):
  - added DOS/VESA support
  - put SVGA card relevant stuff in DLL's (now in emx VESA-package)
    to keep it away from other code
  - added support for variable scanline length
Version 1.2 (04/13/1993):
  - added support for non bios standard vga modes
    (320x240x256, 320x400x256, 320x480x256)
  - added functions g_getimage, g_imagesize and g_putimage
Version 1.3 (05/14/1993)
  - bug fixes to support graphics adapters with a single memory
    window for both read and write operations
    (such as trident 8900)
  - changed makefile for compatibilty with any (?) make
  - added virtual screen support (g_virtual, g_refresh, g_real)
Version 1.4 (06/23/1993)
  - fixed some bugs:
    - switching session by CTRL-ESC made the program dump its core
      after a call to g_mode(GMODE_VGA_OFF) (OS/2 only).
    - palette manipulation was not possible (DOS only).
    - case of different window-size and -granularity was
      handled wrong.
Version 1.5 (12/20/1993)
  - adjusted to run with emx 0.8h and vesa_emx 1.5.
    Note that g_unlock() and g_unlockall() have been changed!


7.Future plans:
---------------
- support 16 color and mono modes
- include Matthias Burian's font package
  (this package is also available from ftp.cdrom.com, it still
   works with this new release of svgakit).


8.License and Copying:
----------------------

Most of the code is taken from the original graphics library for emx/gcc,
so it is copyright by Eberhard Mattes. Refer to copying.emx (included in
the emx package) for further information.
The other code is copyright Johannes Martin. It is to be used and copied
under the same conditions as the rest of the package, so look at
copying.emx again...


9.Thanks:
---------
Thanks to all who reported bugs and helped to correct them.


10.Author:
----------

Johannes Martin                  Internet: JMARTIN@GOOFY.ZDV.UNI-MAINZ.DE
Pfarrer-Dorn-Strae 25
D-55127 Mainz Marienborn
Germany
