Documentation/porting.txt

   1 *Incomplete*
   2
   3
   4 ***Driver-supplied functions:
   5         These functions will only be called after the driver code calls
   6         FCEUI_LoadGame() or FCEUI_Emulate().
   7
   8 void FCEUD_Update(uint8 *XBuf, int32 *Buffer, int Count);
   9         Called by FCE Ultra on every emulated frame.  This function should
  10         perform the following three things(in any order):
  11
  12         1.
  13           Update the data pointed to by the pointers passed to
  14           FCEUI_SetInput() and FCEUI_SetInputFC().
  15         2.
  16           Copy contents of XBuf over to video memory(or whatever needs to be
  17           done to make the contents of XBuf visible on screen).
  18           Each line is 256 pixels(and bytes) in width, and there can be 240
  19           lines.  The pitch for each line is 272 bytes.
  20           XBuf will be 0 if the symbol FRAMESKIP is defined and this frame
  21           was skipped.
  22         3.
  23           Write the contents of "Buffer" to the sound device.  "Count" is the
  24           number of samples to write.  Only the lower 16-bits of each
  25           sample are used, so each 32-bit sample in "Buffer" can be converted to
  26           signed 16-bit by dropping the upper 16 bits.
  27           When sound was disabled for the frame, "Count" will be 0.
  28
  29 void FCEUD_SetPalette(uint8 index, uint8 r, uint8 g, uint8 b);
  30         Set palette entry "index" to specified RGB values(value: min=0, max=255).
  31
  32 void FCEUD_GetPalette(uint8 index, uint8 *r, uint8 *g, uint8 *b);
  33         Get palette entry "index" data.
  34
  35 void FCEUD_PrintError(char *s);
  36         Print/Display an error message string pointed to by "s".
  37
  38 int FCEUD_NetworkConnect(void);
  39         Initialize a network connection.  Return 0 if an error occurs.
  40
  41 int FCEUD_NetworkRecvData(uint8 *data, uint32 len, int block);
  42         Receive "len" bytes of data to "data".  If block is 0 and "len" amount
  43         of data is not available, return -1.  If block is 1, wait until the
  44         requested amount of data is available.
  45         Return 0 on failure.
  46
  47 int FCEUD_NetworkSendData(uint8 *data, uint32 len);
  48         Send "len" bytes of "data".  Return 0 on failure.
  49
  50 void FCEUD_NetworkClose(void);
  51         Close the network connection.
  52
  53
  54 ***FCE Ultra functions(called by the driver code):
  55         The FCEUI_* functions may only be called before FCEUI_Emulate() is
  56         called or after it returns and before it is called again, or after the
  57         following functions are called and before they return:
  58                 FCEUD_Update();
  59         Calling the FCEUI_* functions at any other time may result in
  60         undefined behavior.
  61
  62 void FCEUI_SetInput(int port, int type, void *ptr, int attrib);
  63 void FCEUI_SetInputFC(int type, void *ptr, int attrib);
  64 void FCEUI_DisableFourScore(int s);
  65
  66 void FCEUI_SetSnapName(int a);
  67
  68 void FCEUI_DisableSpriteLimitation(int a);
  69         Disables the 8-sprite-per-scanline limitation of the NES if "a"
  70         is nonzero.  The default behavior is the limitation is enabled.
  71
  72 void FCEUI_SaveExtraDataUnderBase(int a);
  73         If "a" is nonzero, save extra non-volatile game data(battery-backed
  74         RAM) under FCE Ultra's base directory.  Otherwise, the behavior is
  75         to save it under the same directory the game is located in(this is
  76         the default behavior).
  77
  78 FCEUGI *FCEUI_LoadGame(char *name);
  79         Loads a new file.  "name" is the full path of the file to load.
  80         Returns 0 on failure, or a pointer to data type "FCEUGI":
  81         See file "git.h" for more details on this structure.
  82
  83 int FCEUI_Initialize(void);
  84         Allocates and initializes memory.  Should only be called once, before
  85         any calls to other FCEU functions.
  86
  87 void FCEUI_SetBaseDirectory(void);
  88         Specifies the base FCE Ultra directory.  This should be called
  89         immediately after FCEUI_Initialize() and any time afterwards.
  90
  91 void FCEUI_SetDirOverride(int which, char *n);
  92
  93         FCEUIOD_CHEATS  - Cheats
  94         FCEUIOD_MISC    - Miscellaneous stuff(custom game palettes)
  95         FCEUIOD_NV      - Non-volatile game data(battery backed RAM)
  96         FCEUIOD_SNAPS   - Screen snapshots
  97         FCEUIOD_STATE   - Save states
  98
  99 void FCEUI_Emulate(void);
 100         Enters the emulation loop.  This loop will be exited when FCEUI_CloseGame()
 101         is called.  This function obviously shouldn't be called if FCEUI_LoadGame()
 102         wasn't called or FCEUI_CloseGame() was called after FCEUI_LoadGame().
 103
 104 void FCEUI_CloseGame(void);
 105         Closes the loaded game and frees all memory used to load it.
 106         Also causes FCEUI_Emulate() to return.
 107
 108 void FCEUI_SetRenderedLines(int ntscf, int ntscl, int palf, int pall);
 109         Sets the first(minimum is 0) and last(NOT the last scanline plus one;
 110         maximum is 239) scanlines of background data to draw, for both NTSC
 111         emulation mode and PAL emulation mode.
 112
 113         Defaults are as if this function were called with the variables set
 114         up as follows:
 115                 ntscf=8, ntscl=239, palf=0, pall=239
 116
 117 void FCEUI_SetNetworkPlay(int type);
 118         Sets status of network play according to "type".  If type is 0,
 119         then network play is disabled.  If type is 1, then we are server.
 120         If type is 2, then we are a client.
 121
 122 void FCEUI_SelectState(int w);
 123         Selects the state "slot" to save to and load from.
 124
 125 void FCEUI_SaveState(void);
 126         Saves the current virtual NES state from the "slot" selected by
 127         FCEUI_SelectState().
 128
 129 void FCEUI_LoadState(void);
 130         Loads the current virtual NES state from the "slot" selected by
 131         FCEUI_SelectState().
 132
 133 void FCEUI_SaveSnapshot(void);
 134         Saves a screen snapshot.
 135
 136 void FCEUI_DispMessage(char *msg);
 137         Displays a short, one-line message using FCE Ultra's built-in
 138         functions and ASCII font data.
 139
 140 int32 FCEUI_GetDesiredFPS(void);
 141         Returns the desired FPS based on whether NTSC or PAL emulation is
 142         enabled, shifted left by 24 bits(this is necessary because the real
 143         FPS value is not a whole integer).  This function should only be
 144         necessary if sound emulation is disabled.
 145
 146 int FCEUI_GetCurrentVidSystem(int *slstart, int *slend);
 147         Convenience function(not strictly necessary, but reduces excessive code
 148         duplication); returns currently emulated video system
 149         (0=NTSC, 1=PAL).  It will also set the variables pointed to by slstart
 150         and slend to the first and last scanlines to be rendered, respectively,
 151         if slstart and slend are not 0.
 152
 153 int FCEUI_AddCheat(char *name, uint16 addr, uint8 val);
 154         Adds a RAM cheat with the specified name to patch the address "addr"
 155         with the value "val".
 156
 157 int FCEUI_DelCheat(uint32 which);
 158         Deletes the specified(by number) cheat.
 159
 160 void FCEUI_ListCheats(void (*callb)(char *name, uint16 a, uint8 v));
 161         Causes FCE Ultra to go through the list of all cheats loaded for
 162         the current game and call callb() for each cheat with the cheat
 163         information.
 164
 165 int FCEUI_GetCheat(uint32 which, char **name, int32 *a, int32 *v, int *s);
 166         Gets information on the cheat referenced by "which".
 167
 168 int FCEUI_SetCheat(uint32 which, char *name, int32 a, int32 v, int s);
 169         Sets information for the cheat referenced by "which".
 170
 171 void FCEUI_CheatSearchBegin(void);
 172         Begins the cheat search process.  Current RAM values are copied
 173         to a buffer to later be processed by the other cheat search functions.
 174
 175 void FCEUI_CheatSearchEnd(int type, int v1, int v2);
 176         Searches the buffer using the search method specified by "type"
 177         and the parameters "v1" and "v2".
 178
 179 int32 FCEUI_CheatSearchGetCount(void);
 180         Returns the number of matches from the cheat search.
 181
 182 void FCEUI_CheatSearchGet(void (*callb)(uint16 a, int last, int current));
 183
 184 void FCEUI_CheatSearchGetRange(int first, int last, void (*callb)(uint16 a, int last, int current));
 185         Like FCEUI_CheatSearchGet(), but you can specify the first and last
 186         matches to get.
 187
 188 void FCEUI_CheatSearchShowExcluded(void);
 189         Undos any exclusions of valid addresses done by FCEUI_CheatSearchEnd().
 190
 191 void FCEUI_CheatSearchSetCurrentAsOriginal(void);
 192         Copies the current values in RAM into the cheat search buffer.
 193
 194 ***Recognized defined symbols:
 195
 196 The following defined symbols affect the way FCE Ultra is compiled:
 197
 198         C80x86
 199         - Include 80x86 inline assembly in AT&T syntax.
 200
 201         FRAMESKIP
 202         - Include frame skipping code.
 203
 204         NETWORK
 205         - Include network play code.
 206
 207         FPS
 208         - Compile code that prints out a number when FCE Ultra exits
 209           that represents the average fps.
 210
 211         ZLIB
 212         - Compile support for compressed PKZIP-style files AND gzip compressed
 213           files.  "unzip.c" will need to be compiled and linked in by you if
 214           this is defined(it's in the zlib subdirectory).
 215
 216         LSB_FIRST
 217         - Compile code to expect that variables that are greater than 8 bits
 218           in size are stored Least Significant Byte First in memory.
 219
 220         PSS_STYLE x
 221         - Sets the path separator style to the integer 'x'.  Valid styles are:
 222           1: Only "/" - For UNIX platforms.
 223           2: Both "/" and "\" - For Windows and MSDOS platforms.
 224           3: Only "\" - For ???.
 225           4: Only ":" - For Macintoshes and Apple IIs ^_^.
 226
 227
 228
 229