FCE Ultra Porting Guide
Updated: October 4, 2003
*Incomplete*
***Driver-supplied functions:
These functions will only be called after the driver code calls
FCEUI_LoadGame() or FCEUI_Emulate().
void FCEUD_Update(uint8 *XBuf, int32 *Buffer, int Count);
Called by FCE Ultra on every emulated frame. This function should
perform the following three things(in any order):
1.
Update the data pointed to by the pointers passed to
FCEUI_SetInput() and FCEUI_SetInputFC().
2.
Copy contents of XBuf over to video memory(or whatever needs to be
done to make the contents of XBuf visible on screen).
Each line is 256 pixels(and bytes) in width, and there can be 240
lines. The pitch for each line is 272 bytes.
XBuf will be 0 if the symbol FRAMESKIP is defined and this frame
was skipped.
3.
Write the contents of "Buffer" to the sound device. "Count" is the
number of samples to write. Only the lower 16-bits of each
sample are used, so each 32-bit sample in "Buffer" can be converted to
signed 16-bit by dropping the upper 16 bits.
When sound was disabled for the frame, "Count" will be 0.
void FCEUD_SetPalette(uint8 index, uint8 r, uint8 g, uint8 b);
Set palette entry "index" to specified RGB values(value: min=0, max=255).
void FCEUD_GetPalette(uint8 index, uint8 *r, uint8 *g, uint8 *b);
Get palette entry "index" data.
void FCEUD_PrintError(char *s);
Print/Display an error message string pointed to by "s".
void FCEUD_Message(char *s);
Display a status message string.
int FCEUD_NetworkConnect(void);
Initialize a network connection. Return 0 if an error occurs.
int FCEUD_GetDataFromClients(uint8 *data);
/* Sends 5 bytes of data to all clients. */
int FCEUD_SendDataToClients(uint8 *data);
/* Sends 1 byte of data to server, and maybe a command. */
int FCEUD_SendDataToServer(uint8 v, uint8 cmd);
/* Gets 5 bytes of data from the server. This function must block. */
int FCEUD_GetDataFromServer(uint8 *data);
void FCEUD_NetworkClose(void);
Close the network connection.
***FCE Ultra functions(called by the driver code):
The FCEUI_* functions may only be called before FCEUI_Emulate() is
called or after it returns and before it is called again, or after the
following functions are called and before they return:
FCEUD_Update();
Calling the FCEUI_* functions at any other time may result in
undefined behavior.
void FCEUI_SetInput(int port, int type, void *ptr, int attrib);
"port" can be either 0 or 1, and corresponds to the physical
ports on the front of a NES.
"type" may be:
SI_NONE - No input on this port.
SI_GAMEPAD - Standard NES gamepad
SI_ZAPPER - "Zapper" light gun.
SI_POWERPAD - Power-pad mat.
SI_ARKANOID - Arkanoid controller.
void FCEUI_SetInputFC(int type, void *ptr, int attrib);
Special Famicom devices.
"type" may be:
SIFC_NONE - No input here.
SIFC_ARKANOID - Arkanoid controller.
SIFC_SHADOW - "Space Shadow" gun.
SIFC_4PLAYER - Famicom 4-player adapter
SIFC_FKB - Family Keyboard
void FCEUI_DisableFourScore(int s);
Disables four-score emulation if s is nonzero.
void FCEUI_SetSnapName(int a);
0 to order screen snapshots numerically(0.png), 1 to order them file
base-numerically(smb3-0.png).
void FCEUI_DisableSpriteLimitation(int a);
Disables the 8-sprite-per-scanline limitation of the NES if "a"
is nonzero. The default behavior is the limitation is enabled.
void FCEUI_SaveExtraDataUnderBase(int a);
If "a" is nonzero, save extra non-volatile game data(battery-backed
RAM) under FCE Ultra's base directory. Otherwise, the behavior is
to save it under the same directory the game is located in(this is
the default behavior).
FCEUGI *FCEUI_LoadGame(char *name);
Loads a new file. "name" is the full path of the file to load.
Returns 0 on failure, or a pointer to data type "FCEUGI":
See file "git.h" for more details on this structure.
int FCEUI_Initialize(void);
Allocates and initializes memory. Should only be called once, before
any calls to other FCEU functions.
void FCEUI_SetBaseDirectory(void);
Specifies the base FCE Ultra directory. This should be called
immediately after FCEUI_Initialize() and any time afterwards.
void FCEUI_SetDirOverride(int which, char *n);
FCEUIOD_CHEATS - Cheats
FCEUIOD_MISC - Miscellaneous stuff(custom game palettes)
FCEUIOD_NV - Non-volatile game data(battery backed RAM)
FCEUIOD_SNAPS - Screen snapshots
FCEUIOD_STATE - Save states
void FCEUI_Emulate(void);
Enters the emulation loop. This loop will be exited when FCEUI_CloseGame()
is called. This function obviously shouldn't be called if FCEUI_LoadGame()
wasn't called or FCEUI_CloseGame() was called after FCEUI_LoadGame().
void FCEUI_CloseGame(void);
Closes the loaded game and frees all memory used to load it.
Also causes FCEUI_Emulate() to return.
void FCEUI_ResetNES(void);
void FCEUI_PowerNES(void);
void FCEUI_SetRenderedLines(int ntscf, int ntscl, int palf, int pall);
Sets the first(minimum is 0) and last(NOT the last scanline plus one;
maximum is 239) scanlines of background data to draw, for both NTSC
emulation mode and PAL emulation mode.
Defaults are as if this function were called with the variables set
up as follows:
ntscf=8, ntscl=231, palf=0, pall=239
void FCEUI_SetNetworkPlay(int type);
Sets status of network play according to "type". If type is 0,
then network play is disabled. If type is 1, then we are server.
If type is 2, then we are a client.
void FCEUI_SelectState(int w);
Selects the state "slot" to save to and load from.
void FCEUI_SaveState(void);
Saves the current virtual NES state from the "slot" selected by
FCEUI_SelectState().
void FCEUI_LoadState(void);
Loads the current virtual NES state from the "slot" selected by
FCEUI_SelectState().
void FCEUI_SaveSnapshot(void);
Saves a screen snapshot.
void FCEUI_DispMessage(char *msg);
Displays a short, one-line message using FCE Ultra's built-in
functions and ASCII font data.
int32 FCEUI_GetDesiredFPS(void);
Returns the desired FPS based on whether NTSC or PAL emulation is
enabled, shifted left by 24 bits(this is necessary because the real
FPS value is not a whole integer). This function should only be
necessary if sound emulation is disabled.
int FCEUI_GetCurrentVidSystem(int *slstart, int *slend);
Convenience function(not strictly necessary, but reduces excessive code
duplication); returns currently emulated video system
(0=NTSC, 1=PAL). It will also set the variables pointed to by slstart
and slend to the first and last scanlines to be rendered, respectively,
if slstart and slend are not 0.
void FCEUI_GetNTSCTH(int *tint, int *hue);
void FCEUI_SetNTSCTH(int n, int tint, int hue);
int FCEUI_AddCheat(char *name, uint16 addr, uint8 val);
Adds a RAM cheat with the specified name to patch the address "addr"
with the value "val".
int FCEUI_DelCheat(uint32 which);
Deletes the specified(by number) cheat.
void FCEUI_ListCheats(void (*callb)(char *name, uint16 a, uint8 v));
Causes FCE Ultra to go through the list of all cheats loaded for
the current game and call callb() for each cheat with the cheat
information.
int FCEUI_GetCheat(uint32 which, char **name, int32 *a, int32 *v, int *s);
Gets information on the cheat referenced by "which".
int FCEUI_SetCheat(uint32 which, char *name, int32 a, int32 v, int s);
Sets information for the cheat referenced by "which".
void FCEUI_CheatSearchBegin(void);
Begins the cheat search process. Current RAM values are copied
to a buffer to later be processed by the other cheat search functions.
void FCEUI_CheatSearchEnd(int type, int v1, int v2);
Searches the buffer using the search method specified by "type"
and the parameters "v1" and "v2".
int32 FCEUI_CheatSearchGetCount(void);
Returns the number of matches from the cheat search.
void FCEUI_CheatSearchGet(void (*callb)(uint16 a, int last, int current));
void FCEUI_CheatSearchGetRange(int first, int last, void (*callb)(uint16 a, int last, int current));
Like FCEUI_CheatSearchGet(), but you can specify the first and last
matches to get.
void FCEUI_CheatSearchShowExcluded(void);
Undos any exclusions of valid addresses done by FCEUI_CheatSearchEnd().
void FCEUI_CheatSearchSetCurrentAsOriginal(void);
Copies the current values in RAM into the cheat search buffer.
void FCEUI_MemDump(uint16 a, int32 len, void (*callb)(uint16 a, uint8 v));
Callback to dump memory.
void FCEUI_DumpMem(char *fname, uint32 start, uint32 end);
Dump memory to filename fname.
void FCEUI_MemPoke(uint16 a, uint8 v, int hl);
Write a byte to specified address. Set hl to 1 to attempt to store
it to ROM("high-level" write).
void FCEUI_NMI(void);
Triggers(queues) an NMI.
void FCEUI_IRQ(void);
Triggers(queues) an IRQ.
void FCEUI_Disassemble(uint16 a, int (*callb)(uint16 a, char *s));
Text disassembly.
void FCEUI_GetIVectors(uint16 *reset, uint16 *irq, uint16 *nmi);
Get current interrupt vectors.
***Recognized defined symbols:
The following defined symbols affect the way FCE Ultra is compiled:
C80x86
- Include 80x86 inline assembly in AT&T syntax, if available. Also
use special 80x86-specific C constructs if the compiler is compatible.
FRAMESKIP
- Include frame skipping code.
NETWORK
- Include network play code.
FPS
- Compile code that prints out a number when FCE Ultra exits
that represents the average fps.
ZLIB
- Compile support for compressed PKZIP-style files AND gzip compressed
files. "unzip.c" will need to be compiled and linked in by you if
this is defined(it's in the zlib subdirectory).
LSB_FIRST
- Compile code to expect that variables that are greater than 8 bits
in size are stored Least Significant Byte First in memory.
PSS_STYLE x
- Sets the path separator style to the integer 'x'. Valid styles are:
1: Only "/" - For UNIX platforms.
2: Both "/" and "\" - For Windows and MSDOS platforms.
3: Only "\" - For ???.
4: Only ":" - For Apple IIs ^_^.
