When you release a port, please include YOUR contact information for users
to report bugs and other problems.
I get a ton of e-mails about a color problem in the Nokia P900 port of SMS
Plus because the author apparently included my e-mail address (please link
to my webpage instead) and listed NO contact information for him/herself.
Also, let me know when you release a port, so I can forward these types
of e-mails appropriately.
----------------------------------------------------------------------------
What's changed for SMS Plus v1.2
I haven't finished up the porting notes so some things aren't covered yet;
look at the DOS source for an example.
After calling system_init(), use the following functions:
system_poweron() - Call once, can run game afterwards
system_reset() - Can call during gameplay if user wants a hard reset
system_poweroff() - Call once when done with a game.
When loading multiple ROMs in a single session, you'd call poweroff() when
done with a game, then poweron() after the next one was loaded.
SRAM is loaded when poweron() or reset() is called.
SRAM is saved when poweroff() is called.
The SRAM management function has changed:
void system_manage_sram(uint8 *sram, int slot, int mode);
'mode' is either SRAM_SAVE or SRAM_LOAD.
The slot parameter is ignored for now.
If there was SRAM to load, set sms.save = 1;
Otherwise, clear SRAM to zero.
See the DOS code for an implementation of this function.
Sound emulation
The following structure holds sound related information:
struct {
/* Input parameters */
int sample_rate;
int fps;
uint32 psg_clock;
uint32 fm_clock;
int fm_which;
void (*mixer_callback)(int16 **stream, int16 **output, int length);
/* Working data */
int16 *stream[STREAM_MAX];
int16 *output[2];
/* Outputs */
int enabled;
int buffer_size;
int sample_count;
} snd;
Normally you would set up this structure before calling system_init().
You can change the input parameters and call sound_init() again to change
them. Here are how the parameters should be used:
snd.sample_rate Set to the desired sample rate, e.g. 22050, 44100.
Set to 0 to disable sound emulation.
snd.fps Set to 50 (PAL) or 60 (NTSC) to specify the emulated
sound replay rate. PAL consoles are not completely
supported yet, I would advise leaving this at 60.
snd.psg_clock Set to the SN76489 clock speed.
Normally this is 3579545. (3.58 MHz)
snd.fm_clock Set to the YM2413 clock speed.
Normally this is 3579545. (3.58 MHz)
snd.fm_which Set to SND_EMU2413 or SND_YM2413 depending on the FM
sound chip emulator you want to use. You can change
this and call sound_init() again for realtime switching.
snd.mixer_callback Set to NULL to use the default stream mixing routine,
or point it to your own.
Calling sound_init() will return 0 if sound emulation was disabled or an
error occured, or 1 if initialization was successful. The following
variables will be valid for use afterwards:
snd.enabled Set to 1 if sound emulation is enabled, 0 if disabled.
snd.buffer_size Size of sample buffer in bytes.
snd.sample_count Length of sample buffer in samples.
snd.stream Sound streams for the built-in mixer function or a user
supplied one to use.
snd.output Mixed audio generated by the built-in mixer function
that can be output to a sound device. Updated after each
call to system_frame().
An example of setup and use is as follows:
// Init code
snd.sample_rate = 44100;
snd.fps = 60;
snd.psg_clock = 3579545;
snd.fm_clock = 3579545;
snd.fm_which = SND_EMU2413;
snd.mixer_callback = NULL;
system_init();
// Change some parameter later on
snd.fm_which = SND_YM2413;
sound_init();
// Update code
system_frame();
osd_play_stream_stereo( snd.output, snd.buffer_size );
Custom mixing
You can provide your own mixing routine to combine audio streams. Some
uses might include:
- Per-stream volume adjustment, filtering, effects.
- Stereo output of YM2413 sound.
- Bass-boost on YM2413 rhythm output.
- Can take advantage of in-hardware playback/mixing (console ports, etc.)
There are four sound streams available:
STREAM_PSG_L SN76489 left channel output
STREAM_PSG_R SN76489 right channel output
STREAM_FM_MO YM2413 melody channel output
STREAM_FM_RO YM2413 rhythm channel output
The two YM2413 outputs are mixed together, along with the PSG output, for
a single monoaural channel in all versions of the SMS and related hardware
that support FM sound.
Synopsis of audio features by console:
FM sound Stereo PSG Output
Mark III No No Mono
Mark III+FM Yes No Mono
SMS 1 No No Mono
SMS 2 No No Mono
SMS 1 (J) Yes No Mono
Game Gear No Yes Stereo (headphone jack) Mono (speaker)
Audio from the YM2413 emulator has a lower volume than EMU2413 and will
need to be adjusted.
See the default mixer routine in 'sound.c' for an example.
----------------------------------------------------------------------------
Porting notes for earlier 0.9.x versions
----------------------------------------------------------------------------
You can check out the DOS specific code to get an idea of
how to port SMS Plus.
0.) Machine dependant issues
----------------------------
Everything should compile fine for big-endian platforms, however
I'm not sure the 8-bit pixel to 16-bit pixel conversion function
in 'render.c' is endian safe.
You need to either define or not define 'LSB_FIRST' in your makefile,
depending on your needs.
1.) Graphics
------------
The emulated display can be shown in either 8-bit or 16-bit color.
The following structure is used by the rendering routines to
draw the display, and you need to set it up prior to running the
emulation.
typedef struct
{
uint8 *data;
int width;
int height;
int pitch;
int depth;
struct
{
uint8 color[PALETTE_MAX][3];
uint8 dirty[PALETTE_MAX];
uint8 update;
}pal;
}t_bitmap;
'data' - Pointer to a linear chunk of memory. This should be at least
256x192 pixels in size. You can modify this pointer between
frames for double buffering (if it's pointed into memory mapped
video RAM), or point it to system memory so further changes
can be made. (like special effects, or for converting the
graphics data to 24 or 32-bit format)
'width' - Width of the bitmap, in pixels.
'height' - Height of the bitmap, in pixels.
'pitch' - Width of the bitmap, in *bytes*.
'depth' - Color depth. Must be 8 or 16.
'color' - An array of 32 RGB values, each scaled up to eight bits.
'dirty' - Each entry is nonzero if the color has been modified.
'update' - Nonzero if one or more colors have been modified.
If you are using 8-bit color, please note that each pixel drawn to
the bitmap uses some extra unused bits during the rendering process.
You can either mask out these bits using the PIXEL_MASK constant
from 'system.h', or set palette ranges 20-3F, 40-5F to the same
values as 00-1F.
If you are using 16-bit color, you can ignore the members of the 'pal'
structure. Remember to adjust the MAKE_PIXEL macro in 'render.h' to
whatever format your display uses. By default it will make a 16-bit
pixel in RGB 5:6:5 format.
The macros BMP_X_OFFSET, BMP_Y_OFFSET, give the offset into the
bitmap. This is because the SMS display takes up the entire bitmap,
while the GG display is centered in the middle. These macros provide
a convenient way to get the right offset.
The PALETTE_MAX constant returns the size of the palette.
This is currently set to 32 entries.
2.) Sound
---------
Sound emulation is handled through the following structure:
typedef struct
{
int fps; /* Set to 50 or 60 FPS for PAL or NTSC games */
int sample_rate; /* Set between 8000 and 48000 */
int enabled; /* 1= Init OK, 0= Sound disabled or error */
int sample_count; /* Length of buffer in samples */
int buffer_size; /* Size of buffer in bytes */
int16 *output[2]; /* Left and right channels */
} snd_t;
You must call 'system_init()' and pass the desired sample rate as an
parameter to enable sound emulation. You can set the sample rate to
zero if you do not want sound emulation. Remember that 'snd.enabled'
will be set afterwards to indicate if any errors occured.
You also must call 'system_shutdown()' when you are done running
the virtual console emulation, so some memory used by the sound
emulation code can be freed.
3.) Input
---------
Input is handled through the following structure:
typedef struct
{
int pad[2];
int system;
}t_input;
'pad[]' - Corresponds to joystick one and joystick two.
'system' - System buttons, specifically pause, start, and reset.
During each frame, you should clear members of this structure to zero,
then update each one using the INPUT_* constants in 'system.h'.
4.) Game Images
---------------
Game images are handled through the following structure:
typedef struct
{
uint8 *rom;
uint8 pages;
uint8 type;
}t_cart;
'rom' - Pointer to the ROM image.
'pages' - ROM size divided by 16k.
'type' - Set to either TYPE_SMS or TYPE_GG.
Games can be identified by their extension, which is usually '.sms'
or '.gg'. Some games have an optional 512-byte header which you must
remove. Remember to adjust the file size accordingly.
5.) Battery backed RAM
----------------------
Some game cartridges can have up to 32k of battery backed RAM present.
There are two variables relating to this:
typedef struct
{
uint8 sram[0x8000];
uint8 save;
}t_sms;
'sram' - This is the data that should be saved and loaded.
'save' - This is nonzero if the contents of sram[] should be saved.
It's impossible to know if a game will use battery backed RAM, so the
emulation code waits until a game tries to read or write it, and then
sets the 'save' flag meaning the data needs to be saved.
The basic way to deal with this is:
1. Load a game file
2. If a file with the same name, and the extension .sav exists,
then load that data into 'sram' and set the 'save' flag.
3. When exiting, check if the 'save' flag is nonzero, and if so,
write the contents of sram[] to a file with the extension .sav
and the same filename as the game file loaded.
Note that when system_reset() is called, the function 'system_load_sram'
which has a prototype in 'system.h' will be called. You *must* implement
this function. All it has to do is see if any saved battery backed RAM
is present, and update the save/sram[] members accordingly.
6.) Miscellaneous
-----------------
Before running the virtual console emulation, you can set up
these two variables:
sms.use_fm : 0= No YM2413 sound, 1= YM2413 sound
sms.country : Set to TYPE_DOMESTIC (Japan), TYPE_OVERSEAS
Some games will display different text depending on the country
setting. The default value is TYPE_OVERSEAS. This is suitable for every
country but Japan.
Some games have different music if the YM2413 sound chip is present.
If the 'fm_enable' value is set to one, then games can detect it.
If you want to use FM sound, you must ensure that 'use_fm' is nonzero
before loading a game, since this variable controls if games can detect
the YM2413 chip as well as actual YM2413 output.
Some games will only enable YM2413 sound if the country type is
also set to TYPE_DOMESTIC. One such example is Wonderboy 3.
Both of these variables are preserved when system_reset() is called.
You can call load_state/save_state to save and restore the current state
of the virtual console emulation. You need to pass a file handle as
a parameter to these functions. Therefore, you are responsible for ensuring
the file exists, and the file name. The naming convention is that all
state files are named '.st0' up to '.st9'.
7.) Function reference
----------------------
void system_init(int sound_rate);
You must set up the 'bitmap' and 'cart' structures prior to calling this
function. If you want sound emulation, pass the desired sample rate
(8000..44100). Afterwards, check the members of the 'snd' structure to see
if you can use sound emulation. You can now call system_frame() and the like.
void system_shutdown(void);
Call this when you're done with the emulation. Not terribly important
as it only frees some memory allocated by the sound emulation routines...
void system_reset(void)
Reset the virtual console emulation. This is called internally when
the INPUT_HARD_RESET flag for 'input.system' is set.
void system_load_sram(void);
Refresh the 'sms.sram[]' and 'sms.save' variables.
You must impelement this function yourself.
void system_frame(int skip);
You need to call this function 60 times a second. Pass zero as the
parameter to draw the current frame, otherwise pass one to omit
the drawing process. (ideal for frame skipping) Afterwards,
the 'bitmap' and 'snd' structures will be updated with the current
graphics and sound data. You should set up the 'input' structure
before calling this function.
8.) Example
-----------
Here's a brief overview of how to use all this:
- do machine dependant initialization (audio, video, init input, etc.)
- set up bitmap structure
- set up cart structure (load game)
- call system_init()
- if snd.enabled is set, we can use sound
- load sram data if it exists for the game
in a loop:
- update input structure based on gamepad/keyboard
- call system_frame()
- play sound using 'snd.buffer'
- copy 'bitmap.data' to the video display
- quit if needed
- save sram data if the game used it
- call system_shutdown()
9.) Other notes on porting
--------------------------
- Please read the license first.
- You must release the source code to your port in accordance with the GPL.
If you have made *no* changes to the main source code, meaning everything
in the root directory, and the cpu and dos directories, then you
do not have to include those files. No point in wasting space.
Otherwise, you must include those files with the changes clearly stated.
If the changes are the kind that could benefit other ports (like a bug
fix), then just let me know so I can update the main distribution, and
don't bother releasing those files. But let me know before you release
your port, however.
If you are using some commercial libraries to take care of items like
audio output, or if you have developed some routines which you do not want
made public (i.e. an assembly optimized blitter, or some custom joypad
polling functions), then you do not have to include those files.
I prefer it where anybody can download a port of SMS Plus and compile it
themselves, but I realize this isn't always possible.
It would be nice, and is not required, that you could organize the
source in the same way I have it set up. For instance, maintaining the
same directory structure, but adding an '/myport' directory with your
specific files, and an appropriate makefile.
- You must clearly state in the executable that you are the porter,
and that I wrote the program. Include YOUR contact information (e-mail
address, website URL). This is so users will not ask me questions on how
to use a specific port, which I know nothing about.
- You need to provide documentation. Please remember to mention
the licensing stuff pertaining to SMS Plus and the MAME code that's
mentioned (for example) in the original 'readme' I wrote. Or just
include my documentation and make some additions.
Please link to my website in the documentation, so people will know
where to get the original source code.