                        SVGAKIT for emx
                        ---------------


This SVGAKIT for emx is an extension of the fullscreen graphics library
of emx. Most of the functions contained in the graphics library for emx have
not been changed, so this documentation explains only new features of the
SVGAKIT. Refer to emx's libref.doc for full reference to the emx graphics
library.


1.  System Requirements:
------------------------

- emx 0.8h or later
- the emx VESA package (available from the same site as svgakit)
- graphic adapter supported by emx VESA package or standard vga


2.  Supported Video-Modes:
--------------------------

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


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

See Installation of the VESA package for emx first.

Unzip the package. All files should be extracted to \emx\jm\svgakit.1_6.
Type "make install" to compile the library (jmgraph.a) and the test programs.
After compilation the library will be copied to \emx\lib and the header file
jmgraph.h will be copied to \emx\include.

In prior versions of SVGAKIT the library was called graph.a and the header
file was called graph.h. If you installed any prior version of SVGAKIT you
may delete these files now or type "make oldinstall" to overwrite them with
jmgraph.a and jmgraph.h.

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

Run the small Targa-Viewer "TGAVIEW.EXE". Type "tgaview -h" for help on the
parameters.

Note: Some make utilities fail to install the svgakit properly.
      If this happens, try "make install2" or "make oldinstall2"
      instead of "make install" or "make oldinstall".
      However this requires the "cp" program. It is available with
      the gnu file utilities, available from ftp.cdrom.com.
      If you don't want to install the "cp" program you'll have to
      do the last installation steps yourself:
        copy jmgraph.h \emx\include
        copy jmgraph.a \emx\include
      or (instead of "make oldinstall")
        copy jmgraph.h \emx\include\graph.h
        copy jmgraph.a \emx\include\graph.a


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

In contrast to the original graphics library for emx, 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 themselves, it is not necessary for you to lock the
screen.  But if you do so, screen output will become much
faster. Remember, though, that it is not possible to switch from or to
your program while the 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 libref.doc:
---------------------------

Include the following passage in /emx/doc/libref.doc:

---cut here---
------------------------------------------------------------------------------
#include <jmgraph.h>                                             [emx/svgakit]

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

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

See also: g_setpal

------------------------------------------------------------------------------
#include <jmgraph.h>                                             [emx/svgakit]

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

         Copy contents of specified rectangle on screen to buf.

         In 16 color modes x0 must be a multiple of 8, x1 must
         be a multiple of 8 minus 1.

See also: g_imagesize, g_putimage

------------------------------------------------------------------------------
#include <jmgraph.h>                                             [emx/svgakit]

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 <jmgraph.h>                                             [emx/svgakit]

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 <jmgraph.h>                                             [emx/svgakit]

int g_memsize;

         Minimum buffer size to save graphics screen by g_save.

See also: g_restore, g_save

------------------------------------------------------------------------------
#include <jmgraph.h>                                             [emx/svgakit]

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

         Copy contents of buf to specified rectangle on screen.

         In 16 color modes x0 must be a multiple of 8, x1 must
         be a multiple of 8 minus 1.

See also: g_imagesize, g_getimage

------------------------------------------------------------------------------
#include <jmgraph.h>                                             [emx/svgakit]

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 <jmgraph.h>                                             [emx/svgakit]

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.

         In 16 color modes x0 and x2 must be a multiple of 8, x1 must
         be a multiple of 8 minus 1.

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

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

void g_restore (void *buf);

         Restore graphics screen from buffer.

See also: g_save, g_memsize

------------------------------------------------------------------------------
#include <jmgraph.h>                                             [emx/svgakit]

void g_save (void *buf);

         Save graphics screen to the buffer pointed to by buf. The
         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 <jmgraph.h>                                             [emx/svgakit]

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 <jmgraph.h>                                             [emx/svgakit]

int g_mode (int mode);

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

    When switching to text mode g_mode() always returns 0. When
    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 graph (use the -lgraph option) and vesa (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!
Version 1.6 (04/28/1993)
  - graph.h and graph.a renamed to jmgraph.h and jmgraph.a (optionally)
  - "make install2"/"make oldinstall2" uses now cp instead of copy
    (for compatibility with gnumake)
  - support for 16 color modes
  - bugs fixed
  - tgaview can now do color reduction (for 16- and 256-color modes)
    (not a very good algorithm..., does anyone know a better one?)


7.  Future plans:
-----------------

- include Matthias Burian's font package
  (this package is also available from ftp.cdrom.com, it still
   works with this new release of svgakit if you use
   "make oldinstall" to install svgakit).


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

Most of the code is taken from the original graphics library for emx,
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
