porting.txt

SFC游戏模拟器 snes9x 1.43 的原代码

restoring the current game to exact same spot. Call this routine while
you're processing any pending system events when S9xMainLoop has returned
control to you in your main loop.

-> bool8 S9xUnfreezeGame (const char *filename)

Restore the SNES hardware back to the exactly the state it was in when
S9xFreezeGame was used to generate the file specified. You have to arrange
the correct ROM is already loaded using Memory.LoadROM, an easy way to
arrange this is to base freeze-game filenames on the ROM image name. The
Linux, UNIX and DOS 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 S9xNextController ()

The real SNES allows several different types of devices to be plugged into
the game controller ports. The devices Snes9x emulates are a joy-pad,
multi-player adaptor (allowing a further 4 joy-pads to be plugged in),
a 2-button mouse and a light gun known as the SuperScope.

Each call to S9xNextController will step the current emulated device on to
the next device in the sequence multi-player, joy-pad, mouse on port 1,
mouse on port 2, light gun then back to multi-player again. Defines
allocating a number of each device type are in snes9x.h. The currently
selected device is stored in IPPU.Controller if you want to give some
feedback to the user. The initial value of IPPU.Controller (set when
S9xReset is called) is obtained from Settings.ControllerOption based on
currently enabled options.

Some ROMs object to certain non-joy-pad devices being plugged into the real
SNES while they are running, all Super FX games should only allow joy-pads to
be plugged in because the Super FX chip and any other device would overload
the SNES power supply. Tetris and Dr. Mario also objects for reasons best
known to itself. For this reason there are switches in the Settings
structure to enable and display the emulation of the various devices.

const char *S9xGameGenieToRaw (const char *code, uint32 &address, uint8 &byte)

const char *S9xProActionReplayToRaw (const char *code, uint32 &address, 
                                     uint8 &byte)

const char *S9xGoldFingerToRaw (const char *code, uint32 &address, bool8 &sram,
			        uint8 &num_bytes, uint8 bytes[3])

void S9xApplyCheats (bool8 apply)

void S9xRemoveCheats ()

void S9xAddCheat (uint32 address, bool8 cpu_address, bool8 sram, uint8 num_bytes,
	          uint8 byte1, uint8 byte2, uint8 byte3)

void S9xDeleteCheats ()

void S9xDoDebug ()

Interface Routines You Need to Implement
----------------------------------------

bool8 S9xOpenSnapshotFile (const char *base, bool8 read_only, STREAM *file)
***************************************************************************
void S9xCloseSnapshotFile (STREAM file)
***************************************

Routines to open and close freeze-game files. STREAM is defined as a
gzFile if ZLIB is defined else its 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.

void S9xExit ()
***************

Called when some fatal error situation arises or when the 'q' debugger
command is used. The Mac port just beeps and drops back to the GUI when
S9xExit is called, the MS-DOS, Linux and Solaris ports all call exit () to
terminate the emulator process.

void S9xParseArg (char **argv, int &index, int argc)
****************************************************

void S9xExtraUsage ()
*********************

If you're going to be using the simple command line parser, when it
encounters an unknown option it calls S9xUsage which is supposed to report
all options the generic parse knows about (I haven't been keeping it up to
date of late). S9xUsage then, in turn calls S9xExtraUsage which you
implement to report any port-specific options available.

void S9xGraphicsMode ()
***********************
void S9xTextMode ()
*******************

The SNES debugger calls these routines to switch from a graphics screen
mode used to display the SNES game to a debugger screen used to display
debugger output. If the SNES screen can be displayed at the same time as
a text display, as would be the case when the host system implements a
graphical window system, or you're not going to support the SNES debugger,
then these routines should do nothing.

On the X Window System UNIX/Linux port, these routines do nothing where as
on the MS-DOS port they switch between a graphics screen mode and a text-only
screen mode.

bool8 S9xInitUpdate ()
**********************

Called just before Snes9x starts to render a SNES screen. The Windows port
uses this call to lock Direct X screen area to allow exclusive access; on
other existing ports its implemented as an empty function.

bool8 S9xDeinitDisplay (int width, int height, bool8 sixteen_bit)
*****************************************************************

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. Width is always 256, unless you're
supporting SNES hi-res. screen modes (Settings.SupportHiRes is TRUE), in
which case it can be 256 or 512. The height parameter can be either 224 or
239 if you're only supporting SNES lo-res. screen modes, or 224, 239, 448 or
478 if hi-res. SNES screen modes are being supported.

All current ports support scaling the SNES screen to fill the host system's
screen, the many ports even supports interpolation - blending the colours of
adjacent pixels to help hide the fact they've been scaled - and scan-line
simulation - slightly darkening every other horizontal line.

Don't forget that if you're just placing the SNES image centerally in the
screen then you might need to clear areas of the screen if the SNES image
changes size between calls to S9xDeinitDisplay. The MS-DOS and UNIX ports
currently don't do this which results in junk being left on the screen if
the ROM changes SNES screen modes.

The sixteen_bit is just a copy of the Settings.SixteenBit setting and if
TRUE indicates a 16-bit SNES screen image has been rendered, 8-bit otherwise.

void S9xMessage (int type, int number, const char *message)
***********************************************************

I've started work on converting all the old printfs into calls to this
routine.  When Snes9x wants to display an error, information or warning
message, it calls this routine. 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 calls this function to actually open the host operating system's
sound device, or initialise the sound card in MS-DOS port. 

The mode parameter is the value passed in on the command line with the -r
command line flag, assuming you're using the Snes9x parser. Its meant to
indicate what playback the sound hardware should be set to, value 1 to 7.
I think the real SNES sound chip playback rate is 30kHz, but such high
playback rates take a lot of native CPU power to emulate. The default
playback rate is 22kHz for the MS-DOS and UNIX ports.

The stereo flag indicates if the user wants stereo sound. Again, stereo
sound takes more CPU to power to emulate compared to mono sound.

The buffer_size value indicates what sample buffer size the user wants,
usually zero, meaning you should pick the value best suited to the current
playback rate. Sound data is normally passed to the sound hardware in
blocks, the smaller the block the less latency between the SNES game playing
a sound and it being heard by the user. But if you pick a too smaller value,
and you're having to periodically poll the operating system to see if it can
accept more sound data, then the sound output will break up because other
actions such as rendering the SNES screen can prevent you from polling the
hardware often enough and the operating system runs out of sound data to
play.

The MS-DOS port uses a buffer size of 128 samples since the sound card
sends an interrupt when more data is required which is acted upon promptly,
where as the Linux and Solaris ports use a buffer size of 512 samples or
more depending on the playback rate. Stereo and 16-bit sound both double the
actual size of the buffer in bytes.

uint32 S9xReadJoypad (int which1_0_to_4)
****************************************

This function is called to return a bit-wise mask of the state of one of the
five emulated SNES controllers. Return 0 if you're not supporting controllers
past a certain number or return the mask representing the current state of
the controller number passed as a parameter or'ed with 0x80000000.

Symbolic constants are defined in snes9x.h indicating the bit positions of
the various SNES buttons and direction indicators; they're all in the form
SNES_X_MASK where X is the SNES controller button name.

The MS-DOS and X Window System ports record what keys are currently pressed
and use that to build up a mask, the Windows port polls the operating system
when S9xReadJoypad is called to find out what keys are pressed. All ports
also implement host joysticks and joy-pads via this interface.

bool8 S9xReadMousePosition (int which1_0_to_1, int &x, int &y, uint32 &buttons)
*******************************************************************************

Used by Snes9x to get the current position of the host pointing device,
usually a mouse, used to emulated the SNES mouse. Snes9x converts the x and
y values to delta values required by the SNES mouse, so the actual x and y
values are unimportant, only the change in value since the last call to
this function is used. 

Graphical windowing systems normally restrict the movement of the pointer on
the screen, if you're porting to such an environment you might want to make
a note of the change in position in the mouse since the last time you asked
the operating system the mouse position, add this change in value to some
saved x and y value, the reposition the pointer back to the centre of the
SNES display window. The saved x and y values will be the values returned
by this function.

The buttons return value is a bit-wise mask of the two SNES mouse buttons,
bit 0 for button 1 (left) and bit 1 for button 2 (right).

bool8 S9xReadSuperScopePosition (int &x, int &y, uint32 &buttons)
*****************************************************************

void S9xSetPalette ()
*********************

void S9xSyncSpeed ()
S9xUnixProcessSound
void _makepath(char *, char const *, char const *, char const *, char const *)
void _splitpath(char const *, char *, char *, char *, char *)


Sound Generation
----------------

Settings
--------