This is brief description of the steps to port Snes9x to the new platform which is at least similar to Workstation or PC. It describes what code you have to write and what functions exist that you can make use of. It also gives some insights as to how Snes9x actually works, although that will be subject of another document yet to be written.
A C++ compiler. Snes9x really isn't written in C++, it just uses the C++ compiler as a “better C” compiler to get inline functions and so on. GCC is good for compiling Snes9x (http://gcc.gnu.org/).
A fast CPU. SNES emulation is very compute intensive; two, or sometimes three CPUs to emulate, an 8-channel 16-bit stereo sound digital signal processor with real-time sample decompression, filter and echo effects, two custom graphics processor chips that can produce transparency, scaling, rotation and window effects in 32768 colors, and finally hardware DMA all take their toll on the host CPU.
Enough RAM. Snes9x uses 8MB to load SNES ROM images and several MB for emulating sound, graphics, custom chips, and so on. Moreover, additional tens MB will be required when Snes9x loads graphics packs used in S-DD1 and SPC7110 games.
A 16-bit color (two bytes per pixel) or deeper display, at least 512*478 pixels in resolution. Pixel format conversion may be required before you place the rendered SNES screen on to the display.
Sound output requires spooling 8-bit or 16-bit, mono or stereo digital sound data to the host sound system. Some ports can use interrupts or callbacks from the sound system to know when more sound data is required, most other ports have to periodically poll the host sound system to see if more data is required; if it is then the sound mixing code is called to fill the sound buffer with SNES sound data, which then can be passed on to the host sound system. Sound data is generated as an array of bytes (uint8) for 8-bit sound or shorts (int16) for 16-bit data. Stereo sound data generates twice as many samples, with each channel's samples interleaved, first left's then right's.
For the user to be able to control and play SNES games, some form of input device is required, a joypad or keyboard, for example. The real SNES can have 2 eight-button digital joypads connected to it or 5 joypads when an optional multi-player adaptor is connected, although most games only require a single joypad. Access to all eight buttons and the direction pad, of course, are usually required by most games. Snes9x does emulate the multi-player adaptor hardware, if you were wondering, but its still up to you to provide the emulation of the individual joypads.
The real SNES also has a SNES mouse, Super Scope and Justifier (light-gun) available as optional extras. Snes9x can emulate all of these using some form of pointing device, usually the host system's mouse.
Some SNES game cartridges contains a small amount of extra RAM and a battery, so ROMs could save a player's progress through a game for games that takes many hours to play from start to finish. Snes9x simulates this S-RAM by saving the contents of the area of memory occupied by the S-RAM into a file then automatically restoring it again the next time the user plays the same game. If the hardware you're porting to doesn't have a storage media available then you could be in trouble.
Snes9x also implements freeze-game files which can record the state of the SNES hardware and RAM at a particular point in time and can restore it to that exact state at a later date - the result is that users can save a game at any point, not just at save-game or password points provided by the original game coders. Each freeze file is over 400k in size. To help save disk space, Snes9x can be compiled with zlib (http://www.zlib.net/), which is used to GZIP compress the freeze files, reducing the size to typically below 100k. zlib is also used to load GZIP or ZIP compressed ROM images. Additionally, Snes9x supports JMA archives compressed with NSRT (http://nsrt.edgeemu.com/).
DEBUGGER
Enables extra code to assist you in debugging SNES ROMs. The debugger has only ever been a quick-hack and user-interface to debugger facilities is virtually non-existent. Most of the debugger information is output via stdout and enabling the debugger slows the whole emulator down slightly. However, the debugger options available are very powerful; you could use it to help get your port working. You probably still want to ship the finished version with the debugger disabled, it will only confuse non-technical users.
RIGHTSHIFT_IS_SAR
Define this if your compiler uses shift right arithmetic for signed values. For example, GCC and Visual C++ use shift right arithmetic.
NO_INLINE_SET_GET
Define this to stop several of the memory access functions (S9xGetByte, S9xSetByte, S9xGetWord and S9xSetWord) from being defined inline. Whether the C++ compiler actually inlines when this symbol is not defined is up to the compiler itself. Inlines functions can speed up the emulation on some architectures at the cost of increased code size. Try fiddling with this option once you've got port working to see if it helps the speed of your port.
CPU_SHUTDOWN / SPC700_SHUTDOWN
They are both speed up hacks. When defined and if Settings.ShutdownMaster is true, Snes9x starts watching for when either the main or sound CPU is in a simply loop waiting for a known event to happen - like the end of the current scanline, and interrupt or a sound timer to reach a particular value. If Snes9x spots either CPU in such a loop, it simply skips the emulation of that CPU's instructions until the event happens. It can be a big win with lots of SNES games, but will break a small number of games. In this case, set Settings.ShutdownMaster to false before you load a ROM image. It disables both hacks. Note that these hacks are forcibly disabled in some games. See Memory.ApplyROMFixes function for the list of such games.
CORRECT_VRAM_READS
You must define this. It allows correct VRAM reads.
NEW_COLOUR_BLENDING
Highly recommended. It enables the most accurate but slowest color math. To the contrary, OLD_COLOUR_BLENDING enables the fastest but most inaccurate color math.
ZLIB / UNZIP_SUPPORT / JMA_SUPPORT
Define these if you want to support GZIP/ZIP/JMA compressed ROM images and GZIP compressed freeze-game files.
ZSNES_FX / ZSNES_C4
Define these if your CPU is x86 compatible and you're going to use the ZSNES Super FX and C4 assembler codes.
USE_OPENGL
Define this and set Settings.OpenGLEnable to true, then you'll get the rendered SNES image as one OpenGL texture.
ZLIB
UNZIP_SUPPORT
JMA_SUPPORT
CPU_SHUTDOWN
SPC700_SHUTDOWN
NEW_COLOUR_BLENDING
RIGHTSHIFT_IS_SAR
CORRECT_VRAM_READS
You may need to edit port.h to fit Snes9x to your system.
If the byte ordering of your system is least significant byte first, make sure LSB_FIRST is defined, otherwise make sure it's not defined.
You'll need to make sure what pixel format your system uses for 16-bit colors (RGB565, RGB555, BGR565 or BGR555), and if it's not RGB565, define PIXEL_FORMAT to it so that Snes9x will use it to render the SNES screen. For example, Windows uses RGB565, Mac OS X uses RGB555. If your system supports more than one pixel format, you can define GFX_MULTI_FORMAT and change Snes9x's pixel format dynamically by calling S9xSetRenderPixelFormat function. If your system is 24 or 32-bit only, then don't define anything; instead write a conversion routine that will take a complete rendered 16-bit SNES screen in RGB565 format and convert to the format required to be displayed on your system.
port.h also typedefs some types; uint8 for an unsigned 8-bit quantity, uint16 for an unsigned 16-bit quantity, uint32 for a 32-bit unsigned quantity and bool8 for a true/false type. Signed versions are also typedef'ed.
The CHECK_SOUND macro can be defined to invoke some code that polls your sound system to see if it can accept any more sound data. Snes9x makes calls to this macro several times when it is rendering the SNES screen, during large SNES DMAs and after every emulated CPU instruction. Since this CHECK_SOUND macro is invoked often, the code should only take a very small amount of time to execute or it will slow down the emulator's performance. The UNIX/Linux ports use a system timer and set a variable when it has expired; the CHECK_SOUND only has to check to see if the variable is set. On the Mac OS X port, it is driven by callbacks and the CHECK_SOUND macro is defined to be empty.
Read controls.h, crosshair.h, controls.txt and control-inputs.txt for details. This section is the minimal explanation to get the SNES controls workable.
The real SNES allows several different types of devices to be plugged into the game controller ports. The devices Snes9x emulates are a joypad, multi-player adaptor known as the Multi Player 5 or Multi Tap (allowing a further 4 joypads to be plugged in), a 2-button mouse, a light gun known as the Super Scope, and a light gun known as the Justifier.
In your initialization code, call S9xUnmapAllControl function.
Map any IDs to each SNES controller's buttons and pointers. (ID 249-255 are reserved).
Typically, use S9xMapPointer function for the pointer of the SNES mouse, Super Scope and Justifier, S9xMapButton function for other buttons. Set poll to false for the joypad buttons, true for the other buttons and pointers.
S9xMapButton(k1P_A_Button, s9xcommand_t cmd = S9xGetCommandT("Joypad1 A"), false);
In your main emulation loop, after S9xMainLoop function is called, check your system's keyboard/joypad, and call S9xReportButton function to report the states of the SNES joypad buttons to Snes9x.
void MyMainLoop (void)
{
S9xMainLoop();
MyReportButttons();
}
void MyReportButtons (void)
{
S9xReportButton(k1P_A_Button, (key_is_pressed ? true : false));
}
Prepare your S9xPollButton and S9xPollPointer function to reply Snes9x's request for other buttons/cursors states.
Call S9xSetController function. It connects each input device to each SNES input port.
Here's typical controller settings that is used by the real SNES games:
Joypad
S9xSetController(0, CTL_JOYPAD, 0, 0, 0, 0);
S9xSetController(1, CTL_JOYPAD, 1, 0, 0, 0);
Mouse (port 1)
S9xSetController(0, CTL_MOUSE, 0, 0, 0, 0);
S9xSetController(1, CTL_JOYPAD, 1, 0, 0, 0);
Mouse (port 2)
S9xSetController(0, CTL_JOYPAD, 0, 0, 0, 0);
S9xSetController(1, CTL_MOUSE, 1, 0, 0, 0);
Super Scope
S9xSetController(0, CTL_JOYPAD, 0, 0, 0, 0);
S9xSetController(1, CTL_SUPERSCOPE, 0, 0, 0, 0);
Multi Player 5
S9xSetController(0, CTL_JOYPAD, 0, 0, 0, 0);
S9xSetController(1, CTL_MP5, 1, 2, 3, 4);
Justifier
S9xSetController(0, CTL_JOYPAD, 0, 0, 0, 0);
S9xSetController(1, CTL_JUSTIFIER, 0, 0, 0, 0);
Justifier (2 players)
S9xSetController(0, CTL_JOYPAD, 0, 0, 0, 0);
S9xSetController(1, CTL_JUSTIFIER, 1, 0, 0, 0);
bool8 Memory.Init (void)
Allocates and initializes several major lumps of memory, for example the SNES ROM and RAM arrays, tile cache arrays, etc. Returns false if memory allocation fails.
void Memory.Deinit (void)
Deallocates the memory allocations made by Memory.Init function.
bool8 S9xGraphicsInit (void)
Allocates and initializes several lookup tables used to speed up SNES graphics rendering. Call after you have initialized the GFX.Screen and GFX.Pitch values. Returns false if memory allocation fails.
void S9xGraphicsDeinit (void)
Deallocates the memory allocations made by S9xGraphicsInit function.
bool8 S9xInitAPU (void)
Allocates and initializes several arrays used by the sound CPU and sound generation code. Returns false if memory allocation fails.
void S9xDeinitAPU (void)
Deallocates the allocations made by S9xInitAPU function.
bool8 S9xInitSound (int mode, bool8 stereo, int buffer_size)
Does more sound code initialization and opens the host system's sound device by calling S9xOpenSoundDevice function provided by you.
In practice, Snes9x uses the stereo value but the rest two are not used and just passed to S9xOpenSoundDevice function, so you can decide the usage of mode and buffer_size by yourself.
void S9xReset (void)
Resets the SNES emulated hardware back to the state it was in at “switch-on” except the S-RAM area is preserved (“hardware reset”). The effect is it resets the current game back to the start. This function is automatically called by Memory.LoadROM function.
void S9xSoftReset (void)
Similar to S9xReset function, but “software reset” as you press the SNES reset button.
bool8 Memory.LoadROM (const char *filepath)
Attempts to load the specified ROM image filename into the emulated ROM area. There are many different SNES ROM image formats and the code attempts to auto-detect as many different types as it can and in a vast majority of the cases gets it right.
There are several ROM image options in the Settingsstructure; allow the user to set them before calling Memory.LoadROM function, or make sure they are all reset to default values before each call to Memory.LoadROM function. See Settings.ForceXXX in snes9x.h.
bool8 Memory.LoadMultiCart (const char *cartApath, const char *cartBpath)
Attempts to load multiple ROM images into the emulated ROM area, for the multiple cartridge systems such as Sufami Turbo, Same Game, etc.
bool8 Memory.LoadSRAM (const char *filepath)
Call this function to load the associated S-RAM save file (if any). The filename should be based on the ROM image name to allow easy linkage. The current ports change the directory and the filename extension of the ROM filename to derive the S-RAM filename.
bool8 Memory.SaveSRAM (const char *filepath)
Call this function to save the emulated S-RAM area into a file so it can be restored again the next time the user wants to play the game. Remember to call this when just before the emulator exits or when the user has been playing a game and is about to load another one.
void S9xMainLoop (void)
The emulator main loop. Call this from your own main loop that calls this function (if a ROM image is loaded and the game is not paused), processes any pending host system events, then goes back around the loop again until the emulator exits. S9xMainLoop function normally returns control to your main loop once every emulated frame, when it reaches the start of scan-line zero. However, the function can return more often if the DEBUGGER compile-time flag is defined and the CPU has hit a break point, or the DEBUG_MODE_FLAG bit is set in CPU.Flags or instruction single-stepping is enabled.
void S9xMixSamples (uint8 *buffer, int sample_count)
Call this function from your host sound system handling code to fill the specified buffer with ready mixed SNES sound data. If 16-bit sound mode is chosen, then the buffer will be filled with an array of sample_count int16, otherwise an array of sample_count uint8. If stereo sound generation is selected the buffer is filled with the same number of samples, but in pairs, first a left channel sample followed by the right channel sample. There is a limit on how much data S9xMixSamples function can deal with in one go and hence a limit on the sample_count value; the limit is the value of the MAX_BUFFER_SIZE symbol, normally 4096 bytes.
void S9xSetPlaybackRate (uint32 playback_rate)
Call this function when initializing your sound system, typically in S9xOpenSoundDevice function. 32000 is recommended because the real SNES uses 32000Hz. The max value is 48000.
bool8 S9xSetSoundMute (bool8 mute)
Call with a true parameter to prevent S9xMixSamples function from processing SNES sample data and instead just filling the return buffer with silent sound data. Useful if your sound system is interrupt or callback driven and the game has been paused either directly or indirectly because the user interacting with the emulator's user interface in some way.
bool8 S9xFreezeGame (const char *filepath)
Call this function to record the current SNES hardware state into a file, the file can be loaded back using S9xUnfreezeGame function at a later date effectively restoring the current game to exact same spot. Call this function while you're processing any pending system events when S9xMainLoop function has returned control to you in your main loop.
bool8 S9xUnfreezeGame (const char *filepath)
Restore the SNES hardware back to the exactly the state it was in when S9xFreezeGame function was used to generate the file specified. You have to arrange the correct ROM is already loaded using Memory.LoadROM function, an easy way to arrange this is to base freeze-game filenames on the ROM image name. The UNIX/Linux ports load freeze-game files when the user presses a function key, with the names romfilename.000 for F1, romfilename.001 for F2, etc. Games are frozen in the first place when the user presses Shift-function key. You could choose some other scheme.
void S9xSetInfoString (const char *string)
Call this function if you want to show a message onto the SNES screen.
See movie.h and movie.cpp to support the Snes9x movie feature.
See cheats.h, cheats.cpp and cheats2.cpp to support the cheat feature.
bool8 S9xOpenSnapshotFile (const char *filepath, bool8 read_only, STREAM *file)
This function opens a freeze-game file. STREAM is defined as a gzFile if ZLIB is defined else it's defined as FILE *. The read_only parameter is set to true when reading a freeze-game file and false when writing a freeze-game file. Open the file filepath and return its pointer file.
void S9xCloseSnapshotFile (STREAM file)
This function closes the freeze-game file opened by S9xOpenSnapshotFile function.
void S9xExit (void)
Called when some fatal error situation arises or when the “q” debugger command is used.
bool8 S9xInitUpdate (void)
Called just before Snes9x begins to render an SNES screen. Use this function if you should prepare before drawing, otherwise let it empty.
bool8 S9xDeinitUpdate (int width, int height)
Called once a complete SNES screen has been rendered into the GFX.Screen memory buffer, now is your chance to copy the SNES rendered screen to the host computer's screen memory. The problem is that you have to cope with different sized SNES rendered screens: 256*224, 256*239, 512*224, 512*239, 512*448 and 512*478.
void S9xMessage (int type, int number, const char *message)
When Snes9x wants to display an error, information or warning message, it calls this function. Check in messages.h for the types and individual message numbers that Snes9x currently passes as parameters.
The idea is display the message string so the user can see it, but you choose not to display anything at all, or change the message based on the message number or message type.
Eventually all debug output will also go via this function, trace information already does.
bool8 S9xOpenSoundDevice (int mode, bool8 stereo, int buffer_size)
S9xInitSound function calls this function to actually open the host sound device. The three parameters are the just the same as you passed in S9xInitSound function.
const char *S9xGetFilename (const char *extension, enum s9x_getdirtype dirtype)
When Snes9x needs to know the name of the cheat/ips file and so on, this function is called. Check extension and dirtype, and return the appropriate filename. The current ports return the ROM file path with the given extension.
const char *S9xGetFilenameInc (const char *extension, enum s9x_getdirtype dirtype)
Almost the same as S9xGetFilename function, but used for saving SPC files etc. So you have to take care not to delete the previously saved file, by increasing the number of the filename; romname.000.spc, romname.001.spc, ...
const char *S9xGetDirectory (enum s9x_getdirtype dirtype)
Called when Snes9x wants to know the directory dirtype.
extern "C" char *osd_GetPackDir (void)
Called when Snes9x wants to know the directory of the SPC7110 graphics pack.
const char *S9xChooseFilename (bool8 read_only)
If you port can match Snes9x's built-in LoadFreezeFile/SaveFreezeFile command (see controls.cpp), you may choose to use this function. Otherwise return NULL.
const char *S9xChooseMovieFilename (bool8 read_only)
If you port can match Snes9x's built-in BeginRecordingMovie/LoadMovie command (see controls.cpp), you may choose to use this function. Otherwise return NULL.
const char *S9xBasename (const char *path)
Called when Snes9x wants to know the name of the ROM image. Typically, extract the filename from path and return it.
void S9xAutoSaveSRAM (void)
If Settings.AutoSaveDelay is not zero, Snes9x calls this function when the contents of the S-RAM has been changed. Simply call Memory.SaveSRAM function from this function.
void S9xGenerateSound (void)
Use this function if you defined CHECK_SOUND in port.h.
void S9xToggleSoundChannel (int c)
If you port can match Snes9x's built-in SoundChannelXXX command (see controls.cpp), you may choose to use this function. Otherwise return NULL. Basically, turn on/off the sound channel c (0-7), and turn on all channels if c is 8.
void S9xSetPalette (void)
Called when the SNES color palette has changed. Use this function if your system should change its color palette to match the SNES's. Otherwise let it empty.
void S9xSyncSpeed (void)
Called at the end of S9xMainLoop function, when emulating one frame has been done. You should adjust the frame rate in this function.
void S9xLoadSDD1Data (void)
Called when the S-DD1 game is being loaded. If the user wants to use the on-the-fly S-DD1 decoding, simply set Settings.SDD1Pack to true and return. Otherwise, set Settings.SDD1Pack to false, allocates two memory spaces, read the graphics pack files (sdd1gfx.idx and sdd1gfx.dat) into the spaces, and set each Memory.SDD1XXX value correctly.
uint16 *GFX.Screen
A uint16 array pointer to (at least) 2*512*478 bytes buffer where Snes9x puts the rendered SNES screen. However, if your port will not support hires mode (Settings.SupportHiRes = false), then a 2*256*239 bytes buffer is allowed. You should allocate the space by yourself. As well you can change the GFX.Screen value after S9xDeinitUpdate function is called so that double-buffering will be easy.
uint32 GFX.Pitch
Bytes per line (not pixels per line) of the GFX.Screen buffer. Typically set it to 1024. When the SNES screen is 256 pixels width and Settings.OpenGLEnable is false, last half 512 bytes per line are unused. When Settings.OpenGLEnable is true, GFX.Pitch is ignored.
int spc_is_dumping
Set this to 1 when the user is requesting SPC dumping. The SPC file will be saved when the next key-on event comes.
void (*LoadUp7110) (char *) / uint16 cacheMegs
LoadUp7110 is a pointer to the function that loads SPC7110 graphics packs. Set this to &SPC7110Load if the user want to store all the data (several tens MB) into memory, &SPC7110Grab to store cacheMegs MB data into memory, or &SPC7110Open not to store any data into memory.
There are various switches in the Settings structure. See snes9x.h for details. At least the settings below are required for good emulation.
memset(&Settings, 0, sizeof(Settings));
Settings.MouseMaster = true;
Settings.SuperScopeMaster = true;
Settings.MultiPlayer5Master = true;
Settings.JustifierMaster = true;
Settings.ShutdownMaster = false;
Settings.BlockInvalidVRAMAccess = true;
Settings.HDMATimingHack = 100;
Settings.APUEnabled = true;
Settings.NextAPUEnabled = true;
Settings.SoundPlaybackRate = 32000;
Settings.Stereo = true;
Settings.SixteenBitSound = true;
Settings.SoundEnvelopeHeightReading = true;
Settings.DisableSampleCaching = true;
Settings.InterpolatedSound = true;
Settings.Transparency = true;
Settings.SupportHiRes = true;
Settings.SDD1Pack = true;