		Snes9X v0.23 Released 14th October 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
Sound Problems
Converting ROM Images
Speeding up the Emulation
Credits

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

This read-me file describes the Linux i386 and Sun Solaris Sparc ports of
Snes9x, a freeware Super Nintendo Entertainment System (SNES) emulator.
Other ports are available: Jerremy Koot works on the Windows 95 port, Chad
Kitching looks after the DOS port and John Stiles works on the Mac port.

Snes9X is coded in C++ with an assembler CPU emulation core on the Linux and
MS-DOS ports. It is a spare-time project being written by myself and Jerremy
Koot. Chad Kitching has provided several bug fixes and suggestions in the
past.

Key Features
------------
o Speed: Snes9x now gives NLKSNES, formally the the fastest SNES emulator, a
  run for its money, while being more compatible, supporting sound and have
  more features. Also, many parts of Snes9x are still in C++; more speed
  could be gained be rewriting other parts of the emulator in assembler.
  NLKSNES is already written in assembler.
  Many games now play full speed on a P100 WITH SOUND will only a frame skip
  of one.
o 16-bit, digital stereo sound on all ports.
o Two screen refresh methods, an accurate, but slower mode and a much faster
  tile-based mode which now has all the features of the line-by-line code.
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 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 shaped H-DMA zoom effects.
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
----------
Snes9X v0.23
------------
- 16bit sound level lowered slightly to help sound clipping problems when
  all eight SNES sound channels are playing.
- Added option to disable graphic window effects - T2: The Arcade Game doesn't
  seem to like them.
- Mode 7 "outside screen area" register interpretation fixed - now the
  Actraiser map screen looks a better.
- Old DMA code hack for Battle Toads: Double Dragon removed as it was no
  longer required and it was causing problems for Ys III.
  Use -h 100 to actually play Battle Toads.

Snes9X v0.22
------------
- Crash bug fixed in mode 7 tile-based graphics window code.

Snes9X v0.21
------------
- Tile redraw code now supports mosaic and multi-window graphics effects -
  no need to use the slower line-by-line graphics engine at all.
- Fixed sprite priority problem on mode 7 screen when using tile redraw.
- All tiles from background #2 was not always been drawn on mode 1.
- Fixed some graphic glitches on some split screen effects when using tile
  redraw method.
- Minor sound speed ups.
- Added support to DMA code for ROMs that rely on the DMA memory accesses
  wrapping inside the same bank.
- Noise sound channel volume clipping bug fixed.
- 24bit X Window System server support fixed on Solaris (I think).

Snes9X v0.2
-----------
- C++ and assembler CPU emulations rewritten with many speed improvements.
- SPC700 emulation speeded up and partially rewritten in assembler.
- Line-by-line graphics code rewritten for more speed - still have lots more
  ideas on how to improve speed further.
- Tile-based graphics code rewritten for  a major speed increase, and
  its features extended to support all those in the line-based code except
  for mosaic and graphic window effects.
- Tile-based graphics code now the default redraw method.
- DMA code rewritten for speed - really helps ROMs that make use of a lot of
  DMA.
- Mode 7 screen rotation code rewritten for a major speed increase. Also,
  several scrolling offset bugs fixed.
- Several sound code fixes and speed ups.
- LoROM S-RAM memory map bug fixed. Now Uniracers works plus several others.
- V-RAM reading bug fixed. This fixed at least three ROMs that I know of.
- Variable-cycle length emulation removed as a fixed-length cycle emulation
  was faster to implement. Unfortunately, this has broken compatibility with
  several ROMs which I'll try and fix soon.
- Auto-frame rate adjust can now be turned on and off using the +/- keys.

Snes9X v0.12
------------
- Auto-frame rate adjust to keep a constant game and music speed - idea from
  Bloodlust (thanks).
- Sound state now saved and restored in snapshot files.
- Pro Action Reply, Game Genie(TM) and Gold Finger cheat code support.
- Added long name forms of all the command line switches.
- Added option to disable a few "internal" speed up hacks that caused problems
  for some games with sound enabled - e.g. Super Off Road Racing.
- Sound code rewritten to help support a group of ROMs that spool sound data
  between the two the CPUs in real-time, although I'm still having timing
  problems with these ROMs.
- Fixed memory locking problem on the MS-DOS port. It was effectively
  preventing virtual memory from working, causing problems for people with
  limited RAM.
- A few more sound fixes.
- Speed ups to the tile-based redraw code.

Snes9X v0.1
-----------
- 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.

Coming Soon
-----------
- Linux and Solaris versions with a GUI.
- Sub-screen addition/subtraction using a full 32000 colour screen mode - none
  of this simulate-in-256-colours rubbish.

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, pseudo 512 horizontal pixel mode and an interlaced display are all
missing. Also, colour palette changes during the frame are not emulated
correctly.

A couple of other odd features that no ROMs seem to use are also missing.

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
------------------

The Linux port requires a Pentium-class PC or higher running Linux with 16Mb
or more of RAM and 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.

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:
http://www.fortunecity.com/tattooine/hal/71/index.htm or
http://gameland.duth.gr

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 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. This can be changed by setting the
environment variable SNES96_SNAPSHOT_DIR to point to a different directory.

Some command line flags are available:

Sound options:
-S or -sound (default: on)
   Enable sound CPU emulation and actual sound output.
-NS or -nosound
   Disable sound CPU emulation and sound output, useful for the few ROMs
   where sound emulation causes them to lock up due to timing errors.
-stereo (default: mono)
   Enable stereo sound output (requires more CPU power to implement)
-r 0-7 or -soundquality 0-7 (default: 4)
   Sound playback rate/quality:
       0 - disable sound, 1 - 8192, 2 - 11025, 3 - 16500, 4 - 22050 (default),
       5 - 29300, 6 - 36600, 7 - 44000.
-B size or -buffersize size (default: auto-select)
   Sound playback buffer size in bytes 128-4096

Cheat options:
-gg <code> or -gamegenie <code>
   Supply a Game Genie code for the current ROM. Up to 10 codes can be in
   affect at once. Game Genie codes for many SNES games are available from:
   http://game-genie.nvc.cc.ca.us
-ar <code> or -actionreplay <code>
   Supply a Pro-Action Reply code for the current ROM. Up to 10 codes can be in
   affect at once. At the moment, codes which alter RAM do not work.
-gf <code> or -goldfinger <code>
   Supply a Gold Finger code for the current ROM. Up to 10 codes can be in
   affect at once.

Speed up/slow down options: (See "Speeding Up The Emulation")
-f <frame skip count> or -frameskip <frame skip count> (default: auto-adjust)
   Set this value to deliberately fix the frame skip rate and disable auto-
   speed regulation. Use a larger value faster emulation but more jerky
   movement and a smaller value for smooth but slower screen updates.
   Use '+' and '-' keys to modify the value during a game.
-h <0-200> or -cycles <0-200>(default: 90)
   Percentage of CPU cycles to execute per scan line, decrease value to
   increase emulation frame rate. Most ROMs work with a value of 85 or above.
-O or -tileredraw (default: enabled)
   Enable cached-tiled based screen redrawing method. Gives a very noticeable
   frame rate increase.
-NO or -lineredraw (default: tile redraw)
   Enable line-by-line redraw method. Slower than the cached-tile method but
   future versions might support more emulation features than the tile
   method.
-j or -nojoy
   Turn off automatic joystick detection (joystick polling on the PC slows
   the emulator down).

Linux S-VGA:
-m <0-4> or -mode <0-4> (default: 2)
   Screen mode/resolution (try -m 0 if the default mode is not compatible
                           with your hardware)
         0 - 320x240 ModeX, 1 - 320x200 VGA, 2 - 256x256 Non-standard VGA,
         3 - 640x480 S-VGA, 4 - 800x600 S-VGA
-scale (default: no scale)
   Scale SNES image to fit screen resolution (doesn't work with ModeX screen).

ROM image format options:
-i or -interleaved (default: auto-detect 32Mbit ROM images)
   Inform emulator ROM image is in interleaved format.
-FH or -F or -forcehirom (default: auto-detect)
   Force Hi-ROM memory map for ROMs where the Hi-ROM header test fails.
-FL or -forcelorom (default: auto-detect)
   Force Lo-ROM memory map for ROMs where the Hi-ROM header test fails, e.g
   Micro Machines, Pacman, Double Dragon.
-o or -old (default: disabled)
   Enable old-style joy-pad emulation (required by a few ROMs, e.g.
   Super Bomber man 1, Star Wars trilogy)
-p or -pal (default: auto-detect)
   Fool ROM into thinking this is a PAL SNES system.
-n or -ntsc (default: auto-detect)
   Fool ROM into thinking this is a NTSC SNES system.
-ss <0-3> or -soundskip <0-3> (default: 0)
   SPC-700 skip wait method - NOT USED IF SOUND IS ENABLED.
   Use 1 for Metroid 3 and Animatics, and 3 for NBA Live 96.
-L or -layering (default: off)
   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> or -loadsnapshot <snapshot file name>
   Load snapshot file and required ROM image and restart game from saved
   position.
-H or -nohdma (default: H-DMA enabled)
   Turn off the H-DMA emulation. Pressing '0' during a game toggles H-DMA on
   and off. Only use if H-DMA causes a problem for a game, e.g.
   Super Punchout.
-N or -nospeedhacks (default: speed hacks)
   Turn off a couple of speed hacks. The hacks boost the speed of many ROMs
   with sound enabled but cause problems a few ROMs, e.g. Super Off-Road Racer.
-nw or -Settings.DisableGraphicWindows (default: graphics windows emulated)
   Disable graphics windows emulation - use for T2: The Arcade Game until I
   can figure out where the bug is.

Joystick options:
-4 or -four (default: auto-detect two-button joystick)
   Joystick connected to computer has 4 buttons.
-6 or -six (default: auto-detect two-button joystick)
   Joystick connected to computer has 6 buttons.
-s or -swap
   Swap emulated joy-pad 1 and 2 around, pressing '6' during a game does the
   same thing.
-j or -nojoy
   Turn off automatic joystick detection (joystick polling on the PC slows
   the emulator down).

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

snes9x 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.
'BackSpace'		Toggle emulation of graphics window effects on/off.
			Disable effects to play T2: The Arcade Game.

'-'			Decrease frame redraw skip rate
'+'			Increase frame redraw skip rate
			The sequence is auto-frame rate adjust, render every
                        frame, render 1 frame in two, render 1 frame in three,
                        render 1 frame in four, etc.
'F2'                    Load a game's saved position
'F3'                    Save a game's position

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

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

The Linux port 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 kernel must 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.

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 256x256x256, which might not
work on your system. Try using the -m 0 command, if that's the case, to
enable the slower, but more compatible 320x240 mode-x screen mode.

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. Try turning off sound support. You might also have to change the
   sound skip method using the -ss command line option.
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.). 
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 or -frameskip <frame skip rate> (default auto-adjust)
   Set this value to deliberately fix the frame skip rate and disable auto-
   speed regulation. Use a larger value for faster emulation but more jerky
   movement and a smaller value for smooth but slower screen updates.
   Use '+' and '-' keys to modify the value during a game.

-ft or -frametime <Milliseconds per emulated frame> (default: 20)
   If auto-speed regulation is in effect, this value is used as the time, in
   milliseconds, that an emulated frame should take. The frame skip rate
   is automatically adjusted or the CPU paused to try and maintain this
   target. 486 and low-end Pentium machines might never be able to hit the
   default 20ms target with sound enabled, so you might want to increase this
   value to maintain a constant, but slower game speed.
   Under Linux and Solaris this value is currently limited to next greater
   10ms value.

-h or -cycles <CPU percentage of cycles execute> (default: 90)
   Lowering this value will increase the frame rate 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! Most games work with a value
   of 85 or above.

-m or -mode <screen mode> (default: 2)
   Some screen modes allow faster screen update than others, -m 2, the default
   is usually the fastest on most systems, but try the other modes, you never
   know.

-j or -nojoy (default: auto-detect)
   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.

Disabling 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 also consider lowering 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
-------

Game Genie(TM), Gold Finger and Pro Action Replay cheat system information was
obtained from DiskDude's SNES Kart v1.6 document.

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) for his quest for sound information
and the Windows 95 icon.

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).

SNES is a trademark of Nintendo. 
Sun, Solaris and Sparc are trademarks of Sun Microsystems, Inc.  
Game Genie is a trademark of Lewis Galoob Toys, Inc.
------------------------------------------------------------------------------
Gary Henderson (gary@daniver.demon.co.uk)
