porting.txt

FCEU Next Porting Guide
 Updated: November 28, 2011

***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.
	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.

***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_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.

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_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_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_DispMessage(char *msg);
	Displays a short, one-line message using FCE Ultra's built-in
	functions and ASCII font data.

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).

***Recognized defined symbols:

The following defined symbols affect the way FCE Ultra is compiled:

	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 ^_^.