some refactoring, no change in performance seen
[fceu.git] / 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