290 lines
9.9 KiB
Plaintext
290 lines
9.9 KiB
Plaintext
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 ^_^.
|
|
|
|
|
|
|
|
|