how2port.txt

著名SFC模拟器Snes9x的源代码。

Initialisation Code
-------------------

This is what the Linux, UNIX and MS-DOS ports do, I suspect your code
might be similar:

- The Settings structure is initialised to some sensible default values -
  check the main function in unix.cpp for the values it uses.

- The command line is parsed, options specified override default values in
  the Settings structure and specify a ROM image filename that the user
  wants loaded. Your port could load user preferences from a file or some
  other source at this point. Most values, with a little care, can be changed
  via a GUI once the emulator is running.

- Some Settings structure value validation takes place, for example if
  transparency effects are requested the code also makes sure 16-bit
  screen rendering is turned on as well.

- Memory.Init() and S9xInitAPU() are called, checking neither failed. The
  only reason they would fail is if memory allocation failed.

- Memory.LoadROM (filename) is called to load the specified ROM image into
  memory. If that worked Memory.LoadSRAM (sram_filename) is called to load
  the ROM's S-RAM file, if one exists. The all current ports base the
  sram_filename on the filename of the ROM image, changing the file's
  extension (the .smc or whatever bit) and changing the directory where its
  located - you won't be able to save S-RAM files onto a CD if that's where
  the ROM image is located!

  If your port has a GUI, you can delay this step until the user picks an
  image to load.

  SNES roms images come in all shapes and sizes, some with headers, some
  without, some have been mangled by the copier device in one of two ways, and
  some split into several pieces; plus the SNES itself has several different
  memory map models. The code tries to auto-detect all these various types,
  but sometimes the SNES ROM header information has been manually edited by
  someone at some stage and the code guesses wrong. To help it out it these
  situations, the Settings structure contains several options to force a
  particular ROM image format; these values must be initialised prior to each
  call to Memory.LoadROM(filename).

- The Linux and UNIX ports now do some more operating system initialisation
  ready for a system timer to be started.

- The host display hardware is now initialised. The actual screen depth and
  resolution should be picked based on the user preferences if possible.
  The X Window System port can't control the screen depth or resolution, if
  the user requests transparency effects but the display hardware is only
  set to 8-bit, it has to invoke an extra step of converting the 16-bit SNES
  rendered screen to a fixed palette 8-bit display just before the SNES
  screen is copied to the display hardware.

  The GFX.Screen pointer needs to be initialised to point to an array of
  uint8 for 8-bit screen rendering or uint16 for 16-bit rendering, cast to
  an array of uint8. The array needs to be at least 256x239 bytes or shorts
  in size for lo-res only support (Settings.SupportHiRes = FALSE) or
  512x478 for lo-res and hi-res support. If transparency effects are
  required, the GFX.SubScreen array also needs to be initialised to another
  identically sized array of the same type, otherwise it can be just
  initialised to NULL.

  The GFX.Pitch variable needs to be set to the number of bytes on each line
  of the arrays, e.g. 256 for lo-res only support, up to 1024 for 16-bit
  hi-res support. If GFX.Screen is pointing into an existing array, one
  created by the library function rather than just calling malloc or new,
  then set GFX.Pitch to the number of bytes per line of that array,
  including any padding the library function may have added.

  If the target hardware supports fast access to video RAM, the screen is in
  16-bit format supported by the SNES rendering code and you can double
  buffer the display, you might want to point GFX.Screen directly at the
  video buffer RAM. You will need to recompute the GFX.Delta value every
  time you change the GFX.Screen value to double-buffer the rendering and
  display.

- A call to S9xGraphicsInit() is made; make sure all your graphics rendering
  options are setup correctly by now. If later, you want to change some
  settings, for example 16-bit to 8-bit rendering, call S9xGraphicsDeinit()
  first, change your settings, GFX.Screen and GFX.SubScreen arrays, etc.,
  then call S9xGraphicsInit() again.

- S9xInitSound(int playbackrate, bool8 stereo, int sound_buffer_size)
  is now called, which in turn will call your S9xOpenSoundDevice function -
  see below.

- The display is switched to graphics mode using a call to S9xGraphicsMode().

- The system timer is started; its used for keeping the emulator speed
  relatively constant on the MS-DOS port and noting when the sound hardware
  sound should be able to accept more sound data on the Linux and UNIX ports.

- A main loop is entered which is just a loop constantly calling
  S9xMainLoop() then polling the operating system for any pending events
  such as key presses and releases, joystick updates, mouse position
  updates, GUI user interaction, etc. 

  Pause functionality can be implemented by skipping the call to S9xMainLoop
  and muting the sound output by calling S9xSetSoundMute (TRUE).

  Don't enter the main loop until a SNES ROM image has been loaded, or at
  least skip calling S9xMainLoop inside the loop until one is and make sure
  S9xReset is called instead before entering the main loop. The Mac port
  implements this technique by starting in pause mode and refusing to unpause
  until a ROM image is loaded.

  S9xMainLoop processes SNES CPU emulation, SNES screen rendering, DMA and
  H-DMA emulation, until emulated scan-line 0 is reached, then it returns.
  Now is your chance to process any system events pending, scan the
  keyboard, read joystick values, etc.

  If DEBUGGER compile-time support is enabled and the CPU emulation has hit
  a break point or single-stepping is switched on, or the DEBUG_MODE_FLAG is
  set in the CPU.Flags variable, then the S9xMainLoop routine returns early,
  allowing you to act on the event in some way. The Linux, DOS and UNIX ports
  respond to the DEBUG_MODE_FLAG being set by calling S9xDoDebug(), which in
  turn outputs the current instruction and loops reading commands from stdin
  and outputting debug information, currently via stdout. The debugger
  desperately needs rewriting to support a GUI interface, more descriptive
  commands and better error handling; maybe one day...

Existing Interface Routines
---------------------------

These are routines already written that you will either need to call or
might find useful.

-> bool8 Memory.Init ()

Allocates and initialises 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 ()

Undoes the memory allocations made by Memory.Init.

-> bool8 S9xGraphicsInit ()

Allocated and initialises several lookup tables used to speed up SNES
graphics rendering. Call after you have initialised the GFX.Screen, 
GFX.SubScreen and GFX.Pitch values. If Settings.Transparency is false it
does not allocate tables used to speed up transparency effects. If you
want to provide the user with option to turn the effects on and off during
game play, make sure Settings.Transparency is true when this function is
called, it can later be set to FALSE.

Returns FALSE if memory allocation fails.

-> void S9xGraphicsDeinit ()

Undoes the memory allocations made by S9xGraphicsInit.

-> bool8 S9xInitAPU ()

Allocates and initialises several arrays used by the sound CPU and sound
generation code.

-> void S9xDeinitAPU ()

Undoes the allocations made by S9xInitAPU.

-> bool8 S9xInitSound (int mode, bool8 stereo, int buffer_size)

Does more sound code initialisation and opens the host system's sound hardware
by calling the S9xOpenSoundDevice function provided by you.

-> void S9xReset ()

Resets the SNES emulated hardware back to the state it was in at 'switch-on'
except the S-RAM area is presevered. The effect is it resets the current game
back to the start. This function is automatically called by Memory.LoROM.

-> bool8 Memory.LoadROM (const char *filename)

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. However, some ROM images have been edited by someone at
some stage or have been mangled by the ROM copier that produced them and
LoadROM needs help. Inparticular, it can't auto-detect the odd way in which
some Super FX games have been mangled and needs to be told, via
Settings.Interleaved2, that the ROM image is in that format, or that
odd-sized ROM images have a 512 byte copier header.

There are several other ROM image options in the Settings structure;
allow the user to set them before calling LoadROM, or make sure they all
reset to default values before each call to LoadROM.

-> bool8 Memory.LoadSRAM (const char *filename)

Call this routine 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 *filename)

Call this routine 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()

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 normally returns control to your main loop once every emulated
frame, when it reaches the start of scan-line zero. However, the routine
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 routine from your host sound hardware handling code to fill the
specified buffer with ready mixed SNES sound data. If 16-bit sound mode is
choosen, 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 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.

-> bool8 S9xSetSoundMute (bool8 mute)

Call with a TRUE parmeter to prevent S9xMixSamples 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 *filename)

Call this routine to record the current SNES hardware state into a file,
the file can be loaded back using S9xUnfreezeGame at a later date effectively