                        VESA-package for emx/gcc
                        ------------------------

This is a package that enables emx-programs to call the VESA Bios-Extensions
under DOS. It also supplies some drivers for doing fullscreen and windowed
graphics under OS/2.
The svgakit for emx uses this package and implements some higher level
graphics routines. It should be stored on the same sites as this package.


1.Installation:
---------------
- Unzip the package. All files should be extracted to /emx/jm/vesa.1_5
- Type "make install" and wait until compilation and installation has
  finished. Note that "make install" expects the directories /emx/dll
  and /emx/bin to exist on the current drive.

DOS:
  - If your graphics card has native VESA support (i.e. VESA Bios Extension
    in ROM), no preparation is neccesary.
  - If not, just load your VESA Bios-Extension TSR.
    (should be on the driver disk for your graphic card, see below, section 2)
  - If you don't have a VESA Bios-Extension TSR, only standard vga modes
    (i.e. 320x200x256 and 640x480x16) will be supported.

OS/2:
  "make install" will build several dynamic link libraries and will copy
  them to \emx\dll. It will also copy the file "pmscreen.exe" to /emx/bin.
  "\emx\dll" has to be mentioned in the LIBPATH statement of your CONFIG.SYS.
  "\emx\bin" should be mentioned in the PATH environment variable.

  When a program using the vesa package first calls a VESA function, it
  loads one of the following DLLs:
  - VESA_PM.DLL   ---  for all graphics adapters supported by OS/2
                       Resolutions: up to 1280x1024x256
                       requires PMSCREEN.EXE to bin mentioned in the
                       PATH environment variable or the environment
                       variable PMSCREEN point to PMSCREEN.EXE.
                       (example: "C:> set PMSCREEN=c:\mybins\pmscreen.exe")
  - VESA_IBM.DLL  ---  for Standard VGA and all unsupported SVGA Adapters
                       Resolutions: 640x480x16
                                    320x200x256
                                    320x240x256
                                    320x400x256
                                    360x480x256
  - VESA_ET4.DLL  ---  for ET4000 based SVGA Adapters
                       Resolutions: up to 1024x768x16
                                          1024x768x256
  - VESA_ET5.DLL  ---  for ET4000 based Hi-/True-Color SVGA Adapters
                       Resolutions: up to 1024x768x16
                                          1024x768x256
                                           512x768x32k
                                           512x768x64k
                                           341x768x16m
                       Note: will not be supported in future releases
  - VESA_ET6.DLL  ---  for ET4000 based SVGA Adapters
                       Resolutions: ALL resolutions supported by
                                    your DOS Vesa Bios-Extension
                       Note: see section "VESA_ET6.DLL"
  - VESA_TR8.DLL  ---  for Trident 8900 based SVGA Adapters
                       Resolutions: up to 1024x768x16
                                          1024x768x256
                       Tested only for 640x480x256 and 800x600x256.

  VESA_PM.DLL opens two Presentation Manager windows (one for text and one
  for graphics) to display the output of your programs. All other DLLs run
  in an OS/2 fullscreen session.

  By default, the vesa package loads "VESA_PM.DLL". If you want the vesa
  package to load another DLL specify the name of the DLL to load in the
  environment variable "VESADLL". For example, type "set VESADLL=VESA_ET4"
  to make the vesa package load "VESA_ET4.DLL". Note that you MUST NOT
  specify the path or the extension of the DLL.

- To test the vesa package run "VESATEST.EXE". It should show information
  on all supported video modes.
- Get the svgakit for emx. It uses this vesa package. Note that svgakit
  currently only supports video modes with at least 256 colors.


2.How to get a DOS VESA Bios-Extension:
---------------------------------------
If you don't have a VESA Bios-Extension for your graphic adapter, get the
files kjb/MGL/univbe??.zip and kjb/MGL/vesatsrs.zip from
godzilla.cgl.rmit.oz.au. They contain a large variety of Bios-Extensions
for most graphic adapters.
These files are also available from garbo.uwasa.fi and oak.oakland.edu.

If you've got a standard vga (or if you don't find a VESA Bios-Extension)
you may want to use the VESA Bios-Extension "VESA_IBM.COM" which is included
in this package. It supports the standard vga modes and some non-standard
modes all vga cards are able to do.


3.How to get an OS/2 VESA Driver:
---------------------------------
If you have a graphics adapter which is not yet supported by this packages,
you have to write your own one. Don't be afraid: It is not such difficult.
If your graphic card is recognized by the OS/2 SVGA.EXE it should work
like that:
- Get a DOS VESA Bios-Extension for your graphic card. Additional information
  on your graphic card will be helpfull.
  (/kjb/MGL/vgadoc2.zip at godzilla.cgl.rmit.oz.au for example)
- Compile the VESA-package.
- Boot DOS and run "VESATEST.EXE". Now it displays information on the
  supported graphic modes. Write it down (or use "VESATEST.EXE > XYZ.DAT")
  to pipe the output of "VESATEST.EXE" to "XYZ.DAT".
- Look at "C:\OS2\SVGADATA.PMI" and find the modes that are both supported
  by OS/2 and your VESA Bios-Extension (X,Y-Resolution and number of colors
  should be equal).
- "Copy vesa_et4.c vesa_xxx.c" where 'xxx' is short for your graphic card.
  Now change the 'Modes' and 'ModeInfos'-Structures according to the
  information "VESATEST.EXE" gave you.
- Look at the documentation on your graphic card or debug your VESA
  Bios-Extension by calling interrupt 0x10 with ax=0x4f05 to see how
  Bank switching is done for your graphic card and change the functions
  "OS2VesaSetWindow" and "OS2VesaGetWindow".
- Change the makefile to compile and link your "vesa_xxx.c" like
  "vesa_et4.c".
- Run "make" to compile the new library. Then set the environment variable
  VESADLL to "vesa_xxx" and try to run "VESATEST.EXE". The output should be
  at least similar to the output you got when running VESATEST.EXE with DOS.
- Get the svgakit for emx and try to run "GRAPH.EXE".
- If everything works, send the source to me (see below). I'll include it
  in future releases of this VESA-package.

If you don't know how to start, just contact me. I'll try to get infos on
your graphics adapter and send you some code that should work. If not, we
can try to fix the bugs together (you report the symptoms, I'll look at the
code).


4.VESA-Function reference:
--------------------------
a) Look at the file "vesa.txt" in "/kjb/MGL/vgadoc2.zip" at
   godzilla.cgl.rmit.oz.au for reference on the 'real'
   VESA Bios-Extension.

b) - To use the VESA-package with DOS you have allow direct port
     and memory access to your programs. This can be done by
     running "emxbind -aq myexe.exe -acim" after linking.
   - All DLLs except VESA_PM.DLL need your program to be run in
     an OS/2 fullscreen session. To tell OS/2 to automatically
     switch to an OS/2 fullscreen session when your program starts
     use the emxbind utility after linking your program:
     "emxbind -e -f myexe.exe"

c) Reference:

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaInitialize(void);

    Initialize VESA-Driver. Return TRUE if sucessfull, else FALSE.

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaGetInfo(PVESAINFO pVesaInfo);

    Get VESA-Driver and SuperVGA Information:

    typedef struct
      {
        VESAWORD Version;          /* VESA Version number (now 1.2) */
        VESACHAR *OEMName;         /* pointer to OEM name           */
        VESAWORD *Modes;           /* pointer to list of supported  */
      } VESAINFO, *PVESAINFO;      /* modes terminated with 0xFFFF  */

    VesaGetInfo returns TRUE on success else FALSE. If VesaGetInfo returns
    FALSE the VESA Bios-Extension or emx VESA-driver is not loaded (DOS only).

    See also: VesaGetInfo()

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaGetModeInfo(VESAWORD Mode, PVESAMODEINFO pVesaModeInfo);

    Get Information on specified mode. See at "VESA.TXT" mentioned in a)
    for explanation of fields. The fields called "reserved" are not
    included here. Two fields are different from standard VESA:

    SetWindowFunc points to a function to set the current memory window.
    GetWindowFunc points to a function to get the current memory window.
    (Standard VESA has only one pointer for both "get" and "set").
    Look at VesaSetWindow and VesaGetWindow for parameters for
    SetWindowFunc and GetWindowFunc.

    typedef struct
      {
        VESAWORD ModeAttributes;
        VESACHAR WindowAAttributes;
        VESACHAR WindowBAttributes;
        VESAWORD WindowGranularity;
        VESAWORD WindowSize;
        VESAPTR  WindowAStart;
        VESAPTR  WindowBStart;
        VESASET  SetWindowFunc;
        VESAGET  GetWindowFunc;
        VESAWORD BytesPerScanline;
        VESAWORD Width;
        VESAWORD Height;
        VESACHAR CharacterWidth;
        VESACHAR CharacterHeight;
        VESACHAR NumberOfMemoryPlanes;
        VESACHAR NumberOfBitsPerPixel;
        VESACHAR NumberOfBanks;
        VESACHAR MemoryModelType;
        VESACHAR SizeOfBank;
        VESACHAR NumberofPages;
        VESACHAR RedMaskSize;
        VESACHAR RedMaskPosition;
        VESACHAR GreenMaskSize;
        VESACHAR GreenMaskPosition;
        VESACHAR BlueMaskSize;
        VESACHAR BlueMaskPosition;
        VESACHAR ReservedMaskSize;
        VESACHAR ReservedMaskPosition;
      } VESAMODEINFO, *PVESAMODEINFO;

    VesaGetModeInfo returns TRUE on success and FALSE if the requested mode
    is not supported.

    CAUTION: When running with OS/2 the WindowAStart and WindowBStart fields
       are only valid if:
       - You have activated the graphics mode by calling VesaSetMode().
       - Your application is executed in foreground (can be forced by
         calling VesaLockScreen() before calling VesaGetModeInfo();
         don't forget to call VesaUnlockScreen()).

    See also: VesaGetInfo(), VesaSetMode(), VesaGetMode(),
              VesaSetWindow(), VesaGetWindow(),
              VesaLockScreen(), VesaUnlockScreen()

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaSetMode(VESAWORD Mode);
VESABOOL VesaGetMode(PVESAWORD Mode);

    Activate specified/get current video mode.

    VesaSetMode/VesaGetMode returns TRUE on success else FALSE.

    See also: VesaGetModeInfo()

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaSetWindow(VESACHAR Window, VESAWORD Address);
VESABOOL VesaGetWindow(VESACHAR Window, PVESAWORD Address);

    Set/Get current video memory window address.

    VesaSetWindow/VesaGetWindow returns TRUE on success else FALSE.

    CAUTION: Lock the screen via VesaLockScreen() before calling
       VesaSetWindow()/VesaGetWindow(). To increase speed this functions
       do neither test if Screen is already locked nor lock it themselves.
       Calling this functions without locking the screen can cause
       unpredictable results!

    See also: VesaGetModeInfo(), VesaLockScreen(), VesaUnlockScreen()

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaSetScanlineLength(VESAWORD NumberOfPixels);
VESABOOL VesaGetScanlineLength(PVESAWORD BytesPerScanline,
                               PVESAWORD NumberOfPixels,
                               PVESAWORD NumberOfScanlines);

    Set/Get logical scanline length.

    VesaSetScanlineLength/VesaGetScanlineLength returns TRUE on success
    else FALSE. If screen is not locked and program is running in
    background these functions return FALSE.

    See also: VesaGetModeInfo(), VesaLockScreen(), VesaUnlockScreen()

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaSetSwitchFunc(VESASWITCH SwitchFunc);

    Specify a function which is called everytime the user switches the
    program from background to foreground or vice versa. The function
    has to save/restore the contents of the video memory.

    Calling VesaSetSwitchFunc(NULL) causes OS/2 to save/restore the
    video memory itself (this is the default).

    'SwitchFunc' has to be defined as follows:

    void SwitchFunc(int Restore)
    {
      ...
    }

    The Parameter 'Restore' signals the function whether it should save
    (Restore = 0) or restore (Restore = 1) the video memory.

    To access the video memory from within this function you don't have
    to use screen locking.

    VesaSetSwitchFunc returns TRUE on success else FALSE.

    This function has no effect under DOS and does not belong to the
    standard VESA Bios-Extension.

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaLockScreen(VESACHAR wait);

    This function locks the screen. This is required to do before you
    access the screen memory. The parameter 'wait' specifies wheter
    VesaLockScreen() should return with an error if the program isn't
    in foreground (wait = 0) or should wait until the program is
    switched to foreground (wait = 1).

    VesaLockScreen return TRUE if locking was successfull else FALSE
    (if wait = 0).

    This function has no effect under DOS and does not belong to the
    standard VESA Bios-Extension.

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaUnlockScreen(void);

    This function unlocks the screen previously locked by VesaLockScreen().

    This function has no effect under DOS and does not belong to the
    standard VESA Bios-Extension.

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaSetModified(void);

    This function tells the VESA Bios-Extension to update the screen.

    This function has only effect when VESA_PM.DLL is used under OS/2.
    It does not belong to the standard VESA Bios-Extension.

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaSetPalette(VESAWORD   StartIndex,
                        VESAWORD   NumberOfEntries,
                        PCVESACHAR Palette,
                        VESABOOL   Wait);
VESABOOL VesaGetPalette(VESAWORD   StartIndex,
                        VESAWORD   NumberOfEntries,
                        PVESACHAR  Palette);

    Set/Get the palette entries from first to (first + n - 1). For each
    entry 3 bytes are taken from Palette: red, green, blue. Each byte
    should have a value between 0 and 63, inclusive.

    If Wait is non-zero VesaSetPalette waits for the vertical retrace
    to avoid snow on the screen.

    This function does not belong to the standard VESA Bios-Extension.

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaGetCharacter(PVESACHAR pchar);

    Wait until a key is pressed and return its ASCII-Code in *pchar. If
    a function key is pressed, VesaGetCharacter returns 0 in *pchar. The
    next call to VesaGetCharacter will return the SCAN-Code of the key
    pressed.

    This function does not belong to the standard VESA Bios-Extension.

    Note: You may use "normal" emx, C-library, or OS/2-Api Calls instead
          of VesaGetCharacter. However, if you want your program to work
          with VESA_PM.DLL under OS/2 you should use VesaGetCharacter.

------------------------------------------------------------------------------
#include <vesa.h>                                                       [VESA]

VESABOOL VesaKeyboardHit(PVESACHAR pchar);

    Return if a key has been pressed.

    This function does not belong to the standard VESA Bios-Extension.

    Note: You may use "normal" emx, C-library, or OS/2-Api Calls instead
          of VesaKeyboardHit. However, if you want your program to work
          with VESA_PM.DLL under OS/2 you should use VesaKeyboardHit.

------------------------------------------------------------------------------


5.The "VESA_ET6.DLL":
---------------------
VESA_ET6.DLL does not use OS/2-functions to switch between video modes. It
programs the registers of the ET4000 graphics controller directly. The
information on the video modes is stored in the file "vesamode.dat". This
information may differ between different graphic adapters and monitors. So
it has to be created first. To do this, follow the following instructions:

1.Boot DOS (because "modedump.exe" uses emx, you cannot run it in
  OS/2 DOS-Fullscreen).
2.Load your VESA Bios-Extension.
3.Run "modedump.exe". A file called "vesamode.dat" should be created.
4.Move "vesamode.dat" to some directory mentioned in your DPATH statement
  in config.sys (I put it in C:\OS2).

CAUTION: Because VESA_ET6.DLL directly programs the graphic adapter, it
         may cause damage to your monitor!
         Never use a "vesamode.dat" on a computer+monitor other than the
         one you created the file with!


6.The new "VESA_PM.DLL" and "PMSCREEN.EXE":
-------------------------------------------
When your program first calls a vesa function, the vesa library will load
VESA_PM.DLL (if you didn't specify another DLL as default, see section 1).
VESA_PM.DLL will start PMSCREEN.EXE. All output via stdout and stderr will
be redirected to the text window of PMSCREEN.EXE. Most input to either the
text window or the graphics window of PMSCREEN is redirected to stdin of
your program. In addition you may ask for input using VesaGetCharacter and
VesaKeyboardHit.
Do not use OS/2 VIO- and KBD-Calls. They will act in the window/fullscreen
your program was started from.

In the system menu of PMSCREEN.EXE you may choose "Update Screen" to force
PMSCREEN to update its screen.

If you choose "PM-Screen Settings" PMSCREEN will show you its settings
dialog. It contains the following entries:
- Time between screen updates:
  The screen will be updated all ... milliseconds, if neccesary (i.e.
  if the screen contents have changed, and your program correctly told
  PMSCREEN that it changed the contents).
- Use physical palette:
  If checked, PMSCREEN will modify the physical palette to best display
  the colors your programs needs.
- Use full palette:
  By default, OS/2 reserves about 20 palette entries for its own use
  and does not let your program change then. If you check this button,
  PMSCREEN will use even these 20 entries of the palette.
  At least on my machine (with ET4000 card), this seems not to work
  correct. The palette is only modified if my programs run in background,
  while it should be modified if it runs in foreground...
- Display in original size:
  This tells PMSCREEN not to stretch or shrink the output of your program.
  This will increase speed and quality of the output.


7.History:
----------
Version 1.1 (04/03/1993):
  - initial release
Version 1.2 (04/13/1993):
  - Bug fixed in vesa_*.dll:
    if VesaSetScanLineLength can't set the desired scanline length
    it has to set the first possible GREATER than the desired (was LOWER)
  - Included standard VGA non-bios modes 320x240x256, 320x400x256
    and 360x480x256 in vesa_ibm.dll.
Version 1.3 (05/14/1993)
  - VESA_IBM.COM and VESA_EMX.COM now check if they are already installed
  - mode information on standard vesa modes and standard vga modes (12h,13h)
    now included in libvesa.a:
    - should solve problems with some VESA Bios-Extensions
    - modes 12h and 13h now available with any VESA Bios-Extension
  - new VESA_TR8.DLL for graphics adapters with Trident 8900 chipset (beta)
  - new VESA_ET6.DLL to get access to more video modes
  - removed dummy-function "atexit" from common.c
Version 1.4 (06/23/1993)
  - an Interface to the DOS VESA-Bios Extension is now part of emx*.exe.
    So vesa_emx.com is not neccessary any more.
  - VESA_TR8.DLL should now work
  - fixed some silly bugs
Version 1.5 (12/20/1993)
  - many big changes, some are:
    - new VESA_PM.DLL to run program in a PM-Window
    - Keyboard-Interface added
    - DLLs now compiled with -Zomf -Zsys.
  - some small changes to make vesa_emx work with emx 0.8h


8.License:
----------
- You are allowed to copy and change the whole VESA package provided that you
  do not change the copyright statement in the files and copy this
  documentation together with the VESA package.
- You are allowed to copy the DLL's (for example together with your
  application programs).
- You are allowed to copy "VESA_EMX.COM", "VESA_IBM.COM" and "MODEDUMP.EXE".


9.Future plans:
---------------
- include mouse interface
- make some other vesa DLLs work...
- let PMSCREEN save settings
- change font size for the PMSCREEN text window (optionally)
- ...


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


11.Copyright:
-------------

The VESA package for emx was written and is Copyright (c) 1993 by

    Johannes Martin
    Pfarrer-Dorn-Strae 26
    D-55127 Mainz-Marienborn

    Internet: JMARTIN@GOOFY.ZDV.UNI-MAINZ.DE
