******* Virtual GameBoy MS-DOS *******
                  The Portable Nintendo GameBoy Emulator
                               version 0.8b1
                                     
        Core emulator code copyright (C) 1995,1996  Marat Fayzullin
              MS-DOS port copyright (C) 1996  Marcel de Kogel
                                     
               GameBoy is a registered trademark of Nintendo.
                 MS-DOS is a trademark of Microsoft Corp.

Note: VGB-DOS requires the presence of a DPMI server. If you don't run the
program under a DPMI-hosted environment (Windows, OS/2, QPMI, ...), put
the file CSDPMI.EXE included in CWSDPMI.ZIP somewhere in your path.

Hardware Requirements
=====================
A 486DX-33 (486DX2-66 recommended)
A VGA compatible video card
Adlib/Adlib Gold/SBPro/SB16 and joystick supported

Files included in VGB-DOS.ZIP
==============================
VGB-DOS.EXE    The emulator
VGB-DOS.TXT    This file
VGB-DOS.GIF    A GIF file containing the title screen. You can replace
               this with your own. Make sure the file is in 256-color,
               320x200, non-interlaced GIF87A format. The first 64 colors
               are reserved for use by the emulator
KEYS.EXE       Small utility to alter the key mappings
CWSDMI.ZIP     A DPMI server required by VGB-DOS.EXE
Some utilities for use with VGB MS-DOS can be found on the VGB MS-DOS
distribution site at http://www.komkon.org/~dekogel/vgb.html
More information about VGB and GameBoy in general can be found on the VGB
distibution site at http://www.freeflight.com/fms/VGB

Default Key Mappings
====================
Cursor Keys  -  Movement
Left Alt     -  Button A
Left Ctrl    -  Button B
Left Shift   -  Start
Z            -  Select

Special Keys
============
F1-F4        -  Toggle sound channels 1-4 on/off
F5           -  Toggle sound on/off
F8           -  Pause & Blank screen
F9           -  Pause
F11          -  Decrease volume. Volume control only works on SBPro and
                SB16 compatible sound cards
F12          -  Increase volume
Both Alts +  -  Reset GameBoy
Both Ctrls
ESC/F10      -  Quit emulator

Command line options
====================
-help                          Print a help page describing all available
                               command line options
-ifreq <frequency>             Select interrupt frequency [60]
                               If you want your games to run faster,
                               increase the interrupt frequency. If you
                               want them to run slower, decrease it. Use -
                               ifreq 0 to disable sync
-verbose <level>               Select debugging messages [1]
                               0 - Silent           1 - Startup messages
                               2 - Illegal writes   4 - Illegal CPU ops
                               8 - Bank switching
-vperiod <period>              Set VBlank interrupts period [69905 cycles]
-uperiod <period>              Number of interrupts per screen update [0]
                               Selecting 0 will enable real-time refresh
                               checking. If emulation is chunky, try -
                               uperiod 2 or -uperiod 3
-cheat <GG code>               Activate GameGenie cheat [none]
-delay/-nodelay                Delay/Don't delay screen refresh [-delay]
-crc/-nocrc                    Check/Don't check cartridge CRC [-crc]
-video <mode>                  Select video mode [0]
                               0 - 320x200 with title screen
                               1 - 320x200 without title screen
                               2 - 360x144 full screen mode
                               3 - 180x144 full screen mode
                               4 - 256x200 with title screen
                               5 - 256x200 without title screen
                               Please note that modes 2-5 may not be
                               compatible with your VGA card or monitor
-background <filename>         Select .GIF file to use as background [VGB-
                               DOS.GIF] (Only works in video modes 0 and
                               4)
-sound <mode>                  Select sound mode [1]
                               0 - No sound
                               1 - Adlib
                               You may want to have the sound turned off
                               by default for certain games, as the
                               emulation isn't nearly perfect
-stereo <mode>                 Select stereo mode [1]
                               0 - mono
                               1 - normal
                               2 - reversed
-volume <value>                Select initial volume [10]. 0 is silent, 15
                               is maximum. Volume control only works on
                               SBPro or SB16 compatible cards
-logsnd <filename>             Select sound log file [NULL]
-color0 <name>                 Change color#0 [white]
-color1 <name>                 Change color#1 [#B0B0B0]
-color2 <name>                 Change color#2 [#606060]
-color3 <name>                 Change color#3 [black]
-backgroundcolorX              Same as -colorX, but only changes the
-spritecolorX                  background/sprite/window colors
-windowcolorX
-colorscheme <scheme>          Select a pre-defined or user-defined color
                               scheme [0].
                               Currently pre-defined color schemes are:
                               0 - Gray
                               1 - Green
                               2 - Yellow/Blue
                               3 - High contrast green
                               4 - Yellow
                               5 - Amber
-backgroundcolorscheme         Select background/sprite/window color
-spritecolorscheme             scheme
-windowcolorscheme
-definecolorscheme <c0> <c1>   Define a color scheme. Color schemes 0 to
<c2> <c3>                      127 are reserved, schemes 128 to 255 can be
                               defined
-brightness <value>            Select image brightness [0]
                               -100 - Darkest  100 - Brightest
-backgroundbrightness          Select background/sprite/window brightness
-spritebrightness
-windowbrightness
-swapbuttons <flags>           Select buttons to swap [0]
                               1 - Swap joystick buttons
                               2 - Swap keyboard buttons
                               3 - Swap both
-autoa <mode>                  Select button A autofire mode [0] 0 - No
                               autofire 1 - Autofire
-autob <mode>                  Select button B autofire mode [0] 0 - No
                               autofire 1 - Autofire
-keys <string>                 Alter key mappings
Some command line options may be abbreviated. You can get a list of
supported abbreviations by using the -help command line option

Color names supported
=====================
The following color names can be used with the -colorX options: black,
blue, green, cyan, red, magenta, brown, gray, dkgray, dkblue, dkgreen,
dkcyan, dkred, dkmagenta, yellow, orange, pink, white. You can also
specify an RGB value with #RRGGBB, e.g. -color0 #AA0055 will set color 0
to brown.

Soundtrack file format
======================
The soundtrack file format is as follows:
Header:
string         `GameBoy Soundtrack File 1.1',0x1A
dword          Number of cycles per second
60 bytes       Reserved (0)
Data:
0xFF <dword>   Number of cycles passed since last log
0xFE <word>    ...
0xFD <byte>    ...
0xF0           End track
0x00-0x16      Sound register write. Second byte is the value to write
word=16-bit unsigned integer, LSB first
dword=32-bit unsigned integer, LSB first

Configuration files
===================
The emulator loads two configuration files (if present) before it loads a
cartridge rom: VGB-DOS.CFG located in the emulator's directory and
CART.CFG (e.g. DKONG.CFG if you load DKONG.GB) located in the cartridge
dump's directory. These are plain text files containing optional command
line options. Options can be separated with spaces, tabs or returns.

Troubleshooting
===============
-  If the emulator refuses to load your ROM images, check if it's CRC is
   correct and if it's size is a multiple of 8192 bytes. If it's CRC is
   incorrect, you might want to try using -nocrc, although getting a
   correct image is prefered. If it's size is incorrect, there might be a
   SmartCard header attached to the file. Try stripping the first 512
   bytes
-  If a game doesn't run correctly, try increasing vperiod to about 100000
-  If display is incorrect, try -nodelay or -uperiod 1

History
=======
0.8b1   Fixed LCD state and serial I/O emulation, implemented sprite
        priorities and improved sprite refreshing, added autofire options,
        soundtrack can now be saved into a file, key mappings can now be
        changed, increased speed
0.6.2   Fixed a major bug in the GB's timer interrupt scheme and a minor
        bug in the RAM page allocation scheme
0.6.1   Fixed lots of bugs, added sprite color control
0.5.2   Major speedup, added sync option, fixed some bugs, added color
        scheme support and a few other options
0.5.1   Initial release

Credits
=======
- The GIF decoding routines and the title GIF itself were taken from Jeff
  Frohwein's code. Jeff also helped fixing lots of bugs in the emulator.
  Thanks Jeff!
- VGB-DOS was compiled using DJ Delorie's DJGPP v2.0. DJGPP is a 32 bit C
  compiler for MS-DOS. Source code and binaries of DJGPP are available at
  http://www.delorie.com.

Please send your comments to Marcel at
m.dekogel@student.utwente.nl
BUT PLEASE, DO NOT ASK FOR ROM IMAGES!