		Snes9X 0.1 Released 8th July 1997
		---------------------------------

Gary Henderson (gary@daniver.demon.co.uk)

Contents
--------
Introduction
Key Features
What's New
What's Missing
What You Will Need
Getting Started/Command Line Options
Keyboard Controls
Joystick Support
Linux S-VGA Full-Screen Mode
Problems With ROMs
Converting ROM Images
Speeding up the Emulation
Credits

Introduction
------------

This is a Super Nintendo Entertainment System (SNES) emulator for Linux i386,
MS-DOS and Sun Solaris Sparc featuring work-in-progress 16-bit, digital
stereo sound on all ports. Jerremy Koot is working on a Windows 95 port.

Snes9X is coded in C++ with an assembler CPU emulation core on the Linux and
MS-DOS ports. More parts will be recoded in assembler in later versions.

It is a spare-time project done for my own interest that I thought other
people might enjoy. I've had virtually no help from anyone else over the past
few months. 90% of the time I spend on Snes9X isn't spent writing new code at
all - its time taken trying to discover how certain SNES features work,
speeding up existing code while still keeping it portable, testing or writing
documentation.

The SNES is a much more complex beast to emulate than say the NES. It has a
more complex main CPU, clocked twice as fast the NES, that can address more
memory and larger ROM images. It has four background layers compared to the
one on the NES, each of which can display up to 256 colours at once compared
to 32 on the NES. It has twice as many sprites as the NES, each of which can
be twice as large as those on the NES and interleaved between background
layers. It has more DMA channels, raster H-DMA effects, another CPU purely for
sound and almost twice as many sound channels - each of which plays compressed
sound samples rather than simple square or triangle waves and each sound
channel has hardware volume envelopes. The SNES also has transparency effects
(not emulated yet) that pushes up the possible number of colours on the screen
to 32768.

For people who think all SNES emulators are "crap" - don't use them, go and
use a real SNES instead. For people who think NLKSNES is the best emulator
because its the fastest - good luck finding a ROM it works with and enjoy the
silence. For people who think Bloodlust Software will be their only hope for
SNES emulation - enjoy the wait. For everyone else, please enjoy this release
and I'm sorry, but you'll just have to give me more time before a GUI/more
speed/transparency effects/better joystick support/DSP/SuperFX/screen
saving/cheat codes/net-link/speed-limiting code/<insert your favourite missing
feature here> are implemented.

Sorry for not being able to respond to every e-mail message I get - all are
read but wives/children/work/vacations/crappy mail reading programs all
conspire to prevent me from having the time to respond to every message.

Key Features
------------
o 16-bit, digital stereo sound on all ports. A large number of ROMs work with
  sound enabled, but most suffer from problems ranging from varying music
  playback speed to almost random noise output or silence. Sound emulation
  work is continuing.
o Two screen refresh methods, an accurate, but slow mode and a NLKSNES-type
  mode which is much faster - although not as fast as NLKSNES as it is coded
  in assembler - but only works well with some ROMs.
o Multiple screen mode supported on the Linux S-VGA and MS-DOS ports.
o Simultaneous two SNES joy-pad emulation allowing two player games to be
  played.
o Lots of ROMs work, the numbers are increasing with each release (slowly).
o Support for one 2, 4 or 6 button joystick or two 2-button joysticks - Linux
  and MS-DOS ports only.
o The only Snes emulator to have a large part of its documentation ripped
  off as well as its code.
o Speed, with a 100% assembler CPU emulation core on Linux and MS-DOS ports -
  it was the fastest SNES emulator around until recently and might be again
  one day.
o Snapshot a game in progress and restore the game to that exact point at
  a later time.
o Complete, fast mode 7 emulation (screen rotation and scaling) - all except
  one rarely used feature.
o Complete H-DMA emulation for those split screen and wavy background effects.
o Background clip windows for those H-DMA zoom effects.
o Variable CPU cycles length as on the real SNES, for fast and slow ROM
  emulation.
o Mosaic effect.
o Compressed and/or split ROM image support.
o SNES image scaling.
o 8-bit, 16-bit and 24-bit X11 server support.
o An uncrackable binary - mainly because it has no protection to crack such as
  time limits, limited colours, etc., etc. and never will.

What's New
----------
- Sound support on all ports.
- The name has changed!
- Multiple SPC700 CPU emulation fixes and several sound DSP fixes - many more
  ROMs work with sound enabled.
- Added fix for ROMs that re-use sprites during the same frame.
- Fixed bug I accidentally added to Allegro keyboard scanning code - now no
  more lock ups when Caps-lock or Pause pressed on DOS port.
- Documented some extra keys and command line options that have always been
  there.
- Asm CPU core speed ups.
- Minor bug fix that helps Final Fantasy 3.
- Added code to help some games that use sub-screen addition/subtraction.
  The lack of sub-screen addition/subtraction shows itself as background
  'priority' problems - now you don't have to toggle background layers on
  and off so often just to see hidden text, characters, or maps, etc.
  Use -L to enable. Toggle with '8' during a game to see if it makes a
  difference.
  Acts as a good intermediate solution until sub-screen addition/subtraction
  is actually implemented in a future release.
- Made several bug fixes to the old, but faster tile-based drawing code
  (enabled by pressing '9') - now several more ROMs work with it enabled.
- Modified sound skipper code - helps several ROMs that previously didn't work
  with the current selection of APU skippers.
- Improved sound mixing code so volume is not attenuated so much, giving
  better results on 8bit sound cards.
- Changed the frequency at which the joystick polling routine is called - now
  called every-other frame rather than every 3rd frame.
- Recompiled Linux and DOS ports with the Pentium optimising version of gcc -
  gives a few percent speed increase (on a Pentium processor).
- Fixed sprite priority bug with Mode 7 - apparently Final Fantasy 3 needs
  this.
- Fixed a screen clipping problem with the Linux S-VGA mode.
- Fixed bug that had crept in with -m 2 Linux S-VGA mode.
- Fixed S-VGA Linux version with sound enabled.
- Fixed #define problem that was stopping DOS snapshot saving from working.

What's Missing
--------------

Sub-screen addition and subtraction (used for transparency effects), offset
change mode (no idea what its used for), sound pitch modulation and echo
effects and pseudo 512 horizontal pixel mode.

A couple of other odd features that no ROMs seem to use are also missing:
direct colour output and interlaced display.

Some ROM cartridges contained additional hardware such as the SuperFX chip (a
16MHz RISC processor) or DSP chip, neither of these chips are emulated at the
moment so games that use them like Mario Kart, DOOM, Yoshi's Island, etc.
don't work.

What You Will Need
------------------

You will need a Pentium-class PC or higher running Linux, MS-DOS or Windows
95. Machines running MS-DOS will need at least 8Mb of RAM while machines
running Linux or Windows 95 will need at least 16Mb of RAM.

The Linux port requires a recent, stable kernel version; I'm using 2.0.27.
The Sun Solaris Sparc port requires a fast Sun Sparc workstation running
Solaris 5.x.  Both the UNIX ports are dynamically linked and will require
access to various shared libraries. Use ldd snes9x to make sure you have all
the required libraries on your system.
 
The Solaris port and the Linux X11 version will also need an X server running.

For sound output on the Linux port, your kernel will require the 2.0 sound
drivers configured and linked in. The MS-DOS port will require a Sound Blaster
sound card or register-level compatible card.

Access to SNES ROM images in *.smc, *.sfc, *.fig or *.1, *.2, or sf32xxxa,
sf32xxxb, etc., format will also help otherwise you will have nothing to run!
Several public domain images are available from:
http://www.rollanet.org/~khigh/emulator.htm

Some commercial ROM images are available via the Internet, try following links
from:
http://members.aol.com/zorkwiz/snesrom.htm

Please note, it is illegal in most countries to have commercial ROM images
without also owning the actual SNES ROM cartridge.

PLEASE DO NOT ASK JERREMY OR MYSELF FOR ROM IMAGES OR FOR INFORMATION ON WHERE
TO GET MORE, WE DO NOT KNOW AND WILL IGNORE ALL SUCH E-MAILS OR, IF WE ARE
HAVING A PARTICULARLY BAD DAY, FORWARD THE E-MAIL TO THE EMULATOR ABUSE
DATABASE.

Getting Started
---------------

From a shell or DOS session just type:
snes9x <ROM filename>

ROM images are normally loaded from the directory ./roms. This can be
changed by specifying a pathname with the image name or setting the
environment variable SNES96_ROM_DIR to point to a different directory.

Snapshot files and S-RAM save files are normally read from and written to the
directory $HOME/.snes96_snapshots for the UNIX ports or .\SNESNAPS for the
MS-DOS port. This can be changed by setting the environment variable
SNES96_SNAPSHOT_DIR to point to a different drive/directory.

Some command line flags are available:

Sound options:
-S Enable sound CPU emulation and actual sound output. Also allows several
   ROMs to run that used to get stuck in sound down-load code.
   DO NOT USE GAME SNAPSHOT FEATURE WITH SOUND CPU ENABLED.
-stereo Enable stereo sound output (needs high-end Pentium-class machine)
-r 0-7 Sound playback rate/quality:
       0 - disable sound, 1 - 8192, 2 - 11025, 3 - 16500, 4 - 22050 (default),
       5 - 29300, 6 - 36600, 7 - 44000.
Linux and Solaris ports only:
-B Buffer size in bytes 128-4096 (default auto-select for playback rate)

Speed up/slow down options: (See "Speeding Up The Emulation")
-f <frame skip count> (2)
-h <0-100> Percentage of cpu cycles to execute per scan line (100)
-O Enable old, cached-tiled based screen redrawing method. Gives noticeable
   speed increase but many ROMs can exhibit slight to severer screen redisplay
   problems.
-j Turn off automatic joystick detection (joystick polling on the PC slows
   the emulator down).

MS-DOS:
-m <0-8> Screen mode/resolution (try -m 2)
         0 - 320x240 ModeX, 1 - 320x200 VGA, 2 - 256x256 Non-standard VGA,
         3 - 640x480 Auto-detect, 4 - 640x480 VESA1, 5 - 640x480 VESA2
         6 - 640x480 VESA2 Linear, 7 - 640x400 Extended,
         8 - 800x600 Auto-detect.
-scale Scale SNES image to fit screen resolution.

Linux S-VGA:
-m <0-4> Screen mode/resolution (try -m 2)
         0 - 320x240 ModeX, 1 - 320x200 VGA, 2 - 256x256 Non-standard VGA,
         3 - 640x480 S-VGA, 4 - 800x600 S-VGA
-scale   Scale SNES image to fit screen resolution.

ROM image format options:
-i Inform emulator ROM image is in interleaved format.
-F Force Hi-ROM memory map for ROMs where the Hi-ROM header test fails.
-FL Force Lo-ROM memory map for ROMs where the Hi-ROM header test fails.
-o Enable old-style joy-pad emulation (required by a few ROMs, e.g.
   Super Bomber man 1, Star Wars trilogy)
-p Fool ROM into thinking this is a PAL SNES system.  (not usually
-n Fool ROM into thinking this is a NTSC SNES system.  required)
-ss <0-3> SPC-700 skip wait method (0) - NOT USED IF SOUND IS ENABLED.
          Use 1 for Metroid 3 and Animatics, and 3 for NBA Live 96.
-L Swap background layer priorities from background involved in sub-screen
   addition/subtraction. Can improve some games playability - no need to
   constantly toggle background layers on and off to read text/see maps, etc.
   Toggle feature on and off during game by pressing '8'.
-l <snapshot file name> Load snapshot file and required ROM image and restart
			game from saved position. DO NOT USE WITH -S OPTION.
-H Turn off the H-DMA emulation. Pressing '0' during a game toggles H-DMA
   on and off.
 
Joystick options:
-4 Joystick connected to computer has 4 buttons.
-6 Joystick connected to computer has 6 buttons.
-s Swap emulated joy-pad 1 and 2 around, pressing '6' during a game does the
   same thing.
-j Turn off automatic joystick detection.

For example, to start a game called "mario", with sound, tile-based redrawing
and 256x256 graphics mode, type:

snes9x -S -m 2 -O mario.smc

Keyboard Controls
-----------------

While the emulator is running:
'Escape'                 Quit the emulator
'Pause' or 'Scroll Lock' Pause the emulator

Joy-pad 1:
'up' or 'u'             Up direction
'down', 'j' or 'n'      Down direction
'left' or 'h'           Left direction
'right' or 'k'          Right direction
'a', 'v' or 'q'         TL button
'z', 'b' or 'w'         TR button
's', 'm' or 'e'         X button
'x', ',' or 'r'         Y button
'd', '.' or 't'         A button
'c', '/' or 'y'         B button
'Left Control' or 'Left Meta' Start button
'Left Shift'            Select button

Joy-pad 2:
'Keypad 8'              Up direction
'Keypad 2'              Down direction
'Keypad 6'              Left direction
'Keypad 4'              Right direction
'Insert'                TL button
'Delete'                TR button
'Home'                  X button
'End'                   Y button
'Page Up'               A button
'Page Down'             B button
'Right Control' or 'Right Meta'	Start button
'Right Shift'           Select button

'0'                     Toggle H-DMA emulation on/off.
'1'                     Toggle background 1 on/off (useful for speeding up the
'2'                     Toggle background 2 on/off  emulation and for ROMs
'3'                     Toggle background 3 on/off  that use colour addition in
'4'                     Toggle background 4 on/off  a certain way, e.g. zelda)
'5'                     Toggle sprites (OBJs) on/off
'6'                     Toggle swapping of joy-pad one and two around
'8'                     Toggle background layer priorities for backgrounds
                        involved in sub-screen addition/subtraction.
'9'			Toggle old, cached-tiled based screen redrawing method
			on/off. Gives noticeable speed increase but many ROMs
			can exhibit slight to severer screen redisplay
			problems.

'-'			Decrease frame redraw skip rate
'+'			Increase frame redraw skip rate
'F2'                    Load snapshot of game in progress (DO NOT USE WITH
'F3'                    Save snapshot of game in progress  SOUND CPU ENABLED)

'F4' -> 'F11'		Toggle sound channels on/off
'F12'			Turn on all sound channels.

Joystick Support
----------------

The Linux and MS-DOS ports of Snes9X supports one or two 2-button joysticks,
or one 4-button or 6-button joystick - this limitation is imposed by PC
hardware. The Linux port requires the kernel to have the joystick driver
compiled in or loaded as a module to enable Snes9X to access the joystick(s).
The driver source code is available from:
http://sunsite.unc.edu/pub/Linux/kernel/patches/console/joystick-0.8.0.tar.gz
Don't forget to also make the two devices in /dev - /dev/js0 and /dev/js1 and
make them readable by everyone; documentation supplied with the driver gives
details of this.

On a 2-button joystick only the A and B SNES buttons are available, the
remaining 4 can still be accessed via the keyboard.

The following diagram showing you the button layout for 6-button PC joy-pads
that look similar to real SNES joy-pads:

     ---TL---           ---TR---

        ^                  X
        |
     <-   ->            Y     A
        |       /  /
        v                  B


Make sure the joystick is centred or no buttons pressed for joy-pads when
the emulator is first started to enable auto-calibration to work.

For DOS users who want to use GRIP keyboard emulation support, use the -j
command line option to disable automatic joystick detection.

Linux S-VGA Full-Screen Mode
----------------------------

The Linux port of Snes9X is supplied as two binaries: snes9x for the
X Window System version and ssnes9x for the S-VGA 256x256 full-screen version.

The S-VGA version needs root permissions so it can write to the PC video
registers to change screen modes (the X server has the same problem). You can
either run as root (not recommended) or set the binary to run set-uid root as
follows:

Log on as root or su to root.
Change to the directory where the ssnes9x binary is stored.
Type:
chown root ssnes9x
chmod 4555 ssnes9x

Now the binary can be run by an ordinary user in much the same way the
X server can. The default VGA screen mode is 320x240x256 mode-X, which should
work on any system. However, mode-X slows down the emulator a little so you
might what to try using the -m 2 command line flag to see if the slightly
faster 256x256x256 screen mode is compatible with your system.

Problems With ROMs
------------------

If the emulator just displays a black screen for over 10 seconds then one
of the following could be true:

1) The ROM image is corrupt. More likely is the ROM image is in interleaved 
   format; use the -i command line flag to tell the emulator it is in this
   format.
2) Some ROMs have a bad ROM header, mostly home-brewed SNES games or hacked
   commercial games. Snes9X cannot then detect if it is a Lo-ROM or Hi-ROM
   game and just guesses. You might have to use the -F to force Hi-ROM or -FL
   to force Lo-ROM to help it out.
3) The ROM is in a loop waiting for the Sound CPU to respond with a particular
   value and the sound wait skip code in the emulator hasn't spotted the fact.
   Try using a different -ss command line option value in the range 0 to 3.
   You could also try the -S command line flag which enables the
   SPC700 emulation. This allows several ROMs to continue that previously were
   stuck in sound down-load code.
4) The ROMs FAST ROM protection check has failed and the ROM has deliberately
   crashed itself. The only thing you could try is one of the utilities on
   the 'net that remove such protection.
5) You have set the -h command line value too low.
6) The original SNES ROM cartridge had additional hardware inside that is not
   emulated yet - this is true for all SuperFX games (DOOM, etc.) and DSP
   games (Mario Kart, Yoshi's Island, etc.). Some of the later ROMs (1994+)
   had additional hardware as a form of protection (Williams Arcade Classics,
   Clay Fighters II, etc.). There is nothing you can do about these games
   except patching the ROM or wait until I emulate the missing hardware, but
   this must be done individually, for each game.  (Williams Arcade Classics
   is already supported).
7) The ROM image has found a CPU emulator instruction or memory map bug -
   please e-mail with name of ROM images that do this. Unfortunately, it is
   difficult to tell this problem from the protection failure problem
   described above without disassembling the ROM.

If the game starts normally but refuses to go beyond the title screen try
using the -o command line flag to enable old-style SNES joy-pad emulation or
try pressing '6' in the emulator to swap joy-pads around; Mario All Stars
swaps joy-pads around with old-style SNES joy-pad emulation enabled.

If the ROM says "This game is not for your system" or something similar,
try using the -p flag to force PAL mode or -n to force NTSC mode.

Also, some ROMs use background colour addition (which isn't emulated yet) in
such a way that is hides the character you are trying to control or important
scenery; try toggling the background layers on and off with the keys 1 to 4 to
see if you can find the background layer causing the problem and leave it
switched off or try pressing '8' which changes the background priority levels
for backgrounds involved in sub-screen addition/subtraction.

Converting ROM Images
---------------------

If you have a ROM image in several pieces, simply rename them so their
filename extensions are numbered: e.g. game.1, game.2, etc. Then, when
loading the ROM image, just specify the name of the first part; the remaining
parts will be loaded automatically.

If they are already in the form sf32xxxa, sf32xxxb, etc., you don't even have
to rename them; just specify the name of the first part, as above.

Speeding up the Emulation
-------------------------

Try the following command line flags:
-f <frame skip rate> (default 2: only every 3rd frame is rendered and
		      displayed)
	Increasing this value will speed up the emulator but make screen
	updates more jerky. During a game, the '+' and '-' keys increase or
	decrease the frame skip rate.

-O Enable cached-tile based screen redraw code. Pressing '9' during a game
   also toggles this redraw method on and off. It gives a very noticeable
   speed increase but can cause severer screen redisplay problems on some ROMs,
   which was why I removed the code in the first place. However, it might make
   all the difference for people with slower machines.

-h <CPU percentage of cycles per scan line to execute> (default 100)
	Lowering this value will also speed up the emulator but setting the
	value too low can cause problems from some ROMs because not
	enough CPU instructions are being executed per frame as the ROM
	expects and can actually slow down a game!

-m <screen mode> Some screen modes allow faster screen update than others,
        try -m 2 to see if the faster, non-mode X VGA mode is compatible with
        your system. MS-DOS users could try -m 3 or higher to try one of the
        VESA screen modes.

-j Disable automatic joystick detection. Reading joystick values on a PC takes
   a relatively long time. If you have a joystick attached to your computer
   that you are not using, use this option to stop the joystick from being
   polled.

DOS users should make sure they have a good DOS graphics card. For example,
Snes9X runs almost as fast on my P100 desktop machine as it does on my P166
laptop; the reason being CPU write access speed to the graphics memory on my
laptop is a lot slower than on my desktop machine. If you are suffering from a
slow write-access graphics card, wait for the Windows 95 port as that will use
hardware accelerated bit-blt, where available, to copy screen data into
memory on the graphics card.

Not enabling sound also speeds up the emulator because to get sound on an SNES
another 2.5MHz CPU must be emulated together with the eight channel sound DSP
and real-time sample decompression. If you must have sound, don't enable
stereo output and may be lower the playback rate.

Turning off some of the background layers by pressing '1' to '4' also speeds
up the emulator. As always, you could try running the emulator on a faster
machine/graphics card!

Credits
-------

A great big thank you to Steve Snake for his insights into SNES sound sample
decompression.

Many thanks must go to Jerremy Koot (jkoot@euronet.nl) because without all
his hard work on the original Snes96 and Snes97 Windows 95 versions, Snes9X
would not exist in its current form.

Thanks to Lee Hyde (lee@jlp1.demon.co.uk) and his quest for sound information.

Thanks also to a person who shall remain nameless for his continuing quest for
SNES information on my behalf (thanks to him, SuperFX emulation might be a
reality one day).

I would also like to thank Shawn Hargreaves (shawn@talula.demon.co.uk) for
the Allegro library which made porting Snes9X relatively easy and my many beta
testers - both official and unofficial!

SNES is a trademark of Nintendo. 
Sun, Solaris and Sparc are trademarks of Sun Microsystems, Inc.  
MS-DOS and Windows 95 are trademarks of the MicroSoft Corporation.

------------------------------------------------------------------------------
Gary Henderson (gary@daniver.demon.co.uk)
