AmigActive 6/AACD06.ISO/AACD/Emulation/AmigaVGB/VGB.doc

Text File | 2000-07-08 | 19KB | 429 lines

                   ******* Virtual GameBoy *******
                The Portable Nintendo GameBoy Emulator
                             version 0.7

                         by Marat Fayzullin

                      email: [e-mail]
                            IRC:  RST38h
                 WWW: http://www.freeflight.com/fms/

         (*) GameBoy is a registered trademark of Nintendo.



                       * NEW IN THIS VERSION *

o CPU emulation is somewhat sped up
o CPU cycles (not ops) are now used for synchronization
o LCD controller's state changes are done correctly
  (which may slow things down somewhat)
o Sprite priorities implemented
  (which may slow things down somewhat)
o RAM size bug fixed
o Separate autofire for buttons A and B
o Saving soundtrack into a file
o Separate colors for background, window, and sprites
o -nodelay is made default now



                          * INTRODUCTION *

  Please, *carefully* read this manual. Do not write me email with
questions answered in here, as such letters are going to be ignored: I
have too many other things to do to answer the same questions over and
over again.
  *Windows users* will find a special section downgraded in content for
better comprehension.

  Virtual GameBoy (VGB) is a portable emulator of the Nintendo GameBoy
handheld videogame console written in C. Although many things do not work
quite well yet, it was able to run about 85% of games checked with it. You
can always get the latest VGB source code, binaries, and support files
from

                  http://www.freeflight.com/fms/VGB/

GameBoy-related archives with technical and other info are located at

                  http://www.freeflight.com/fms/GameBoy/
                  ftp://ftp.komkon.org/pub/GameBoy/

  There are versions of VGB for Amiga, Macintosh, and IBM PC (both
MeSsyDOS and Windoze). Following people are maintaining ports of VGB to
these systems:

MSDOS:      Marcel de Kogel [[e-mail]]
Windows:    Marat Fayzullin [[e-mail]]
Macintosh:  John Stiles [[e-mail]]

  If you would like to port VGB to another system, or make changes in
VGB's code *please*, contact me by email or some other means. Note, that
VGB source code is freely distributable, but it is *not* public domain.
You can not use it in commercial purposes unless you contact me to arrange
the conditions of such usage and get my permission. Feel free to look at
existing drivers as well as at other code. More explanations follow.

  This manual covers two different VGB distributions:

1. *** Source Code Distribution ***
  This distribution contains C sources of the emulator, and the
screen/keyboard drivers for Unix/X. Virtual GameBoy has been tested on the
following Unix systems:

  SunOS   Solaris   OSF/1   FreeBSD   HP/UX   Linux   AIX

2. *** VGB-Windows Distribution ***
  Due to the flood of requests from the people who use DOS/Windows running
PCs and are unable to compile the emulator on their own, I have ported VGB
under Microsoft Windows. This distribution contains an executable of a
limited version of VGB-Windows which doesn't allow you to reload a new
game from a menu when emulation is already running, and has an annoying
"Virtual GameBoy DEMO" message across its window. The uncrippled version
of VGB-Windows is available for $35US from

  Marat Fayzullin
  6304 Hampton Place
  Elkridge, MD 21227
  USA

  VGB-Windows is a 32-bit application which runs under Windows 95 and
Windows NT. It is compiled with Borland C++ and needs Microsoft WinG
library which can be obtained from

  ftp://ftp.microsoft.com/Softlib/MSFILES/WING10.EXE



               * SHORT MANUAL FOR THE WINDOWS USERS *

  In order to use VGB-Windows, you will first have to install WinG
graphical library which can be obtained from Microsoft (see address
above). Borland's BWCC32.DLL is *no longer needed*, although you do need
to have Windows95 in order to run VGB (3.xx will not do).
  All options are stored in the VGB.INI file individually for each game.
Unregistered version does not support .INI file though, so you won't be
able to store any options in it.
  VGB-Windows runs in a resizable window with the following menus:

o File
  o New
    This option allows to run a new game.
  o Cheat
    This option allows to add and delete GameGenie codes. Codes are stored
    in the .INI file separately for each game. Up to 256 codes per game
    can be entered.
  o Setup
    This option pops up a setup dialog allowing to change all 4 GameBoy's
    colors and some emulation parameters:
    o Palette
      Use this group of controls to select a color and change its RGB
      components. The palette controls may not work very well if you
      run Windows in 256-color mode. Use 16-bit or 24-bit graphical
      mode for best effect. There are 12 colors you can adjust:
      4 background colors, 4 window colors, and 4 sprite colors.
    o VBlank Period
      This parameter determines how many CPU cycles will be executed
      between vertical blanking interrupts. Setting it lower may speed
      up the emulation, but setting it too low will hang it.
    o Update Period
      This parameter determines how many vertical blanking interrupts
      will pass between window refreshes. It is usually set to 2, but
      you can increase it to make VGB work faster. The sprite
      movements become jerky at high update periods though, and some
      sprites may simply disappear.
    o Delay Line Interrupts
      If you see "dirty" horizontal lines in some games, you may turn
      this option on or off to remove them. There is no some universal
      state of this option which will work for all games though.
    o Check CRC
      With this switch off, VGB will not check the control sums of
      the loaded cartridges.
    o Save CPU
      With this switch on, VGB will suspend the execution when its
      window is inactive.
    o Autofire A
      Turn this on to make the [A] button generate series of keypresses
      instead of a single keypress.
    o Autofire B
      Turn this on to make the [B] button generate series of keypresses
      instead of a single keypress.
    o Reset
      By pressing this button, you restart VGB.
  o Quit
    Quit the emulation. A .SAV file will be saved if the game has a
    battery-backed RAM.
o Size
  o 1:1  These options change the window size to be the same as in real
  o 2:1  GameBoy, or 2/3/4 times bigger. Please, note that you can change
  o 3:1  window size by simple dragging the bottom-right corner of a
  o 4:1  window with the mouse.
o Help
  o Info
    This option will show information about the current cartridge,
    including its name, likely producer name, size, checksum, etc.
  o About
    This option will display a dialog box with copyright information
    and other legal stuff.



                   * FREQUENTLY ASKED QUESTIONS *

1. What is GameBoy?
  GameBoy is a handheld videogame machine produced by Nintendo. It is
built around a custom CPU similar to Z80, but with some changes. GameBoy
is frequently laughed at because of its reflective green-on-yellow LCD
screen which in fact is its virtue. Due to the low power consumption of
its LCD, GameBoy can work for 35 hours off 4 AA batteries. There is a lot
of good games produced for GameBoy, both classics (Tetris, Pacman,
Asteroids, etc.) and specific ones (Final Fantasy series for GB). It
excells in RPGs and classic games where gameplay is more important than
graphics. More information about GameBoy is available from

           http://www.freeflight.com/fms/GameBoy/

2. Where do I get GameBoy games?
  You buy the cartridges. GameBoy software is copyrighted and still sold.
Therefore, its distribution is an act of piracy. Nothing prohibits you
from backing up a cartridge you own and playing it on the emulator though.
To back up a GameBoy cartridge, you can use either SmartCard copier (about
$100 for a standalone version), or a self-built copier designed by Pascal
Felber, description of which is available at

           http://www.freeflight.com/fms/GameBoy/

Please, DO NOT SEND ME MAIL ASKING TO SEND YOU THE CARTRIDGE FILES OR TELL
YOU WHERE TO FIND THEM. I ignore such letters.

3. Where is the complete list of command line options of VGB?
  Use -help option. It will tell VGB to display all options available in
your version. Following are the currently available options:

  -verbose <level>    - Select debugging messages [5]
                        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 [2]
  -help               - Print this help page
  -cheat <GG code>    - Activate a GameGenie cheat
  -delay/-nodelay     - Delay/don't delay line interrupts [-nodelay]
  -crc/-nocrc         - Check/don't check cartridge CRC [-crc]
  -autoa/-noautoa     - Autofire/No autofire for button A [-noautoa]
  -autob/-noautob     - Autofire/No autofire for button B [-noautob]
  -logsnd <filename>  - Write soundtrack to a file [off]
  -trap <address>     - Trap execution when PC reaches address [FFFFh]
  -shm/-noshm         - Use/don't use MIT SHM extensions for X [-shm]
  -saver/-nosaver     - Save/don't save CPU when inactive [-saver]
  -colorN <name>      - Change color #N [white,#989898,#585858,black]
  -bcolorN <name>     - Change background color #N [same]
  -scolorN <name>     - Change sprite color #N [same]
  -wcolorN <name>     - Change window color #N [same]

4. What are the keys used in VGB?

  [SPACE] - A button (also: A,S,D,F,G,H,J,K,L)
  [LALT]  - B button (also: Z,X,C,V,B,N,M)
  [TAB]   - SELECT button
  [ENTER] - START button
  [ESC]   - Quit emulation (also: [F12])

  [F1]    - Go into built-in debugger (Not implemented in Windows)
  [F2]    - Show LCD controller registers (Not implemented in Windows)

5. Why is the emulator so slow on my PC?
  Because your PC is too slow to run it. The emulator is written entirely
in C language and therefore is quite slow. Although it works on 486/33 and
even 386/33 PCs, it runs best on a Pentium/90 or a DEC Alpha/150. You can
try to speed it up by increasing -uperiod value controlling the number of
interrupts between screen updates to 3-6, and by decreasing -iperiod value
controlling the number of CPU cycles between interrupts.

6. Can I compile the emulator with my Borland/Turbo C compiler?
  You can, given that your compiler creates executables using flat 32bit
memory model. Two PC compilers which do that are WATCOM (using DOS4GW DOS
extender) and GCC (using DJPP extender). The only 32bit Borland/Turbo C
compiler that I'm aware is for Windows though.

7. Is it legal to spread GameBoy cartridge snapshots?
  NO. Be aware of the fact that by using commercial software you haven't
bought, you are commencing an act of piracy. Not that I care, anyway...

8. Why some games do not run with VGB?
  As it was said before, VGB emulation is not completely accurate yet.
Also, some games will probably never run on VGB.

o If emulator does not even recognize the ROM image, its CRC may be
  wrong. Try turning CRC checking off.
  although you really need to find an uncorrupted ROM image.
o Check you ROM image size: it must be a multiple of 8192. If it is
  512 bytes longer, then you may have a SmartCard copier header
  attached to it. In this case, remove first 512 bytes of the file.
o If a game refuses to work, try increasing -vperiod value, or moving
  a "VBlank Period" knob in the VGB-Windows setup window.
o If you see a group of "dirty" lines on VGB screen, or a game behaves
  strangely, try -delay/-nodelay options, or check/clear the "Delay
  Line Interrupts" checkbox in the VGB-Windows setup window.
o If some sprites blink or do not appear at all, try changing -uperiod
  value from 1 to 10 (1 will give you the best picture, but the slowest
  emulation), or moving an "Update Period" knob in the VGB-Windows
  setup window.

9. Palette controls in VGB-Windows do not work.
  This probably means that you are running Windows in the 256-color mode.
In this mode, not all of 256 possible colors are available, and you will
be able to choose only from the available colors. Switch Windows into
16-bit or 24-bit graphics and palette will start working.

10. I start VGB-Windows, but it tells me that WING.DLL is not found.
  This means that you haven't installed WinG library necessary to run VGB.
Check the information in the beginning of this manual on how to obtain
WinG.

11. I start VGB-Windows, but it tells me that BWCC32.DLL is not found.
  VGB-Windows comes with a file called BWCC32.DLL. This file should be
either kept in the directory from which VGB runs, or put into
\WINDOWS\SYSTEM directory. If you haven't got this file, you are
probably using an illegal distribution of VGB-Windows.

12. When compiling emulator under Unix, I get "undefined name" errors.
  This means that your linker can not find the libraries necessary for the
emulator (namely, libX11.a and libXext.a) or some additional libraries
(like libsocket.a and libnsl.a) are required. Find these libraries in your
system and modify the Makefile so that the final invocation of the C
compiler has "-L<path_to_libs>" options. If you have no libXext.a library,
try #undefining MITSHM option.

13. When starting emulator under Unix, I get X_ShmAttach error.
  You are probably trying to run the emulator on a remote Xterminal while
it attempts to use shared memory for interfacing with X. Use -noshm option
to tell it not to use shared memory.

14. The emulation starts under Unix, but then I get X_PutImage error.
  Unix/X version of fMSX currently needs 256-color X. Neither 2-color
nor TrueColor Xterminals will work with the drivers included into
"official" VGB distribution.

15. I start the Unix version of the emulator but the window stays black.
  Some other X application took over all available colors so that the
emulation could not allocate any for itself. Check if you run XV,
Netscape, or something similar.

16. How can I get sound in VGB?
  The Unix/X version has no sound yet, although there are some works going
on in this direction. In the "official" DOS version, use -s option. Your
soundcard should be SoundBlasterPro-compatible though, and the sound is
very rudimentary.

17. How can I get joystick to work with VGB?
  Joystick is not supported yet.




                         * COMPILATION TIPS *

  If you are compiling the emulator under Unix, use Makefile. Notice that
#define UNIX is present in this case.
  The emulation is written in fairly portable C code and may therefore be
compiled with any decent ANSI C compiler. It relies on a flat 32bit memory
model though, so Borland compilers will choke on it. Standard CC or GCC
should do the job under Unix, although beware of GCC code generation
bugs. If you are working under MeSsyDOS, use WATCOM C which is known to
work. Under (God prohibits) Windows, use Borland C++ which has 32bit
compilation model. On Amiga, use SAS/C. On Macintoshes, use Metrowerks C.
  If you are using an Intel-based computer or any other machine which has
least-significant-byte-first data layout (for example, DEC Alpha), insert

                #define LSB_FIRST

in the beginning of Z80.h file. The emulator will not work otherwise.
  If you put

                #define DEBUG

in the beginning of Z80.h, the emulator will print debugging information
about CPU registers after executing each command. You can turn debugging
on and off by setting Trace variable to 1 and 0 accordingly. Also, by
setting Trap variable to some address you will make it start tracing when
PC reaches this address (-trap option).
  When you port the program to a new machine, you have to write a set of
drivers for keyboard, sprites, and all the screen modes you want to
emulate.  The emulator comes with a set of drivers for XWindows system.
The common code for these drivers is located in Common.h and can be used
for other systems too. Screen drivers use simple XSIZE*YSIZE array of
bytes to generate image, so in most cases you will only need to adjust
these drivers to your own needs. Note that the X11 drivers use so-called
MIT Shared Memory Extension for fast transfers from buffer to a window. If
you do not have MIT SHM extension in your system, remove

                #define MITSHM

You can also turn MITSHM off (for example, if you use remote X terminal)
by setting UseSHM variable to 0 before starting the emulation (-noshm
option).



                          * CODE STRUCTURE *

  Several other variables control the behaviour of the emulator. All of
them should be set before starting the emulation in order to take effect:

Verbose = 0..31
  Defines amount of debugging information printed by emulator. Default
  value is 1. Each bit of this variable enables printing of some kind
  of debugging info (VDP,CPU,memory,etc.).
VPeriod = 10000..199999
  Defines how many CPU cycles should be executed between two interrupts.
  Normal interrupt rate is 60Hz for NTSC systems or 50Hz for PAL systems.
  Default value of VPeriod is 69905.
CPURunning = 0/1
  Set this variable to 0 to stop CPU and exit the emulation.
AutoA = 0/1
  Emulate autofire on the first fire button. Default value is 0.
AutoB = 0/1
  Emulate autofire on the second fire button. Default value is 0.
SndName = "filename"
  When SndName is not NULL, VGB will open a file with this name, and
  save the soundtrack into it. The default value is NULL.
Trace = 0/1
  Print debugging information about CPU state. Default value is 1.
  #define DEBUG should be present in order to use this option. Tracing
  can be turned on and off during execution, for example, in keyboard
  driver.
Trap = 0x0000..0xFFFF
  Automatically start tracing when PC reaches given address. #define
  DEBUG should be present in order to use this option.
UPeriod = 1..10
  Defines how many interrupts should pass between two consequent screen
  updates. Default value of UPeriod is 2.
CartName = "cartridge.file"
  Name of a .GB file to load. Default value is "CART.GB". This variable
  is ignored if no file exists.
UseSHM = 0/1
  Use MIT SHM extension in X11 screen drivers. Default value is 1.
  #define MITSHM should be present in order to use this option.

  In order to run the emulation:

  1. Set all necessary variables.
  2. Initialize screen and keyboard drivers. In the case of X11 drivers,
     it is done by calling InitMachine() implemented in Unix.c and
     returning 1 on success or 0 otherwise,
  3. Call StartGB().
  4. Call TrashGB().
  5. Shut down screen and keyboard. In X11 case, by calling TrashMachine().
  6. Exit the program.

  Take a look at VGB.c to see an example of a sequence explained above.



---------------
Marat Fayzullin