diff options
Diffstat (limited to 'apps/plugins/puzzles/src/devel.but')
-rw-r--r-- | apps/plugins/puzzles/src/devel.but | 4895 |
1 files changed, 4895 insertions, 0 deletions
diff --git a/apps/plugins/puzzles/src/devel.but b/apps/plugins/puzzles/src/devel.but new file mode 100644 index 0000000000..a38fdda5d0 --- /dev/null +++ b/apps/plugins/puzzles/src/devel.but | |||
@@ -0,0 +1,4895 @@ | |||
1 | \cfg{text-indent}{0} | ||
2 | \cfg{text-width}{72} | ||
3 | \cfg{text-title-align}{left} | ||
4 | \cfg{text-chapter-align}{left} | ||
5 | \cfg{text-chapter-numeric}{true} | ||
6 | \cfg{text-chapter-suffix}{. } | ||
7 | \cfg{text-chapter-underline}{-} | ||
8 | \cfg{text-section-align}{0}{left} | ||
9 | \cfg{text-section-numeric}{0}{true} | ||
10 | \cfg{text-section-suffix}{0}{. } | ||
11 | \cfg{text-section-underline}{0}{-} | ||
12 | \cfg{text-section-align}{1}{left} | ||
13 | \cfg{text-section-numeric}{1}{true} | ||
14 | \cfg{text-section-suffix}{1}{. } | ||
15 | \cfg{text-section-underline}{1}{-} | ||
16 | \cfg{text-versionid}{0} | ||
17 | |||
18 | \cfg{html-contents-filename}{index.html} | ||
19 | \cfg{html-template-filename}{%k.html} | ||
20 | \cfg{html-index-filename}{docindex.html} | ||
21 | \cfg{html-leaf-level}{1} | ||
22 | \cfg{html-contents-depth-0}{1} | ||
23 | \cfg{html-contents-depth-1}{3} | ||
24 | \cfg{html-leaf-contains-contents}{true} | ||
25 | |||
26 | \define{dash} \u2013{-} | ||
27 | |||
28 | \title Developer documentation for Simon Tatham's puzzle collection | ||
29 | |||
30 | This is a guide to the internal structure of Simon Tatham's Portable | ||
31 | Puzzle Collection (henceforth referred to simply as \q{Puzzles}), | ||
32 | for use by anyone attempting to implement a new puzzle or port to a | ||
33 | new platform. | ||
34 | |||
35 | This guide is believed correct as of r6190. Hopefully it will be | ||
36 | updated along with the code in future, but if not, I've at least | ||
37 | left this version number in here so you can figure out what's | ||
38 | changed by tracking commit comments from there onwards. | ||
39 | |||
40 | \C{intro} Introduction | ||
41 | |||
42 | The Puzzles code base is divided into four parts: a set of | ||
43 | interchangeable front ends, a set of interchangeable back ends, a | ||
44 | universal \q{middle end} which acts as a buffer between the two, and | ||
45 | a bunch of miscellaneous utility functions. In the following | ||
46 | sections I give some general discussion of each of these parts. | ||
47 | |||
48 | \H{intro-frontend} Front end | ||
49 | |||
50 | The front end is the non-portable part of the code: it's the bit | ||
51 | that you replace completely when you port to a different platform. | ||
52 | So it's responsible for all system calls, all GUI interaction, and | ||
53 | anything else platform-specific. | ||
54 | |||
55 | The current front ends in the main code base are for Windows, GTK | ||
56 | and MacOS X; I also know of a third-party front end for PalmOS. | ||
57 | |||
58 | The front end contains \cw{main()} or the local platform's | ||
59 | equivalent. Top-level control over the application's execution flow | ||
60 | belongs to the front end (it isn't, for example, a set of functions | ||
61 | called by a universal \cw{main()} somewhere else). | ||
62 | |||
63 | The front end has complete freedom to design the GUI for any given | ||
64 | port of Puzzles. There is no centralised mechanism for maintaining | ||
65 | the menu layout, for example. This has a cost in consistency (when I | ||
66 | \e{do} want the same menu layout on more than one platform, I have | ||
67 | to edit two pieces of code in parallel every time I make a change), | ||
68 | but the advantage is that local GUI conventions can be conformed to | ||
69 | and local constraints adapted to. For example, MacOS X has strict | ||
70 | human interface guidelines which specify a different menu layout | ||
71 | from the one I've used on Windows and GTK; there's nothing stopping | ||
72 | the OS X front end from providing a menu layout consistent with | ||
73 | those guidelines. | ||
74 | |||
75 | Although the front end is mostly caller rather than the callee in | ||
76 | its interactions with other parts of the code, it is required to | ||
77 | implement a small API for other modules to call, mostly of drawing | ||
78 | functions for games to use when drawing their graphics. The drawing | ||
79 | API is documented in \k{drawing}; the other miscellaneous front end | ||
80 | API functions are documented in \k{frontend-api}. | ||
81 | |||
82 | \H{intro-backend} Back end | ||
83 | |||
84 | A \q{back end}, in this collection, is synonymous with a \q{puzzle}. | ||
85 | Each back end implements a different game. | ||
86 | |||
87 | At the top level, a back end is simply a data structure, containing | ||
88 | a few constants (flag words, preferred pixel size) and a large | ||
89 | number of function pointers. Back ends are almost invariably callee | ||
90 | rather than caller, which means there's a limitation on what a back | ||
91 | end can do on its own initiative. | ||
92 | |||
93 | The persistent state in a back end is divided into a number of data | ||
94 | structures, which are used for different purposes and therefore | ||
95 | likely to be switched around, changed without notice, and otherwise | ||
96 | updated by the rest of the code. It is important when designing a | ||
97 | back end to put the right pieces of data into the right structures, | ||
98 | or standard midend-provided features (such as Undo) may fail to | ||
99 | work. | ||
100 | |||
101 | The functions and variables provided in the back end data structure | ||
102 | are documented in \k{backend}. | ||
103 | |||
104 | \H{intro-midend} Middle end | ||
105 | |||
106 | Puzzles has a single and universal \q{middle end}. This code is | ||
107 | common to all platforms and all games; it sits in between the front | ||
108 | end and the back end and provides standard functionality everywhere. | ||
109 | |||
110 | People adding new back ends or new front ends should generally not | ||
111 | need to edit the middle end. On rare occasions there might be a | ||
112 | change that can be made to the middle end to permit a new game to do | ||
113 | something not currently anticipated by the middle end's present | ||
114 | design; however, this is terribly easy to get wrong and should | ||
115 | probably not be undertaken without consulting the primary maintainer | ||
116 | (me). Patch submissions containing unannounced mid-end changes will | ||
117 | be treated on their merits like any other patch; this is just a | ||
118 | friendly warning that mid-end changes will need quite a lot of | ||
119 | merits to make them acceptable. | ||
120 | |||
121 | Functionality provided by the mid-end includes: | ||
122 | |||
123 | \b Maintaining a list of game state structures and moving back and | ||
124 | forth along that list to provide Undo and Redo. | ||
125 | |||
126 | \b Handling timers (for move animations, flashes on completion, and | ||
127 | in some cases actually timing the game). | ||
128 | |||
129 | \b Handling the container format of game IDs: receiving them, | ||
130 | picking them apart into parameters, description and/or random seed, | ||
131 | and so on. The game back end need only handle the individual parts | ||
132 | of a game ID (encoded parameters and encoded game description); | ||
133 | everything else is handled centrally by the mid-end. | ||
134 | |||
135 | \b Handling standard keystrokes and menu commands, such as \q{New | ||
136 | Game}, \q{Restart Game} and \q{Quit}. | ||
137 | |||
138 | \b Pre-processing mouse events so that the game back ends can rely | ||
139 | on them arriving in a sensible order (no missing button-release | ||
140 | events, no sudden changes of which button is currently pressed, | ||
141 | etc). | ||
142 | |||
143 | \b Handling the dialog boxes which ask the user for a game ID. | ||
144 | |||
145 | \b Handling serialisation of entire games (for loading and saving a | ||
146 | half-finished game to a disk file, or for handling application | ||
147 | shutdown and restart on platforms such as PalmOS where state is | ||
148 | expected to be saved). | ||
149 | |||
150 | Thus, there's a lot of work done once by the mid-end so that | ||
151 | individual back ends don't have to worry about it. All the back end | ||
152 | has to do is cooperate in ensuring the mid-end can do its work | ||
153 | properly. | ||
154 | |||
155 | The API of functions provided by the mid-end to be called by the | ||
156 | front end is documented in \k{midend}. | ||
157 | |||
158 | \H{intro-utils} Miscellaneous utilities | ||
159 | |||
160 | In addition to these three major structural components, the Puzzles | ||
161 | code also contains a variety of utility modules usable by all of the | ||
162 | above components. There is a set of functions to provide | ||
163 | platform-independent random number generation; functions to make | ||
164 | memory allocation easier; functions which implement a balanced tree | ||
165 | structure to be used as necessary in complex algorithms; and a few | ||
166 | other miscellaneous functions. All of these are documented in | ||
167 | \k{utils}. | ||
168 | |||
169 | \H{intro-structure} Structure of this guide | ||
170 | |||
171 | There are a number of function call interfaces within Puzzles, and | ||
172 | this guide will discuss each one in a chapter of its own. After | ||
173 | that, \k{writing} discusses how to design new games, with some | ||
174 | general design thoughts and tips. | ||
175 | |||
176 | \C{backend} Interface to the back end | ||
177 | |||
178 | This chapter gives a detailed discussion of the interface that each | ||
179 | back end must implement. | ||
180 | |||
181 | At the top level, each back end source file exports a single global | ||
182 | symbol, which is a \c{const struct game} containing a large number | ||
183 | of function pointers and a small amount of constant data. This | ||
184 | structure is called by different names depending on what kind of | ||
185 | platform the puzzle set is being compiled on: | ||
186 | |||
187 | \b On platforms such as Windows and GTK, which build a separate | ||
188 | binary for each puzzle, the game structure in every back end has the | ||
189 | same name, \cq{thegame}; the front end refers directly to this name, | ||
190 | so that compiling the same front end module against a different back | ||
191 | end module builds a different puzzle. | ||
192 | |||
193 | \b On platforms such as MacOS X and PalmOS, which build all the | ||
194 | puzzles into a single monolithic binary, the game structure in each | ||
195 | back end must have a different name, and there's a helper module | ||
196 | \c{list.c} (constructed automatically by the same Perl script that | ||
197 | builds the \cw{Makefile}s) which contains a complete list of those | ||
198 | game structures. | ||
199 | |||
200 | On the latter type of platform, source files may assume that the | ||
201 | preprocessor symbol \c{COMBINED} has been defined. Thus, the usual | ||
202 | code to declare the game structure looks something like this: | ||
203 | |||
204 | \c #ifdef COMBINED | ||
205 | \c #define thegame net /* or whatever this game is called */ | ||
206 | \e iii iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii | ||
207 | \c #endif | ||
208 | \c | ||
209 | \c const struct game thegame = { | ||
210 | \c /* lots of structure initialisation in here */ | ||
211 | \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii | ||
212 | \c }; | ||
213 | |||
214 | Game back ends must also internally define a number of data | ||
215 | structures, for storing their various persistent state. This chapter | ||
216 | will first discuss the nature and use of those structures, and then | ||
217 | go on to give details of every element of the game structure. | ||
218 | |||
219 | \H{backend-structs} Data structures | ||
220 | |||
221 | Each game is required to define four separate data structures. This | ||
222 | section discusses each one and suggests what sorts of things need to | ||
223 | be put in it. | ||
224 | |||
225 | \S{backend-game-params} \c{game_params} | ||
226 | |||
227 | The \c{game_params} structure contains anything which affects the | ||
228 | automatic generation of new puzzles. So if puzzle generation is | ||
229 | parametrised in any way, those parameters need to be stored in | ||
230 | \c{game_params}. | ||
231 | |||
232 | Most puzzles currently in this collection are played on a grid of | ||
233 | squares, meaning that the most obvious parameter is the grid size. | ||
234 | Many puzzles have additional parameters; for example, Mines allows | ||
235 | you to control the number of mines in the grid independently of its | ||
236 | size, Net can be wrapping or non-wrapping, Solo has difficulty | ||
237 | levels and symmetry settings, and so on. | ||
238 | |||
239 | A simple rule for deciding whether a data item needs to go in | ||
240 | \c{game_params} is: would the user expect to be able to control this | ||
241 | data item from either the preset-game-types menu or the \q{Custom} | ||
242 | game type configuration? If so, it's part of \c{game_params}. | ||
243 | |||
244 | \c{game_params} structures are permitted to contain pointers to | ||
245 | subsidiary data if they need to. The back end is required to provide | ||
246 | functions to create and destroy \c{game_params}, and those functions | ||
247 | can allocate and free additional memory if necessary. (It has not | ||
248 | yet been necessary to do this in any puzzle so far, but the | ||
249 | capability is there just in case.) | ||
250 | |||
251 | \c{game_params} is also the only structure which the game's | ||
252 | \cw{compute_size()} function may refer to; this means that any | ||
253 | aspect of the game which affects the size of the window it needs to | ||
254 | be drawn in must be stored in \c{game_params}. In particular, this | ||
255 | imposes the fundamental limitation that random game generation may | ||
256 | not have a random effect on the window size: game generation | ||
257 | algorithms are constrained to work by starting from the grid size | ||
258 | rather than generating it as an emergent phenomenon. (Although this | ||
259 | is a restriction in theory, it has not yet seemed to be a problem.) | ||
260 | |||
261 | \S{backend-game-state} \c{game_state} | ||
262 | |||
263 | While the user is actually playing a puzzle, the \c{game_state} | ||
264 | structure stores all the data corresponding to the current state of | ||
265 | play. | ||
266 | |||
267 | The mid-end keeps \c{game_state}s in a list, and adds to the list | ||
268 | every time the player makes a move; the Undo and Redo functions step | ||
269 | back and forth through that list. | ||
270 | |||
271 | Therefore, a good means of deciding whether a data item needs to go | ||
272 | in \c{game_state} is: would a player expect that data item to be | ||
273 | restored on undo? If so, put it in \c{game_state}, and this will | ||
274 | automatically happen without you having to lift a finger. If not | ||
275 | \dash for example, the deaths counter in Mines is precisely | ||
276 | something that does \e{not} want to be reset to its previous state | ||
277 | on an undo \dash then you might have found a data item that needs to | ||
278 | go in \c{game_ui} instead. | ||
279 | |||
280 | During play, \c{game_state}s are often passed around without an | ||
281 | accompanying \c{game_params} structure. Therefore, any information | ||
282 | in \c{game_params} which is important during play (such as the grid | ||
283 | size) must be duplicated within the \c{game_state}. One simple | ||
284 | method of doing this is to have the \c{game_state} structure | ||
285 | \e{contain} a \c{game_params} structure as one of its members, | ||
286 | although this isn't obligatory if you prefer to do it another way. | ||
287 | |||
288 | \S{backend-game-drawstate} \c{game_drawstate} | ||
289 | |||
290 | \c{game_drawstate} carries persistent state relating to the current | ||
291 | graphical contents of the puzzle window. The same \c{game_drawstate} | ||
292 | is passed to every call to the game redraw function, so that it can | ||
293 | remember what it has already drawn and what needs redrawing. | ||
294 | |||
295 | A typical use for a \c{game_drawstate} is to have an array mirroring | ||
296 | the array of grid squares in the \c{game_state}; then every time the | ||
297 | redraw function was passed a \c{game_state}, it would loop over all | ||
298 | the squares, and physically redraw any whose description in the | ||
299 | \c{game_state} (i.e. what the square needs to look like when the | ||
300 | redraw is completed) did not match its description in the | ||
301 | \c{game_drawstate} (i.e. what the square currently looks like). | ||
302 | |||
303 | \c{game_drawstate} is occasionally completely torn down and | ||
304 | reconstructed by the mid-end, if the user somehow forces a full | ||
305 | redraw. Therefore, no data should be stored in \c{game_drawstate} | ||
306 | which is \e{not} related to the state of the puzzle window, because | ||
307 | it might be unexpectedly destroyed. | ||
308 | |||
309 | The back end provides functions to create and destroy | ||
310 | \c{game_drawstate}, which means it can contain pointers to | ||
311 | subsidiary allocated data if it needs to. A common thing to want to | ||
312 | allocate in a \c{game_drawstate} is a \c{blitter}; see | ||
313 | \k{drawing-blitter} for more on this subject. | ||
314 | |||
315 | \S{backend-game-ui} \c{game_ui} | ||
316 | |||
317 | \c{game_ui} contains whatever doesn't fit into the above three | ||
318 | structures! | ||
319 | |||
320 | A new \c{game_ui} is created when the user begins playing a new | ||
321 | instance of a puzzle (i.e. during \q{New Game} or after entering a | ||
322 | game ID etc). It persists until the user finishes playing that game | ||
323 | and begins another one (or closes the window); in particular, | ||
324 | \q{Restart Game} does \e{not} destroy the \c{game_ui}. | ||
325 | |||
326 | \c{game_ui} is useful for implementing user-interface state which is | ||
327 | not part of \c{game_state}. Common examples are keyboard control | ||
328 | (you wouldn't want to have to separately Undo through every cursor | ||
329 | motion) and mouse dragging. See \k{writing-keyboard-cursor} and | ||
330 | \k{writing-howto-dragging}, respectively, for more details. | ||
331 | |||
332 | Another use for \c{game_ui} is to store highly persistent data such | ||
333 | as the Mines death counter. This is conceptually rather different: | ||
334 | where the Net cursor position was \e{not important enough} to | ||
335 | preserve for the player to restore by Undo, the Mines death counter | ||
336 | is \e{too important} to permit the player to revert by Undo! | ||
337 | |||
338 | A final use for \c{game_ui} is to pass information to the redraw | ||
339 | function about recent changes to the game state. This is used in | ||
340 | Mines, for example, to indicate whether a requested \q{flash} should | ||
341 | be a white flash for victory or a red flash for defeat; see | ||
342 | \k{writing-flash-types}. | ||
343 | |||
344 | \H{backend-simple} Simple data in the back end | ||
345 | |||
346 | In this section I begin to discuss each individual element in the | ||
347 | back end structure. To begin with, here are some simple | ||
348 | self-contained data elements. | ||
349 | |||
350 | \S{backend-name} \c{name} | ||
351 | |||
352 | \c const char *name; | ||
353 | |||
354 | This is a simple ASCII string giving the name of the puzzle. This | ||
355 | name will be used in window titles, in game selection menus on | ||
356 | monolithic platforms, and anywhere else that the front end needs to | ||
357 | know the name of a game. | ||
358 | |||
359 | \S{backend-winhelp} \c{winhelp_topic} | ||
360 | |||
361 | \c const char *winhelp_topic; | ||
362 | |||
363 | This member is used on Windows only, to provide online help. | ||
364 | Although the Windows front end provides a separate binary for each | ||
365 | puzzle, it has a single monolithic help file; so when a user selects | ||
366 | \q{Help} from the menu, the program needs to open the help file and | ||
367 | jump to the chapter describing that particular puzzle. | ||
368 | |||
369 | Therefore, each chapter in \c{puzzles.but} is labelled with a | ||
370 | \e{help topic} name, similar to this: | ||
371 | |||
372 | \c \cfg{winhelp-topic}{games.net} | ||
373 | |||
374 | And then the corresponding game back end encodes the topic string | ||
375 | (here \cq{games.net}) in the \c{winhelp_topic} element of the game | ||
376 | structure. | ||
377 | |||
378 | \H{backend-params} Handling game parameter sets | ||
379 | |||
380 | In this section I present the various functions which handle the | ||
381 | \c{game_params} structure. | ||
382 | |||
383 | \S{backend-default-params} \cw{default_params()} | ||
384 | |||
385 | \c game_params *(*default_params)(void); | ||
386 | |||
387 | This function allocates a new \c{game_params} structure, fills it | ||
388 | with the default values, and returns a pointer to it. | ||
389 | |||
390 | \S{backend-fetch-preset} \cw{fetch_preset()} | ||
391 | |||
392 | \c int (*fetch_preset)(int i, char **name, game_params **params); | ||
393 | |||
394 | This function is one of the two APIs a back end can provide to | ||
395 | populate the \q{Type} menu, which provides a list of conveniently | ||
396 | accessible preset parameters for most games. | ||
397 | |||
398 | The function is called with \c{i} equal to the index of the preset | ||
399 | required (numbering from zero). It returns \cw{FALSE} if that preset | ||
400 | does not exist (if \c{i} is less than zero or greater than the | ||
401 | largest preset index). Otherwise, it sets \c{*params} to point at a | ||
402 | newly allocated \c{game_params} structure containing the preset | ||
403 | information, sets \c{*name} to point at a newly allocated C string | ||
404 | containing the preset title (to go on the \q{Type} menu), and | ||
405 | returns \cw{TRUE}. | ||
406 | |||
407 | If the game does not wish to support any presets at all, this | ||
408 | function is permitted to return \cw{FALSE} always. | ||
409 | |||
410 | If the game wants to return presets in the form of a hierarchical menu | ||
411 | instead of a flat list (and, indeed, even if it doesn't), then it may | ||
412 | set this function pointer to \cw{NULL}, and instead fill in the | ||
413 | alternative function pointer \cw{preset_menu} | ||
414 | (\k{backend-preset-menu}). | ||
415 | |||
416 | \S{backend-preset-menu} \cw{preset_menu()} | ||
417 | |||
418 | \c struct preset_menu *(*preset_menu)(void); | ||
419 | |||
420 | This function is the more flexible of the two APIs by which a back end | ||
421 | can define a collection of preset game parameters. | ||
422 | |||
423 | This function simply returns a complete menu hierarchy, in the form of | ||
424 | a \c{struct preset_menu} (see \k{midend-get-presets}) and further | ||
425 | submenus (if it wishes) dangling off it. There are utility functions | ||
426 | described in \k{utils-presets} to make it easy for the back end to | ||
427 | construct this menu. | ||
428 | |||
429 | If the game has no need to return a hierarchy of menus, it may instead | ||
430 | opt to implement the \cw{fetch_preset()} function (see | ||
431 | \k{backend-fetch-preset}). | ||
432 | |||
433 | The game need not fill in the \c{id} fields in the preset menu | ||
434 | structures. The mid-end will do that after it receives the structure | ||
435 | from the game, and before passing it on to the front end. | ||
436 | |||
437 | \S{backend-encode-params} \cw{encode_params()} | ||
438 | |||
439 | \c char *(*encode_params)(const game_params *params, int full); | ||
440 | |||
441 | The job of this function is to take a \c{game_params}, and encode it | ||
442 | in a string form for use in game IDs. The return value must be a | ||
443 | newly allocated C string, and \e{must} not contain a colon or a hash | ||
444 | (since those characters are used to mark the end of the parameter | ||
445 | section in a game ID). | ||
446 | |||
447 | Ideally, it should also not contain any other potentially | ||
448 | controversial punctuation; bear in mind when designing a string | ||
449 | parameter format that it will probably be used on both Windows and | ||
450 | Unix command lines under a variety of exciting shell quoting and | ||
451 | metacharacter rules. Sticking entirely to alphanumerics is the | ||
452 | safest thing; if you really need punctuation, you can probably get | ||
453 | away with commas, periods or underscores without causing anybody any | ||
454 | major inconvenience. If you venture far beyond that, you're likely | ||
455 | to irritate \e{somebody}. | ||
456 | |||
457 | (At the time of writing this, all existing games have purely | ||
458 | alphanumeric string parameter formats. Usually these involve a | ||
459 | letter denoting a parameter, followed optionally by a number giving | ||
460 | the value of that parameter, with a few mandatory parts at the | ||
461 | beginning such as numeric width and height separated by \cq{x}.) | ||
462 | |||
463 | If the \c{full} parameter is \cw{TRUE}, this function should encode | ||
464 | absolutely everything in the \c{game_params}, such that a subsequent | ||
465 | call to \cw{decode_params()} (\k{backend-decode-params}) will yield | ||
466 | an identical structure. If \c{full} is \cw{FALSE}, however, you | ||
467 | should leave out anything which is not necessary to describe a | ||
468 | \e{specific puzzle instance}, i.e. anything which only takes effect | ||
469 | when a new puzzle is \e{generated}. For example, the Solo | ||
470 | \c{game_params} includes a difficulty rating used when constructing | ||
471 | new puzzles; but a Solo game ID need not explicitly include the | ||
472 | difficulty, since to describe a puzzle once generated it's | ||
473 | sufficient to give the grid dimensions and the location and contents | ||
474 | of the clue squares. (Indeed, one might very easily type in a puzzle | ||
475 | out of a newspaper without \e{knowing} what its difficulty level is | ||
476 | in Solo's terminology.) Therefore, Solo's \cw{encode_params()} only | ||
477 | encodes the difficulty level if \c{full} is set. | ||
478 | |||
479 | \S{backend-decode-params} \cw{decode_params()} | ||
480 | |||
481 | \c void (*decode_params)(game_params *params, char const *string); | ||
482 | |||
483 | This function is the inverse of \cw{encode_params()} | ||
484 | (\k{backend-encode-params}). It parses the supplied string and fills | ||
485 | in the supplied \c{game_params} structure. Note that the structure | ||
486 | will \e{already} have been allocated: this function is not expected | ||
487 | to create a \e{new} \c{game_params}, but to modify an existing one. | ||
488 | |||
489 | This function can receive a string which only encodes a subset of | ||
490 | the parameters. The most obvious way in which this can happen is if | ||
491 | the string was constructed by \cw{encode_params()} with its \c{full} | ||
492 | parameter set to \cw{FALSE}; however, it could also happen if the | ||
493 | user typed in a parameter set manually and missed something out. Be | ||
494 | prepared to deal with a wide range of possibilities. | ||
495 | |||
496 | When dealing with a parameter which is not specified in the input | ||
497 | string, what to do requires a judgment call on the part of the | ||
498 | programmer. Sometimes it makes sense to adjust other parameters to | ||
499 | bring them into line with the new ones. In Mines, for example, you | ||
500 | would probably not want to keep the same mine count if the user | ||
501 | dropped the grid size and didn't specify one, since you might easily | ||
502 | end up with more mines than would actually fit in the grid! On the | ||
503 | other hand, sometimes it makes sense to leave the parameter alone: a | ||
504 | Solo player might reasonably expect to be able to configure size and | ||
505 | difficulty independently of one another. | ||
506 | |||
507 | This function currently has no direct means of returning an error if | ||
508 | the string cannot be parsed at all. However, the returned | ||
509 | \c{game_params} is almost always subsequently passed to | ||
510 | \cw{validate_params()} (\k{backend-validate-params}), so if you | ||
511 | really want to signal parse errors, you could always have a \c{char | ||
512 | *} in your parameters structure which stored an error message, and | ||
513 | have \cw{validate_params()} return it if it is non-\cw{NULL}. | ||
514 | |||
515 | \S{backend-free-params} \cw{free_params()} | ||
516 | |||
517 | \c void (*free_params)(game_params *params); | ||
518 | |||
519 | This function frees a \c{game_params} structure, and any subsidiary | ||
520 | allocations contained within it. | ||
521 | |||
522 | \S{backend-dup-params} \cw{dup_params()} | ||
523 | |||
524 | \c game_params *(*dup_params)(const game_params *params); | ||
525 | |||
526 | This function allocates a new \c{game_params} structure and | ||
527 | initialises it with an exact copy of the information in the one | ||
528 | provided as input. It returns a pointer to the new duplicate. | ||
529 | |||
530 | \S{backend-can-configure} \c{can_configure} | ||
531 | |||
532 | \c int can_configure; | ||
533 | |||
534 | This boolean data element is set to \cw{TRUE} if the back end | ||
535 | supports custom parameter configuration via a dialog box. If it is | ||
536 | \cw{TRUE}, then the functions \cw{configure()} and | ||
537 | \cw{custom_params()} are expected to work. See \k{backend-configure} | ||
538 | and \k{backend-custom-params} for more details. | ||
539 | |||
540 | \S{backend-configure} \cw{configure()} | ||
541 | |||
542 | \c config_item *(*configure)(const game_params *params); | ||
543 | |||
544 | This function is called when the user requests a dialog box for | ||
545 | custom parameter configuration. It returns a newly allocated array | ||
546 | of \cw{config_item} structures, describing the GUI elements required | ||
547 | in the dialog box. The array should have one more element than the | ||
548 | number of controls, since it is terminated with a \cw{C_END} marker | ||
549 | (see below). Each array element describes the control together with | ||
550 | its initial value; the front end will modify the value fields and | ||
551 | return the updated array to \cw{custom_params()} (see | ||
552 | \k{backend-custom-params}). | ||
553 | |||
554 | The \cw{config_item} structure contains the following elements: | ||
555 | |||
556 | \c char *name; | ||
557 | \c int type; | ||
558 | \c char *sval; | ||
559 | \c int ival; | ||
560 | |||
561 | \c{name} is an ASCII string giving the textual label for a GUI | ||
562 | control. It is \e{not} expected to be dynamically allocated. | ||
563 | |||
564 | \c{type} contains one of a small number of \c{enum} values defining | ||
565 | what type of control is being described. The meaning of the \c{sval} | ||
566 | and \c{ival} fields depends on the value in \c{type}. The valid | ||
567 | values are: | ||
568 | |||
569 | \dt \c{C_STRING} | ||
570 | |||
571 | \dd Describes a text input box. (This is also used for numeric | ||
572 | input. The back end does not bother informing the front end that the | ||
573 | box is numeric rather than textual; some front ends do have the | ||
574 | capacity to take this into account, but I decided it wasn't worth | ||
575 | the extra complexity in the interface.) For this type, \c{ival} is | ||
576 | unused, and \c{sval} contains a dynamically allocated string | ||
577 | representing the contents of the input box. | ||
578 | |||
579 | \dt \c{C_BOOLEAN} | ||
580 | |||
581 | \dd Describes a simple checkbox. For this type, \c{sval} is unused, | ||
582 | and \c{ival} is \cw{TRUE} or \cw{FALSE}. | ||
583 | |||
584 | \dt \c{C_CHOICES} | ||
585 | |||
586 | \dd Describes a drop-down list presenting one of a small number of | ||
587 | fixed choices. For this type, \c{sval} contains a list of strings | ||
588 | describing the choices; the very first character of \c{sval} is used | ||
589 | as a delimiter when processing the rest (so that the strings | ||
590 | \cq{:zero:one:two}, \cq{!zero!one!two} and \cq{xzeroxonextwo} all | ||
591 | define a three-element list containing \cq{zero}, \cq{one} and | ||
592 | \cq{two}). \c{ival} contains the index of the currently selected | ||
593 | element, numbering from zero (so that in the above example, 0 would | ||
594 | mean \cq{zero} and 2 would mean \cq{two}). | ||
595 | |||
596 | \lcont{ | ||
597 | |||
598 | Note that for this control type, \c{sval} is \e{not} dynamically | ||
599 | allocated, whereas it was for \c{C_STRING}. | ||
600 | |||
601 | } | ||
602 | |||
603 | \dt \c{C_END} | ||
604 | |||
605 | \dd Marks the end of the array of \c{config_item}s. All other fields | ||
606 | are unused. | ||
607 | |||
608 | The array returned from this function is expected to have filled in | ||
609 | the initial values of all the controls according to the input | ||
610 | \c{game_params} structure. | ||
611 | |||
612 | If the game's \c{can_configure} flag is set to \cw{FALSE}, this | ||
613 | function is never called and need not do anything at all. | ||
614 | |||
615 | \S{backend-custom-params} \cw{custom_params()} | ||
616 | |||
617 | \c game_params *(*custom_params)(const config_item *cfg); | ||
618 | |||
619 | This function is the counterpart to \cw{configure()} | ||
620 | (\k{backend-configure}). It receives as input an array of | ||
621 | \c{config_item}s which was originally created by \cw{configure()}, | ||
622 | but in which the control values have since been changed in | ||
623 | accordance with user input. Its function is to read the new values | ||
624 | out of the controls and return a newly allocated \c{game_params} | ||
625 | structure representing the user's chosen parameter set. | ||
626 | |||
627 | (The front end will have modified the controls' \e{values}, but | ||
628 | there will still always be the same set of controls, in the same | ||
629 | order, as provided by \cw{configure()}. It is not necessary to check | ||
630 | the \c{name} and \c{type} fields, although you could use | ||
631 | \cw{assert()} if you were feeling energetic.) | ||
632 | |||
633 | This function is not expected to (and indeed \e{must not}) free the | ||
634 | input \c{config_item} array. (If the parameters fail to validate, | ||
635 | the dialog box will stay open.) | ||
636 | |||
637 | If the game's \c{can_configure} flag is set to \cw{FALSE}, this | ||
638 | function is never called and need not do anything at all. | ||
639 | |||
640 | \S{backend-validate-params} \cw{validate_params()} | ||
641 | |||
642 | \c char *(*validate_params)(const game_params *params, int full); | ||
643 | |||
644 | This function takes a \c{game_params} structure as input, and checks | ||
645 | that the parameters described in it fall within sensible limits. (At | ||
646 | the very least, grid dimensions should almost certainly be strictly | ||
647 | positive, for example.) | ||
648 | |||
649 | Return value is \cw{NULL} if no problems were found, or | ||
650 | alternatively a (non-dynamically-allocated) ASCII string describing | ||
651 | the error in human-readable form. | ||
652 | |||
653 | If the \c{full} parameter is set, full validation should be | ||
654 | performed: any set of parameters which would not permit generation | ||
655 | of a sensible puzzle should be faulted. If \c{full} is \e{not} set, | ||
656 | the implication is that these parameters are not going to be used | ||
657 | for \e{generating} a puzzle; so parameters which can't even sensibly | ||
658 | \e{describe} a valid puzzle should still be faulted, but parameters | ||
659 | which only affect puzzle generation should not be. | ||
660 | |||
661 | (The \c{full} option makes a difference when parameter combinations | ||
662 | are non-orthogonal. For example, Net has a boolean option | ||
663 | controlling whether it enforces a unique solution; it turns out that | ||
664 | it's impossible to generate a uniquely soluble puzzle with wrapping | ||
665 | walls and width 2, so \cw{validate_params()} will complain if you | ||
666 | ask for one. However, if the user had just been playing a unique | ||
667 | wrapping puzzle of a more sensible width, and then pastes in a game | ||
668 | ID acquired from somebody else which happens to describe a | ||
669 | \e{non}-unique wrapping width-2 puzzle, then \cw{validate_params()} | ||
670 | will be passed a \c{game_params} containing the width and wrapping | ||
671 | settings from the new game ID and the uniqueness setting from the | ||
672 | old one. This would be faulted, if it weren't for the fact that | ||
673 | \c{full} is not set during this call, so Net ignores the | ||
674 | inconsistency. The resulting \c{game_params} is never subsequently | ||
675 | used to generate a puzzle; this is a promise made by the mid-end | ||
676 | when it asks for a non-full validation.) | ||
677 | |||
678 | \H{backend-descs} Handling game descriptions | ||
679 | |||
680 | In this section I present the functions that deal with a textual | ||
681 | description of a puzzle, i.e. the part that comes after the colon in | ||
682 | a descriptive-format game ID. | ||
683 | |||
684 | \S{backend-new-desc} \cw{new_desc()} | ||
685 | |||
686 | \c char *(*new_desc)(const game_params *params, random_state *rs, | ||
687 | \c char **aux, int interactive); | ||
688 | |||
689 | This function is where all the really hard work gets done. This is | ||
690 | the function whose job is to randomly generate a new puzzle, | ||
691 | ensuring solubility and uniqueness as appropriate. | ||
692 | |||
693 | As input it is given a \c{game_params} structure and a random state | ||
694 | (see \k{utils-random} for the random number API). It must invent a | ||
695 | puzzle instance, encode it in string form, and return a dynamically | ||
696 | allocated C string containing that encoding. | ||
697 | |||
698 | Additionally, it may return a second dynamically allocated string in | ||
699 | \c{*aux}. (If it doesn't want to, then it can leave that parameter | ||
700 | completely alone; it isn't required to set it to \cw{NULL}, although | ||
701 | doing so is harmless.) That string, if present, will be passed to | ||
702 | \cw{solve()} (\k{backend-solve}) later on; so if the puzzle is | ||
703 | generated in such a way that a solution is known, then information | ||
704 | about that solution can be saved in \c{*aux} for \cw{solve()} to | ||
705 | use. | ||
706 | |||
707 | The \c{interactive} parameter should be ignored by almost all | ||
708 | puzzles. Its purpose is to distinguish between generating a puzzle | ||
709 | within a GUI context for immediate play, and generating a puzzle in | ||
710 | a command-line context for saving to be played later. The only | ||
711 | puzzle that currently uses this distinction (and, I fervently hope, | ||
712 | the only one which will \e{ever} need to use it) is Mines, which | ||
713 | chooses a random first-click location when generating puzzles | ||
714 | non-interactively, but which waits for the user to place the first | ||
715 | click when interactive. If you think you have come up with another | ||
716 | puzzle which needs to make use of this parameter, please think for | ||
717 | at least ten minutes about whether there is \e{any} alternative! | ||
718 | |||
719 | Note that game description strings are not required to contain an | ||
720 | encoding of parameters such as grid size; a game description is | ||
721 | never separated from the \c{game_params} it was generated with, so | ||
722 | any information contained in that structure need not be encoded | ||
723 | again in the game description. | ||
724 | |||
725 | \S{backend-validate-desc} \cw{validate_desc()} | ||
726 | |||
727 | \c char *(*validate_desc)(const game_params *params, const char *desc); | ||
728 | |||
729 | This function is given a game description, and its job is to | ||
730 | validate that it describes a puzzle which makes sense. | ||
731 | |||
732 | To some extent it's up to the user exactly how far they take the | ||
733 | phrase \q{makes sense}; there are no particularly strict rules about | ||
734 | how hard the user is permitted to shoot themself in the foot when | ||
735 | typing in a bogus game description by hand. (For example, Rectangles | ||
736 | will not verify that the sum of all the numbers in the grid equals | ||
737 | the grid's area. So a user could enter a puzzle which was provably | ||
738 | not soluble, and the program wouldn't complain; there just wouldn't | ||
739 | happen to be any sequence of moves which solved it.) | ||
740 | |||
741 | The one non-negotiable criterion is that any game description which | ||
742 | makes it through \cw{validate_desc()} \e{must not} subsequently | ||
743 | cause a crash or an assertion failure when fed to \cw{new_game()} | ||
744 | and thence to the rest of the back end. | ||
745 | |||
746 | The return value is \cw{NULL} on success, or a | ||
747 | non-dynamically-allocated C string containing an error message. | ||
748 | |||
749 | \S{backend-new-game} \cw{new_game()} | ||
750 | |||
751 | \c game_state *(*new_game)(midend *me, const game_params *params, | ||
752 | \c const char *desc); | ||
753 | |||
754 | This function takes a game description as input, together with its | ||
755 | accompanying \c{game_params}, and constructs a \c{game_state} | ||
756 | describing the initial state of the puzzle. It returns a newly | ||
757 | allocated \c{game_state} structure. | ||
758 | |||
759 | Almost all puzzles should ignore the \c{me} parameter. It is | ||
760 | required by Mines, which needs it for later passing to | ||
761 | \cw{midend_supersede_game_desc()} (see \k{backend-supersede}) once | ||
762 | the user has placed the first click. I fervently hope that no other | ||
763 | puzzle will be awkward enough to require it, so everybody else | ||
764 | should ignore it. As with the \c{interactive} parameter in | ||
765 | \cw{new_desc()} (\k{backend-new-desc}), if you think you have a | ||
766 | reason to need this parameter, please try very hard to think of an | ||
767 | alternative approach! | ||
768 | |||
769 | \H{backend-states} Handling game states | ||
770 | |||
771 | This section describes the functions which create and destroy | ||
772 | \c{game_state} structures. | ||
773 | |||
774 | (Well, except \cw{new_game()}, which is in \k{backend-new-game} | ||
775 | instead of under here; but it deals with game descriptions \e{and} | ||
776 | game states and it had to go in one section or the other.) | ||
777 | |||
778 | \S{backend-dup-game} \cw{dup_game()} | ||
779 | |||
780 | \c game_state *(*dup_game)(const game_state *state); | ||
781 | |||
782 | This function allocates a new \c{game_state} structure and | ||
783 | initialises it with an exact copy of the information in the one | ||
784 | provided as input. It returns a pointer to the new duplicate. | ||
785 | |||
786 | \S{backend-free-game} \cw{free_game()} | ||
787 | |||
788 | \c void (*free_game)(game_state *state); | ||
789 | |||
790 | This function frees a \c{game_state} structure, and any subsidiary | ||
791 | allocations contained within it. | ||
792 | |||
793 | \H{backend-ui} Handling \c{game_ui} | ||
794 | |||
795 | \S{backend-new-ui} \cw{new_ui()} | ||
796 | |||
797 | \c game_ui *(*new_ui)(const game_state *state); | ||
798 | |||
799 | This function allocates and returns a new \c{game_ui} structure for | ||
800 | playing a particular puzzle. It is passed a pointer to the initial | ||
801 | \c{game_state}, in case it needs to refer to that when setting up | ||
802 | the initial values for the new game. | ||
803 | |||
804 | \S{backend-free-ui} \cw{free_ui()} | ||
805 | |||
806 | \c void (*free_ui)(game_ui *ui); | ||
807 | |||
808 | This function frees a \c{game_ui} structure, and any subsidiary | ||
809 | allocations contained within it. | ||
810 | |||
811 | \S{backend-encode-ui} \cw{encode_ui()} | ||
812 | |||
813 | \c char *(*encode_ui)(const game_ui *ui); | ||
814 | |||
815 | This function encodes any \e{important} data in a \c{game_ui} | ||
816 | structure in string form. It is only called when saving a | ||
817 | half-finished game to a file. | ||
818 | |||
819 | It should be used sparingly. Almost all data in a \c{game_ui} is not | ||
820 | important enough to save. The location of the keyboard-controlled | ||
821 | cursor, for example, can be reset to a default position on reloading | ||
822 | the game without impacting the user experience. If the user should | ||
823 | somehow manage to save a game while a mouse drag was in progress, | ||
824 | then discarding that mouse drag would be an outright \e{feature}. | ||
825 | |||
826 | A typical thing that \e{would} be worth encoding in this function is | ||
827 | the Mines death counter: it's in the \c{game_ui} rather than the | ||
828 | \c{game_state} because it's too important to allow the user to | ||
829 | revert it by using Undo, and therefore it's also too important to | ||
830 | allow the user to revert it by saving and reloading. (Of course, the | ||
831 | user could edit the save file by hand... But if the user is \e{that} | ||
832 | determined to cheat, they could just as easily modify the game's | ||
833 | source.) | ||
834 | |||
835 | \S{backend-decode-ui} \cw{decode_ui()} | ||
836 | |||
837 | \c void (*decode_ui)(game_ui *ui, const char *encoding); | ||
838 | |||
839 | This function parses a string previously output by \cw{encode_ui()}, | ||
840 | and writes the decoded data back into the provided \c{game_ui} | ||
841 | structure. | ||
842 | |||
843 | \S{backend-changed-state} \cw{changed_state()} | ||
844 | |||
845 | \c void (*changed_state)(game_ui *ui, const game_state *oldstate, | ||
846 | \c const game_state *newstate); | ||
847 | |||
848 | This function is called by the mid-end whenever the current game | ||
849 | state changes, for any reason. Those reasons include: | ||
850 | |||
851 | \b a fresh move being made by \cw{interpret_move()} and | ||
852 | \cw{execute_move()} | ||
853 | |||
854 | \b a solve operation being performed by \cw{solve()} and | ||
855 | \cw{execute_move()} | ||
856 | |||
857 | \b the user moving back and forth along the undo list by means of | ||
858 | the Undo and Redo operations | ||
859 | |||
860 | \b the user selecting Restart to go back to the initial game state. | ||
861 | |||
862 | The job of \cw{changed_state()} is to update the \c{game_ui} for | ||
863 | consistency with the new game state, if any update is necessary. For | ||
864 | example, Same Game stores data about the currently selected tile | ||
865 | group in its \c{game_ui}, and this data is intrinsically related to | ||
866 | the game state it was derived from. So it's very likely to become | ||
867 | invalid when the game state changes; thus, Same Game's | ||
868 | \cw{changed_state()} function clears the current selection whenever | ||
869 | it is called. | ||
870 | |||
871 | When \cw{anim_length()} or \cw{flash_length()} are called, you can | ||
872 | be sure that there has been a previous call to \cw{changed_state()}. | ||
873 | So \cw{changed_state()} can set up data in the \c{game_ui} which will | ||
874 | be read by \cw{anim_length()} and \cw{flash_length()}, and those | ||
875 | functions will not have to worry about being called without the data | ||
876 | having been initialised. | ||
877 | |||
878 | \H{backend-moves} Making moves | ||
879 | |||
880 | This section describes the functions which actually make moves in | ||
881 | the game: that is, the functions which process user input and end up | ||
882 | producing new \c{game_state}s. | ||
883 | |||
884 | \S{backend-interpret-move} \cw{interpret_move()} | ||
885 | |||
886 | \c char *(*interpret_move)(const game_state *state, game_ui *ui, | ||
887 | \c const game_drawstate *ds, | ||
888 | \c int x, int y, int button); | ||
889 | |||
890 | This function receives user input and processes it. Its input | ||
891 | parameters are the current \c{game_state}, the current \c{game_ui} | ||
892 | and the current \c{game_drawstate}, plus details of the input event. | ||
893 | \c{button} is either an ASCII value or a special code (listed below) | ||
894 | indicating an arrow or function key or a mouse event; when | ||
895 | \c{button} is a mouse event, \c{x} and \c{y} contain the pixel | ||
896 | coordinates of the mouse pointer relative to the top left of the | ||
897 | puzzle's drawing area. | ||
898 | |||
899 | (The pointer to the \c{game_drawstate} is marked \c{const}, because | ||
900 | \c{interpret_move} should not write to it. The normal use of that | ||
901 | pointer will be to read the game's tile size parameter in order to | ||
902 | divide mouse coordinates by it.) | ||
903 | |||
904 | \cw{interpret_move()} may return in three different ways: | ||
905 | |||
906 | \b Returning \cw{NULL} indicates that no action whatsoever occurred | ||
907 | in response to the input event; the puzzle was not interested in it | ||
908 | at all. | ||
909 | |||
910 | \b Returning the empty string (\cw{""}) indicates that the input | ||
911 | event has resulted in a change being made to the \c{game_ui} which | ||
912 | will require a redraw of the game window, but that no actual | ||
913 | \e{move} was made (i.e. no new \c{game_state} needs to be created). | ||
914 | |||
915 | \b Returning anything else indicates that a move was made and that a | ||
916 | new \c{game_state} must be created. However, instead of actually | ||
917 | constructing a new \c{game_state} itself, this function is required | ||
918 | to return a string description of the details of the move. This | ||
919 | string will be passed to \cw{execute_move()} | ||
920 | (\k{backend-execute-move}) to actually create the new | ||
921 | \c{game_state}. (Encoding moves as strings in this way means that | ||
922 | the mid-end can keep the strings as well as the game states, and the | ||
923 | strings can be written to disk when saving the game and fed to | ||
924 | \cw{execute_move()} again on reloading.) | ||
925 | |||
926 | The return value from \cw{interpret_move()} is expected to be | ||
927 | dynamically allocated if and only if it is not either \cw{NULL} | ||
928 | \e{or} the empty string. | ||
929 | |||
930 | After this function is called, the back end is permitted to rely on | ||
931 | some subsequent operations happening in sequence: | ||
932 | |||
933 | \b \cw{execute_move()} will be called to convert this move | ||
934 | description into a new \c{game_state} | ||
935 | |||
936 | \b \cw{changed_state()} will be called with the new \c{game_state}. | ||
937 | |||
938 | This means that if \cw{interpret_move()} needs to do updates to the | ||
939 | \c{game_ui} which are easier to perform by referring to the new | ||
940 | \c{game_state}, it can safely leave them to be done in | ||
941 | \cw{changed_state()} and not worry about them failing to happen. | ||
942 | |||
943 | (Note, however, that \cw{execute_move()} may \e{also} be called in | ||
944 | other circumstances. It is only \cw{interpret_move()} which can rely | ||
945 | on a subsequent call to \cw{changed_state()}.) | ||
946 | |||
947 | The special key codes supported by this function are: | ||
948 | |||
949 | \dt \cw{LEFT_BUTTON}, \cw{MIDDLE_BUTTON}, \cw{RIGHT_BUTTON} | ||
950 | |||
951 | \dd Indicate that one of the mouse buttons was pressed down. | ||
952 | |||
953 | \dt \cw{LEFT_DRAG}, \cw{MIDDLE_DRAG}, \cw{RIGHT_DRAG} | ||
954 | |||
955 | \dd Indicate that the mouse was moved while one of the mouse buttons | ||
956 | was still down. The mid-end guarantees that when one of these events | ||
957 | is received, it will always have been preceded by a button-down | ||
958 | event (and possibly other drag events) for the same mouse button, | ||
959 | and no event involving another mouse button will have appeared in | ||
960 | between. | ||
961 | |||
962 | \dt \cw{LEFT_RELEASE}, \cw{MIDDLE_RELEASE}, \cw{RIGHT_RELEASE} | ||
963 | |||
964 | \dd Indicate that a mouse button was released. The mid-end | ||
965 | guarantees that when one of these events is received, it will always | ||
966 | have been preceded by a button-down event (and possibly some drag | ||
967 | events) for the same mouse button, and no event involving another | ||
968 | mouse button will have appeared in between. | ||
969 | |||
970 | \dt \cw{CURSOR_UP}, \cw{CURSOR_DOWN}, \cw{CURSOR_LEFT}, | ||
971 | \cw{CURSOR_RIGHT} | ||
972 | |||
973 | \dd Indicate that an arrow key was pressed. | ||
974 | |||
975 | \dt \cw{CURSOR_SELECT} | ||
976 | |||
977 | \dd On platforms which have a prominent \q{select} button alongside | ||
978 | their cursor keys, indicates that that button was pressed. | ||
979 | |||
980 | In addition, there are some modifiers which can be bitwise-ORed into | ||
981 | the \c{button} parameter: | ||
982 | |||
983 | \dt \cw{MOD_CTRL}, \cw{MOD_SHFT} | ||
984 | |||
985 | \dd These indicate that the Control or Shift key was pressed | ||
986 | alongside the key. They only apply to the cursor keys, not to mouse | ||
987 | buttons or anything else. | ||
988 | |||
989 | \dt \cw{MOD_NUM_KEYPAD} | ||
990 | |||
991 | \dd This applies to some ASCII values, and indicates that the key | ||
992 | code was input via the numeric keypad rather than the main keyboard. | ||
993 | Some puzzles may wish to treat this differently (for example, a | ||
994 | puzzle might want to use the numeric keypad as an eight-way | ||
995 | directional pad), whereas others might not (a game involving numeric | ||
996 | input probably just wants to treat the numeric keypad as numbers). | ||
997 | |||
998 | \dt \cw{MOD_MASK} | ||
999 | |||
1000 | \dd This mask is the bitwise OR of all the available modifiers; you | ||
1001 | can bitwise-AND with \cw{~MOD_MASK} to strip all the modifiers off | ||
1002 | any input value. | ||
1003 | |||
1004 | \S{backend-execute-move} \cw{execute_move()} | ||
1005 | |||
1006 | \c game_state *(*execute_move)(const game_state *state, char *move); | ||
1007 | |||
1008 | This function takes an input \c{game_state} and a move string as | ||
1009 | output from \cw{interpret_move()}. It returns a newly allocated | ||
1010 | \c{game_state} which contains the result of applying the specified | ||
1011 | move to the input game state. | ||
1012 | |||
1013 | This function may return \cw{NULL} if it cannot parse the move | ||
1014 | string (and this is definitely preferable to crashing or failing an | ||
1015 | assertion, since one way this can happen is if loading a corrupt | ||
1016 | save file). However, it must not return \cw{NULL} for any move | ||
1017 | string that really was output from \cw{interpret_move()}: this is | ||
1018 | punishable by assertion failure in the mid-end. | ||
1019 | |||
1020 | \S{backend-can-solve} \c{can_solve} | ||
1021 | |||
1022 | \c int can_solve; | ||
1023 | |||
1024 | This boolean field is set to \cw{TRUE} if the game's \cw{solve()} | ||
1025 | function does something. If it's set to \cw{FALSE}, the game will | ||
1026 | not even offer the \q{Solve} menu option. | ||
1027 | |||
1028 | \S{backend-solve} \cw{solve()} | ||
1029 | |||
1030 | \c char *(*solve)(const game_state *orig, const game_state *curr, | ||
1031 | \c const char *aux, char **error); | ||
1032 | |||
1033 | This function is called when the user selects the \q{Solve} option | ||
1034 | from the menu. | ||
1035 | |||
1036 | It is passed two input game states: \c{orig} is the game state from | ||
1037 | the very start of the puzzle, and \c{curr} is the current one. | ||
1038 | (Different games find one or other or both of these convenient.) It | ||
1039 | is also passed the \c{aux} string saved by \cw{new_desc()} | ||
1040 | (\k{backend-new-desc}), in case that encodes important information | ||
1041 | needed to provide the solution. | ||
1042 | |||
1043 | If this function is unable to produce a solution (perhaps, for | ||
1044 | example, the game has no in-built solver so it can only solve | ||
1045 | puzzles it invented internally and has an \c{aux} string for) then | ||
1046 | it may return \cw{NULL}. If it does this, it must also set | ||
1047 | \c{*error} to an error message to be presented to the user (such as | ||
1048 | \q{Solution not known for this puzzle}); that error message is not | ||
1049 | expected to be dynamically allocated. | ||
1050 | |||
1051 | If this function \e{does} produce a solution, it returns a move string | ||
1052 | suitable for feeding to \cw{execute_move()} | ||
1053 | (\k{backend-execute-move}). Like a (non-empty) string returned from | ||
1054 | \cw{interpret_move()}, the returned string should be dynamically | ||
1055 | allocated. | ||
1056 | |||
1057 | \H{backend-drawing} Drawing the game graphics | ||
1058 | |||
1059 | This section discusses the back end functions that deal with | ||
1060 | drawing. | ||
1061 | |||
1062 | \S{backend-new-drawstate} \cw{new_drawstate()} | ||
1063 | |||
1064 | \c game_drawstate *(*new_drawstate)(drawing *dr, | ||
1065 | \c const game_state *state); | ||
1066 | |||
1067 | This function allocates and returns a new \c{game_drawstate} | ||
1068 | structure for drawing a particular puzzle. It is passed a pointer to | ||
1069 | a \c{game_state}, in case it needs to refer to that when setting up | ||
1070 | any initial data. | ||
1071 | |||
1072 | This function may not rely on the puzzle having been newly started; | ||
1073 | a new draw state can be constructed at any time if the front end | ||
1074 | requests a forced redraw. For games like Pattern, in which initial | ||
1075 | game states are much simpler than general ones, this might be | ||
1076 | important to keep in mind. | ||
1077 | |||
1078 | The parameter \c{dr} is a drawing object (see \k{drawing}) which the | ||
1079 | function might need to use to allocate blitters. (However, this | ||
1080 | isn't recommended; it's usually more sensible to wait to allocate a | ||
1081 | blitter until \cw{set_size()} is called, because that way you can | ||
1082 | tailor it to the scale at which the puzzle is being drawn.) | ||
1083 | |||
1084 | \S{backend-free-drawstate} \cw{free_drawstate()} | ||
1085 | |||
1086 | \c void (*free_drawstate)(drawing *dr, game_drawstate *ds); | ||
1087 | |||
1088 | This function frees a \c{game_drawstate} structure, and any | ||
1089 | subsidiary allocations contained within it. | ||
1090 | |||
1091 | The parameter \c{dr} is a drawing object (see \k{drawing}), which | ||
1092 | might be required if you are freeing a blitter. | ||
1093 | |||
1094 | \S{backend-preferred-tilesize} \c{preferred_tilesize} | ||
1095 | |||
1096 | \c int preferred_tilesize; | ||
1097 | |||
1098 | Each game is required to define a single integer parameter which | ||
1099 | expresses, in some sense, the scale at which it is drawn. This is | ||
1100 | described in the APIs as \cq{tilesize}, since most puzzles are on a | ||
1101 | square (or possibly triangular or hexagonal) grid and hence a | ||
1102 | sensible interpretation of this parameter is to define it as the | ||
1103 | size of one grid tile in pixels; however, there's no actual | ||
1104 | requirement that the \q{tile size} be proportional to the game | ||
1105 | window size. Window size is required to increase monotonically with | ||
1106 | \q{tile size}, however. | ||
1107 | |||
1108 | The data element \c{preferred_tilesize} indicates the tile size | ||
1109 | which should be used in the absence of a good reason to do otherwise | ||
1110 | (such as the screen being too small, or the user explicitly | ||
1111 | requesting a resize if that ever gets implemented). | ||
1112 | |||
1113 | \S{backend-compute-size} \cw{compute_size()} | ||
1114 | |||
1115 | \c void (*compute_size)(const game_params *params, int tilesize, | ||
1116 | \c int *x, int *y); | ||
1117 | |||
1118 | This function is passed a \c{game_params} structure and a tile size. | ||
1119 | It returns, in \c{*x} and \c{*y}, the size in pixels of the drawing | ||
1120 | area that would be required to render a puzzle with those parameters | ||
1121 | at that tile size. | ||
1122 | |||
1123 | \S{backend-set-size} \cw{set_size()} | ||
1124 | |||
1125 | \c void (*set_size)(drawing *dr, game_drawstate *ds, | ||
1126 | \c const game_params *params, int tilesize); | ||
1127 | |||
1128 | This function is responsible for setting up a \c{game_drawstate} to | ||
1129 | draw at a given tile size. Typically this will simply involve | ||
1130 | copying the supplied \c{tilesize} parameter into a \c{tilesize} | ||
1131 | field inside the draw state; for some more complex games it might | ||
1132 | also involve setting up other dimension fields, or possibly | ||
1133 | allocating a blitter (see \k{drawing-blitter}). | ||
1134 | |||
1135 | The parameter \c{dr} is a drawing object (see \k{drawing}), which is | ||
1136 | required if a blitter needs to be allocated. | ||
1137 | |||
1138 | Back ends may assume (and may enforce by assertion) that this | ||
1139 | function will be called at most once for any \c{game_drawstate}. If | ||
1140 | a puzzle needs to be redrawn at a different size, the mid-end will | ||
1141 | create a fresh drawstate. | ||
1142 | |||
1143 | \S{backend-colours} \cw{colours()} | ||
1144 | |||
1145 | \c float *(*colours)(frontend *fe, int *ncolours); | ||
1146 | |||
1147 | This function is responsible for telling the front end what colours | ||
1148 | the puzzle will need to draw itself. | ||
1149 | |||
1150 | It returns the number of colours required in \c{*ncolours}, and the | ||
1151 | return value from the function itself is a dynamically allocated | ||
1152 | array of three times that many \c{float}s, containing the red, green | ||
1153 | and blue components of each colour respectively as numbers in the | ||
1154 | range [0,1]. | ||
1155 | |||
1156 | The second parameter passed to this function is a front end handle. | ||
1157 | The only things it is permitted to do with this handle are to call | ||
1158 | the front-end function called \cw{frontend_default_colour()} (see | ||
1159 | \k{frontend-default-colour}) or the utility function called | ||
1160 | \cw{game_mkhighlight()} (see \k{utils-game-mkhighlight}). (The | ||
1161 | latter is a wrapper on the former, so front end implementors only | ||
1162 | need to provide \cw{frontend_default_colour()}.) This allows | ||
1163 | \cw{colours()} to take local configuration into account when | ||
1164 | deciding on its own colour allocations. Most games use the front | ||
1165 | end's default colour as their background, apart from a few which | ||
1166 | depend on drawing relief highlights so they adjust the background | ||
1167 | colour if it's too light for highlights to show up against it. | ||
1168 | |||
1169 | Note that the colours returned from this function are for | ||
1170 | \e{drawing}, not for printing. Printing has an entirely different | ||
1171 | colour allocation policy. | ||
1172 | |||
1173 | \S{backend-anim-length} \cw{anim_length()} | ||
1174 | |||
1175 | \c float (*anim_length)(const game_state *oldstate, | ||
1176 | \c const game_state *newstate, | ||
1177 | \c int dir, game_ui *ui); | ||
1178 | |||
1179 | This function is called when a move is made, undone or redone. It is | ||
1180 | given the old and the new \c{game_state}, and its job is to decide | ||
1181 | whether the transition between the two needs to be animated or can | ||
1182 | be instant. | ||
1183 | |||
1184 | \c{oldstate} is the state that was current until this call; | ||
1185 | \c{newstate} is the state that will be current after it. \c{dir} | ||
1186 | specifies the chronological order of those states: if it is | ||
1187 | positive, then the transition is the result of a move or a redo (and | ||
1188 | so \c{newstate} is the later of the two moves), whereas if it is | ||
1189 | negative then the transition is the result of an undo (so that | ||
1190 | \c{newstate} is the \e{earlier} move). | ||
1191 | |||
1192 | If this function decides the transition should be animated, it | ||
1193 | returns the desired length of the animation in seconds. If not, it | ||
1194 | returns zero. | ||
1195 | |||
1196 | State changes as a result of a Restart operation are never animated; | ||
1197 | the mid-end will handle them internally and never consult this | ||
1198 | function at all. State changes as a result of Solve operations are | ||
1199 | also not animated by default, although you can change this for a | ||
1200 | particular game by setting a flag in \c{flags} (\k{backend-flags}). | ||
1201 | |||
1202 | The function is also passed a pointer to the local \c{game_ui}. It | ||
1203 | may refer to information in here to help with its decision (see | ||
1204 | \k{writing-conditional-anim} for an example of this), and/or it may | ||
1205 | \e{write} information about the nature of the animation which will | ||
1206 | be read later by \cw{redraw()}. | ||
1207 | |||
1208 | When this function is called, it may rely on \cw{changed_state()} | ||
1209 | having been called previously, so if \cw{anim_length()} needs to | ||
1210 | refer to information in the \c{game_ui}, then \cw{changed_state()} | ||
1211 | is a reliable place to have set that information up. | ||
1212 | |||
1213 | Move animations do not inhibit further input events. If the user | ||
1214 | continues playing before a move animation is complete, the animation | ||
1215 | will be abandoned and the display will jump straight to the final | ||
1216 | state. | ||
1217 | |||
1218 | \S{backend-flash-length} \cw{flash_length()} | ||
1219 | |||
1220 | \c float (*flash_length)(const game_state *oldstate, | ||
1221 | \c const game_state *newstate, | ||
1222 | \c int dir, game_ui *ui); | ||
1223 | |||
1224 | This function is called when a move is completed. (\q{Completed} | ||
1225 | means that not only has the move been made, but any animation which | ||
1226 | accompanied it has finished.) It decides whether the transition from | ||
1227 | \c{oldstate} to \c{newstate} merits a \q{flash}. | ||
1228 | |||
1229 | A flash is much like a move animation, but it is \e{not} interrupted | ||
1230 | by further user interface activity; it runs to completion in | ||
1231 | parallel with whatever else might be going on on the display. The | ||
1232 | only thing which will rush a flash to completion is another flash. | ||
1233 | |||
1234 | The purpose of flashes is to indicate that the game has been | ||
1235 | completed. They were introduced as a separate concept from move | ||
1236 | animations because of Net: the habit of most Net players (and | ||
1237 | certainly me) is to rotate a tile into place and immediately lock | ||
1238 | it, then move on to another tile. When you make your last move, at | ||
1239 | the instant the final tile is rotated into place the screen starts | ||
1240 | to flash to indicate victory \dash but if you then press the lock | ||
1241 | button out of habit, then the move animation is cancelled, and the | ||
1242 | victory flash does not complete. (And if you \e{don't} press the | ||
1243 | lock button, the completed grid will look untidy because there will | ||
1244 | be one unlocked square.) Therefore, I introduced a specific concept | ||
1245 | of a \q{flash} which is separate from a move animation and can | ||
1246 | proceed in parallel with move animations and any other display | ||
1247 | activity, so that the victory flash in Net is not cancelled by that | ||
1248 | final locking move. | ||
1249 | |||
1250 | The input parameters to \cw{flash_length()} are exactly the same as | ||
1251 | the ones to \cw{anim_length()}. | ||
1252 | |||
1253 | Just like \cw{anim_length()}, when this function is called, it may | ||
1254 | rely on \cw{changed_state()} having been called previously, so if it | ||
1255 | needs to refer to information in the \c{game_ui} then | ||
1256 | \cw{changed_state()} is a reliable place to have set that | ||
1257 | information up. | ||
1258 | |||
1259 | (Some games use flashes to indicate defeat as well as victory; | ||
1260 | Mines, for example, flashes in a different colour when you tread on | ||
1261 | a mine from the colour it uses when you complete the game. In order | ||
1262 | to achieve this, its \cw{flash_length()} function has to store a | ||
1263 | flag in the \c{game_ui} to indicate which flash type is required.) | ||
1264 | |||
1265 | \S{backend-status} \cw{status()} | ||
1266 | |||
1267 | \c int (*status)(const game_state *state); | ||
1268 | |||
1269 | This function returns a status value indicating whether the current | ||
1270 | game is still in play, or has been won, or has been conclusively lost. | ||
1271 | The mid-end uses this to implement \cw{midend_status()} | ||
1272 | (\k{midend-status}). | ||
1273 | |||
1274 | The return value should be +1 if the game has been successfully | ||
1275 | solved. If the game has been lost in a situation where further play is | ||
1276 | unlikely, the return value should be -1. If neither is true (so play | ||
1277 | is still ongoing), return zero. | ||
1278 | |||
1279 | Front ends may wish to use a non-zero status as a cue to proactively | ||
1280 | offer the option of starting a new game. Therefore, back ends should | ||
1281 | not return -1 if the game has been \e{technically} lost but undoing | ||
1282 | and continuing is still a realistic possibility. | ||
1283 | |||
1284 | (For instance, games with hidden information such as Guess or Mines | ||
1285 | might well return a non-zero status whenever they reveal the solution, | ||
1286 | whether or not the player guessed it correctly, on the grounds that a | ||
1287 | player would be unlikely to hide the solution and continue playing | ||
1288 | after the answer was spoiled. On the other hand, games where you can | ||
1289 | merely get into a dead end such as Same Game or Inertia might choose | ||
1290 | to return 0 in that situation, on the grounds that the player would | ||
1291 | quite likely press Undo and carry on playing.) | ||
1292 | |||
1293 | \S{backend-redraw} \cw{redraw()} | ||
1294 | |||
1295 | \c void (*redraw)(drawing *dr, game_drawstate *ds, | ||
1296 | \c const game_state *oldstate, | ||
1297 | \c const game_state *newstate, | ||
1298 | \c int dir, const game_ui *ui, | ||
1299 | \c float anim_time, float flash_time); | ||
1300 | |||
1301 | This function is responsible for actually drawing the contents of | ||
1302 | the game window, and for redrawing every time the game state or the | ||
1303 | \c{game_ui} changes. | ||
1304 | |||
1305 | The parameter \c{dr} is a drawing object which may be passed to the | ||
1306 | drawing API functions (see \k{drawing} for documentation of the | ||
1307 | drawing API). This function may not save \c{dr} and use it | ||
1308 | elsewhere; it must only use it for calling back to the drawing API | ||
1309 | functions within its own lifetime. | ||
1310 | |||
1311 | \c{ds} is the local \c{game_drawstate}, of course, and \c{ui} is the | ||
1312 | local \c{game_ui}. | ||
1313 | |||
1314 | \c{newstate} is the semantically-current game state, and is always | ||
1315 | non-\cw{NULL}. If \c{oldstate} is also non-\cw{NULL}, it means that | ||
1316 | a move has recently been made and the game is still in the process | ||
1317 | of displaying an animation linking the old and new states; in this | ||
1318 | situation, \c{anim_time} will give the length of time (in seconds) | ||
1319 | that the animation has already been running. If \c{oldstate} is | ||
1320 | \cw{NULL}, then \c{anim_time} is unused (and will hopefully be set | ||
1321 | to zero to avoid confusion). | ||
1322 | |||
1323 | \c{flash_time}, if it is is non-zero, denotes that the game is in | ||
1324 | the middle of a flash, and gives the time since the start of the | ||
1325 | flash. See \k{backend-flash-length} for general discussion of | ||
1326 | flashes. | ||
1327 | |||
1328 | The very first time this function is called for a new | ||
1329 | \c{game_drawstate}, it is expected to redraw the \e{entire} drawing | ||
1330 | area. Since this often involves drawing visual furniture which is | ||
1331 | never subsequently altered, it is often simplest to arrange this by | ||
1332 | having a special \q{first time} flag in the draw state, and | ||
1333 | resetting it after the first redraw. | ||
1334 | |||
1335 | When this function (or any subfunction) calls the drawing API, it is | ||
1336 | expected to pass colour indices which were previously defined by the | ||
1337 | \cw{colours()} function. | ||
1338 | |||
1339 | \H{backend-printing} Printing functions | ||
1340 | |||
1341 | This section discusses the back end functions that deal with | ||
1342 | printing puzzles out on paper. | ||
1343 | |||
1344 | \S{backend-can-print} \c{can_print} | ||
1345 | |||
1346 | \c int can_print; | ||
1347 | |||
1348 | This flag is set to \cw{TRUE} if the puzzle is capable of printing | ||
1349 | itself on paper. (This makes sense for some puzzles, such as Solo, | ||
1350 | which can be filled in with a pencil. Other puzzles, such as | ||
1351 | Twiddle, inherently involve moving things around and so would not | ||
1352 | make sense to print.) | ||
1353 | |||
1354 | If this flag is \cw{FALSE}, then the functions \cw{print_size()} | ||
1355 | and \cw{print()} will never be called. | ||
1356 | |||
1357 | \S{backend-can-print-in-colour} \c{can_print_in_colour} | ||
1358 | |||
1359 | \c int can_print_in_colour; | ||
1360 | |||
1361 | This flag is set to \cw{TRUE} if the puzzle is capable of printing | ||
1362 | itself differently when colour is available. For example, Map can | ||
1363 | actually print coloured regions in different \e{colours} rather than | ||
1364 | resorting to cross-hatching. | ||
1365 | |||
1366 | If the \c{can_print} flag is \cw{FALSE}, then this flag will be | ||
1367 | ignored. | ||
1368 | |||
1369 | \S{backend-print-size} \cw{print_size()} | ||
1370 | |||
1371 | \c void (*print_size)(const game_params *params, float *x, float *y); | ||
1372 | |||
1373 | This function is passed a \c{game_params} structure and a tile size. | ||
1374 | It returns, in \c{*x} and \c{*y}, the preferred size in | ||
1375 | \e{millimetres} of that puzzle if it were to be printed out on paper. | ||
1376 | |||
1377 | If the \c{can_print} flag is \cw{FALSE}, this function will never be | ||
1378 | called. | ||
1379 | |||
1380 | \S{backend-print} \cw{print()} | ||
1381 | |||
1382 | \c void (*print)(drawing *dr, const game_state *state, int tilesize); | ||
1383 | |||
1384 | This function is called when a puzzle is to be printed out on paper. | ||
1385 | It should use the drawing API functions (see \k{drawing}) to print | ||
1386 | itself. | ||
1387 | |||
1388 | This function is separate from \cw{redraw()} because it is often | ||
1389 | very different: | ||
1390 | |||
1391 | \b The printing function may not depend on pixel accuracy, since | ||
1392 | printer resolution is variable. Draw as if your canvas had infinite | ||
1393 | resolution. | ||
1394 | |||
1395 | \b The printing function sometimes needs to display things in a | ||
1396 | completely different style. Net, for example, is very different as | ||
1397 | an on-screen puzzle and as a printed one. | ||
1398 | |||
1399 | \b The printing function is often much simpler since it has no need | ||
1400 | to deal with repeated partial redraws. | ||
1401 | |||
1402 | However, there's no reason the printing and redraw functions can't | ||
1403 | share some code if they want to. | ||
1404 | |||
1405 | When this function (or any subfunction) calls the drawing API, the | ||
1406 | colour indices it passes should be colours which have been allocated | ||
1407 | by the \cw{print_*_colour()} functions within this execution of | ||
1408 | \cw{print()}. This is very different from the fixed small number of | ||
1409 | colours used in \cw{redraw()}, because printers do not have a | ||
1410 | limitation on the total number of colours that may be used. Some | ||
1411 | puzzles' printing functions might wish to allocate only one \q{ink} | ||
1412 | colour and use it for all drawing; others might wish to allocate | ||
1413 | \e{more} colours than are used on screen. | ||
1414 | |||
1415 | One possible colour policy worth mentioning specifically is that a | ||
1416 | puzzle's printing function might want to allocate the \e{same} | ||
1417 | colour indices as are used by the redraw function, so that code | ||
1418 | shared between drawing and printing does not have to keep switching | ||
1419 | its colour indices. In order to do this, the simplest thing is to | ||
1420 | make use of the fact that colour indices returned from | ||
1421 | \cw{print_*_colour()} are guaranteed to be in increasing order from | ||
1422 | zero. So if you have declared an \c{enum} defining three colours | ||
1423 | \cw{COL_BACKGROUND}, \cw{COL_THIS} and \cw{COL_THAT}, you might then | ||
1424 | write | ||
1425 | |||
1426 | \c int c; | ||
1427 | \c c = print_mono_colour(dr, 1); assert(c == COL_BACKGROUND); | ||
1428 | \c c = print_mono_colour(dr, 0); assert(c == COL_THIS); | ||
1429 | \c c = print_mono_colour(dr, 0); assert(c == COL_THAT); | ||
1430 | |||
1431 | If the \c{can_print} flag is \cw{FALSE}, this function will never be | ||
1432 | called. | ||
1433 | |||
1434 | \H{backend-misc} Miscellaneous | ||
1435 | |||
1436 | \S{backend-can-format-as-text-ever} \c{can_format_as_text_ever} | ||
1437 | |||
1438 | \c int can_format_as_text_ever; | ||
1439 | |||
1440 | This boolean field is \cw{TRUE} if the game supports formatting a | ||
1441 | game state as ASCII text (typically ASCII art) for copying to the | ||
1442 | clipboard and pasting into other applications. If it is \cw{FALSE}, | ||
1443 | front ends will not offer the \q{Copy} command at all. | ||
1444 | |||
1445 | If this field is \cw{TRUE}, the game does not necessarily have to | ||
1446 | support text formatting for \e{all} games: e.g. a game which can be | ||
1447 | played on a square grid or a triangular one might only support copy | ||
1448 | and paste for the former, because triangular grids in ASCII art are | ||
1449 | just too difficult. | ||
1450 | |||
1451 | If this field is \cw{FALSE}, the functions | ||
1452 | \cw{can_format_as_text_now()} (\k{backend-can-format-as-text-now}) | ||
1453 | and \cw{text_format()} (\k{backend-text-format}) are never called. | ||
1454 | |||
1455 | \S{backend-can-format-as-text-now} \c{can_format_as_text_now()} | ||
1456 | |||
1457 | \c int (*can_format_as_text_now)(const game_params *params); | ||
1458 | |||
1459 | This function is passed a \c{game_params} and returns a boolean, | ||
1460 | which is \cw{TRUE} if the game can support ASCII text output for | ||
1461 | this particular game type. If it returns \cw{FALSE}, front ends will | ||
1462 | grey out or otherwise disable the \q{Copy} command. | ||
1463 | |||
1464 | Games may enable and disable the copy-and-paste function for | ||
1465 | different game \e{parameters}, but are currently constrained to | ||
1466 | return the same answer from this function for all game \e{states} | ||
1467 | sharing the same parameters. In other words, the \q{Copy} function | ||
1468 | may enable or disable itself when the player changes game preset, | ||
1469 | but will never change during play of a single game or when another | ||
1470 | game of exactly the same type is generated. | ||
1471 | |||
1472 | This function should not take into account aspects of the game | ||
1473 | parameters which are not encoded by \cw{encode_params()} | ||
1474 | (\k{backend-encode-params}) when the \c{full} parameter is set to | ||
1475 | \cw{FALSE}. Such parameters will not necessarily match up between a | ||
1476 | call to this function and a subsequent call to \cw{text_format()} | ||
1477 | itself. (For instance, game \e{difficulty} should not affect whether | ||
1478 | the game can be copied to the clipboard. Only the actual visible | ||
1479 | \e{shape} of the game can affect that.) | ||
1480 | |||
1481 | \S{backend-text-format} \cw{text_format()} | ||
1482 | |||
1483 | \c char *(*text_format)(const game_state *state); | ||
1484 | |||
1485 | This function is passed a \c{game_state}, and returns a newly | ||
1486 | allocated C string containing an ASCII representation of that game | ||
1487 | state. It is used to implement the \q{Copy} operation in many front | ||
1488 | ends. | ||
1489 | |||
1490 | This function will only ever be called if the back end field | ||
1491 | \c{can_format_as_text_ever} (\k{backend-can-format-as-text-ever}) is | ||
1492 | \cw{TRUE} \e{and} the function \cw{can_format_as_text_now()} | ||
1493 | (\k{backend-can-format-as-text-now}) has returned \cw{TRUE} for the | ||
1494 | currently selected game parameters. | ||
1495 | |||
1496 | The returned string may contain line endings (and will probably want | ||
1497 | to), using the normal C internal \cq{\\n} convention. For | ||
1498 | consistency between puzzles, all multi-line textual puzzle | ||
1499 | representations should \e{end} with a newline as well as containing | ||
1500 | them internally. (There are currently no puzzles which have a | ||
1501 | one-line ASCII representation, so there's no precedent yet for | ||
1502 | whether that should come with a newline or not.) | ||
1503 | |||
1504 | \S{backend-wants-statusbar} \cw{wants_statusbar} | ||
1505 | |||
1506 | \c int wants_statusbar; | ||
1507 | |||
1508 | This boolean field is set to \cw{TRUE} if the puzzle has a use for a | ||
1509 | textual status line (to display score, completion status, currently | ||
1510 | active tiles, etc). | ||
1511 | |||
1512 | \S{backend-is-timed} \c{is_timed} | ||
1513 | |||
1514 | \c int is_timed; | ||
1515 | |||
1516 | This boolean field is \cw{TRUE} if the puzzle is time-critical. If | ||
1517 | so, the mid-end will maintain a game timer while the user plays. | ||
1518 | |||
1519 | If this field is \cw{FALSE}, then \cw{timing_state()} will never be | ||
1520 | called and need not do anything. | ||
1521 | |||
1522 | \S{backend-timing-state} \cw{timing_state()} | ||
1523 | |||
1524 | \c int (*timing_state)(const game_state *state, game_ui *ui); | ||
1525 | |||
1526 | This function is passed the current \c{game_state} and the local | ||
1527 | \c{game_ui}; it returns \cw{TRUE} if the game timer should currently | ||
1528 | be running. | ||
1529 | |||
1530 | A typical use for the \c{game_ui} in this function is to note when | ||
1531 | the game was first completed (by setting a flag in | ||
1532 | \cw{changed_state()} \dash see \k{backend-changed-state}), and | ||
1533 | freeze the timer thereafter so that the user can undo back through | ||
1534 | their solution process without altering their time. | ||
1535 | |||
1536 | \S{backend-flags} \c{flags} | ||
1537 | |||
1538 | \c int flags; | ||
1539 | |||
1540 | This field contains miscellaneous per-backend flags. It consists of | ||
1541 | the bitwise OR of some combination of the following: | ||
1542 | |||
1543 | \dt \cw{BUTTON_BEATS(x,y)} | ||
1544 | |||
1545 | \dd Given any \cw{x} and \cw{y} from the set \{\cw{LEFT_BUTTON}, | ||
1546 | \cw{MIDDLE_BUTTON}, \cw{RIGHT_BUTTON}\}, this macro evaluates to a | ||
1547 | bit flag which indicates that when buttons \cw{x} and \cw{y} are | ||
1548 | both pressed simultaneously, the mid-end should consider \cw{x} to | ||
1549 | have priority. (In the absence of any such flags, the mid-end will | ||
1550 | always consider the most recently pressed button to have priority.) | ||
1551 | |||
1552 | \dt \cw{SOLVE_ANIMATES} | ||
1553 | |||
1554 | \dd This flag indicates that moves generated by \cw{solve()} | ||
1555 | (\k{backend-solve}) are candidates for animation just like any other | ||
1556 | move. For most games, solve moves should not be animated, so the | ||
1557 | mid-end doesn't even bother calling \cw{anim_length()} | ||
1558 | (\k{backend-anim-length}), thus saving some special-case code in | ||
1559 | each game. On the rare occasion that animated solve moves are | ||
1560 | actually required, you can set this flag. | ||
1561 | |||
1562 | \dt \cw{REQUIRE_RBUTTON} | ||
1563 | |||
1564 | \dd This flag indicates that the puzzle cannot be usefully played | ||
1565 | without the use of mouse buttons other than the left one. On some | ||
1566 | PDA platforms, this flag is used by the front end to enable | ||
1567 | right-button emulation through an appropriate gesture. Note that a | ||
1568 | puzzle is not required to set this just because it \e{uses} the | ||
1569 | right button, but only if its use of the right button is critical to | ||
1570 | playing the game. (Slant, for example, uses the right button to | ||
1571 | cycle through the three square states in the opposite order from the | ||
1572 | left button, and hence can manage fine without it.) | ||
1573 | |||
1574 | \dt \cw{REQUIRE_NUMPAD} | ||
1575 | |||
1576 | \dd This flag indicates that the puzzle cannot be usefully played | ||
1577 | without the use of number-key input. On some PDA platforms it causes | ||
1578 | an emulated number pad to appear on the screen. Similarly to | ||
1579 | \cw{REQUIRE_RBUTTON}, a puzzle need not specify this simply if its | ||
1580 | use of the number keys is not critical. | ||
1581 | |||
1582 | \H{backend-initiative} Things a back end may do on its own initiative | ||
1583 | |||
1584 | This section describes a couple of things that a back end may choose | ||
1585 | to do by calling functions elsewhere in the program, which would not | ||
1586 | otherwise be obvious. | ||
1587 | |||
1588 | \S{backend-newrs} Create a random state | ||
1589 | |||
1590 | If a back end needs random numbers at some point during normal play, | ||
1591 | it can create a fresh \c{random_state} by first calling | ||
1592 | \c{get_random_seed} (\k{frontend-get-random-seed}) and then passing | ||
1593 | the returned seed data to \cw{random_new()}. | ||
1594 | |||
1595 | This is likely not to be what you want. If a puzzle needs randomness | ||
1596 | in the middle of play, it's likely to be more sensible to store some | ||
1597 | sort of random state within the \c{game_state}, so that the random | ||
1598 | numbers are tied to the particular game state and hence the player | ||
1599 | can't simply keep undoing their move until they get numbers they | ||
1600 | like better. | ||
1601 | |||
1602 | This facility is currently used only in Net, to implement the | ||
1603 | \q{jumble} command, which sets every unlocked tile to a new random | ||
1604 | orientation. This randomness \e{is} a reasonable use of the feature, | ||
1605 | because it's non-adversarial \dash there's no advantage to the user | ||
1606 | in getting different random numbers. | ||
1607 | |||
1608 | \S{backend-supersede} Supersede its own game description | ||
1609 | |||
1610 | In response to a move, a back end is (reluctantly) permitted to call | ||
1611 | \cw{midend_supersede_game_desc()}: | ||
1612 | |||
1613 | \c void midend_supersede_game_desc(midend *me, | ||
1614 | \c char *desc, char *privdesc); | ||
1615 | |||
1616 | When the user selects \q{New Game}, the mid-end calls | ||
1617 | \cw{new_desc()} (\k{backend-new-desc}) to get a new game | ||
1618 | description, and (as well as using that to generate an initial game | ||
1619 | state) stores it for the save file and for telling to the user. The | ||
1620 | function above overwrites that game description, and also splits it | ||
1621 | in two. \c{desc} becomes the new game description which is provided | ||
1622 | to the user on request, and is also the one used to construct a new | ||
1623 | initial game state if the user selects \q{Restart}. \c{privdesc} is | ||
1624 | a \q{private} game description, used to reconstruct the game's | ||
1625 | initial state when reloading. | ||
1626 | |||
1627 | The distinction between the two, as well as the need for this | ||
1628 | function at all, comes from Mines. Mines begins with a blank grid | ||
1629 | and no idea of where the mines actually are; \cw{new_desc()} does | ||
1630 | almost no work in interactive mode, and simply returns a string | ||
1631 | encoding the \c{random_state}. When the user first clicks to open a | ||
1632 | tile, \e{then} Mines generates the mine positions, in such a way | ||
1633 | that the game is soluble from that starting point. Then it uses this | ||
1634 | function to supersede the random-state game description with a | ||
1635 | proper one. But it needs two: one containing the initial click | ||
1636 | location (because that's what you want to happen if you restart the | ||
1637 | game, and also what you want to send to a friend so that they play | ||
1638 | \e{the same game} as you), and one without the initial click | ||
1639 | location (because when you save and reload the game, you expect to | ||
1640 | see the same blank initial state as you had before saving). | ||
1641 | |||
1642 | I should stress again that this function is a horrid hack. Nobody | ||
1643 | should use it if they're not Mines; if you think you need to use it, | ||
1644 | think again repeatedly in the hope of finding a better way to do | ||
1645 | whatever it was you needed to do. | ||
1646 | |||
1647 | \C{drawing} The drawing API | ||
1648 | |||
1649 | The back end function \cw{redraw()} (\k{backend-redraw}) is required | ||
1650 | to draw the puzzle's graphics on the window's drawing area, or on | ||
1651 | paper if the puzzle is printable. To do this portably, it is | ||
1652 | provided with a drawing API allowing it to talk directly to the | ||
1653 | front end. In this chapter I document that API, both for the benefit | ||
1654 | of back end authors trying to use it and for front end authors | ||
1655 | trying to implement it. | ||
1656 | |||
1657 | The drawing API as seen by the back end is a collection of global | ||
1658 | functions, each of which takes a pointer to a \c{drawing} structure | ||
1659 | (a \q{drawing object}). These objects are supplied as parameters to | ||
1660 | the back end's \cw{redraw()} and \cw{print()} functions. | ||
1661 | |||
1662 | In fact these global functions are not implemented directly by the | ||
1663 | front end; instead, they are implemented centrally in \c{drawing.c} | ||
1664 | and form a small piece of middleware. The drawing API as supplied by | ||
1665 | the front end is a structure containing a set of function pointers, | ||
1666 | plus a \cq{void *} handle which is passed to each of those | ||
1667 | functions. This enables a single front end to switch between | ||
1668 | multiple implementations of the drawing API if necessary. For | ||
1669 | example, the Windows API supplies a printing mechanism integrated | ||
1670 | into the same GDI which deals with drawing in windows, and therefore | ||
1671 | the same API implementation can handle both drawing and printing; | ||
1672 | but on Unix, the most common way for applications to print is by | ||
1673 | producing PostScript output directly, and although it would be | ||
1674 | \e{possible} to write a single (say) \cw{draw_rect()} function which | ||
1675 | checked a global flag to decide whether to do GTK drawing operations | ||
1676 | or output PostScript to a file, it's much nicer to have two separate | ||
1677 | functions and switch between them as appropriate. | ||
1678 | |||
1679 | When drawing, the puzzle window is indexed by pixel coordinates, | ||
1680 | with the top left pixel defined as \cw{(0,0)} and the bottom right | ||
1681 | pixel \cw{(w-1,h-1)}, where \c{w} and \c{h} are the width and height | ||
1682 | values returned by the back end function \cw{compute_size()} | ||
1683 | (\k{backend-compute-size}). | ||
1684 | |||
1685 | When printing, the puzzle's print area is indexed in exactly the | ||
1686 | same way (with an arbitrary tile size provided by the printing | ||
1687 | module \c{printing.c}), to facilitate sharing of code between the | ||
1688 | drawing and printing routines. However, when printing, puzzles may | ||
1689 | no longer assume that the coordinate unit has any relationship to a | ||
1690 | pixel; the printer's actual resolution might very well not even be | ||
1691 | known at print time, so the coordinate unit might be smaller or | ||
1692 | larger than a pixel. Puzzles' print functions should restrict | ||
1693 | themselves to drawing geometric shapes rather than fiddly pixel | ||
1694 | manipulation. | ||
1695 | |||
1696 | \e{Puzzles' redraw functions may assume that the surface they draw | ||
1697 | on is persistent}. It is the responsibility of every front end to | ||
1698 | preserve the puzzle's window contents in the face of GUI window | ||
1699 | expose issues and similar. It is not permissible to request that the | ||
1700 | back end redraw any part of a window that it has already drawn, | ||
1701 | unless something has actually changed as a result of making moves in | ||
1702 | the puzzle. | ||
1703 | |||
1704 | Most front ends accomplish this by having the drawing routines draw | ||
1705 | on a stored bitmap rather than directly on the window, and copying | ||
1706 | the bitmap to the window every time a part of the window needs to be | ||
1707 | redrawn. Therefore, it is vitally important that whenever the back | ||
1708 | end does any drawing it informs the front end of which parts of the | ||
1709 | window it has accessed, and hence which parts need repainting. This | ||
1710 | is done by calling \cw{draw_update()} (\k{drawing-draw-update}). | ||
1711 | |||
1712 | Persistence of old drawing is convenient. However, a puzzle should | ||
1713 | be very careful about how it updates its drawing area. The problem | ||
1714 | is that some front ends do anti-aliased drawing: rather than simply | ||
1715 | choosing between leaving each pixel untouched or painting it a | ||
1716 | specified colour, an antialiased drawing function will \e{blend} the | ||
1717 | original and new colours in pixels at a figure's boundary according | ||
1718 | to the proportion of the pixel occupied by the figure (probably | ||
1719 | modified by some heuristic fudge factors). All of this produces a | ||
1720 | smoother appearance for curves and diagonal lines. | ||
1721 | |||
1722 | An unfortunate effect of drawing an anti-aliased figure repeatedly | ||
1723 | is that the pixels around the figure's boundary come steadily more | ||
1724 | saturated with \q{ink} and the boundary appears to \q{spread out}. | ||
1725 | Worse, redrawing a figure in a different colour won't fully paint | ||
1726 | over the old boundary pixels, so the end result is a rather ugly | ||
1727 | smudge. | ||
1728 | |||
1729 | A good strategy to avoid unpleasant anti-aliasing artifacts is to | ||
1730 | identify a number of rectangular areas which need to be redrawn, | ||
1731 | clear them to the background colour, and then redraw their contents | ||
1732 | from scratch, being careful all the while not to stray beyond the | ||
1733 | boundaries of the original rectangles. The \cw{clip()} function | ||
1734 | (\k{drawing-clip}) comes in very handy here. Games based on a square | ||
1735 | grid can often do this fairly easily. Other games may need to be | ||
1736 | somewhat more careful. For example, Loopy's redraw function first | ||
1737 | identifies portions of the display which need to be updated. Then, | ||
1738 | if the changes are fairly well localised, it clears and redraws a | ||
1739 | rectangle containing each changed area. Otherwise, it gives up and | ||
1740 | redraws the entire grid from scratch. | ||
1741 | |||
1742 | It is possible to avoid clearing to background and redrawing from | ||
1743 | scratch if one is very careful about which drawing functions one | ||
1744 | uses: if a function is documented as not anti-aliasing under some | ||
1745 | circumstances, you can rely on each pixel in a drawing either being | ||
1746 | left entirely alone or being set to the requested colour, with no | ||
1747 | blending being performed. | ||
1748 | |||
1749 | In the following sections I first discuss the drawing API as seen by | ||
1750 | the back end, and then the \e{almost} identical function-pointer | ||
1751 | form seen by the front end. | ||
1752 | |||
1753 | \H{drawing-backend} Drawing API as seen by the back end | ||
1754 | |||
1755 | This section documents the back-end drawing API, in the form of | ||
1756 | functions which take a \c{drawing} object as an argument. | ||
1757 | |||
1758 | \S{drawing-draw-rect} \cw{draw_rect()} | ||
1759 | |||
1760 | \c void draw_rect(drawing *dr, int x, int y, int w, int h, | ||
1761 | \c int colour); | ||
1762 | |||
1763 | Draws a filled rectangle in the puzzle window. | ||
1764 | |||
1765 | \c{x} and \c{y} give the coordinates of the top left pixel of the | ||
1766 | rectangle. \c{w} and \c{h} give its width and height. Thus, the | ||
1767 | horizontal extent of the rectangle runs from \c{x} to \c{x+w-1} | ||
1768 | inclusive, and the vertical extent from \c{y} to \c{y+h-1} | ||
1769 | inclusive. | ||
1770 | |||
1771 | \c{colour} is an integer index into the colours array returned by | ||
1772 | the back end function \cw{colours()} (\k{backend-colours}). | ||
1773 | |||
1774 | There is no separate pixel-plotting function. If you want to plot a | ||
1775 | single pixel, the approved method is to use \cw{draw_rect()} with | ||
1776 | width and height set to 1. | ||
1777 | |||
1778 | Unlike many of the other drawing functions, this function is | ||
1779 | guaranteed to be pixel-perfect: the rectangle will be sharply | ||
1780 | defined and not anti-aliased or anything like that. | ||
1781 | |||
1782 | This function may be used for both drawing and printing. | ||
1783 | |||
1784 | \S{drawing-draw-rect-outline} \cw{draw_rect_outline()} | ||
1785 | |||
1786 | \c void draw_rect_outline(drawing *dr, int x, int y, int w, int h, | ||
1787 | \c int colour); | ||
1788 | |||
1789 | Draws an outline rectangle in the puzzle window. | ||
1790 | |||
1791 | \c{x} and \c{y} give the coordinates of the top left pixel of the | ||
1792 | rectangle. \c{w} and \c{h} give its width and height. Thus, the | ||
1793 | horizontal extent of the rectangle runs from \c{x} to \c{x+w-1} | ||
1794 | inclusive, and the vertical extent from \c{y} to \c{y+h-1} | ||
1795 | inclusive. | ||
1796 | |||
1797 | \c{colour} is an integer index into the colours array returned by | ||
1798 | the back end function \cw{colours()} (\k{backend-colours}). | ||
1799 | |||
1800 | From a back end perspective, this function may be considered to be | ||
1801 | part of the drawing API. However, front ends are not required to | ||
1802 | implement it, since it is actually implemented centrally (in | ||
1803 | \cw{misc.c}) as a wrapper on \cw{draw_polygon()}. | ||
1804 | |||
1805 | This function may be used for both drawing and printing. | ||
1806 | |||
1807 | \S{drawing-draw-line} \cw{draw_line()} | ||
1808 | |||
1809 | \c void draw_line(drawing *dr, int x1, int y1, int x2, int y2, | ||
1810 | \c int colour); | ||
1811 | |||
1812 | Draws a straight line in the puzzle window. | ||
1813 | |||
1814 | \c{x1} and \c{y1} give the coordinates of one end of the line. | ||
1815 | \c{x2} and \c{y2} give the coordinates of the other end. The line | ||
1816 | drawn includes both those points. | ||
1817 | |||
1818 | \c{colour} is an integer index into the colours array returned by | ||
1819 | the back end function \cw{colours()} (\k{backend-colours}). | ||
1820 | |||
1821 | Some platforms may perform anti-aliasing on this function. | ||
1822 | Therefore, do not assume that you can erase a line by drawing the | ||
1823 | same line over it in the background colour; anti-aliasing might lead | ||
1824 | to perceptible ghost artefacts around the vanished line. Horizontal | ||
1825 | and vertical lines, however, are pixel-perfect and not anti-aliased. | ||
1826 | |||
1827 | This function may be used for both drawing and printing. | ||
1828 | |||
1829 | \S{drawing-draw-polygon} \cw{draw_polygon()} | ||
1830 | |||
1831 | \c void draw_polygon(drawing *dr, int *coords, int npoints, | ||
1832 | \c int fillcolour, int outlinecolour); | ||
1833 | |||
1834 | Draws an outlined or filled polygon in the puzzle window. | ||
1835 | |||
1836 | \c{coords} is an array of \cw{(2*npoints)} integers, containing the | ||
1837 | \c{x} and \c{y} coordinates of \c{npoints} vertices. | ||
1838 | |||
1839 | \c{fillcolour} and \c{outlinecolour} are integer indices into the | ||
1840 | colours array returned by the back end function \cw{colours()} | ||
1841 | (\k{backend-colours}). \c{fillcolour} may also be \cw{-1} to | ||
1842 | indicate that the polygon should be outlined only. | ||
1843 | |||
1844 | The polygon defined by the specified list of vertices is first | ||
1845 | filled in \c{fillcolour}, if specified, and then outlined in | ||
1846 | \c{outlinecolour}. | ||
1847 | |||
1848 | \c{outlinecolour} may \e{not} be \cw{-1}; it must be a valid colour | ||
1849 | (and front ends are permitted to enforce this by assertion). This is | ||
1850 | because different platforms disagree on whether a filled polygon | ||
1851 | should include its boundary line or not, so drawing \e{only} a | ||
1852 | filled polygon would have non-portable effects. If you want your | ||
1853 | filled polygon not to have a visible outline, you must set | ||
1854 | \c{outlinecolour} to the same as \c{fillcolour}. | ||
1855 | |||
1856 | Some platforms may perform anti-aliasing on this function. | ||
1857 | Therefore, do not assume that you can erase a polygon by drawing the | ||
1858 | same polygon over it in the background colour. Also, be prepared for | ||
1859 | the polygon to extend a pixel beyond its obvious bounding box as a | ||
1860 | result of this; if you really need it not to do this to avoid | ||
1861 | interfering with other delicate graphics, you should probably use | ||
1862 | \cw{clip()} (\k{drawing-clip}). You can rely on horizontal and | ||
1863 | vertical lines not being anti-aliased. | ||
1864 | |||
1865 | This function may be used for both drawing and printing. | ||
1866 | |||
1867 | \S{drawing-draw-circle} \cw{draw_circle()} | ||
1868 | |||
1869 | \c void draw_circle(drawing *dr, int cx, int cy, int radius, | ||
1870 | \c int fillcolour, int outlinecolour); | ||
1871 | |||
1872 | Draws an outlined or filled circle in the puzzle window. | ||
1873 | |||
1874 | \c{cx} and \c{cy} give the coordinates of the centre of the circle. | ||
1875 | \c{radius} gives its radius. The total horizontal pixel extent of | ||
1876 | the circle is from \c{cx-radius+1} to \c{cx+radius-1} inclusive, and | ||
1877 | the vertical extent similarly around \c{cy}. | ||
1878 | |||
1879 | \c{fillcolour} and \c{outlinecolour} are integer indices into the | ||
1880 | colours array returned by the back end function \cw{colours()} | ||
1881 | (\k{backend-colours}). \c{fillcolour} may also be \cw{-1} to | ||
1882 | indicate that the circle should be outlined only. | ||
1883 | |||
1884 | The circle is first filled in \c{fillcolour}, if specified, and then | ||
1885 | outlined in \c{outlinecolour}. | ||
1886 | |||
1887 | \c{outlinecolour} may \e{not} be \cw{-1}; it must be a valid colour | ||
1888 | (and front ends are permitted to enforce this by assertion). This is | ||
1889 | because different platforms disagree on whether a filled circle | ||
1890 | should include its boundary line or not, so drawing \e{only} a | ||
1891 | filled circle would have non-portable effects. If you want your | ||
1892 | filled circle not to have a visible outline, you must set | ||
1893 | \c{outlinecolour} to the same as \c{fillcolour}. | ||
1894 | |||
1895 | Some platforms may perform anti-aliasing on this function. | ||
1896 | Therefore, do not assume that you can erase a circle by drawing the | ||
1897 | same circle over it in the background colour. Also, be prepared for | ||
1898 | the circle to extend a pixel beyond its obvious bounding box as a | ||
1899 | result of this; if you really need it not to do this to avoid | ||
1900 | interfering with other delicate graphics, you should probably use | ||
1901 | \cw{clip()} (\k{drawing-clip}). | ||
1902 | |||
1903 | This function may be used for both drawing and printing. | ||
1904 | |||
1905 | \S{drawing-draw-thick-line} \cw{draw_thick_line()} | ||
1906 | |||
1907 | \c void draw_thick_line(drawing *dr, float thickness, | ||
1908 | \c float x1, float y1, float x2, float y2, | ||
1909 | \c int colour) | ||
1910 | |||
1911 | Draws a line in the puzzle window, giving control over the line's | ||
1912 | thickness. | ||
1913 | |||
1914 | \c{x1} and \c{y1} give the coordinates of one end of the line. | ||
1915 | \c{x2} and \c{y2} give the coordinates of the other end. | ||
1916 | \c{thickness} gives the thickness of the line, in pixels. | ||
1917 | |||
1918 | Note that the coordinates and thickness are floating-point: the | ||
1919 | continuous coordinate system is in effect here. It's important to | ||
1920 | be able to address points with better-than-pixel precision in this | ||
1921 | case, because one can't otherwise properly express the endpoints of | ||
1922 | lines with both odd and even thicknesses. | ||
1923 | |||
1924 | Some platforms may perform anti-aliasing on this function. The | ||
1925 | precise pixels affected by a thick-line drawing operation may vary | ||
1926 | between platforms, and no particular guarantees are provided. | ||
1927 | Indeed, even horizontal or vertical lines may be anti-aliased. | ||
1928 | |||
1929 | This function may be used for both drawing and printing. | ||
1930 | |||
1931 | \S{drawing-draw-text} \cw{draw_text()} | ||
1932 | |||
1933 | \c void draw_text(drawing *dr, int x, int y, int fonttype, | ||
1934 | \c int fontsize, int align, int colour, char *text); | ||
1935 | |||
1936 | Draws text in the puzzle window. | ||
1937 | |||
1938 | \c{x} and \c{y} give the coordinates of a point. The relation of | ||
1939 | this point to the location of the text is specified by \c{align}, | ||
1940 | which is a bitwise OR of horizontal and vertical alignment flags: | ||
1941 | |||
1942 | \dt \cw{ALIGN_VNORMAL} | ||
1943 | |||
1944 | \dd Indicates that \c{y} is aligned with the baseline of the text. | ||
1945 | |||
1946 | \dt \cw{ALIGN_VCENTRE} | ||
1947 | |||
1948 | \dd Indicates that \c{y} is aligned with the vertical centre of the | ||
1949 | text. (In fact, it's aligned with the vertical centre of normal | ||
1950 | \e{capitalised} text: displaying two pieces of text with | ||
1951 | \cw{ALIGN_VCENTRE} at the same \cw{y}-coordinate will cause their | ||
1952 | baselines to be aligned with one another, even if one is an ascender | ||
1953 | and the other a descender.) | ||
1954 | |||
1955 | \dt \cw{ALIGN_HLEFT} | ||
1956 | |||
1957 | \dd Indicates that \c{x} is aligned with the left-hand end of the | ||
1958 | text. | ||
1959 | |||
1960 | \dt \cw{ALIGN_HCENTRE} | ||
1961 | |||
1962 | \dd Indicates that \c{x} is aligned with the horizontal centre of | ||
1963 | the text. | ||
1964 | |||
1965 | \dt \cw{ALIGN_HRIGHT} | ||
1966 | |||
1967 | \dd Indicates that \c{x} is aligned with the right-hand end of the | ||
1968 | text. | ||
1969 | |||
1970 | \c{fonttype} is either \cw{FONT_FIXED} or \cw{FONT_VARIABLE}, for a | ||
1971 | monospaced or proportional font respectively. (No more detail than | ||
1972 | that may be specified; it would only lead to portability issues | ||
1973 | between different platforms.) | ||
1974 | |||
1975 | \c{fontsize} is the desired size, in pixels, of the text. This size | ||
1976 | corresponds to the overall point size of the text, not to any | ||
1977 | internal dimension such as the cap-height. | ||
1978 | |||
1979 | \c{colour} is an integer index into the colours array returned by | ||
1980 | the back end function \cw{colours()} (\k{backend-colours}). | ||
1981 | |||
1982 | This function may be used for both drawing and printing. | ||
1983 | |||
1984 | The character set used to encode the text passed to this function is | ||
1985 | specified \e{by the drawing object}, although it must be a superset | ||
1986 | of ASCII. If a puzzle wants to display text that is not contained in | ||
1987 | ASCII, it should use the \cw{text_fallback()} function | ||
1988 | (\k{drawing-text-fallback}) to query the drawing object for an | ||
1989 | appropriate representation of the characters it wants. | ||
1990 | |||
1991 | \S{drawing-text-fallback} \cw{text_fallback()} | ||
1992 | |||
1993 | \c char *text_fallback(drawing *dr, const char *const *strings, | ||
1994 | \c int nstrings); | ||
1995 | |||
1996 | This function is used to request a translation of UTF-8 text into | ||
1997 | whatever character encoding is expected by the drawing object's | ||
1998 | implementation of \cw{draw_text()}. | ||
1999 | |||
2000 | The input is a list of strings encoded in UTF-8: \cw{nstrings} gives | ||
2001 | the number of strings in the list, and \cw{strings[0]}, | ||
2002 | \cw{strings[1]}, ..., \cw{strings[nstrings-1]} are the strings | ||
2003 | themselves. | ||
2004 | |||
2005 | The returned string (which is dynamically allocated and must be | ||
2006 | freed when finished with) is derived from the first string in the | ||
2007 | list that the drawing object expects to be able to display reliably; | ||
2008 | it will consist of that string translated into the character set | ||
2009 | expected by \cw{draw_text()}. | ||
2010 | |||
2011 | Drawing implementations are not required to handle anything outside | ||
2012 | ASCII, but are permitted to assume that \e{some} string will be | ||
2013 | successfully translated. So every call to this function must include | ||
2014 | a string somewhere in the list (presumably the last element) which | ||
2015 | consists of nothing but ASCII, to be used by any front end which | ||
2016 | cannot handle anything else. | ||
2017 | |||
2018 | For example, if a puzzle wished to display a string including a | ||
2019 | multiplication sign (U+00D7 in Unicode, represented by the bytes C3 | ||
2020 | 97 in UTF-8), it might do something like this: | ||
2021 | |||
2022 | \c static const char *const times_signs[] = { "\xC3\x97", "x" }; | ||
2023 | \c char *times_sign = text_fallback(dr, times_signs, 2); | ||
2024 | \c sprintf(buffer, "%d%s%d", width, times_sign, height); | ||
2025 | \c draw_text(dr, x, y, font, size, align, colour, buffer); | ||
2026 | \c sfree(buffer); | ||
2027 | |||
2028 | which would draw a string with a times sign in the middle on | ||
2029 | platforms that support it, and fall back to a simple ASCII \cq{x} | ||
2030 | where there was no alternative. | ||
2031 | |||
2032 | \S{drawing-clip} \cw{clip()} | ||
2033 | |||
2034 | \c void clip(drawing *dr, int x, int y, int w, int h); | ||
2035 | |||
2036 | Establishes a clipping rectangle in the puzzle window. | ||
2037 | |||
2038 | \c{x} and \c{y} give the coordinates of the top left pixel of the | ||
2039 | clipping rectangle. \c{w} and \c{h} give its width and height. Thus, | ||
2040 | the horizontal extent of the rectangle runs from \c{x} to \c{x+w-1} | ||
2041 | inclusive, and the vertical extent from \c{y} to \c{y+h-1} | ||
2042 | inclusive. (These are exactly the same semantics as | ||
2043 | \cw{draw_rect()}.) | ||
2044 | |||
2045 | After this call, no drawing operation will affect anything outside | ||
2046 | the specified rectangle. The effect can be reversed by calling | ||
2047 | \cw{unclip()} (\k{drawing-unclip}). The clipping rectangle is | ||
2048 | pixel-perfect: pixels within the rectangle are affected as usual by | ||
2049 | drawing functions; pixels outside are completely untouched. | ||
2050 | |||
2051 | Back ends should not assume that a clipping rectangle will be | ||
2052 | automatically cleared up by the front end if it's left lying around; | ||
2053 | that might work on current front ends, but shouldn't be relied upon. | ||
2054 | Always explicitly call \cw{unclip()}. | ||
2055 | |||
2056 | This function may be used for both drawing and printing. | ||
2057 | |||
2058 | \S{drawing-unclip} \cw{unclip()} | ||
2059 | |||
2060 | \c void unclip(drawing *dr); | ||
2061 | |||
2062 | Reverts the effect of a previous call to \cw{clip()}. After this | ||
2063 | call, all drawing operations will be able to affect the entire | ||
2064 | puzzle window again. | ||
2065 | |||
2066 | This function may be used for both drawing and printing. | ||
2067 | |||
2068 | \S{drawing-draw-update} \cw{draw_update()} | ||
2069 | |||
2070 | \c void draw_update(drawing *dr, int x, int y, int w, int h); | ||
2071 | |||
2072 | Informs the front end that a rectangular portion of the puzzle | ||
2073 | window has been drawn on and needs to be updated. | ||
2074 | |||
2075 | \c{x} and \c{y} give the coordinates of the top left pixel of the | ||
2076 | update rectangle. \c{w} and \c{h} give its width and height. Thus, | ||
2077 | the horizontal extent of the rectangle runs from \c{x} to \c{x+w-1} | ||
2078 | inclusive, and the vertical extent from \c{y} to \c{y+h-1} | ||
2079 | inclusive. (These are exactly the same semantics as | ||
2080 | \cw{draw_rect()}.) | ||
2081 | |||
2082 | The back end redraw function \e{must} call this function to report | ||
2083 | any changes it has made to the window. Otherwise, those changes may | ||
2084 | not become immediately visible, and may then appear at an | ||
2085 | unpredictable subsequent time such as the next time the window is | ||
2086 | covered and re-exposed. | ||
2087 | |||
2088 | This function is only important when drawing. It may be called when | ||
2089 | printing as well, but doing so is not compulsory, and has no effect. | ||
2090 | (So if you have a shared piece of code between the drawing and | ||
2091 | printing routines, that code may safely call \cw{draw_update()}.) | ||
2092 | |||
2093 | \S{drawing-status-bar} \cw{status_bar()} | ||
2094 | |||
2095 | \c void status_bar(drawing *dr, char *text); | ||
2096 | |||
2097 | Sets the text in the game's status bar to \c{text}. The text is copied | ||
2098 | from the supplied buffer, so the caller is free to deallocate or | ||
2099 | modify the buffer after use. | ||
2100 | |||
2101 | (This function is not exactly a \e{drawing} function, but it shares | ||
2102 | with the drawing API the property that it may only be called from | ||
2103 | within the back end redraw function, so this is as good a place as | ||
2104 | any to document it.) | ||
2105 | |||
2106 | The supplied text is filtered through the mid-end for optional | ||
2107 | rewriting before being passed on to the front end; the mid-end will | ||
2108 | prepend the current game time if the game is timed (and may in | ||
2109 | future perform other rewriting if it seems like a good idea). | ||
2110 | |||
2111 | This function is for drawing only; it must never be called during | ||
2112 | printing. | ||
2113 | |||
2114 | \S{drawing-blitter} Blitter functions | ||
2115 | |||
2116 | This section describes a group of related functions which save and | ||
2117 | restore a section of the puzzle window. This is most commonly used | ||
2118 | to implement user interfaces involving dragging a puzzle element | ||
2119 | around the window: at the end of each call to \cw{redraw()}, if an | ||
2120 | object is currently being dragged, the back end saves the window | ||
2121 | contents under that location and then draws the dragged object, and | ||
2122 | at the start of the next \cw{redraw()} the first thing it does is to | ||
2123 | restore the background. | ||
2124 | |||
2125 | The front end defines an opaque type called a \c{blitter}, which is | ||
2126 | capable of storing a rectangular area of a specified size. | ||
2127 | |||
2128 | Blitter functions are for drawing only; they must never be called | ||
2129 | during printing. | ||
2130 | |||
2131 | \S2{drawing-blitter-new} \cw{blitter_new()} | ||
2132 | |||
2133 | \c blitter *blitter_new(drawing *dr, int w, int h); | ||
2134 | |||
2135 | Creates a new blitter object which stores a rectangle of size \c{w} | ||
2136 | by \c{h} pixels. Returns a pointer to the blitter object. | ||
2137 | |||
2138 | Blitter objects are best stored in the \c{game_drawstate}. A good | ||
2139 | time to create them is in the \cw{set_size()} function | ||
2140 | (\k{backend-set-size}), since it is at this point that you first | ||
2141 | know how big a rectangle they will need to save. | ||
2142 | |||
2143 | \S2{drawing-blitter-free} \cw{blitter_free()} | ||
2144 | |||
2145 | \c void blitter_free(drawing *dr, blitter *bl); | ||
2146 | |||
2147 | Disposes of a blitter object. Best called in \cw{free_drawstate()}. | ||
2148 | (However, check that the blitter object is not \cw{NULL} before | ||
2149 | attempting to free it; it is possible that a draw state might be | ||
2150 | created and freed without ever having \cw{set_size()} called on it | ||
2151 | in between.) | ||
2152 | |||
2153 | \S2{drawing-blitter-save} \cw{blitter_save()} | ||
2154 | |||
2155 | \c void blitter_save(drawing *dr, blitter *bl, int x, int y); | ||
2156 | |||
2157 | This is a true drawing API function, in that it may only be called | ||
2158 | from within the game redraw routine. It saves a rectangular portion | ||
2159 | of the puzzle window into the specified blitter object. | ||
2160 | |||
2161 | \c{x} and \c{y} give the coordinates of the top left corner of the | ||
2162 | saved rectangle. The rectangle's width and height are the ones | ||
2163 | specified when the blitter object was created. | ||
2164 | |||
2165 | This function is required to cope and do the right thing if \c{x} | ||
2166 | and \c{y} are out of range. (The right thing probably means saving | ||
2167 | whatever part of the blitter rectangle overlaps with the visible | ||
2168 | area of the puzzle window.) | ||
2169 | |||
2170 | \S2{drawing-blitter-load} \cw{blitter_load()} | ||
2171 | |||
2172 | \c void blitter_load(drawing *dr, blitter *bl, int x, int y); | ||
2173 | |||
2174 | This is a true drawing API function, in that it may only be called | ||
2175 | from within the game redraw routine. It restores a rectangular | ||
2176 | portion of the puzzle window from the specified blitter object. | ||
2177 | |||
2178 | \c{x} and \c{y} give the coordinates of the top left corner of the | ||
2179 | rectangle to be restored. The rectangle's width and height are the | ||
2180 | ones specified when the blitter object was created. | ||
2181 | |||
2182 | Alternatively, you can specify both \c{x} and \c{y} as the special | ||
2183 | value \cw{BLITTER_FROMSAVED}, in which case the rectangle will be | ||
2184 | restored to exactly where it was saved from. (This is probably what | ||
2185 | you want to do almost all the time, if you're using blitters to | ||
2186 | implement draggable puzzle elements.) | ||
2187 | |||
2188 | This function is required to cope and do the right thing if \c{x} | ||
2189 | and \c{y} (or the equivalent ones saved in the blitter) are out of | ||
2190 | range. (The right thing probably means restoring whatever part of | ||
2191 | the blitter rectangle overlaps with the visible area of the puzzle | ||
2192 | window.) | ||
2193 | |||
2194 | If this function is called on a blitter which had previously been | ||
2195 | saved from a partially out-of-range rectangle, then the parts of the | ||
2196 | saved bitmap which were not visible at save time are undefined. If | ||
2197 | the blitter is restored to a different position so as to make those | ||
2198 | parts visible, the effect on the drawing area is undefined. | ||
2199 | |||
2200 | \S{print-mono-colour} \cw{print_mono_colour()} | ||
2201 | |||
2202 | \c int print_mono_colour(drawing *dr, int grey); | ||
2203 | |||
2204 | This function allocates a colour index for a simple monochrome | ||
2205 | colour during printing. | ||
2206 | |||
2207 | \c{grey} must be 0 or 1. If \c{grey} is 0, the colour returned is | ||
2208 | black; if \c{grey} is 1, the colour is white. | ||
2209 | |||
2210 | \S{print-grey-colour} \cw{print_grey_colour()} | ||
2211 | |||
2212 | \c int print_grey_colour(drawing *dr, float grey); | ||
2213 | |||
2214 | This function allocates a colour index for a grey-scale colour | ||
2215 | during printing. | ||
2216 | |||
2217 | \c{grey} may be any number between 0 (black) and 1 (white); for | ||
2218 | example, 0.5 indicates a medium grey. | ||
2219 | |||
2220 | The chosen colour will be rendered to the limits of the printer's | ||
2221 | halftoning capability. | ||
2222 | |||
2223 | \S{print-hatched-colour} \cw{print_hatched_colour()} | ||
2224 | |||
2225 | \c int print_hatched_colour(drawing *dr, int hatch); | ||
2226 | |||
2227 | This function allocates a colour index which does not represent a | ||
2228 | literal \e{colour}. Instead, regions shaded in this colour will be | ||
2229 | hatched with parallel lines. The \c{hatch} parameter defines what | ||
2230 | type of hatching should be used in place of this colour: | ||
2231 | |||
2232 | \dt \cw{HATCH_SLASH} | ||
2233 | |||
2234 | \dd This colour will be hatched by lines slanting to the right at 45 | ||
2235 | degrees. | ||
2236 | |||
2237 | \dt \cw{HATCH_BACKSLASH} | ||
2238 | |||
2239 | \dd This colour will be hatched by lines slanting to the left at 45 | ||
2240 | degrees. | ||
2241 | |||
2242 | \dt \cw{HATCH_HORIZ} | ||
2243 | |||
2244 | \dd This colour will be hatched by horizontal lines. | ||
2245 | |||
2246 | \dt \cw{HATCH_VERT} | ||
2247 | |||
2248 | \dd This colour will be hatched by vertical lines. | ||
2249 | |||
2250 | \dt \cw{HATCH_PLUS} | ||
2251 | |||
2252 | \dd This colour will be hatched by criss-crossing horizontal and | ||
2253 | vertical lines. | ||
2254 | |||
2255 | \dt \cw{HATCH_X} | ||
2256 | |||
2257 | \dd This colour will be hatched by criss-crossing diagonal lines. | ||
2258 | |||
2259 | Colours defined to use hatching may not be used for drawing lines or | ||
2260 | text; they may only be used for filling areas. That is, they may be | ||
2261 | used as the \c{fillcolour} parameter to \cw{draw_circle()} and | ||
2262 | \cw{draw_polygon()}, and as the colour parameter to | ||
2263 | \cw{draw_rect()}, but may not be used as the \c{outlinecolour} | ||
2264 | parameter to \cw{draw_circle()} or \cw{draw_polygon()}, or with | ||
2265 | \cw{draw_line()} or \cw{draw_text()}. | ||
2266 | |||
2267 | \S{print-rgb-mono-colour} \cw{print_rgb_mono_colour()} | ||
2268 | |||
2269 | \c int print_rgb_mono_colour(drawing *dr, float r, float g, | ||
2270 | \c float b, float grey); | ||
2271 | |||
2272 | This function allocates a colour index for a fully specified RGB | ||
2273 | colour during printing. | ||
2274 | |||
2275 | \c{r}, \c{g} and \c{b} may each be anywhere in the range from 0 to 1. | ||
2276 | |||
2277 | If printing in black and white only, these values will be ignored, | ||
2278 | and either pure black or pure white will be used instead, according | ||
2279 | to the \q{grey} parameter. (The fallback colour is the same as the | ||
2280 | one which would be allocated by \cw{print_mono_colour(grey)}.) | ||
2281 | |||
2282 | \S{print-rgb-grey-colour} \cw{print_rgb_grey_colour()} | ||
2283 | |||
2284 | \c int print_rgb_grey_colour(drawing *dr, float r, float g, | ||
2285 | \c float b, float grey); | ||
2286 | |||
2287 | This function allocates a colour index for a fully specified RGB | ||
2288 | colour during printing. | ||
2289 | |||
2290 | \c{r}, \c{g} and \c{b} may each be anywhere in the range from 0 to 1. | ||
2291 | |||
2292 | If printing in black and white only, these values will be ignored, | ||
2293 | and a shade of grey given by the \c{grey} parameter will be used | ||
2294 | instead. (The fallback colour is the same as the one which would be | ||
2295 | allocated by \cw{print_grey_colour(grey)}.) | ||
2296 | |||
2297 | \S{print-rgb-hatched-colour} \cw{print_rgb_hatched_colour()} | ||
2298 | |||
2299 | \c int print_rgb_hatched_colour(drawing *dr, float r, float g, | ||
2300 | \c float b, float hatched); | ||
2301 | |||
2302 | This function allocates a colour index for a fully specified RGB | ||
2303 | colour during printing. | ||
2304 | |||
2305 | \c{r}, \c{g} and \c{b} may each be anywhere in the range from 0 to 1. | ||
2306 | |||
2307 | If printing in black and white only, these values will be ignored, | ||
2308 | and a form of cross-hatching given by the \c{hatch} parameter will | ||
2309 | be used instead; see \k{print-hatched-colour} for the possible | ||
2310 | values of this parameter. (The fallback colour is the same as the | ||
2311 | one which would be allocated by \cw{print_hatched_colour(hatch)}.) | ||
2312 | |||
2313 | \S{print-line-width} \cw{print_line_width()} | ||
2314 | |||
2315 | \c void print_line_width(drawing *dr, int width); | ||
2316 | |||
2317 | This function is called to set the thickness of lines drawn during | ||
2318 | printing. It is meaningless in drawing: all lines drawn by | ||
2319 | \cw{draw_line()}, \cw{draw_circle} and \cw{draw_polygon()} are one | ||
2320 | pixel in thickness. However, in printing there is no clear | ||
2321 | definition of a pixel and so line widths must be explicitly | ||
2322 | specified. | ||
2323 | |||
2324 | The line width is specified in the usual coordinate system. Note, | ||
2325 | however, that it is a hint only: the central printing system may | ||
2326 | choose to vary line thicknesses at user request or due to printer | ||
2327 | capabilities. | ||
2328 | |||
2329 | \S{print-line-dotted} \cw{print_line_dotted()} | ||
2330 | |||
2331 | \c void print_line_dotted(drawing *dr, int dotted); | ||
2332 | |||
2333 | This function is called to toggle the drawing of dotted lines during | ||
2334 | printing. It is not supported during drawing. | ||
2335 | |||
2336 | The parameter \cq{dotted} is a boolean; \cw{TRUE} means that future | ||
2337 | lines drawn by \cw{draw_line()}, \cw{draw_circle} and | ||
2338 | \cw{draw_polygon()} will be dotted, and \cw{FALSE} means that they | ||
2339 | will be solid. | ||
2340 | |||
2341 | Some front ends may impose restrictions on the width of dotted | ||
2342 | lines. Asking for a dotted line via this front end will override any | ||
2343 | line width request if the front end requires it. | ||
2344 | |||
2345 | \H{drawing-frontend} The drawing API as implemented by the front end | ||
2346 | |||
2347 | This section describes the drawing API in the function-pointer form | ||
2348 | in which it is implemented by a front end. | ||
2349 | |||
2350 | (It isn't only platform-specific front ends which implement this | ||
2351 | API; the platform-independent module \c{ps.c} also provides an | ||
2352 | implementation of it which outputs PostScript. Thus, any platform | ||
2353 | which wants to do PS printing can do so with minimum fuss.) | ||
2354 | |||
2355 | The following entries all describe function pointer fields in a | ||
2356 | structure called \c{drawing_api}. Each of the functions takes a | ||
2357 | \cq{void *} context pointer, which it should internally cast back to | ||
2358 | a more useful type. Thus, a drawing \e{object} (\c{drawing *)} | ||
2359 | suitable for passing to the back end redraw or printing functions | ||
2360 | is constructed by passing a \c{drawing_api} and a \cq{void *} to the | ||
2361 | function \cw{drawing_new()} (see \k{drawing-new}). | ||
2362 | |||
2363 | \S{drawingapi-draw-text} \cw{draw_text()} | ||
2364 | |||
2365 | \c void (*draw_text)(void *handle, int x, int y, int fonttype, | ||
2366 | \c int fontsize, int align, int colour, char *text); | ||
2367 | |||
2368 | This function behaves exactly like the back end \cw{draw_text()} | ||
2369 | function; see \k{drawing-draw-text}. | ||
2370 | |||
2371 | \S{drawingapi-draw-rect} \cw{draw_rect()} | ||
2372 | |||
2373 | \c void (*draw_rect)(void *handle, int x, int y, int w, int h, | ||
2374 | \c int colour); | ||
2375 | |||
2376 | This function behaves exactly like the back end \cw{draw_rect()} | ||
2377 | function; see \k{drawing-draw-rect}. | ||
2378 | |||
2379 | \S{drawingapi-draw-line} \cw{draw_line()} | ||
2380 | |||
2381 | \c void (*draw_line)(void *handle, int x1, int y1, int x2, int y2, | ||
2382 | \c int colour); | ||
2383 | |||
2384 | This function behaves exactly like the back end \cw{draw_line()} | ||
2385 | function; see \k{drawing-draw-line}. | ||
2386 | |||
2387 | \S{drawingapi-draw-polygon} \cw{draw_polygon()} | ||
2388 | |||
2389 | \c void (*draw_polygon)(void *handle, int *coords, int npoints, | ||
2390 | \c int fillcolour, int outlinecolour); | ||
2391 | |||
2392 | This function behaves exactly like the back end \cw{draw_polygon()} | ||
2393 | function; see \k{drawing-draw-polygon}. | ||
2394 | |||
2395 | \S{drawingapi-draw-circle} \cw{draw_circle()} | ||
2396 | |||
2397 | \c void (*draw_circle)(void *handle, int cx, int cy, int radius, | ||
2398 | \c int fillcolour, int outlinecolour); | ||
2399 | |||
2400 | This function behaves exactly like the back end \cw{draw_circle()} | ||
2401 | function; see \k{drawing-draw-circle}. | ||
2402 | |||
2403 | \S{drawingapi-draw-thick-line} \cw{draw_thick_line()} | ||
2404 | |||
2405 | \c void draw_thick_line(drawing *dr, float thickness, | ||
2406 | \c float x1, float y1, float x2, float y2, | ||
2407 | \c int colour) | ||
2408 | |||
2409 | This function behaves exactly like the back end | ||
2410 | \cw{draw_thick_line()} function; see \k{drawing-draw-thick-line}. | ||
2411 | |||
2412 | An implementation of this API which doesn't provide high-quality | ||
2413 | rendering of thick lines is permitted to define this function | ||
2414 | pointer to be \cw{NULL}. The middleware in \cw{drawing.c} will notice | ||
2415 | and provide a low-quality alternative using \cw{draw_polygon()}. | ||
2416 | |||
2417 | \S{drawingapi-draw-update} \cw{draw_update()} | ||
2418 | |||
2419 | \c void (*draw_update)(void *handle, int x, int y, int w, int h); | ||
2420 | |||
2421 | This function behaves exactly like the back end \cw{draw_update()} | ||
2422 | function; see \k{drawing-draw-update}. | ||
2423 | |||
2424 | An implementation of this API which only supports printing is | ||
2425 | permitted to define this function pointer to be \cw{NULL} rather | ||
2426 | than bothering to define an empty function. The middleware in | ||
2427 | \cw{drawing.c} will notice and avoid calling it. | ||
2428 | |||
2429 | \S{drawingapi-clip} \cw{clip()} | ||
2430 | |||
2431 | \c void (*clip)(void *handle, int x, int y, int w, int h); | ||
2432 | |||
2433 | This function behaves exactly like the back end \cw{clip()} | ||
2434 | function; see \k{drawing-clip}. | ||
2435 | |||
2436 | \S{drawingapi-unclip} \cw{unclip()} | ||
2437 | |||
2438 | \c void (*unclip)(void *handle); | ||
2439 | |||
2440 | This function behaves exactly like the back end \cw{unclip()} | ||
2441 | function; see \k{drawing-unclip}. | ||
2442 | |||
2443 | \S{drawingapi-start-draw} \cw{start_draw()} | ||
2444 | |||
2445 | \c void (*start_draw)(void *handle); | ||
2446 | |||
2447 | This function is called at the start of drawing. It allows the front | ||
2448 | end to initialise any temporary data required to draw with, such as | ||
2449 | device contexts. | ||
2450 | |||
2451 | Implementations of this API which do not provide drawing services | ||
2452 | may define this function pointer to be \cw{NULL}; it will never be | ||
2453 | called unless drawing is attempted. | ||
2454 | |||
2455 | \S{drawingapi-end-draw} \cw{end_draw()} | ||
2456 | |||
2457 | \c void (*end_draw)(void *handle); | ||
2458 | |||
2459 | This function is called at the end of drawing. It allows the front | ||
2460 | end to do cleanup tasks such as deallocating device contexts and | ||
2461 | scheduling appropriate GUI redraw events. | ||
2462 | |||
2463 | Implementations of this API which do not provide drawing services | ||
2464 | may define this function pointer to be \cw{NULL}; it will never be | ||
2465 | called unless drawing is attempted. | ||
2466 | |||
2467 | \S{drawingapi-status-bar} \cw{status_bar()} | ||
2468 | |||
2469 | \c void (*status_bar)(void *handle, char *text); | ||
2470 | |||
2471 | This function behaves exactly like the back end \cw{status_bar()} | ||
2472 | function; see \k{drawing-status-bar}. | ||
2473 | |||
2474 | Front ends implementing this function need not worry about it being | ||
2475 | called repeatedly with the same text; the middleware code in | ||
2476 | \cw{status_bar()} will take care of this. | ||
2477 | |||
2478 | Implementations of this API which do not provide drawing services | ||
2479 | may define this function pointer to be \cw{NULL}; it will never be | ||
2480 | called unless drawing is attempted. | ||
2481 | |||
2482 | \S{drawingapi-blitter-new} \cw{blitter_new()} | ||
2483 | |||
2484 | \c blitter *(*blitter_new)(void *handle, int w, int h); | ||
2485 | |||
2486 | This function behaves exactly like the back end \cw{blitter_new()} | ||
2487 | function; see \k{drawing-blitter-new}. | ||
2488 | |||
2489 | Implementations of this API which do not provide drawing services | ||
2490 | may define this function pointer to be \cw{NULL}; it will never be | ||
2491 | called unless drawing is attempted. | ||
2492 | |||
2493 | \S{drawingapi-blitter-free} \cw{blitter_free()} | ||
2494 | |||
2495 | \c void (*blitter_free)(void *handle, blitter *bl); | ||
2496 | |||
2497 | This function behaves exactly like the back end \cw{blitter_free()} | ||
2498 | function; see \k{drawing-blitter-free}. | ||
2499 | |||
2500 | Implementations of this API which do not provide drawing services | ||
2501 | may define this function pointer to be \cw{NULL}; it will never be | ||
2502 | called unless drawing is attempted. | ||
2503 | |||
2504 | \S{drawingapi-blitter-save} \cw{blitter_save()} | ||
2505 | |||
2506 | \c void (*blitter_save)(void *handle, blitter *bl, int x, int y); | ||
2507 | |||
2508 | This function behaves exactly like the back end \cw{blitter_save()} | ||
2509 | function; see \k{drawing-blitter-save}. | ||
2510 | |||
2511 | Implementations of this API which do not provide drawing services | ||
2512 | may define this function pointer to be \cw{NULL}; it will never be | ||
2513 | called unless drawing is attempted. | ||
2514 | |||
2515 | \S{drawingapi-blitter-load} \cw{blitter_load()} | ||
2516 | |||
2517 | \c void (*blitter_load)(void *handle, blitter *bl, int x, int y); | ||
2518 | |||
2519 | This function behaves exactly like the back end \cw{blitter_load()} | ||
2520 | function; see \k{drawing-blitter-load}. | ||
2521 | |||
2522 | Implementations of this API which do not provide drawing services | ||
2523 | may define this function pointer to be \cw{NULL}; it will never be | ||
2524 | called unless drawing is attempted. | ||
2525 | |||
2526 | \S{drawingapi-begin-doc} \cw{begin_doc()} | ||
2527 | |||
2528 | \c void (*begin_doc)(void *handle, int pages); | ||
2529 | |||
2530 | This function is called at the beginning of a printing run. It gives | ||
2531 | the front end an opportunity to initialise any required printing | ||
2532 | subsystem. It also provides the number of pages in advance. | ||
2533 | |||
2534 | Implementations of this API which do not provide printing services | ||
2535 | may define this function pointer to be \cw{NULL}; it will never be | ||
2536 | called unless printing is attempted. | ||
2537 | |||
2538 | \S{drawingapi-begin-page} \cw{begin_page()} | ||
2539 | |||
2540 | \c void (*begin_page)(void *handle, int number); | ||
2541 | |||
2542 | This function is called during printing, at the beginning of each | ||
2543 | page. It gives the page number (numbered from 1 rather than 0, so | ||
2544 | suitable for use in user-visible contexts). | ||
2545 | |||
2546 | Implementations of this API which do not provide printing services | ||
2547 | may define this function pointer to be \cw{NULL}; it will never be | ||
2548 | called unless printing is attempted. | ||
2549 | |||
2550 | \S{drawingapi-begin-puzzle} \cw{begin_puzzle()} | ||
2551 | |||
2552 | \c void (*begin_puzzle)(void *handle, float xm, float xc, | ||
2553 | \c float ym, float yc, int pw, int ph, float wmm); | ||
2554 | |||
2555 | This function is called during printing, just before printing a | ||
2556 | single puzzle on a page. It specifies the size and location of the | ||
2557 | puzzle on the page. | ||
2558 | |||
2559 | \c{xm} and \c{xc} specify the horizontal position of the puzzle on | ||
2560 | the page, as a linear function of the page width. The front end is | ||
2561 | expected to multiply the page width by \c{xm}, add \c{xc} (measured | ||
2562 | in millimetres), and use the resulting x-coordinate as the left edge | ||
2563 | of the puzzle. | ||
2564 | |||
2565 | Similarly, \c{ym} and \c{yc} specify the vertical position of the | ||
2566 | puzzle as a function of the page height: the page height times | ||
2567 | \c{ym}, plus \c{yc} millimetres, equals the desired distance from | ||
2568 | the top of the page to the top of the puzzle. | ||
2569 | |||
2570 | (This unwieldy mechanism is required because not all printing | ||
2571 | systems can communicate the page size back to the software. The | ||
2572 | PostScript back end, for example, writes out PS which determines the | ||
2573 | page size at print time by means of calling \cq{clippath}, and | ||
2574 | centres the puzzles within that. Thus, exactly the same PS file | ||
2575 | works on A4 or on US Letter paper without needing local | ||
2576 | configuration, which simplifies matters.) | ||
2577 | |||
2578 | \cw{pw} and \cw{ph} give the size of the puzzle in drawing API | ||
2579 | coordinates. The printing system will subsequently call the puzzle's | ||
2580 | own print function, which will in turn call drawing API functions in | ||
2581 | the expectation that an area \cw{pw} by \cw{ph} units is available | ||
2582 | to draw the puzzle on. | ||
2583 | |||
2584 | Finally, \cw{wmm} gives the desired width of the puzzle in | ||
2585 | millimetres. (The aspect ratio is expected to be preserved, so if | ||
2586 | the desired puzzle height is also needed then it can be computed as | ||
2587 | \cw{wmm*ph/pw}.) | ||
2588 | |||
2589 | Implementations of this API which do not provide printing services | ||
2590 | may define this function pointer to be \cw{NULL}; it will never be | ||
2591 | called unless printing is attempted. | ||
2592 | |||
2593 | \S{drawingapi-end-puzzle} \cw{end_puzzle()} | ||
2594 | |||
2595 | \c void (*end_puzzle)(void *handle); | ||
2596 | |||
2597 | This function is called after the printing of a specific puzzle is | ||
2598 | complete. | ||
2599 | |||
2600 | Implementations of this API which do not provide printing services | ||
2601 | may define this function pointer to be \cw{NULL}; it will never be | ||
2602 | called unless printing is attempted. | ||
2603 | |||
2604 | \S{drawingapi-end-page} \cw{end_page()} | ||
2605 | |||
2606 | \c void (*end_page)(void *handle, int number); | ||
2607 | |||
2608 | This function is called after the printing of a page is finished. | ||
2609 | |||
2610 | Implementations of this API which do not provide printing services | ||
2611 | may define this function pointer to be \cw{NULL}; it will never be | ||
2612 | called unless printing is attempted. | ||
2613 | |||
2614 | \S{drawingapi-end-doc} \cw{end_doc()} | ||
2615 | |||
2616 | \c void (*end_doc)(void *handle); | ||
2617 | |||
2618 | This function is called after the printing of the entire document is | ||
2619 | finished. This is the moment to close files, send things to the | ||
2620 | print spooler, or whatever the local convention is. | ||
2621 | |||
2622 | Implementations of this API which do not provide printing services | ||
2623 | may define this function pointer to be \cw{NULL}; it will never be | ||
2624 | called unless printing is attempted. | ||
2625 | |||
2626 | \S{drawingapi-line-width} \cw{line_width()} | ||
2627 | |||
2628 | \c void (*line_width)(void *handle, float width); | ||
2629 | |||
2630 | This function is called to set the line thickness, during printing | ||
2631 | only. Note that the width is a \cw{float} here, where it was an | ||
2632 | \cw{int} as seen by the back end. This is because \cw{drawing.c} may | ||
2633 | have scaled it on the way past. | ||
2634 | |||
2635 | However, the width is still specified in the same coordinate system | ||
2636 | as the rest of the drawing. | ||
2637 | |||
2638 | Implementations of this API which do not provide printing services | ||
2639 | may define this function pointer to be \cw{NULL}; it will never be | ||
2640 | called unless printing is attempted. | ||
2641 | |||
2642 | \S{drawingapi-text-fallback} \cw{text_fallback()} | ||
2643 | |||
2644 | \c char *(*text_fallback)(void *handle, const char *const *strings, | ||
2645 | \c int nstrings); | ||
2646 | |||
2647 | This function behaves exactly like the back end \cw{text_fallback()} | ||
2648 | function; see \k{drawing-text-fallback}. | ||
2649 | |||
2650 | Implementations of this API which do not support any characters | ||
2651 | outside ASCII may define this function pointer to be \cw{NULL}, in | ||
2652 | which case the central code in \cw{drawing.c} will provide a default | ||
2653 | implementation. | ||
2654 | |||
2655 | \H{drawingapi-frontend} The drawing API as called by the front end | ||
2656 | |||
2657 | There are a small number of functions provided in \cw{drawing.c} | ||
2658 | which the front end needs to \e{call}, rather than helping to | ||
2659 | implement. They are described in this section. | ||
2660 | |||
2661 | \S{drawing-new} \cw{drawing_new()} | ||
2662 | |||
2663 | \c drawing *drawing_new(const drawing_api *api, midend *me, | ||
2664 | \c void *handle); | ||
2665 | |||
2666 | This function creates a drawing object. It is passed a | ||
2667 | \c{drawing_api}, which is a structure containing nothing but | ||
2668 | function pointers; and also a \cq{void *} handle. The handle is | ||
2669 | passed back to each function pointer when it is called. | ||
2670 | |||
2671 | The \c{midend} parameter is used for rewriting the status bar | ||
2672 | contents: \cw{status_bar()} (see \k{drawing-status-bar}) has to call | ||
2673 | a function in the mid-end which might rewrite the status bar text. | ||
2674 | If the drawing object is to be used only for printing, or if the | ||
2675 | game is known not to call \cw{status_bar()}, this parameter may be | ||
2676 | \cw{NULL}. | ||
2677 | |||
2678 | \S{drawing-free} \cw{drawing_free()} | ||
2679 | |||
2680 | \c void drawing_free(drawing *dr); | ||
2681 | |||
2682 | This function frees a drawing object. Note that the \cq{void *} | ||
2683 | handle is not freed; if that needs cleaning up it must be done by | ||
2684 | the front end. | ||
2685 | |||
2686 | \S{drawing-print-get-colour} \cw{print_get_colour()} | ||
2687 | |||
2688 | \c void print_get_colour(drawing *dr, int colour, int printincolour, | ||
2689 | \c int *hatch, float *r, float *g, float *b) | ||
2690 | |||
2691 | This function is called by the implementations of the drawing API | ||
2692 | functions when they are called in a printing context. It takes a | ||
2693 | colour index as input, and returns the description of the colour as | ||
2694 | requested by the back end. | ||
2695 | |||
2696 | \c{printincolour} is \cw{TRUE} iff the implementation is printing in | ||
2697 | colour. This will alter the results returned if the colour in | ||
2698 | question was specified with a black-and-white fallback value. | ||
2699 | |||
2700 | If the colour should be rendered by hatching, \c{*hatch} is filled | ||
2701 | with the type of hatching desired. See \k{print-grey-colour} for | ||
2702 | details of the values this integer can take. | ||
2703 | |||
2704 | If the colour should be rendered as solid colour, \c{*hatch} is | ||
2705 | given a negative value, and \c{*r}, \c{*g} and \c{*b} are filled | ||
2706 | with the RGB values of the desired colour (if printing in colour), | ||
2707 | or all filled with the grey-scale value (if printing in black and | ||
2708 | white). | ||
2709 | |||
2710 | \C{midend} The API provided by the mid-end | ||
2711 | |||
2712 | This chapter documents the API provided by the mid-end to be called | ||
2713 | by the front end. You probably only need to read this if you are a | ||
2714 | front end implementor, i.e. you are porting Puzzles to a new | ||
2715 | platform. If you're only interested in writing new puzzles, you can | ||
2716 | safely skip this chapter. | ||
2717 | |||
2718 | All the persistent state in the mid-end is encapsulated within a | ||
2719 | \c{midend} structure, to facilitate having multiple mid-ends in any | ||
2720 | port which supports multiple puzzle windows open simultaneously. | ||
2721 | Each \c{midend} is intended to handle the contents of a single | ||
2722 | puzzle window. | ||
2723 | |||
2724 | \H{midend-new} \cw{midend_new()} | ||
2725 | |||
2726 | \c midend *midend_new(frontend *fe, const game *ourgame, | ||
2727 | \c const drawing_api *drapi, void *drhandle) | ||
2728 | |||
2729 | Allocates and returns a new mid-end structure. | ||
2730 | |||
2731 | The \c{fe} argument is stored in the mid-end. It will be used when | ||
2732 | calling back to functions such as \cw{activate_timer()} | ||
2733 | (\k{frontend-activate-timer}), and will be passed on to the back end | ||
2734 | function \cw{colours()} (\k{backend-colours}). | ||
2735 | |||
2736 | The parameters \c{drapi} and \c{drhandle} are passed to | ||
2737 | \cw{drawing_new()} (\k{drawing-new}) to construct a drawing object | ||
2738 | which will be passed to the back end function \cw{redraw()} | ||
2739 | (\k{backend-redraw}). Hence, all drawing-related function pointers | ||
2740 | defined in \c{drapi} can expect to be called with \c{drhandle} as | ||
2741 | their first argument. | ||
2742 | |||
2743 | The \c{ourgame} argument points to a container structure describing | ||
2744 | a game back end. The mid-end thus created will only be capable of | ||
2745 | handling that one game. (So even in a monolithic front end | ||
2746 | containing all the games, this imposes the constraint that any | ||
2747 | individual puzzle window is tied to a single game. Unless, of | ||
2748 | course, you feel brave enough to change the mid-end for the window | ||
2749 | without closing the window...) | ||
2750 | |||
2751 | \H{midend-free} \cw{midend_free()} | ||
2752 | |||
2753 | \c void midend_free(midend *me); | ||
2754 | |||
2755 | Frees a mid-end structure and all its associated data. | ||
2756 | |||
2757 | \H{midend-tilesize} \cw{midend_tilesize()} | ||
2758 | |||
2759 | \c int midend_tilesize(midend *me); | ||
2760 | |||
2761 | Returns the \cq{tilesize} parameter being used to display the | ||
2762 | current puzzle (\k{backend-preferred-tilesize}). | ||
2763 | |||
2764 | \H{midend-set-params} \cw{midend_set_params()} | ||
2765 | |||
2766 | \c void midend_set_params(midend *me, game_params *params); | ||
2767 | |||
2768 | Sets the current game parameters for a mid-end. Subsequent games | ||
2769 | generated by \cw{midend_new_game()} (\k{midend-new-game}) will use | ||
2770 | these parameters until further notice. | ||
2771 | |||
2772 | The usual way in which the front end will have an actual | ||
2773 | \c{game_params} structure to pass to this function is if it had | ||
2774 | previously got it from \cw{midend_get_presets()} | ||
2775 | (\k{midend-get-presets}). Thus, this function is usually called in | ||
2776 | response to the user making a selection from the presets menu. | ||
2777 | |||
2778 | \H{midend-get-params} \cw{midend_get_params()} | ||
2779 | |||
2780 | \c game_params *midend_get_params(midend *me); | ||
2781 | |||
2782 | Returns the current game parameters stored in this mid-end. | ||
2783 | |||
2784 | The returned value is dynamically allocated, and should be freed | ||
2785 | when finished with by passing it to the game's own | ||
2786 | \cw{free_params()} function (see \k{backend-free-params}). | ||
2787 | |||
2788 | \H{midend-size} \cw{midend_size()} | ||
2789 | |||
2790 | \c void midend_size(midend *me, int *x, int *y, int user_size); | ||
2791 | |||
2792 | Tells the mid-end to figure out its window size. | ||
2793 | |||
2794 | On input, \c{*x} and \c{*y} should contain the maximum or requested | ||
2795 | size for the window. (Typically this will be the size of the screen | ||
2796 | that the window has to fit on, or similar.) The mid-end will | ||
2797 | repeatedly call the back end function \cw{compute_size()} | ||
2798 | (\k{backend-compute-size}), searching for a tile size that best | ||
2799 | satisfies the requirements. On exit, \c{*x} and \c{*y} will contain | ||
2800 | the size needed for the puzzle window's drawing area. (It is of | ||
2801 | course up to the front end to adjust this for any additional window | ||
2802 | furniture such as menu bars and window borders, if necessary. The | ||
2803 | status bar is also not included in this size.) | ||
2804 | |||
2805 | Use \c{user_size} to indicate whether \c{*x} and \c{*y} are a | ||
2806 | requested size, or just a maximum size. | ||
2807 | |||
2808 | If \c{user_size} is set to \cw{TRUE}, the mid-end will treat the | ||
2809 | input size as a request, and will pick a tile size which | ||
2810 | approximates it \e{as closely as possible}, going over the game's | ||
2811 | preferred tile size if necessary to achieve this. The mid-end will | ||
2812 | also use the resulting tile size as its preferred one until further | ||
2813 | notice, on the assumption that this size was explicitly requested | ||
2814 | by the user. Use this option if you want your front end to support | ||
2815 | dynamic resizing of the puzzle window with automatic scaling of the | ||
2816 | puzzle to fit. | ||
2817 | |||
2818 | If \c{user_size} is set to \cw{FALSE}, then the game's tile size | ||
2819 | will never go over its preferred one, although it may go under in | ||
2820 | order to fit within the maximum bounds specified by \c{*x} and | ||
2821 | \c{*y}. This is the recommended approach when opening a new window | ||
2822 | at default size: the game will use its preferred size unless it has | ||
2823 | to use a smaller one to fit on the screen. If the tile size is | ||
2824 | shrunk for this reason, the change will not persist; if a smaller | ||
2825 | grid is subsequently chosen, the tile size will recover. | ||
2826 | |||
2827 | The mid-end will try as hard as it can to return a size which is | ||
2828 | less than or equal to the input size, in both dimensions. In extreme | ||
2829 | circumstances it may fail (if even the lowest possible tile size | ||
2830 | gives window dimensions greater than the input), in which case it | ||
2831 | will return a size greater than the input size. Front ends should be | ||
2832 | prepared for this to happen (i.e. don't crash or fail an assertion), | ||
2833 | but may handle it in any way they see fit: by rejecting the game | ||
2834 | parameters which caused the problem, by opening a window larger than | ||
2835 | the screen regardless of inconvenience, by introducing scroll bars | ||
2836 | on the window, by drawing on a large bitmap and scaling it into a | ||
2837 | smaller window, or by any other means you can think of. It is likely | ||
2838 | that when the tile size is that small the game will be unplayable | ||
2839 | anyway, so don't put \e{too} much effort into handling it | ||
2840 | creatively. | ||
2841 | |||
2842 | If your platform has no limit on window size (or if you're planning | ||
2843 | to use scroll bars for large puzzles), you can pass dimensions of | ||
2844 | \cw{INT_MAX} as input to this function. You should probably not do | ||
2845 | that \e{and} set the \c{user_size} flag, though! | ||
2846 | |||
2847 | The midend relies on the frontend calling \cw{midend_new_game()} | ||
2848 | (\k{midend-new-game}) before calling \cw{midend_size()}. | ||
2849 | |||
2850 | \H{midend-reset-tilesize} \cw{midend_reset_tilesize()} | ||
2851 | |||
2852 | \c void midend_reset_tilesize(midend *me); | ||
2853 | |||
2854 | This function resets the midend's preferred tile size to that of the | ||
2855 | standard puzzle. | ||
2856 | |||
2857 | As discussed in \k{midend-size}, puzzle resizes are typically | ||
2858 | 'sticky', in that once the user has dragged the puzzle to a different | ||
2859 | window size, the resulting tile size will be remembered and used when | ||
2860 | the puzzle configuration changes. If you \e{don't} want that, e.g. if | ||
2861 | you want to provide a command to explicitly reset the puzzle size back | ||
2862 | to its default, then you can call this just before calling | ||
2863 | \cw{midend_size()} (which, in turn, you would probably call with | ||
2864 | \c{user_size} set to \cw{FALSE}). | ||
2865 | |||
2866 | \H{midend-new-game} \cw{midend_new_game()} | ||
2867 | |||
2868 | \c void midend_new_game(midend *me); | ||
2869 | |||
2870 | Causes the mid-end to begin a new game. Normally the game will be a | ||
2871 | new randomly generated puzzle. However, if you have previously | ||
2872 | called \cw{midend_game_id()} or \cw{midend_set_config()}, the game | ||
2873 | generated might be dictated by the results of those functions. (In | ||
2874 | particular, you \e{must} call \cw{midend_new_game()} after calling | ||
2875 | either of those functions, or else no immediate effect will be | ||
2876 | visible.) | ||
2877 | |||
2878 | You will probably need to call \cw{midend_size()} after calling this | ||
2879 | function, because if the game parameters have been changed since the | ||
2880 | last new game then the window size might need to change. (If you | ||
2881 | know the parameters \e{haven't} changed, you don't need to do this.) | ||
2882 | |||
2883 | This function will create a new \c{game_drawstate}, but does not | ||
2884 | actually perform a redraw (since you often need to call | ||
2885 | \cw{midend_size()} before the redraw can be done). So after calling | ||
2886 | this function and after calling \cw{midend_size()}, you should then | ||
2887 | call \cw{midend_redraw()}. (It is not necessary to call | ||
2888 | \cw{midend_force_redraw()}; that will discard the draw state and | ||
2889 | create a fresh one, which is unnecessary in this case since there's | ||
2890 | a fresh one already. It would work, but it's usually excessive.) | ||
2891 | |||
2892 | \H{midend-restart-game} \cw{midend_restart_game()} | ||
2893 | |||
2894 | \c void midend_restart_game(midend *me); | ||
2895 | |||
2896 | This function causes the current game to be restarted. This is done | ||
2897 | by placing a new copy of the original game state on the end of the | ||
2898 | undo list (so that an accidental restart can be undone). | ||
2899 | |||
2900 | This function automatically causes a redraw, i.e. the front end can | ||
2901 | expect its drawing API to be called from \e{within} a call to this | ||
2902 | function. Some back ends require that \cw{midend_size()} | ||
2903 | (\k{midend-size}) is called before \cw{midend_restart_game()}. | ||
2904 | |||
2905 | \H{midend-force-redraw} \cw{midend_force_redraw()} | ||
2906 | |||
2907 | \c void midend_force_redraw(midend *me); | ||
2908 | |||
2909 | Forces a complete redraw of the puzzle window, by means of | ||
2910 | discarding the current \c{game_drawstate} and creating a new one | ||
2911 | from scratch before calling the game's \cw{redraw()} function. | ||
2912 | |||
2913 | The front end can expect its drawing API to be called from within a | ||
2914 | call to this function. Some back ends require that \cw{midend_size()} | ||
2915 | (\k{midend-size}) is called before \cw{midend_force_redraw()}. | ||
2916 | |||
2917 | \H{midend-redraw} \cw{midend_redraw()} | ||
2918 | |||
2919 | \c void midend_redraw(midend *me); | ||
2920 | |||
2921 | Causes a partial redraw of the puzzle window, by means of simply | ||
2922 | calling the game's \cw{redraw()} function. (That is, the only things | ||
2923 | redrawn will be things that have changed since the last redraw.) | ||
2924 | |||
2925 | The front end can expect its drawing API to be called from within a | ||
2926 | call to this function. Some back ends require that \cw{midend_size()} | ||
2927 | (\k{midend-size}) is called before \cw{midend_redraw()}. | ||
2928 | |||
2929 | \H{midend-process-key} \cw{midend_process_key()} | ||
2930 | |||
2931 | \c int midend_process_key(midend *me, int x, int y, int button); | ||
2932 | |||
2933 | The front end calls this function to report a mouse or keyboard | ||
2934 | event. The parameters \c{x}, \c{y} and \c{button} are almost | ||
2935 | identical to the ones passed to the back end function | ||
2936 | \cw{interpret_move()} (\k{backend-interpret-move}), except that the | ||
2937 | front end is \e{not} required to provide the guarantees about mouse | ||
2938 | event ordering. The mid-end will sort out multiple simultaneous | ||
2939 | button presses and changes of button; the front end's responsibility | ||
2940 | is simply to pass on the mouse events it receives as accurately as | ||
2941 | possible. | ||
2942 | |||
2943 | (Some platforms may need to emulate absent mouse buttons by means of | ||
2944 | using a modifier key such as Shift with another mouse button. This | ||
2945 | tends to mean that if Shift is pressed or released in the middle of | ||
2946 | a mouse drag, the mid-end will suddenly stop receiving, say, | ||
2947 | \cw{LEFT_DRAG} events and start receiving \cw{RIGHT_DRAG}s, with no | ||
2948 | intervening button release or press events. This too is something | ||
2949 | which the mid-end will sort out for you; the front end has no | ||
2950 | obligation to maintain sanity in this area.) | ||
2951 | |||
2952 | The front end \e{should}, however, always eventually send some kind | ||
2953 | of button release. On some platforms this requires special effort: | ||
2954 | Windows, for example, requires a call to the system API function | ||
2955 | \cw{SetCapture()} in order to ensure that your window receives a | ||
2956 | mouse-up event even if the pointer has left the window by the time | ||
2957 | the mouse button is released. On any platform that requires this | ||
2958 | sort of thing, the front end \e{is} responsible for doing it. | ||
2959 | |||
2960 | Calling this function is very likely to result in calls back to the | ||
2961 | front end's drawing API and/or \cw{activate_timer()} | ||
2962 | (\k{frontend-activate-timer}). | ||
2963 | |||
2964 | The return value from \cw{midend_process_key()} is non-zero, unless | ||
2965 | the effect of the keypress was to request termination of the | ||
2966 | program. A front end should shut down the puzzle in response to a | ||
2967 | zero return. | ||
2968 | |||
2969 | \H{midend-colours} \cw{midend_colours()} | ||
2970 | |||
2971 | \c float *midend_colours(midend *me, int *ncolours); | ||
2972 | |||
2973 | Returns an array of the colours required by the game, in exactly the | ||
2974 | same format as that returned by the back end function \cw{colours()} | ||
2975 | (\k{backend-colours}). Front ends should call this function rather | ||
2976 | than calling the back end's version directly, since the mid-end adds | ||
2977 | standard customisation facilities. (At the time of writing, those | ||
2978 | customisation facilities are implemented hackily by means of | ||
2979 | environment variables, but it's not impossible that they may become | ||
2980 | more full and formal in future.) | ||
2981 | |||
2982 | \H{midend-timer} \cw{midend_timer()} | ||
2983 | |||
2984 | \c void midend_timer(midend *me, float tplus); | ||
2985 | |||
2986 | If the mid-end has called \cw{activate_timer()} | ||
2987 | (\k{frontend-activate-timer}) to request regular callbacks for | ||
2988 | purposes of animation or timing, this is the function the front end | ||
2989 | should call on a regular basis. The argument \c{tplus} gives the | ||
2990 | time, in seconds, since the last time either this function was | ||
2991 | called or \cw{activate_timer()} was invoked. | ||
2992 | |||
2993 | One of the major purposes of timing in the mid-end is to perform | ||
2994 | move animation. Therefore, calling this function is very likely to | ||
2995 | result in calls back to the front end's drawing API. | ||
2996 | |||
2997 | \H{midend-get-presets} \cw{midend_get_presets()} | ||
2998 | |||
2999 | \c struct preset_menu *midend_get_presets(midend *me, int *id_limit); | ||
3000 | |||
3001 | Returns a data structure describing this game's collection of preset | ||
3002 | game parameters, organised into a hierarchical structure of menus and | ||
3003 | submenus. | ||
3004 | |||
3005 | The return value is a pointer to a data structure containing the | ||
3006 | following fields (among others, which are not intended for front end | ||
3007 | use): | ||
3008 | |||
3009 | \c struct preset_menu { | ||
3010 | \c int n_entries; | ||
3011 | \c struct preset_menu_entry *entries; | ||
3012 | \c /* and other things */ | ||
3013 | \e iiiiiiiiiiiiiiiiiiiiii | ||
3014 | \c }; | ||
3015 | |||
3016 | Those fields describe the intended contents of one particular menu in | ||
3017 | the hierarchy. \cq{entries} points to an array of \cq{n_entries} | ||
3018 | items, each of which is a structure containing the following fields: | ||
3019 | |||
3020 | \c struct preset_menu_entry { | ||
3021 | \c char *title; | ||
3022 | \c game_params *params; | ||
3023 | \c struct preset_menu *submenu; | ||
3024 | \c int id; | ||
3025 | \c }; | ||
3026 | |||
3027 | Of these fields, \cq{title} and \cq{id} are present in every entry, | ||
3028 | giving (respectively) the textual name of the menu item and an integer | ||
3029 | identifier for it. The integer id will correspond to the one returned | ||
3030 | by \c{midend_which_preset} (\k{midend-which-preset}), when that preset | ||
3031 | is the one selected. | ||
3032 | |||
3033 | The other two fields are mutually exclusive. Each \c{struct | ||
3034 | preset_menu_entry} will have one of those fields \cw{NULL} and the | ||
3035 | other one non-null. If the menu item is an actual preset, then | ||
3036 | \cq{params} will point to the set of game parameters that go with the | ||
3037 | name; if it's a submenu, then \cq{submenu} instead will be non-null, | ||
3038 | and will point at a subsidiary \c{struct preset_menu}. | ||
3039 | |||
3040 | The complete hierarchy of these structures is owned by the mid-end, | ||
3041 | and will be freed when the mid-end is freed. The front end should not | ||
3042 | attempt to free any of it. | ||
3043 | |||
3044 | The integer identifiers will be allocated densely from 0 upwards, so | ||
3045 | that it's reasonable for the front end to allocate an array which uses | ||
3046 | them as indices, if it needs to store information per preset menu | ||
3047 | item. For this purpose, the front end may pass the second parameter | ||
3048 | \cq{id_limit} to \cw{midend_get_presets} as the address of an \c{int} | ||
3049 | variable, into which \cw{midend_get_presets} will write an integer one | ||
3050 | larger than the largest id number actually used (i.e. the number of | ||
3051 | elements the front end would need in the array). | ||
3052 | |||
3053 | Submenu-type entries also have integer identifiers. | ||
3054 | |||
3055 | \H{midend-which-preset} \cw{midend_which_preset()} | ||
3056 | |||
3057 | \c int midend_which_preset(midend *me); | ||
3058 | |||
3059 | Returns the numeric index of the preset game parameter structure | ||
3060 | which matches the current game parameters, or a negative number if | ||
3061 | no preset matches. Front ends could use this to maintain a tick | ||
3062 | beside one of the items in the menu (or tick the \q{Custom} option | ||
3063 | if the return value is less than zero). | ||
3064 | |||
3065 | The returned index value (if non-negative) will match the \c{id} field | ||
3066 | of the corresponding \cw{struct preset_menu_entry} returned by | ||
3067 | \c{midend_get_presets()} (\k{midend-get-presets}). | ||
3068 | |||
3069 | \H{midend-wants-statusbar} \cw{midend_wants_statusbar()} | ||
3070 | |||
3071 | \c int midend_wants_statusbar(midend *me); | ||
3072 | |||
3073 | This function returns \cw{TRUE} if the puzzle has a use for a | ||
3074 | textual status line (to display score, completion status, currently | ||
3075 | active tiles, time, or anything else). | ||
3076 | |||
3077 | Front ends should call this function rather than talking directly to | ||
3078 | the back end. | ||
3079 | |||
3080 | \H{midend-get-config} \cw{midend_get_config()} | ||
3081 | |||
3082 | \c config_item *midend_get_config(midend *me, int which, | ||
3083 | \c char **wintitle); | ||
3084 | |||
3085 | Returns a dialog box description for user configuration. | ||
3086 | |||
3087 | On input, \cw{which} should be set to one of three values, which | ||
3088 | select which of the various dialog box descriptions is returned: | ||
3089 | |||
3090 | \dt \cw{CFG_SETTINGS} | ||
3091 | |||
3092 | \dd Requests the GUI parameter configuration box generated by the | ||
3093 | puzzle itself. This should be used when the user selects \q{Custom} | ||
3094 | from the game types menu (or equivalent). The mid-end passes this | ||
3095 | request on to the back end function \cw{configure()} | ||
3096 | (\k{backend-configure}). | ||
3097 | |||
3098 | \dt \cw{CFG_DESC} | ||
3099 | |||
3100 | \dd Requests a box suitable for entering a descriptive game ID (and | ||
3101 | viewing the existing one). The mid-end generates this dialog box | ||
3102 | description itself. This should be used when the user selects | ||
3103 | \q{Specific} from the game menu (or equivalent). | ||
3104 | |||
3105 | \dt \cw{CFG_SEED} | ||
3106 | |||
3107 | \dd Requests a box suitable for entering a random-seed game ID (and | ||
3108 | viewing the existing one). The mid-end generates this dialog box | ||
3109 | description itself. This should be used when the user selects | ||
3110 | \q{Random Seed} from the game menu (or equivalent). | ||
3111 | |||
3112 | The returned value is an array of \cw{config_item}s, exactly as | ||
3113 | described in \k{backend-configure}. Another returned value is an | ||
3114 | ASCII string giving a suitable title for the configuration window, | ||
3115 | in \c{*wintitle}. | ||
3116 | |||
3117 | Both returned values are dynamically allocated and will need to be | ||
3118 | freed. The window title can be freed in the obvious way; the | ||
3119 | \cw{config_item} array is a slightly complex structure, so a utility | ||
3120 | function \cw{free_cfg()} is provided to free it for you. See | ||
3121 | \k{utils-free-cfg}. | ||
3122 | |||
3123 | (Of course, you will probably not want to free the \cw{config_item} | ||
3124 | array until the dialog box is dismissed, because before then you | ||
3125 | will probably need to pass it to \cw{midend_set_config}.) | ||
3126 | |||
3127 | \H{midend-set-config} \cw{midend_set_config()} | ||
3128 | |||
3129 | \c char *midend_set_config(midend *me, int which, | ||
3130 | \c config_item *cfg); | ||
3131 | |||
3132 | Passes the mid-end the results of a configuration dialog box. | ||
3133 | \c{which} should have the same value which it had when | ||
3134 | \cw{midend_get_config()} was called; \c{cfg} should be the array of | ||
3135 | \c{config_item}s returned from \cw{midend_get_config()}, modified to | ||
3136 | contain the results of the user's editing operations. | ||
3137 | |||
3138 | This function returns \cw{NULL} on success, or otherwise (if the | ||
3139 | configuration data was in some way invalid) an ASCII string | ||
3140 | containing an error message suitable for showing to the user. | ||
3141 | |||
3142 | If the function succeeds, it is likely that the game parameters will | ||
3143 | have been changed and it is certain that a new game will be | ||
3144 | requested. The front end should therefore call | ||
3145 | \cw{midend_new_game()}, and probably also re-think the window size | ||
3146 | using \cw{midend_size()} and eventually perform a refresh using | ||
3147 | \cw{midend_redraw()}. | ||
3148 | |||
3149 | \H{midend-game-id} \cw{midend_game_id()} | ||
3150 | |||
3151 | \c char *midend_game_id(midend *me, char *id); | ||
3152 | |||
3153 | Passes the mid-end a string game ID (of any of the valid forms | ||
3154 | \cq{params}, \cq{params:description} or \cq{params#seed}) which the | ||
3155 | mid-end will process and use for the next generated game. | ||
3156 | |||
3157 | This function returns \cw{NULL} on success, or otherwise (if the | ||
3158 | configuration data was in some way invalid) an ASCII string | ||
3159 | containing an error message (not dynamically allocated) suitable for | ||
3160 | showing to the user. In the event of an error, the mid-end's | ||
3161 | internal state will be left exactly as it was before the call. | ||
3162 | |||
3163 | If the function succeeds, it is likely that the game parameters will | ||
3164 | have been changed and it is certain that a new game will be | ||
3165 | requested. The front end should therefore call | ||
3166 | \cw{midend_new_game()}, and probably also re-think the window size | ||
3167 | using \cw{midend_size()} and eventually case a refresh using | ||
3168 | \cw{midend_redraw()}. | ||
3169 | |||
3170 | \H{midend-get-game-id} \cw{midend_get_game_id()} | ||
3171 | |||
3172 | \c char *midend_get_game_id(midend *me) | ||
3173 | |||
3174 | Returns a descriptive game ID (i.e. one in the form | ||
3175 | \cq{params:description}) describing the game currently active in the | ||
3176 | mid-end. The returned string is dynamically allocated. | ||
3177 | |||
3178 | \H{midend-get-random-seed} \cw{midend_get_random_seed()} | ||
3179 | |||
3180 | \c char *midend_get_random_seed(midend *me) | ||
3181 | |||
3182 | Returns a random game ID (i.e. one in the form \cq{params#seedstring}) | ||
3183 | describing the game currently active in the mid-end, if there is one. | ||
3184 | If the game was created by entering a description, no random seed will | ||
3185 | currently exist and this function will return \cw{NULL}. | ||
3186 | |||
3187 | The returned string, if it is non-\cw{NULL}, is dynamically allocated. | ||
3188 | |||
3189 | \H{midend-can-format-as-text-now} \cw{midend_can_format_as_text_now()} | ||
3190 | |||
3191 | \c int midend_can_format_as_text_now(midend *me); | ||
3192 | |||
3193 | Returns \cw{TRUE} if the game code is capable of formatting puzzles | ||
3194 | of the currently selected game type as ASCII. | ||
3195 | |||
3196 | If this returns \cw{FALSE}, then \cw{midend_text_format()} | ||
3197 | (\k{midend-text-format}) will return \cw{NULL}. | ||
3198 | |||
3199 | \H{midend-text-format} \cw{midend_text_format()} | ||
3200 | |||
3201 | \c char *midend_text_format(midend *me); | ||
3202 | |||
3203 | Formats the current game's current state as ASCII text suitable for | ||
3204 | copying to the clipboard. The returned string is dynamically | ||
3205 | allocated. | ||
3206 | |||
3207 | If the game's \c{can_format_as_text_ever} flag is \cw{FALSE}, or if | ||
3208 | its \cw{can_format_as_text_now()} function returns \cw{FALSE}, then | ||
3209 | this function will return \cw{NULL}. | ||
3210 | |||
3211 | If the returned string contains multiple lines (which is likely), it | ||
3212 | will use the normal C line ending convention (\cw{\\n} only). On | ||
3213 | platforms which use a different line ending convention for data in | ||
3214 | the clipboard, it is the front end's responsibility to perform the | ||
3215 | conversion. | ||
3216 | |||
3217 | \H{midend-solve} \cw{midend_solve()} | ||
3218 | |||
3219 | \c char *midend_solve(midend *me); | ||
3220 | |||
3221 | Requests the mid-end to perform a Solve operation. | ||
3222 | |||
3223 | On success, \cw{NULL} is returned. On failure, an error message (not | ||
3224 | dynamically allocated) is returned, suitable for showing to the | ||
3225 | user. | ||
3226 | |||
3227 | The front end can expect its drawing API and/or | ||
3228 | \cw{activate_timer()} to be called from within a call to this | ||
3229 | function. Some back ends require that \cw{midend_size()} | ||
3230 | (\k{midend-size}) is called before \cw{midend_solve()}. | ||
3231 | |||
3232 | \H{midend-status} \cw{midend_status()} | ||
3233 | |||
3234 | \c int midend_status(midend *me); | ||
3235 | |||
3236 | This function returns +1 if the midend is currently displaying a game | ||
3237 | in a solved state, -1 if the game is in a permanently lost state, or 0 | ||
3238 | otherwise. This function just calls the back end's \cw{status()} | ||
3239 | function. Front ends may wish to use this as a cue to proactively | ||
3240 | offer the option of starting a new game. | ||
3241 | |||
3242 | (See \k{backend-status} for more detail about the back end's | ||
3243 | \cw{status()} function and discussion of what should count as which | ||
3244 | status code.) | ||
3245 | |||
3246 | \H{midend-can-undo} \cw{midend_can_undo()} | ||
3247 | |||
3248 | \c int midend_can_undo(midend *me); | ||
3249 | |||
3250 | Returns \cw{TRUE} if the midend is currently in a state where the undo | ||
3251 | operation is meaningful (i.e. at least one position exists on the undo | ||
3252 | chain before the present one). Front ends may wish to use this to | ||
3253 | visually activate and deactivate an undo button. | ||
3254 | |||
3255 | \H{midend-can-redo} \cw{midend_can_redo()} | ||
3256 | |||
3257 | \c int midend_can_redo(midend *me); | ||
3258 | |||
3259 | Returns \cw{TRUE} if the midend is currently in a state where the redo | ||
3260 | operation is meaningful (i.e. at least one position exists on the redo | ||
3261 | chain after the present one). Front ends may wish to use this to | ||
3262 | visually activate and deactivate a redo button. | ||
3263 | |||
3264 | \H{midend-serialise} \cw{midend_serialise()} | ||
3265 | |||
3266 | \c void midend_serialise(midend *me, | ||
3267 | \c void (*write)(void *ctx, void *buf, int len), | ||
3268 | \c void *wctx); | ||
3269 | |||
3270 | Calling this function causes the mid-end to convert its entire | ||
3271 | internal state into a long ASCII text string, and to pass that | ||
3272 | string (piece by piece) to the supplied \c{write} function. | ||
3273 | |||
3274 | Desktop implementations can use this function to save a game in any | ||
3275 | state (including half-finished) to a disk file, by supplying a | ||
3276 | \c{write} function which is a wrapper on \cw{fwrite()} (or local | ||
3277 | equivalent). Other implementations may find other uses for it, such | ||
3278 | as compressing the large and sprawling mid-end state into a | ||
3279 | manageable amount of memory when a palmtop application is suspended | ||
3280 | so that another one can run; in this case \cw{write} might want to | ||
3281 | write to a memory buffer rather than a file. There may be other uses | ||
3282 | for it as well. | ||
3283 | |||
3284 | This function will call back to the supplied \c{write} function a | ||
3285 | number of times, with the first parameter (\c{ctx}) equal to | ||
3286 | \c{wctx}, and the other two parameters pointing at a piece of the | ||
3287 | output string. | ||
3288 | |||
3289 | \H{midend-deserialise} \cw{midend_deserialise()} | ||
3290 | |||
3291 | \c char *midend_deserialise(midend *me, | ||
3292 | \c int (*read)(void *ctx, void *buf, int len), | ||
3293 | \c void *rctx); | ||
3294 | |||
3295 | This function is the counterpart to \cw{midend_serialise()}. It | ||
3296 | calls the supplied \cw{read} function repeatedly to read a quantity | ||
3297 | of data, and attempts to interpret that data as a serialised mid-end | ||
3298 | as output by \cw{midend_serialise()}. | ||
3299 | |||
3300 | The \cw{read} function is called with the first parameter (\c{ctx}) | ||
3301 | equal to \c{rctx}, and should attempt to read \c{len} bytes of data | ||
3302 | into the buffer pointed to by \c{buf}. It should return \cw{FALSE} | ||
3303 | on failure or \cw{TRUE} on success. It should not report success | ||
3304 | unless it has filled the entire buffer; on platforms which might be | ||
3305 | reading from a pipe or other blocking data source, \c{read} is | ||
3306 | responsible for looping until the whole buffer has been filled. | ||
3307 | |||
3308 | If the de-serialisation operation is successful, the mid-end's | ||
3309 | internal data structures will be replaced by the results of the | ||
3310 | load, and \cw{NULL} will be returned. Otherwise, the mid-end's state | ||
3311 | will be completely unchanged and an error message (typically some | ||
3312 | variation on \q{save file is corrupt}) will be returned. As usual, | ||
3313 | the error message string is not dynamically allocated. | ||
3314 | |||
3315 | If this function succeeds, it is likely that the game parameters | ||
3316 | will have been changed. The front end should therefore probably | ||
3317 | re-think the window size using \cw{midend_size()}, and probably | ||
3318 | cause a refresh using \cw{midend_redraw()}. | ||
3319 | |||
3320 | Because each mid-end is tied to a specific game back end, this | ||
3321 | function will fail if you attempt to read in a save file generated by | ||
3322 | a different game from the one configured in this mid-end, even if your | ||
3323 | application is a monolithic one containing all the puzzles. See | ||
3324 | \k{identify-game} for a helper function which will allow you to | ||
3325 | identify a save file before you instantiate your mid-end in the first | ||
3326 | place. | ||
3327 | |||
3328 | \H{identify-game} \cw{identify_game()} | ||
3329 | |||
3330 | \c char *identify_game(char **name, | ||
3331 | \c int (*read)(void *ctx, void *buf, int len), | ||
3332 | \c void *rctx); | ||
3333 | |||
3334 | This function examines a serialised midend stream, of the same kind | ||
3335 | used by \cw{midend_serialise()} and \cw{midend_deserialise()}, and | ||
3336 | returns the \cw{name} field of the game back end from which it was | ||
3337 | saved. | ||
3338 | |||
3339 | You might want this if your front end was a monolithic one containing | ||
3340 | all the puzzles, and you wanted to be able to load an arbitrary save | ||
3341 | file and automatically switch to the right game. Probably your next | ||
3342 | step would be to iterate through \cw{gamelist} (\k{frontend-backend}) | ||
3343 | looking for a game structure whose \cw{name} field matched the | ||
3344 | returned string, and give an error if you didn't find one. | ||
3345 | |||
3346 | On success, the return value of this function is \cw{NULL}, and the | ||
3347 | game name string is written into \cw{*name}. The caller should free | ||
3348 | that string after using it. | ||
3349 | |||
3350 | On failure, \cw{*name} is \cw{NULL}, and the return value is an error | ||
3351 | message (which does not need freeing at all). | ||
3352 | |||
3353 | (This isn't strictly speaking a midend function, since it doesn't | ||
3354 | accept or return a pointer to a midend. You'd probably call it just | ||
3355 | \e{before} deciding what kind of midend you wanted to instantiate.) | ||
3356 | |||
3357 | \H{midend-request-id-changes} \cw{midend_request_id_changes()} | ||
3358 | |||
3359 | \c void midend_request_id_changes(midend *me, | ||
3360 | \c void (*notify)(void *), void *ctx); | ||
3361 | |||
3362 | This function is called by the front end to request notification by | ||
3363 | the mid-end when the current game IDs (either descriptive or | ||
3364 | random-seed) change. This can occur as a result of keypresses ('n' for | ||
3365 | New Game, for example) or when a puzzle supersedes its game | ||
3366 | description (see \k{backend-supersede}). After this function is | ||
3367 | called, any change of the game ids will cause the mid-end to call | ||
3368 | \cw{notify(ctx)} after the change. | ||
3369 | |||
3370 | This is for use by puzzles which want to present the game description | ||
3371 | to the user constantly (e.g. as an HTML hyperlink) instead of only | ||
3372 | showing it when the user explicitly requests it. | ||
3373 | |||
3374 | This is a function I anticipate few front ends needing to implement, | ||
3375 | so I make it a callback rather than a static function in order to | ||
3376 | relieve most front ends of the need to provide an empty | ||
3377 | implementation. | ||
3378 | |||
3379 | \H{frontend-backend} Direct reference to the back end structure by | ||
3380 | the front end | ||
3381 | |||
3382 | Although \e{most} things the front end needs done should be done by | ||
3383 | calling the mid-end, there are a few situations in which the front | ||
3384 | end needs to refer directly to the game back end structure. | ||
3385 | |||
3386 | The most obvious of these is | ||
3387 | |||
3388 | \b passing the game back end as a parameter to \cw{midend_new()}. | ||
3389 | |||
3390 | There are a few other back end features which are not wrapped by the | ||
3391 | mid-end because there didn't seem much point in doing so: | ||
3392 | |||
3393 | \b fetching the \c{name} field to use in window titles and similar | ||
3394 | |||
3395 | \b reading the \c{can_configure}, \c{can_solve} and | ||
3396 | \c{can_format_as_text_ever} fields to decide whether to add those | ||
3397 | items to the menu bar or equivalent | ||
3398 | |||
3399 | \b reading the \c{winhelp_topic} field (Windows only) | ||
3400 | |||
3401 | \b the GTK front end provides a \cq{--generate} command-line option | ||
3402 | which directly calls the back end to do most of its work. This is | ||
3403 | not really part of the main front end code, though, and I'm not sure | ||
3404 | it counts. | ||
3405 | |||
3406 | In order to find the game back end structure, the front end does one | ||
3407 | of two things: | ||
3408 | |||
3409 | \b If the particular front end is compiling a separate binary per | ||
3410 | game, then the back end structure is a global variable with the | ||
3411 | standard name \cq{thegame}: | ||
3412 | |||
3413 | \lcont{ | ||
3414 | |||
3415 | \c extern const game thegame; | ||
3416 | |||
3417 | } | ||
3418 | |||
3419 | \b If the front end is compiled as a monolithic application | ||
3420 | containing all the puzzles together (in which case the preprocessor | ||
3421 | symbol \cw{COMBINED} must be defined when compiling most of the code | ||
3422 | base), then there will be two global variables defined: | ||
3423 | |||
3424 | \lcont{ | ||
3425 | |||
3426 | \c extern const game *gamelist[]; | ||
3427 | \c extern const int gamecount; | ||
3428 | |||
3429 | \c{gamelist} will be an array of \c{gamecount} game structures, | ||
3430 | declared in the automatically constructed source module \c{list.c}. | ||
3431 | The application should search that array for the game it wants, | ||
3432 | probably by reaching into each game structure and looking at its | ||
3433 | \c{name} field. | ||
3434 | |||
3435 | } | ||
3436 | |||
3437 | \H{frontend-api} Mid-end to front-end calls | ||
3438 | |||
3439 | This section describes the small number of functions which a front | ||
3440 | end must provide to be called by the mid-end or other standard | ||
3441 | utility modules. | ||
3442 | |||
3443 | \H{frontend-get-random-seed} \cw{get_random_seed()} | ||
3444 | |||
3445 | \c void get_random_seed(void **randseed, int *randseedsize); | ||
3446 | |||
3447 | This function is called by a new mid-end, and also occasionally by | ||
3448 | game back ends. Its job is to return a piece of data suitable for | ||
3449 | using as a seed for initialisation of a new \c{random_state}. | ||
3450 | |||
3451 | On exit, \c{*randseed} should be set to point at a newly allocated | ||
3452 | piece of memory containing some seed data, and \c{*randseedsize} | ||
3453 | should be set to the length of that data. | ||
3454 | |||
3455 | A simple and entirely adequate implementation is to return a piece | ||
3456 | of data containing the current system time at the highest | ||
3457 | conveniently available resolution. | ||
3458 | |||
3459 | \H{frontend-activate-timer} \cw{activate_timer()} | ||
3460 | |||
3461 | \c void activate_timer(frontend *fe); | ||
3462 | |||
3463 | This is called by the mid-end to request that the front end begin | ||
3464 | calling it back at regular intervals. | ||
3465 | |||
3466 | The timeout interval is left up to the front end; the finer it is, | ||
3467 | the smoother move animations will be, but the more CPU time will be | ||
3468 | used. Current front ends use values around 20ms (i.e. 50Hz). | ||
3469 | |||
3470 | After this function is called, the mid-end will expect to receive | ||
3471 | calls to \cw{midend_timer()} on a regular basis. | ||
3472 | |||
3473 | \H{frontend-deactivate-timer} \cw{deactivate_timer()} | ||
3474 | |||
3475 | \c void deactivate_timer(frontend *fe); | ||
3476 | |||
3477 | This is called by the mid-end to request that the front end stop | ||
3478 | calling \cw{midend_timer()}. | ||
3479 | |||
3480 | \H{frontend-fatal} \cw{fatal()} | ||
3481 | |||
3482 | \c void fatal(char *fmt, ...); | ||
3483 | |||
3484 | This is called by some utility functions if they encounter a | ||
3485 | genuinely fatal error such as running out of memory. It is a | ||
3486 | variadic function in the style of \cw{printf()}, and is expected to | ||
3487 | show the formatted error message to the user any way it can and then | ||
3488 | terminate the application. It must not return. | ||
3489 | |||
3490 | \H{frontend-default-colour} \cw{frontend_default_colour()} | ||
3491 | |||
3492 | \c void frontend_default_colour(frontend *fe, float *output); | ||
3493 | |||
3494 | This function expects to be passed a pointer to an array of three | ||
3495 | \cw{float}s. It returns the platform's local preferred background | ||
3496 | colour in those three floats, as red, green and blue values (in that | ||
3497 | order) ranging from \cw{0.0} to \cw{1.0}. | ||
3498 | |||
3499 | This function should only ever be called by the back end function | ||
3500 | \cw{colours()} (\k{backend-colours}). (Thus, it isn't a | ||
3501 | \e{midend}-to-frontend function as such, but there didn't seem to be | ||
3502 | anywhere else particularly good to put it. Sorry.) | ||
3503 | |||
3504 | \C{utils} Utility APIs | ||
3505 | |||
3506 | This chapter documents a variety of utility APIs provided for the | ||
3507 | general use of the rest of the Puzzles code. | ||
3508 | |||
3509 | \H{utils-random} Random number generation | ||
3510 | |||
3511 | Platforms' local random number generators vary widely in quality and | ||
3512 | seed size. Puzzles therefore supplies its own high-quality random | ||
3513 | number generator, with the additional advantage of giving the same | ||
3514 | results if fed the same seed data on different platforms. This | ||
3515 | allows game random seeds to be exchanged between different ports of | ||
3516 | Puzzles and still generate the same games. | ||
3517 | |||
3518 | Unlike the ANSI C \cw{rand()} function, the Puzzles random number | ||
3519 | generator has an \e{explicit} state object called a | ||
3520 | \c{random_state}. One of these is managed by each mid-end, for | ||
3521 | example, and passed to the back end to generate a game with. | ||
3522 | |||
3523 | \S{utils-random-init} \cw{random_new()} | ||
3524 | |||
3525 | \c random_state *random_new(char *seed, int len); | ||
3526 | |||
3527 | Allocates, initialises and returns a new \c{random_state}. The input | ||
3528 | data is used as the seed for the random number stream (i.e. using | ||
3529 | the same seed at a later time will generate the same stream). | ||
3530 | |||
3531 | The seed data can be any data at all; there is no requirement to use | ||
3532 | printable ASCII, or NUL-terminated strings, or anything like that. | ||
3533 | |||
3534 | \S{utils-random-copy} \cw{random_copy()} | ||
3535 | |||
3536 | \c random_state *random_copy(random_state *tocopy); | ||
3537 | |||
3538 | Allocates a new \c{random_state}, copies the contents of another | ||
3539 | \c{random_state} into it, and returns the new state. If exactly the | ||
3540 | same sequence of functions is subseqently called on both the copy and | ||
3541 | the original, the results will be identical. This may be useful for | ||
3542 | speculatively performing some operation using a given random state, | ||
3543 | and later replaying that operation precisely. | ||
3544 | |||
3545 | \S{utils-random-free} \cw{random_free()} | ||
3546 | |||
3547 | \c void random_free(random_state *state); | ||
3548 | |||
3549 | Frees a \c{random_state}. | ||
3550 | |||
3551 | \S{utils-random-bits} \cw{random_bits()} | ||
3552 | |||
3553 | \c unsigned long random_bits(random_state *state, int bits); | ||
3554 | |||
3555 | Returns a random number from 0 to \cw{2^bits-1} inclusive. \c{bits} | ||
3556 | should be between 1 and 32 inclusive. | ||
3557 | |||
3558 | \S{utils-random-upto} \cw{random_upto()} | ||
3559 | |||
3560 | \c unsigned long random_upto(random_state *state, unsigned long limit); | ||
3561 | |||
3562 | Returns a random number from 0 to \cw{limit-1} inclusive. | ||
3563 | |||
3564 | \S{utils-random-state-encode} \cw{random_state_encode()} | ||
3565 | |||
3566 | \c char *random_state_encode(random_state *state); | ||
3567 | |||
3568 | Encodes the entire contents of a \c{random_state} in printable | ||
3569 | ASCII. Returns a dynamically allocated string containing that | ||
3570 | encoding. This can subsequently be passed to | ||
3571 | \cw{random_state_decode()} to reconstruct the same \c{random_state}. | ||
3572 | |||
3573 | \S{utils-random-state-decode} \cw{random_state_decode()} | ||
3574 | |||
3575 | \c random_state *random_state_decode(char *input); | ||
3576 | |||
3577 | Decodes a string generated by \cw{random_state_encode()} and | ||
3578 | reconstructs an equivalent \c{random_state} to the one encoded, i.e. | ||
3579 | it should produce the same stream of random numbers. | ||
3580 | |||
3581 | This function has no error reporting; if you pass it an invalid | ||
3582 | string it will simply generate an arbitrary random state, which may | ||
3583 | turn out to be noticeably non-random. | ||
3584 | |||
3585 | \S{utils-shuffle} \cw{shuffle()} | ||
3586 | |||
3587 | \c void shuffle(void *array, int nelts, int eltsize, random_state *rs); | ||
3588 | |||
3589 | Shuffles an array into a random order. The interface is much like | ||
3590 | ANSI C \cw{qsort()}, except that there's no need for a compare | ||
3591 | function. | ||
3592 | |||
3593 | \c{array} is a pointer to the first element of the array. \c{nelts} | ||
3594 | is the number of elements in the array; \c{eltsize} is the size of a | ||
3595 | single element (typically measured using \c{sizeof}). \c{rs} is a | ||
3596 | \c{random_state} used to generate all the random numbers for the | ||
3597 | shuffling process. | ||
3598 | |||
3599 | \H{utils-presets} Presets menu management | ||
3600 | |||
3601 | The function \c{midend_get_presets()} (\k{midend-get-presets}) returns | ||
3602 | a data structure describing a menu hierarchy. Back ends can also | ||
3603 | choose to provide such a structure to the mid-end, if they want to | ||
3604 | group their presets hierarchically. To make this easy, there are a few | ||
3605 | utility functions to construct preset menu structures, and also one | ||
3606 | intended for front-end use. | ||
3607 | |||
3608 | \S{utils-preset-menu-new} \cw{preset_menu_new()} | ||
3609 | |||
3610 | \c struct preset_menu *preset_menu_new(void); | ||
3611 | |||
3612 | Allocates a new \c{struct preset_menu}, and initialises it to hold no | ||
3613 | menu items. | ||
3614 | |||
3615 | \S{utils-preset-menu-add_submenu} \cw{preset_menu_add_submenu()} | ||
3616 | |||
3617 | \c struct preset_menu *preset_menu_add_submenu | ||
3618 | \c (struct preset_menu *parent, char *title); | ||
3619 | |||
3620 | Adds a new submenu to the end of an existing preset menu, and returns | ||
3621 | a pointer to a newly allocated \c{struct preset_menu} describing the | ||
3622 | submenu. | ||
3623 | |||
3624 | The string parameter \cq{title} must be dynamically allocated by the | ||
3625 | caller. The preset-menu structure will take ownership of it, so the | ||
3626 | caller must not free it. | ||
3627 | |||
3628 | \S{utils-preset-menu-add-preset} \cw{preset_menu_add_preset()} | ||
3629 | |||
3630 | \c void preset_menu_add_preset | ||
3631 | \c (struct preset_menu *menu, char *title, game_params *params); | ||
3632 | |||
3633 | Adds a preset game configuration to the end of a preset menu. | ||
3634 | |||
3635 | Both the string parameter \cq{title} and the game parameter structure | ||
3636 | \cq{params} itself must be dynamically allocated by the caller. The | ||
3637 | preset-menu structure will take ownership of it, so the caller must | ||
3638 | not free it. | ||
3639 | |||
3640 | \S{utils-preset-menu-lookup-by-id} \cw{preset_menu_lookup_by_id()} | ||
3641 | |||
3642 | \c game_params *preset_menu_lookup_by_id | ||
3643 | \c (struct preset_menu *menu, int id); | ||
3644 | |||
3645 | Given a numeric index, searches recursively through a preset menu | ||
3646 | hierarchy to find the corresponding menu entry, and returns a pointer | ||
3647 | to its existing \c{game_params} structure. | ||
3648 | |||
3649 | This function is intended for front end use (but front ends need not | ||
3650 | use it if they prefer to do things another way). If a front end finds | ||
3651 | it inconvenient to store anything more than a numeric index alongside | ||
3652 | each menu item, then this function provides an easy way for the front | ||
3653 | end to get back the actual game parameters corresponding to a menu | ||
3654 | item that the user has selected. | ||
3655 | |||
3656 | \H{utils-alloc} Memory allocation | ||
3657 | |||
3658 | Puzzles has some central wrappers on the standard memory allocation | ||
3659 | functions, which provide compile-time type checking, and run-time | ||
3660 | error checking by means of quitting the application if it runs out | ||
3661 | of memory. This doesn't provide the best possible recovery from | ||
3662 | memory shortage, but on the other hand it greatly simplifies the | ||
3663 | rest of the code, because nothing else anywhere needs to worry about | ||
3664 | \cw{NULL} returns from allocation. | ||
3665 | |||
3666 | \S{utils-snew} \cw{snew()} | ||
3667 | |||
3668 | \c var = snew(type); | ||
3669 | \e iii iiii | ||
3670 | |||
3671 | This macro takes a single argument which is a \e{type name}. It | ||
3672 | allocates space for one object of that type. If allocation fails it | ||
3673 | will call \cw{fatal()} and not return; so if it does return, you can | ||
3674 | be confident that its return value is non-\cw{NULL}. | ||
3675 | |||
3676 | The return value is cast to the specified type, so that the compiler | ||
3677 | will type-check it against the variable you assign it into. Thus, | ||
3678 | this ensures you don't accidentally allocate memory the size of the | ||
3679 | wrong type and assign it into a variable of the right one (or vice | ||
3680 | versa!). | ||
3681 | |||
3682 | \S{utils-snewn} \cw{snewn()} | ||
3683 | |||
3684 | \c var = snewn(n, type); | ||
3685 | \e iii i iiii | ||
3686 | |||
3687 | This macro is the array form of \cw{snew()}. It takes two arguments; | ||
3688 | the first is a number, and the second is a type name. It allocates | ||
3689 | space for that many objects of that type, and returns a type-checked | ||
3690 | non-\cw{NULL} pointer just as \cw{snew()} does. | ||
3691 | |||
3692 | \S{utils-sresize} \cw{sresize()} | ||
3693 | |||
3694 | \c var = sresize(var, n, type); | ||
3695 | \e iii iii i iiii | ||
3696 | |||
3697 | This macro is a type-checked form of \cw{realloc()}. It takes three | ||
3698 | arguments: an input memory block, a new size in elements, and a | ||
3699 | type. It re-sizes the input memory block to a size sufficient to | ||
3700 | contain that many elements of that type. It returns a type-checked | ||
3701 | non-\cw{NULL} pointer, like \cw{snew()} and \cw{snewn()}. | ||
3702 | |||
3703 | The input memory block can be \cw{NULL}, in which case this function | ||
3704 | will behave exactly like \cw{snewn()}. (In principle any | ||
3705 | ANSI-compliant \cw{realloc()} implementation ought to cope with | ||
3706 | this, but I've never quite trusted it to work everywhere.) | ||
3707 | |||
3708 | \S{utils-sfree} \cw{sfree()} | ||
3709 | |||
3710 | \c void sfree(void *p); | ||
3711 | |||
3712 | This function is pretty much equivalent to \cw{free()}. It is | ||
3713 | provided with a dynamically allocated block, and frees it. | ||
3714 | |||
3715 | The input memory block can be \cw{NULL}, in which case this function | ||
3716 | will do nothing. (In principle any ANSI-compliant \cw{free()} | ||
3717 | implementation ought to cope with this, but I've never quite trusted | ||
3718 | it to work everywhere.) | ||
3719 | |||
3720 | \S{utils-dupstr} \cw{dupstr()} | ||
3721 | |||
3722 | \c char *dupstr(const char *s); | ||
3723 | |||
3724 | This function dynamically allocates a duplicate of a C string. Like | ||
3725 | the \cw{snew()} functions, it guarantees to return non-\cw{NULL} or | ||
3726 | not return at all. | ||
3727 | |||
3728 | (Many platforms provide the function \cw{strdup()}. As well as | ||
3729 | guaranteeing never to return \cw{NULL}, my version has the advantage | ||
3730 | of being defined \e{everywhere}, rather than inconveniently not | ||
3731 | quite everywhere.) | ||
3732 | |||
3733 | \S{utils-free-cfg} \cw{free_cfg()} | ||
3734 | |||
3735 | \c void free_cfg(config_item *cfg); | ||
3736 | |||
3737 | This function correctly frees an array of \c{config_item}s, | ||
3738 | including walking the array until it gets to the end and freeing | ||
3739 | precisely those \c{sval} fields which are expected to be dynamically | ||
3740 | allocated. | ||
3741 | |||
3742 | (See \k{backend-configure} for details of the \c{config_item} | ||
3743 | structure.) | ||
3744 | |||
3745 | \H{utils-tree234} Sorted and counted tree functions | ||
3746 | |||
3747 | Many games require complex algorithms for generating random puzzles, | ||
3748 | and some require moderately complex algorithms even during play. A | ||
3749 | common requirement during these algorithms is for a means of | ||
3750 | maintaining sorted or unsorted lists of items, such that items can | ||
3751 | be removed and added conveniently. | ||
3752 | |||
3753 | For general use, Puzzles provides the following set of functions | ||
3754 | which maintain 2-3-4 trees in memory. (A 2-3-4 tree is a balanced | ||
3755 | tree structure, with the property that all lookups, insertions, | ||
3756 | deletions, splits and joins can be done in \cw{O(log N)} time.) | ||
3757 | |||
3758 | All these functions expect you to be storing a tree of \c{void *} | ||
3759 | pointers. You can put anything you like in those pointers. | ||
3760 | |||
3761 | By the use of per-node element counts, these tree structures have | ||
3762 | the slightly unusual ability to look elements up by their numeric | ||
3763 | index within the list represented by the tree. This means that they | ||
3764 | can be used to store an unsorted list (in which case, every time you | ||
3765 | insert a new element, you must explicitly specify the position where | ||
3766 | you wish to insert it). They can also do numeric lookups in a sorted | ||
3767 | tree, which might be useful for (for example) tracking the median of | ||
3768 | a changing data set. | ||
3769 | |||
3770 | As well as storing sorted lists, these functions can be used for | ||
3771 | storing \q{maps} (associative arrays), by defining each element of a | ||
3772 | tree to be a (key, value) pair. | ||
3773 | |||
3774 | \S{utils-newtree234} \cw{newtree234()} | ||
3775 | |||
3776 | \c tree234 *newtree234(cmpfn234 cmp); | ||
3777 | |||
3778 | Creates a new empty tree, and returns a pointer to it. | ||
3779 | |||
3780 | The parameter \c{cmp} determines the sorting criterion on the tree. | ||
3781 | Its prototype is | ||
3782 | |||
3783 | \c typedef int (*cmpfn234)(void *, void *); | ||
3784 | |||
3785 | If you want a sorted tree, you should provide a function matching | ||
3786 | this prototype, which returns like \cw{strcmp()} does (negative if | ||
3787 | the first argument is smaller than the second, positive if it is | ||
3788 | bigger, zero if they compare equal). In this case, the function | ||
3789 | \cw{addpos234()} will not be usable on your tree (because all | ||
3790 | insertions must respect the sorting order). | ||
3791 | |||
3792 | If you want an unsorted tree, pass \cw{NULL}. In this case you will | ||
3793 | not be able to use either \cw{add234()} or \cw{del234()}, or any | ||
3794 | other function such as \cw{find234()} which depends on a sorting | ||
3795 | order. Your tree will become something more like an array, except | ||
3796 | that it will efficiently support insertion and deletion as well as | ||
3797 | lookups by numeric index. | ||
3798 | |||
3799 | \S{utils-freetree234} \cw{freetree234()} | ||
3800 | |||
3801 | \c void freetree234(tree234 *t); | ||
3802 | |||
3803 | Frees a tree. This function will not free the \e{elements} of the | ||
3804 | tree (because they might not be dynamically allocated, or you might | ||
3805 | be storing the same set of elements in more than one tree); it will | ||
3806 | just free the tree structure itself. If you want to free all the | ||
3807 | elements of a tree, you should empty it before passing it to | ||
3808 | \cw{freetree234()}, by means of code along the lines of | ||
3809 | |||
3810 | \c while ((element = delpos234(tree, 0)) != NULL) | ||
3811 | \c sfree(element); /* or some more complicated free function */ | ||
3812 | \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii | ||
3813 | |||
3814 | \S{utils-add234} \cw{add234()} | ||
3815 | |||
3816 | \c void *add234(tree234 *t, void *e); | ||
3817 | |||
3818 | Inserts a new element \c{e} into the tree \c{t}. This function | ||
3819 | expects the tree to be sorted; the new element is inserted according | ||
3820 | to the sort order. | ||
3821 | |||
3822 | If an element comparing equal to \c{e} is already in the tree, then | ||
3823 | the insertion will fail, and the return value will be the existing | ||
3824 | element. Otherwise, the insertion succeeds, and \c{e} is returned. | ||
3825 | |||
3826 | \S{utils-addpos234} \cw{addpos234()} | ||
3827 | |||
3828 | \c void *addpos234(tree234 *t, void *e, int index); | ||
3829 | |||
3830 | Inserts a new element into an unsorted tree. Since there is no | ||
3831 | sorting order to dictate where the new element goes, you must | ||
3832 | specify where you want it to go. Setting \c{index} to zero puts the | ||
3833 | new element right at the start of the list; setting \c{index} to the | ||
3834 | current number of elements in the tree puts the new element at the | ||
3835 | end. | ||
3836 | |||
3837 | Return value is \c{e}, in line with \cw{add234()} (although this | ||
3838 | function cannot fail except by running out of memory, in which case | ||
3839 | it will bomb out and die rather than returning an error indication). | ||
3840 | |||
3841 | \S{utils-index234} \cw{index234()} | ||
3842 | |||
3843 | \c void *index234(tree234 *t, int index); | ||
3844 | |||
3845 | Returns a pointer to the \c{index}th element of the tree, or | ||
3846 | \cw{NULL} if \c{index} is out of range. Elements of the tree are | ||
3847 | numbered from zero. | ||
3848 | |||
3849 | \S{utils-find234} \cw{find234()} | ||
3850 | |||
3851 | \c void *find234(tree234 *t, void *e, cmpfn234 cmp); | ||
3852 | |||
3853 | Searches for an element comparing equal to \c{e} in a sorted tree. | ||
3854 | |||
3855 | If \c{cmp} is \cw{NULL}, the tree's ordinary comparison function | ||
3856 | will be used to perform the search. However, sometimes you don't | ||
3857 | want that; suppose, for example, each of your elements is a big | ||
3858 | structure containing a \c{char *} name field, and you want to find | ||
3859 | the element with a given name. You \e{could} achieve this by | ||
3860 | constructing a fake element structure, setting its name field | ||
3861 | appropriately, and passing it to \cw{find234()}, but you might find | ||
3862 | it more convenient to pass \e{just} a name string to \cw{find234()}, | ||
3863 | supplying an alternative comparison function which expects one of | ||
3864 | its arguments to be a bare name and the other to be a large | ||
3865 | structure containing a name field. | ||
3866 | |||
3867 | Therefore, if \c{cmp} is not \cw{NULL}, then it will be used to | ||
3868 | compare \c{e} to elements of the tree. The first argument passed to | ||
3869 | \c{cmp} will always be \c{e}; the second will be an element of the | ||
3870 | tree. | ||
3871 | |||
3872 | (See \k{utils-newtree234} for the definition of the \c{cmpfn234} | ||
3873 | function pointer type.) | ||
3874 | |||
3875 | The returned value is the element found, or \cw{NULL} if the search | ||
3876 | is unsuccessful. | ||
3877 | |||
3878 | \S{utils-findrel234} \cw{findrel234()} | ||
3879 | |||
3880 | \c void *findrel234(tree234 *t, void *e, cmpfn234 cmp, int relation); | ||
3881 | |||
3882 | This function is like \cw{find234()}, but has the additional ability | ||
3883 | to do a \e{relative} search. The additional parameter \c{relation} | ||
3884 | can be one of the following values: | ||
3885 | |||
3886 | \dt \cw{REL234_EQ} | ||
3887 | |||
3888 | \dd Find only an element that compares equal to \c{e}. This is | ||
3889 | exactly the behaviour of \cw{find234()}. | ||
3890 | |||
3891 | \dt \cw{REL234_LT} | ||
3892 | |||
3893 | \dd Find the greatest element that compares strictly less than | ||
3894 | \c{e}. \c{e} may be \cw{NULL}, in which case it finds the greatest | ||
3895 | element in the whole tree (which could also be done by | ||
3896 | \cw{index234(t, count234(t)-1)}). | ||
3897 | |||
3898 | \dt \cw{REL234_LE} | ||
3899 | |||
3900 | \dd Find the greatest element that compares less than or equal to | ||
3901 | \c{e}. (That is, find an element that compares equal to \c{e} if | ||
3902 | possible, but failing that settle for something just less than it.) | ||
3903 | |||
3904 | \dt \cw{REL234_GT} | ||
3905 | |||
3906 | \dd Find the smallest element that compares strictly greater than | ||
3907 | \c{e}. \c{e} may be \cw{NULL}, in which case it finds the smallest | ||
3908 | element in the whole tree (which could also be done by | ||
3909 | \cw{index234(t, 0)}). | ||
3910 | |||
3911 | \dt \cw{REL234_GE} | ||
3912 | |||
3913 | \dd Find the smallest element that compares greater than or equal to | ||
3914 | \c{e}. (That is, find an element that compares equal to \c{e} if | ||
3915 | possible, but failing that settle for something just bigger than | ||
3916 | it.) | ||
3917 | |||
3918 | Return value, as before, is the element found or \cw{NULL} if no | ||
3919 | element satisfied the search criterion. | ||
3920 | |||
3921 | \S{utils-findpos234} \cw{findpos234()} | ||
3922 | |||
3923 | \c void *findpos234(tree234 *t, void *e, cmpfn234 cmp, int *index); | ||
3924 | |||
3925 | This function is like \cw{find234()}, but has the additional feature | ||
3926 | of returning the index of the element found in the tree; that index | ||
3927 | is written to \c{*index} in the event of a successful search (a | ||
3928 | non-\cw{NULL} return value). | ||
3929 | |||
3930 | \c{index} may be \cw{NULL}, in which case this function behaves | ||
3931 | exactly like \cw{find234()}. | ||
3932 | |||
3933 | \S{utils-findrelpos234} \cw{findrelpos234()} | ||
3934 | |||
3935 | \c void *findrelpos234(tree234 *t, void *e, cmpfn234 cmp, int relation, | ||
3936 | \c int *index); | ||
3937 | |||
3938 | This function combines all the features of \cw{findrel234()} and | ||
3939 | \cw{findpos234()}. | ||
3940 | |||
3941 | \S{utils-del234} \cw{del234()} | ||
3942 | |||
3943 | \c void *del234(tree234 *t, void *e); | ||
3944 | |||
3945 | Finds an element comparing equal to \c{e} in the tree, deletes it, | ||
3946 | and returns it. | ||
3947 | |||
3948 | The input tree must be sorted. | ||
3949 | |||
3950 | The element found might be \c{e} itself, or might merely compare | ||
3951 | equal to it. | ||
3952 | |||
3953 | Return value is \cw{NULL} if no such element is found. | ||
3954 | |||
3955 | \S{utils-delpos234} \cw{delpos234()} | ||
3956 | |||
3957 | \c void *delpos234(tree234 *t, int index); | ||
3958 | |||
3959 | Deletes the element at position \c{index} in the tree, and returns | ||
3960 | it. | ||
3961 | |||
3962 | Return value is \cw{NULL} if the index is out of range. | ||
3963 | |||
3964 | \S{utils-count234} \cw{count234()} | ||
3965 | |||
3966 | \c int count234(tree234 *t); | ||
3967 | |||
3968 | Returns the number of elements currently in the tree. | ||
3969 | |||
3970 | \S{utils-splitpos234} \cw{splitpos234()} | ||
3971 | |||
3972 | \c tree234 *splitpos234(tree234 *t, int index, int before); | ||
3973 | |||
3974 | Splits the input tree into two pieces at a given position, and | ||
3975 | creates a new tree containing all the elements on one side of that | ||
3976 | position. | ||
3977 | |||
3978 | If \c{before} is \cw{TRUE}, then all the items at or after position | ||
3979 | \c{index} are left in the input tree, and the items before that | ||
3980 | point are returned in the new tree. Otherwise, the reverse happens: | ||
3981 | all the items at or after \c{index} are moved into the new tree, and | ||
3982 | those before that point are left in the old one. | ||
3983 | |||
3984 | If \c{index} is equal to 0 or to the number of elements in the input | ||
3985 | tree, then one of the two trees will end up empty (and this is not | ||
3986 | an error condition). If \c{index} is further out of range in either | ||
3987 | direction, the operation will fail completely and return \cw{NULL}. | ||
3988 | |||
3989 | This operation completes in \cw{O(log N)} time, no matter how large | ||
3990 | the tree or how balanced or unbalanced the split. | ||
3991 | |||
3992 | \S{utils-split234} \cw{split234()} | ||
3993 | |||
3994 | \c tree234 *split234(tree234 *t, void *e, cmpfn234 cmp, int rel); | ||
3995 | |||
3996 | Splits a sorted tree according to its sort order. | ||
3997 | |||
3998 | \c{rel} can be any of the relation constants described in | ||
3999 | \k{utils-findrel234}, \e{except} for \cw{REL234_EQ}. All the | ||
4000 | elements having that relation to \c{e} will be transferred into the | ||
4001 | new tree; the rest will be left in the old one. | ||
4002 | |||
4003 | The parameter \c{cmp} has the same semantics as it does in | ||
4004 | \cw{find234()}: if it is not \cw{NULL}, it will be used in place of | ||
4005 | the tree's own comparison function when comparing elements to \c{e}, | ||
4006 | in such a way that \c{e} itself is always the first of its two | ||
4007 | operands. | ||
4008 | |||
4009 | Again, this operation completes in \cw{O(log N)} time, no matter how | ||
4010 | large the tree or how balanced or unbalanced the split. | ||
4011 | |||
4012 | \S{utils-join234} \cw{join234()} | ||
4013 | |||
4014 | \c tree234 *join234(tree234 *t1, tree234 *t2); | ||
4015 | |||
4016 | Joins two trees together by concatenating the lists they represent. | ||
4017 | All the elements of \c{t2} are moved into \c{t1}, in such a way that | ||
4018 | they appear \e{after} the elements of \c{t1}. The tree \c{t2} is | ||
4019 | freed; the return value is \c{t1}. | ||
4020 | |||
4021 | If you apply this function to a sorted tree and it violates the sort | ||
4022 | order (i.e. the smallest element in \c{t2} is smaller than or equal | ||
4023 | to the largest element in \c{t1}), the operation will fail and | ||
4024 | return \cw{NULL}. | ||
4025 | |||
4026 | This operation completes in \cw{O(log N)} time, no matter how large | ||
4027 | the trees being joined together. | ||
4028 | |||
4029 | \S{utils-join234r} \cw{join234r()} | ||
4030 | |||
4031 | \c tree234 *join234r(tree234 *t1, tree234 *t2); | ||
4032 | |||
4033 | Joins two trees together in exactly the same way as \cw{join234()}, | ||
4034 | but this time the combined tree is returned in \c{t2}, and \c{t1} is | ||
4035 | destroyed. The elements in \c{t1} still appear before those in | ||
4036 | \c{t2}. | ||
4037 | |||
4038 | Again, this operation completes in \cw{O(log N)} time, no matter how | ||
4039 | large the trees being joined together. | ||
4040 | |||
4041 | \S{utils-copytree234} \cw{copytree234()} | ||
4042 | |||
4043 | \c tree234 *copytree234(tree234 *t, copyfn234 copyfn, | ||
4044 | \c void *copyfnstate); | ||
4045 | |||
4046 | Makes a copy of an entire tree. | ||
4047 | |||
4048 | If \c{copyfn} is \cw{NULL}, the tree will be copied but the elements | ||
4049 | will not be; i.e. the new tree will contain pointers to exactly the | ||
4050 | same physical elements as the old one. | ||
4051 | |||
4052 | If you want to copy each actual element during the operation, you | ||
4053 | can instead pass a function in \c{copyfn} which makes a copy of each | ||
4054 | element. That function has the prototype | ||
4055 | |||
4056 | \c typedef void *(*copyfn234)(void *state, void *element); | ||
4057 | |||
4058 | and every time it is called, the \c{state} parameter will be set to | ||
4059 | the value you passed in as \c{copyfnstate}. | ||
4060 | |||
4061 | \H{utils-misc} Miscellaneous utility functions and macros | ||
4062 | |||
4063 | This section contains all the utility functions which didn't | ||
4064 | sensibly fit anywhere else. | ||
4065 | |||
4066 | \S{utils-truefalse} \cw{TRUE} and \cw{FALSE} | ||
4067 | |||
4068 | The main Puzzles header file defines the macros \cw{TRUE} and | ||
4069 | \cw{FALSE}, which are used throughout the code in place of 1 and 0 | ||
4070 | (respectively) to indicate that the values are in a boolean context. | ||
4071 | For code base consistency, I'd prefer it if submissions of new code | ||
4072 | followed this convention as well. | ||
4073 | |||
4074 | \S{utils-maxmin} \cw{max()} and \cw{min()} | ||
4075 | |||
4076 | The main Puzzles header file defines the pretty standard macros | ||
4077 | \cw{max()} and \cw{min()}, each of which is given two arguments and | ||
4078 | returns the one which compares greater or less respectively. | ||
4079 | |||
4080 | These macros may evaluate their arguments multiple times. Avoid side | ||
4081 | effects. | ||
4082 | |||
4083 | \S{utils-pi} \cw{PI} | ||
4084 | |||
4085 | The main Puzzles header file defines a macro \cw{PI} which expands | ||
4086 | to a floating-point constant representing pi. | ||
4087 | |||
4088 | (I've never understood why ANSI's \cw{<math.h>} doesn't define this. | ||
4089 | It'd be so useful!) | ||
4090 | |||
4091 | \S{utils-obfuscate-bitmap} \cw{obfuscate_bitmap()} | ||
4092 | |||
4093 | \c void obfuscate_bitmap(unsigned char *bmp, int bits, int decode); | ||
4094 | |||
4095 | This function obscures the contents of a piece of data, by | ||
4096 | cryptographic methods. It is useful for games of hidden information | ||
4097 | (such as Mines, Guess or Black Box), in which the game ID | ||
4098 | theoretically reveals all the information the player is supposed to | ||
4099 | be trying to guess. So in order that players should be able to send | ||
4100 | game IDs to one another without accidentally spoiling the resulting | ||
4101 | game by looking at them, these games obfuscate their game IDs using | ||
4102 | this function. | ||
4103 | |||
4104 | Although the obfuscation function is cryptographic, it cannot | ||
4105 | properly be called encryption because it has no key. Therefore, | ||
4106 | anybody motivated enough can re-implement it, or hack it out of the | ||
4107 | Puzzles source, and strip the obfuscation off one of these game IDs | ||
4108 | to see what lies beneath. (Indeed, they could usually do it much | ||
4109 | more easily than that, by entering the game ID into their own copy | ||
4110 | of the puzzle and hitting Solve.) The aim is not to protect against | ||
4111 | a determined attacker; the aim is simply to protect people who | ||
4112 | wanted to play the game honestly from \e{accidentally} spoiling | ||
4113 | their own fun. | ||
4114 | |||
4115 | The input argument \c{bmp} points at a piece of memory to be | ||
4116 | obfuscated. \c{bits} gives the length of the data. Note that that | ||
4117 | length is in \e{bits} rather than bytes: if you ask for obfuscation | ||
4118 | of a partial number of bytes, then you will get it. Bytes are | ||
4119 | considered to be used from the top down: thus, for example, setting | ||
4120 | \c{bits} to 10 will cover the whole of \cw{bmp[0]} and the \e{top | ||
4121 | two} bits of \cw{bmp[1]}. The remainder of a partially used byte is | ||
4122 | undefined (i.e. it may be corrupted by the function). | ||
4123 | |||
4124 | The parameter \c{decode} is \cw{FALSE} for an encoding operation, | ||
4125 | and \cw{TRUE} for a decoding operation. Each is the inverse of the | ||
4126 | other. (There's no particular reason you shouldn't obfuscate by | ||
4127 | decoding and restore cleartext by encoding, if you really wanted to; | ||
4128 | it should still work.) | ||
4129 | |||
4130 | The input bitmap is processed in place. | ||
4131 | |||
4132 | \S{utils-bin2hex} \cw{bin2hex()} | ||
4133 | |||
4134 | \c char *bin2hex(const unsigned char *in, int inlen); | ||
4135 | |||
4136 | This function takes an input byte array and converts it into an | ||
4137 | ASCII string encoding those bytes in (lower-case) hex. It returns a | ||
4138 | dynamically allocated string containing that encoding. | ||
4139 | |||
4140 | This function is useful for encoding the result of | ||
4141 | \cw{obfuscate_bitmap()} in printable ASCII for use in game IDs. | ||
4142 | |||
4143 | \S{utils-hex2bin} \cw{hex2bin()} | ||
4144 | |||
4145 | \c unsigned char *hex2bin(const char *in, int outlen); | ||
4146 | |||
4147 | This function takes an ASCII string containing hex digits, and | ||
4148 | converts it back into a byte array of length \c{outlen}. If there | ||
4149 | aren't enough hex digits in the string, the contents of the | ||
4150 | resulting array will be undefined. | ||
4151 | |||
4152 | This function is the inverse of \cw{bin2hex()}. | ||
4153 | |||
4154 | \S{utils-game-mkhighlight} \cw{game_mkhighlight()} | ||
4155 | |||
4156 | \c void game_mkhighlight(frontend *fe, float *ret, | ||
4157 | \c int background, int highlight, int lowlight); | ||
4158 | |||
4159 | It's reasonably common for a puzzle game's graphics to use | ||
4160 | highlights and lowlights to indicate \q{raised} or \q{lowered} | ||
4161 | sections. Fifteen, Sixteen and Twiddle are good examples of this. | ||
4162 | |||
4163 | Puzzles using this graphical style are running a risk if they just | ||
4164 | use whatever background colour is supplied to them by the front end, | ||
4165 | because that background colour might be too light to see any | ||
4166 | highlights on at all. (In particular, it's not unheard of for the | ||
4167 | front end to specify a default background colour of white.) | ||
4168 | |||
4169 | Therefore, such puzzles can call this utility function from their | ||
4170 | \cw{colours()} routine (\k{backend-colours}). You pass it your front | ||
4171 | end handle, a pointer to the start of your return array, and three | ||
4172 | colour indices. It will: | ||
4173 | |||
4174 | \b call \cw{frontend_default_colour()} (\k{frontend-default-colour}) | ||
4175 | to fetch the front end's default background colour | ||
4176 | |||
4177 | \b alter the brightness of that colour if it's unsuitable | ||
4178 | |||
4179 | \b define brighter and darker variants of the colour to be used as | ||
4180 | highlights and lowlights | ||
4181 | |||
4182 | \b write those results into the relevant positions in the \c{ret} | ||
4183 | array. | ||
4184 | |||
4185 | Thus, \cw{ret[background*3]} to \cw{ret[background*3+2]} will be set | ||
4186 | to RGB values defining a sensible background colour, and similary | ||
4187 | \c{highlight} and \c{lowlight} will be set to sensible colours. | ||
4188 | |||
4189 | \C{writing} How to write a new puzzle | ||
4190 | |||
4191 | This chapter gives a guide to how to actually write a new puzzle: | ||
4192 | where to start, what to do first, how to solve common problems. | ||
4193 | |||
4194 | The previous chapters have been largely composed of facts. This one | ||
4195 | is mostly advice. | ||
4196 | |||
4197 | \H{writing-editorial} Choosing a puzzle | ||
4198 | |||
4199 | Before you start writing a puzzle, you have to choose one. Your | ||
4200 | taste in puzzle games is up to you, of course; and, in fact, you're | ||
4201 | probably reading this guide because you've \e{already} thought of a | ||
4202 | game you want to write. But if you want to get it accepted into the | ||
4203 | official Puzzles distribution, then there's a criterion it has to | ||
4204 | meet. | ||
4205 | |||
4206 | The current Puzzles editorial policy is that all games should be | ||
4207 | \e{fair}. A fair game is one which a player can only fail to | ||
4208 | complete through demonstrable lack of skill \dash that is, such that | ||
4209 | a better player in the same situation would have \e{known} to do | ||
4210 | something different. | ||
4211 | |||
4212 | For a start, that means every game presented to the user must have | ||
4213 | \e{at least one solution}. Giving the unsuspecting user a puzzle | ||
4214 | which is actually impossible is not acceptable. (There is an | ||
4215 | exception: if the user has selected some non-default option which is | ||
4216 | clearly labelled as potentially unfair, \e{then} you're allowed to | ||
4217 | generate possibly insoluble puzzles, because the user isn't | ||
4218 | unsuspecting any more. Same Game and Mines both have options of this | ||
4219 | type.) | ||
4220 | |||
4221 | Also, this actually \e{rules out} games such as Klondike, or the | ||
4222 | normal form of Mahjong Solitaire. Those games have the property that | ||
4223 | even if there is a solution (i.e. some sequence of moves which will | ||
4224 | get from the start state to the solved state), the player doesn't | ||
4225 | necessarily have enough information to \e{find} that solution. In | ||
4226 | both games, it is possible to reach a dead end because you had an | ||
4227 | arbitrary choice to make and made it the wrong way. This violates | ||
4228 | the fairness criterion, because a better player couldn't have known | ||
4229 | they needed to make the other choice. | ||
4230 | |||
4231 | (GNOME has a variant on Mahjong Solitaire which makes it fair: there | ||
4232 | is a Shuffle operation which randomly permutes all the remaining | ||
4233 | tiles without changing their positions, which allows you to get out | ||
4234 | of a sticky situation. Using this operation adds a 60-second penalty | ||
4235 | to your solution time, so it's to the player's advantage to try to | ||
4236 | minimise the chance of having to use it. It's still possible to | ||
4237 | render the game uncompletable if you end up with only two tiles | ||
4238 | vertically stacked, but that's easy to foresee and avoid using a | ||
4239 | shuffle operation. This form of the game \e{is} fair. Implementing | ||
4240 | it in Puzzles would require an infrastructure change so that the | ||
4241 | back end could communicate time penalties to the mid-end, but that | ||
4242 | would be easy enough.) | ||
4243 | |||
4244 | Providing a \e{unique} solution is a little more negotiable; it | ||
4245 | depends on the puzzle. Solo would have been of unacceptably low | ||
4246 | quality if it didn't always have a unique solution, whereas Twiddle | ||
4247 | inherently has multiple solutions by its very nature and it would | ||
4248 | have been meaningless to even \e{suggest} making it uniquely | ||
4249 | soluble. Somewhere in between, Flip could reasonably be made to have | ||
4250 | unique solutions (by enforcing a zero-dimension kernel in every | ||
4251 | generated matrix) but it doesn't seem like a serious quality problem | ||
4252 | that it doesn't. | ||
4253 | |||
4254 | Of course, you don't \e{have} to care about all this. There's | ||
4255 | nothing stopping you implementing any puzzle you want to if you're | ||
4256 | happy to maintain your puzzle yourself, distribute it from your own | ||
4257 | web site, fork the Puzzles code completely, or anything like that. | ||
4258 | It's free software; you can do what you like with it. But any game | ||
4259 | that you want to be accepted into \e{my} Puzzles code base has to | ||
4260 | satisfy the fairness criterion, which means all randomly generated | ||
4261 | puzzles must have a solution (unless the user has deliberately | ||
4262 | chosen otherwise) and it must be possible \e{in theory} to find that | ||
4263 | solution without having to guess. | ||
4264 | |||
4265 | \H{writing-gs} Getting started | ||
4266 | |||
4267 | The simplest way to start writing a new puzzle is to copy | ||
4268 | \c{nullgame.c}. This is a template puzzle source file which does | ||
4269 | almost nothing, but which contains all the back end function | ||
4270 | prototypes and declares the back end data structure correctly. It is | ||
4271 | built every time the rest of Puzzles is built, to ensure that it | ||
4272 | doesn't get out of sync with the code and remains buildable. | ||
4273 | |||
4274 | So start by copying \c{nullgame.c} into your new source file. Then | ||
4275 | you'll gradually add functionality until the very boring Null Game | ||
4276 | turns into your real game. | ||
4277 | |||
4278 | Next you'll need to add your puzzle to the Makefiles, in order to | ||
4279 | compile it conveniently. \e{Do not edit the Makefiles}: they are | ||
4280 | created automatically by the script \c{mkfiles.pl}, from the file | ||
4281 | called \c{Recipe}. Edit \c{Recipe}, and then re-run \c{mkfiles.pl}. | ||
4282 | |||
4283 | Also, don't forget to add your puzzle to \c{list.c}: if you don't, | ||
4284 | then it will still run fine on platforms which build each puzzle | ||
4285 | separately, but Mac OS X and other monolithic platforms will not | ||
4286 | include your new puzzle in their single binary. | ||
4287 | |||
4288 | Once your source file is building, you can move on to the fun bit. | ||
4289 | |||
4290 | \S{writing-generation} Puzzle generation | ||
4291 | |||
4292 | Randomly generating instances of your puzzle is almost certain to be | ||
4293 | the most difficult part of the code, and also the task with the | ||
4294 | highest chance of turning out to be completely infeasible. Therefore | ||
4295 | I strongly recommend doing it \e{first}, so that if it all goes | ||
4296 | horribly wrong you haven't wasted any more time than you absolutely | ||
4297 | had to. What I usually do is to take an unmodified \c{nullgame.c}, | ||
4298 | and start adding code to \cw{new_game_desc()} which tries to | ||
4299 | generate a puzzle instance and print it out using \cw{printf()}. | ||
4300 | Once that's working, \e{then} I start connecting it up to the return | ||
4301 | value of \cw{new_game_desc()}, populating other structures like | ||
4302 | \c{game_params}, and generally writing the rest of the source file. | ||
4303 | |||
4304 | There are many ways to generate a puzzle which is known to be | ||
4305 | soluble. In this section I list all the methods I currently know of, | ||
4306 | in case any of them can be applied to your puzzle. (Not all of these | ||
4307 | methods will work, or in some cases even make sense, for all | ||
4308 | puzzles.) | ||
4309 | |||
4310 | Some puzzles are mathematically tractable, meaning you can work out | ||
4311 | in advance which instances are soluble. Sixteen, for example, has a | ||
4312 | parity constraint in some settings which renders exactly half the | ||
4313 | game space unreachable, but it can be mathematically proved that any | ||
4314 | position not in that half \e{is} reachable. Therefore, Sixteen's | ||
4315 | grid generation simply consists of selecting at random from a well | ||
4316 | defined subset of the game space. Cube in its default state is even | ||
4317 | easier: \e{every} possible arrangement of the blue squares and the | ||
4318 | cube's starting position is soluble! | ||
4319 | |||
4320 | Another option is to redefine what you mean by \q{soluble}. Black | ||
4321 | Box takes this approach. There are layouts of balls in the box which | ||
4322 | are completely indistinguishable from one another no matter how many | ||
4323 | beams you fire into the box from which angles, which would normally | ||
4324 | be grounds for declaring those layouts unfair; but fortunately, | ||
4325 | detecting that indistinguishability is computationally easy. So | ||
4326 | Black Box doesn't demand that your ball placements match its own; it | ||
4327 | merely demands that your ball placements be \e{indistinguishable} | ||
4328 | from the ones it was thinking of. If you have an ambiguous puzzle, | ||
4329 | then any of the possible answers is considered to be a solution. | ||
4330 | Having redefined the rules in that way, any puzzle is soluble again. | ||
4331 | |||
4332 | Those are the simple techniques. If they don't work, you have to get | ||
4333 | cleverer. | ||
4334 | |||
4335 | One way to generate a soluble puzzle is to start from the solved | ||
4336 | state and make inverse moves until you reach a starting state. Then | ||
4337 | you know there's a solution, because you can just list the inverse | ||
4338 | moves you made and make them in the opposite order to return to the | ||
4339 | solved state. | ||
4340 | |||
4341 | This method can be simple and effective for puzzles where you get to | ||
4342 | decide what's a starting state and what's not. In Pegs, for example, | ||
4343 | the generator begins with one peg in the centre of the board and | ||
4344 | makes inverse moves until it gets bored; in this puzzle, valid | ||
4345 | inverse moves are easy to detect, and \e{any} state that's reachable | ||
4346 | from the solved state by inverse moves is a reasonable starting | ||
4347 | position. So Pegs just continues making inverse moves until the | ||
4348 | board satisfies some criteria about extent and density, and then | ||
4349 | stops and declares itself done. | ||
4350 | |||
4351 | For other puzzles, it can be a lot more difficult. Same Game uses | ||
4352 | this strategy too, and it's lucky to get away with it at all: valid | ||
4353 | inverse moves aren't easy to find (because although it's easy to | ||
4354 | insert additional squares in a Same Game position, it's difficult to | ||
4355 | arrange that \e{after} the insertion they aren't adjacent to any | ||
4356 | other squares of the same colour), so you're constantly at risk of | ||
4357 | running out of options and having to backtrack or start again. Also, | ||
4358 | Same Game grids never start off half-empty, which means you can't | ||
4359 | just stop when you run out of moves \dash you have to find a way to | ||
4360 | fill the grid up \e{completely}. | ||
4361 | |||
4362 | The other way to generate a puzzle that's soluble is to start from | ||
4363 | the other end, and actually write a \e{solver}. This tends to ensure | ||
4364 | that a puzzle has a \e{unique} solution over and above having a | ||
4365 | solution at all, so it's a good technique to apply to puzzles for | ||
4366 | which that's important. | ||
4367 | |||
4368 | One theoretical drawback of generating soluble puzzles by using a | ||
4369 | solver is that your puzzles are restricted in difficulty to those | ||
4370 | which the solver can handle. (Most solvers are not fully general: | ||
4371 | many sets of puzzle rules are NP-complete or otherwise nasty, so | ||
4372 | most solvers can only handle a subset of the theoretically soluble | ||
4373 | puzzles.) It's been my experience in practice, however, that this | ||
4374 | usually isn't a problem; computers are good at very different things | ||
4375 | from humans, and what the computer thinks is nice and easy might | ||
4376 | still be pleasantly challenging for a human. For example, when | ||
4377 | solving Dominosa puzzles I frequently find myself using a variety of | ||
4378 | reasoning techniques that my solver doesn't know about; in | ||
4379 | principle, therefore, I should be able to solve the puzzle using | ||
4380 | only those techniques it \e{does} know about, but this would involve | ||
4381 | repeatedly searching the entire grid for the one simple deduction I | ||
4382 | can make. Computers are good at this sort of exhaustive search, but | ||
4383 | it's been my experience that human solvers prefer to do more complex | ||
4384 | deductions than to spend ages searching for simple ones. So in many | ||
4385 | cases I don't find my own playing experience to be limited by the | ||
4386 | restrictions on the solver. | ||
4387 | |||
4388 | (This isn't \e{always} the case. Solo is a counter-example; | ||
4389 | generating Solo puzzles using a simple solver does lead to | ||
4390 | qualitatively easier puzzles. Therefore I had to make the Solo | ||
4391 | solver rather more advanced than most of them.) | ||
4392 | |||
4393 | There are several different ways to apply a solver to the problem of | ||
4394 | generating a soluble puzzle. I list a few of them below. | ||
4395 | |||
4396 | The simplest approach is brute force: randomly generate a puzzle, | ||
4397 | use the solver to see if it's soluble, and if not, throw it away and | ||
4398 | try again until you get lucky. This is often a viable technique if | ||
4399 | all else fails, but it tends not to scale well: for many puzzle | ||
4400 | types, the probability of finding a uniquely soluble instance | ||
4401 | decreases sharply as puzzle size goes up, so this technique might | ||
4402 | work reasonably fast for small puzzles but take (almost) forever at | ||
4403 | larger sizes. Still, if there's no other alternative it can be | ||
4404 | usable: Pattern and Dominosa both use this technique. (However, | ||
4405 | Dominosa has a means of tweaking the randomly generated grids to | ||
4406 | increase the \e{probability} of them being soluble, by ruling out | ||
4407 | one of the most common ambiguous cases. This improved generation | ||
4408 | speed by over a factor of 10 on the highest preset!) | ||
4409 | |||
4410 | An approach which can be more scalable involves generating a grid | ||
4411 | and then tweaking it to make it soluble. This is the technique used | ||
4412 | by Mines and also by Net: first a random puzzle is generated, and | ||
4413 | then the solver is run to see how far it gets. Sometimes the solver | ||
4414 | will get stuck; when that happens, examine the area it's having | ||
4415 | trouble with, and make a small random change in that area to allow | ||
4416 | it to make more progress. Continue solving (possibly even without | ||
4417 | restarting the solver), tweaking as necessary, until the solver | ||
4418 | finishes. Then restart the solver from the beginning to ensure that | ||
4419 | the tweaks haven't caused new problems in the process of solving old | ||
4420 | ones (which can sometimes happen). | ||
4421 | |||
4422 | This strategy works well in situations where the usual solver | ||
4423 | failure mode is to get stuck in an easily localised spot. Thus it | ||
4424 | works well for Net and Mines, whose most common failure mode tends | ||
4425 | to be that most of the grid is fine but there are a few widely | ||
4426 | separated ambiguous sections; but it would work less well for | ||
4427 | Dominosa, in which the way you get stuck is to have scoured the | ||
4428 | whole grid and not found anything you can deduce \e{anywhere}. Also, | ||
4429 | it relies on there being a low probability that tweaking the grid | ||
4430 | introduces a new problem at the same time as solving the old one; | ||
4431 | Mines and Net also have the property that most of their deductions | ||
4432 | are local, so that it's very unlikely for a tweak to affect | ||
4433 | something half way across the grid from the location where it was | ||
4434 | applied. In Dominosa, by contrast, a lot of deductions use | ||
4435 | information about half the grid (\q{out of all the sixes, only one | ||
4436 | is next to a three}, which can depend on the values of up to 32 of | ||
4437 | the 56 squares in the default setting!), so this tweaking strategy | ||
4438 | would be rather less likely to work well. | ||
4439 | |||
4440 | A more specialised strategy is that used in Solo and Slant. These | ||
4441 | puzzles have the property that they derive their difficulty from not | ||
4442 | presenting all the available clues. (In Solo's case, if all the | ||
4443 | possible clues were provided then the puzzle would already be | ||
4444 | solved; in Slant it would still require user action to fill in the | ||
4445 | lines, but it would present no challenge at all). Therefore, a | ||
4446 | simple generation technique is to leave the decision of which clues | ||
4447 | to provide until the last minute. In other words, first generate a | ||
4448 | random \e{filled} grid with all possible clues present, and then | ||
4449 | gradually remove clues for as long as the solver reports that it's | ||
4450 | still soluble. Unlike the methods described above, this technique | ||
4451 | \e{cannot} fail \dash once you've got a filled grid, nothing can | ||
4452 | stop you from being able to convert it into a viable puzzle. | ||
4453 | However, it wouldn't even be meaningful to apply this technique to | ||
4454 | (say) Pattern, in which clues can never be left out, so the only way | ||
4455 | to affect the set of clues is by altering the solution. | ||
4456 | |||
4457 | (Unfortunately, Solo is complicated by the need to provide puzzles | ||
4458 | at varying difficulty levels. It's easy enough to generate a puzzle | ||
4459 | of \e{at most} a given level of difficulty; you just have a solver | ||
4460 | with configurable intelligence, and you set it to a given level and | ||
4461 | apply the above technique, thus guaranteeing that the resulting grid | ||
4462 | is solvable by someone with at most that much intelligence. However, | ||
4463 | generating a puzzle of \e{at least} a given level of difficulty is | ||
4464 | rather harder; if you go for \e{at most} Intermediate level, you're | ||
4465 | likely to find that you've accidentally generated a Trivial grid a | ||
4466 | lot of the time, because removing just one number is sufficient to | ||
4467 | take the puzzle from Trivial straight to Ambiguous. In that | ||
4468 | situation Solo has no remaining options but to throw the puzzle away | ||
4469 | and start again.) | ||
4470 | |||
4471 | A final strategy is to use the solver \e{during} puzzle | ||
4472 | construction: lay out a bit of the grid, run the solver to see what | ||
4473 | it allows you to deduce, and then lay out a bit more to allow the | ||
4474 | solver to make more progress. There are articles on the web that | ||
4475 | recommend constructing Sudoku puzzles by this method (which is | ||
4476 | completely the opposite way round to how Solo does it); for Sudoku | ||
4477 | it has the advantage that you get to specify your clue squares in | ||
4478 | advance (so you can have them make pretty patterns). | ||
4479 | |||
4480 | Rectangles uses a strategy along these lines. First it generates a | ||
4481 | grid by placing the actual rectangles; then it has to decide where | ||
4482 | in each rectangle to place a number. It uses a solver to help it | ||
4483 | place the numbers in such a way as to ensure a unique solution. It | ||
4484 | does this by means of running a test solver, but it runs the solver | ||
4485 | \e{before} it's placed any of the numbers \dash which means the | ||
4486 | solver must be capable of coping with uncertainty about exactly | ||
4487 | where the numbers are! It runs the solver as far as it can until it | ||
4488 | gets stuck; then it narrows down the possible positions of a number | ||
4489 | in order to allow the solver to make more progress, and so on. Most | ||
4490 | of the time this process terminates with the grid fully solved, at | ||
4491 | which point any remaining number-placement decisions can be made at | ||
4492 | random from the options not so far ruled out. Note that unlike the | ||
4493 | Net/Mines tweaking strategy described above, this algorithm does not | ||
4494 | require a checking run after it completes: if it finishes | ||
4495 | successfully at all, then it has definitely produced a uniquely | ||
4496 | soluble puzzle. | ||
4497 | |||
4498 | Most of the strategies described above are not 100% reliable. Each | ||
4499 | one has a failure rate: every so often it has to throw out the whole | ||
4500 | grid and generate a fresh one from scratch. (Solo's strategy would | ||
4501 | be the exception, if it weren't for the need to provide configurable | ||
4502 | difficulty levels.) Occasional failures are not a fundamental | ||
4503 | problem in this sort of work, however: it's just a question of | ||
4504 | dividing the grid generation time by the success rate (if it takes | ||
4505 | 10ms to generate a candidate grid and 1/5 of them work, then it will | ||
4506 | take 50ms on average to generate a viable one), and seeing whether | ||
4507 | the expected time taken to \e{successfully} generate a puzzle is | ||
4508 | unacceptably slow. Dominosa's generator has a very low success rate | ||
4509 | (about 1 out of 20 candidate grids turn out to be usable, and if you | ||
4510 | think \e{that's} bad then go and look at the source code and find | ||
4511 | the comment showing what the figures were before the generation-time | ||
4512 | tweaks!), but the generator itself is very fast so this doesn't | ||
4513 | matter. Rectangles has a slower generator, but fails well under 50% | ||
4514 | of the time. | ||
4515 | |||
4516 | So don't be discouraged if you have an algorithm that doesn't always | ||
4517 | work: if it \e{nearly} always works, that's probably good enough. | ||
4518 | The one place where reliability is important is that your algorithm | ||
4519 | must never produce false positives: it must not claim a puzzle is | ||
4520 | soluble when it isn't. It can produce false negatives (failing to | ||
4521 | notice that a puzzle is soluble), and it can fail to generate a | ||
4522 | puzzle at all, provided it doesn't do either so often as to become | ||
4523 | slow. | ||
4524 | |||
4525 | One last piece of advice: for grid-based puzzles, when writing and | ||
4526 | testing your generation algorithm, it's almost always a good idea | ||
4527 | \e{not} to test it initially on a grid that's square (i.e. | ||
4528 | \cw{w==h}), because if the grid is square then you won't notice if | ||
4529 | you mistakenly write \c{h} instead of \c{w} (or vice versa) | ||
4530 | somewhere in the code. Use a rectangular grid for testing, and any | ||
4531 | size of grid will be likely to work after that. | ||
4532 | |||
4533 | \S{writing-textformats} Designing textual description formats | ||
4534 | |||
4535 | Another aspect of writing a puzzle which is worth putting some | ||
4536 | thought into is the design of the various text description formats: | ||
4537 | the format of the game parameter encoding, the game description | ||
4538 | encoding, and the move encoding. | ||
4539 | |||
4540 | The first two of these should be reasonably intuitive for a user to | ||
4541 | type in; so provide some flexibility where possible. Suppose, for | ||
4542 | example, your parameter format consists of two numbers separated by | ||
4543 | an \c{x} to specify the grid dimensions (\c{10x10} or \c{20x15}), | ||
4544 | and then has some suffixes to specify other aspects of the game | ||
4545 | type. It's almost always a good idea in this situation to arrange | ||
4546 | that \cw{decode_params()} can handle the suffixes appearing in any | ||
4547 | order, even if \cw{encode_params()} only ever generates them in one | ||
4548 | order. | ||
4549 | |||
4550 | These formats will also be expected to be reasonably stable: users | ||
4551 | will expect to be able to exchange game IDs with other users who | ||
4552 | aren't running exactly the same version of your game. So make them | ||
4553 | robust and stable: don't build too many assumptions into the game ID | ||
4554 | format which will have to be changed every time something subtle | ||
4555 | changes in the puzzle code. | ||
4556 | |||
4557 | \H{writing-howto} Common how-to questions | ||
4558 | |||
4559 | This section lists some common things people want to do when writing | ||
4560 | a puzzle, and describes how to achieve them within the Puzzles | ||
4561 | framework. | ||
4562 | |||
4563 | \S{writing-howto-cursor} Drawing objects at only one position | ||
4564 | |||
4565 | A common phenomenon is to have an object described in the | ||
4566 | \c{game_state} or the \c{game_ui} which can only be at one position. | ||
4567 | A cursor \dash probably specified in the \c{game_ui} \dash is a good | ||
4568 | example. | ||
4569 | |||
4570 | In the \c{game_ui}, it would \e{obviously} be silly to have an array | ||
4571 | covering the whole game grid with a boolean flag stating whether the | ||
4572 | cursor was at each position. Doing that would waste space, would | ||
4573 | make it difficult to find the cursor in order to do anything with | ||
4574 | it, and would introduce the potential for synchronisation bugs in | ||
4575 | which you ended up with two cursors or none. The obviously sensible | ||
4576 | way to store a cursor in the \c{game_ui} is to have fields directly | ||
4577 | encoding the cursor's coordinates. | ||
4578 | |||
4579 | However, it is a mistake to assume that the same logic applies to | ||
4580 | the \c{game_drawstate}. If you replicate the cursor position fields | ||
4581 | in the draw state, the redraw code will get very complicated. In the | ||
4582 | draw state, in fact, it \e{is} probably the right thing to have a | ||
4583 | cursor flag for every position in the grid. You probably have an | ||
4584 | array for the whole grid in the drawstate already (stating what is | ||
4585 | currently displayed in the window at each position); the sensible | ||
4586 | approach is to add a \q{cursor} flag to each element of that array. | ||
4587 | Then the main redraw loop will look something like this | ||
4588 | (pseudo-code): | ||
4589 | |||
4590 | \c for (y = 0; y < h; y++) { | ||
4591 | \c for (x = 0; x < w; x++) { | ||
4592 | \c int value = state->symbol_at_position[y][x]; | ||
4593 | \c if (x == ui->cursor_x && y == ui->cursor_y) | ||
4594 | \c value |= CURSOR; | ||
4595 | \c if (ds->symbol_at_position[y][x] != value) { | ||
4596 | \c symbol_drawing_subroutine(dr, ds, x, y, value); | ||
4597 | \c ds->symbol_at_position[y][x] = value; | ||
4598 | \c } | ||
4599 | \c } | ||
4600 | \c } | ||
4601 | |||
4602 | This loop is very simple, pretty hard to get wrong, and | ||
4603 | \e{automatically} deals both with erasing the previous cursor and | ||
4604 | drawing the new one, with no special case code required. | ||
4605 | |||
4606 | This type of loop is generally a sensible way to write a redraw | ||
4607 | function, in fact. The best thing is to ensure that the information | ||
4608 | stored in the draw state for each position tells you \e{everything} | ||
4609 | about what was drawn there. A good way to ensure that is to pass | ||
4610 | precisely the same information, and \e{only} that information, to a | ||
4611 | subroutine that does the actual drawing; then you know there's no | ||
4612 | additional information which affects the drawing but which you don't | ||
4613 | notice changes in. | ||
4614 | |||
4615 | \S{writing-keyboard-cursor} Implementing a keyboard-controlled cursor | ||
4616 | |||
4617 | It is often useful to provide a keyboard control method in a | ||
4618 | basically mouse-controlled game. A keyboard-controlled cursor is | ||
4619 | best implemented by storing its location in the \c{game_ui} (since | ||
4620 | if it were in the \c{game_state} then the user would have to | ||
4621 | separately undo every cursor move operation). So the procedure would | ||
4622 | be: | ||
4623 | |||
4624 | \b Put cursor position fields in the \c{game_ui}. | ||
4625 | |||
4626 | \b \cw{interpret_move()} responds to arrow keys by modifying the | ||
4627 | cursor position fields and returning \cw{""}. | ||
4628 | |||
4629 | \b \cw{interpret_move()} responds to some sort of fire button by | ||
4630 | actually performing a move based on the current cursor location. | ||
4631 | |||
4632 | \b You might want an additional \c{game_ui} field stating whether | ||
4633 | the cursor is currently visible, and having it disappear when a | ||
4634 | mouse action occurs (so that it doesn't clutter the display when not | ||
4635 | actually in use). | ||
4636 | |||
4637 | \b You might also want to automatically hide the cursor in | ||
4638 | \cw{changed_state()} when the current game state changes to one in | ||
4639 | which there is no move to make (which is the case in some types of | ||
4640 | completed game). | ||
4641 | |||
4642 | \b \cw{redraw()} draws the cursor using the technique described in | ||
4643 | \k{writing-howto-cursor}. | ||
4644 | |||
4645 | \S{writing-howto-dragging} Implementing draggable sprites | ||
4646 | |||
4647 | Some games have a user interface which involves dragging some sort | ||
4648 | of game element around using the mouse. If you need to show a | ||
4649 | graphic moving smoothly over the top of other graphics, use a | ||
4650 | blitter (see \k{drawing-blitter} for the blitter API) to save the | ||
4651 | background underneath it. The typical scenario goes: | ||
4652 | |||
4653 | \b Have a blitter field in the \c{game_drawstate}. | ||
4654 | |||
4655 | \b Set the blitter field to \cw{NULL} in the game's | ||
4656 | \cw{new_drawstate()} function, since you don't yet know how big the | ||
4657 | piece of saved background needs to be. | ||
4658 | |||
4659 | \b In the game's \cw{set_size()} function, once you know the size of | ||
4660 | the object you'll be dragging around the display and hence the | ||
4661 | required size of the blitter, actually allocate the blitter. | ||
4662 | |||
4663 | \b In \cw{free_drawstate()}, free the blitter if it's not \cw{NULL}. | ||
4664 | |||
4665 | \b In \cw{interpret_move()}, respond to mouse-down and mouse-drag | ||
4666 | events by updating some fields in the \cw{game_ui} which indicate | ||
4667 | that a drag is in progress. | ||
4668 | |||
4669 | \b At the \e{very end} of \cw{redraw()}, after all other drawing has | ||
4670 | been done, draw the moving object if there is one. First save the | ||
4671 | background under the object in the blitter; then set a clip | ||
4672 | rectangle covering precisely the area you just saved (just in case | ||
4673 | anti-aliasing or some other error causes your drawing to go beyond | ||
4674 | the area you saved). Then draw the object, and call \cw{unclip()}. | ||
4675 | Finally, set a flag in the \cw{game_drawstate} that indicates that | ||
4676 | the blitter needs restoring. | ||
4677 | |||
4678 | \b At the very start of \cw{redraw()}, before doing anything else at | ||
4679 | all, check the flag in the \cw{game_drawstate}, and if it says the | ||
4680 | blitter needs restoring then restore it. (Then clear the flag, so | ||
4681 | that this won't happen again in the next redraw if no moving object | ||
4682 | is drawn this time.) | ||
4683 | |||
4684 | This way, you will be able to write the rest of the redraw function | ||
4685 | completely ignoring the dragged object, as if it were floating above | ||
4686 | your bitmap and being completely separate. | ||
4687 | |||
4688 | \S{writing-ref-counting} Sharing large invariant data between all | ||
4689 | game states | ||
4690 | |||
4691 | In some puzzles, there is a large amount of data which never changes | ||
4692 | between game states. The array of numbers in Dominosa is a good | ||
4693 | example. | ||
4694 | |||
4695 | You \e{could} dynamically allocate a copy of that array in every | ||
4696 | \c{game_state}, and have \cw{dup_game()} make a fresh copy of it for | ||
4697 | every new \c{game_state}; but it would waste memory and time. A | ||
4698 | more efficient way is to use a reference-counted structure. | ||
4699 | |||
4700 | \b Define a structure type containing the data in question, and also | ||
4701 | containing an integer reference count. | ||
4702 | |||
4703 | \b Have a field in \c{game_state} which is a pointer to this | ||
4704 | structure. | ||
4705 | |||
4706 | \b In \cw{new_game()}, when creating a fresh game state at the start | ||
4707 | of a new game, create an instance of this structure, initialise it | ||
4708 | with the invariant data, and set its reference count to 1. | ||
4709 | |||
4710 | \b In \cw{dup_game()}, rather than making a copy of the structure | ||
4711 | for the new game state, simply set the new game state to point at | ||
4712 | the same copy of the structure, and increment its reference count. | ||
4713 | |||
4714 | \b In \cw{free_game()}, decrement the reference count in the | ||
4715 | structure pointed to by the game state; if the count reaches zero, | ||
4716 | free the structure. | ||
4717 | |||
4718 | This way, the invariant data will persist for only as long as it's | ||
4719 | genuinely needed; \e{as soon} as the last game state for a | ||
4720 | particular puzzle instance is freed, the invariant data for that | ||
4721 | puzzle will vanish as well. Reference counting is a very efficient | ||
4722 | form of garbage collection, when it works at all. (Which it does in | ||
4723 | this instance, of course, because there's no possibility of circular | ||
4724 | references.) | ||
4725 | |||
4726 | \S{writing-flash-types} Implementing multiple types of flash | ||
4727 | |||
4728 | In some games you need to flash in more than one different way. | ||
4729 | Mines, for example, flashes white when you win, and flashes red when | ||
4730 | you tread on a mine and die. | ||
4731 | |||
4732 | The simple way to do this is: | ||
4733 | |||
4734 | \b Have a field in the \c{game_ui} which describes the type of flash. | ||
4735 | |||
4736 | \b In \cw{flash_length()}, examine the old and new game states to | ||
4737 | decide whether a flash is required and what type. Write the type of | ||
4738 | flash to the \c{game_ui} field whenever you return non-zero. | ||
4739 | |||
4740 | \b In \cw{redraw()}, when you detect that \c{flash_time} is | ||
4741 | non-zero, examine the field in \c{game_ui} to decide which type of | ||
4742 | flash to draw. | ||
4743 | |||
4744 | \cw{redraw()} will never be called with \c{flash_time} non-zero | ||
4745 | unless \cw{flash_length()} was first called to tell the mid-end that | ||
4746 | a flash was required; so whenever \cw{redraw()} notices that | ||
4747 | \c{flash_time} is non-zero, you can be sure that the field in | ||
4748 | \c{game_ui} is correctly set. | ||
4749 | |||
4750 | \S{writing-move-anim} Animating game moves | ||
4751 | |||
4752 | A number of puzzle types benefit from a quick animation of each move | ||
4753 | you make. | ||
4754 | |||
4755 | For some games, such as Fifteen, this is particularly easy. Whenever | ||
4756 | \cw{redraw()} is called with \c{oldstate} non-\cw{NULL}, Fifteen | ||
4757 | simply compares the position of each tile in the two game states, | ||
4758 | and if the tile is not in the same place then it draws it some | ||
4759 | fraction of the way from its old position to its new position. This | ||
4760 | method copes automatically with undo. | ||
4761 | |||
4762 | Other games are less obvious. In Sixteen, for example, you can't | ||
4763 | just draw each tile a fraction of the way from its old to its new | ||
4764 | position: if you did that, the end tile would zip very rapidly past | ||
4765 | all the others to get to the other end and that would look silly. | ||
4766 | (Worse, it would look inconsistent if the end tile was drawn on top | ||
4767 | going one way and on the bottom going the other way.) | ||
4768 | |||
4769 | A useful trick here is to define a field or two in the game state | ||
4770 | that indicates what the last move was. | ||
4771 | |||
4772 | \b Add a \q{last move} field to the \c{game_state} (or two or more | ||
4773 | fields if the move is complex enough to need them). | ||
4774 | |||
4775 | \b \cw{new_game()} initialises this field to a null value for a new | ||
4776 | game state. | ||
4777 | |||
4778 | \b \cw{execute_move()} sets up the field to reflect the move it just | ||
4779 | performed. | ||
4780 | |||
4781 | \b \cw{redraw()} now needs to examine its \c{dir} parameter. If | ||
4782 | \c{dir} is positive, it determines the move being animated by | ||
4783 | looking at the last-move field in \c{newstate}; but if \c{dir} is | ||
4784 | negative, it has to look at the last-move field in \c{oldstate}, and | ||
4785 | invert whatever move it finds there. | ||
4786 | |||
4787 | Note also that Sixteen needs to store the \e{direction} of the move, | ||
4788 | because you can't quite determine it by examining the row or column | ||
4789 | in question. You can in almost all cases, but when the row is | ||
4790 | precisely two squares long it doesn't work since a move in either | ||
4791 | direction looks the same. (You could argue that since moving a | ||
4792 | 2-element row left and right has the same effect, it doesn't matter | ||
4793 | which one you animate; but in fact it's very disorienting to click | ||
4794 | the arrow left and find the row moving right, and almost as bad to | ||
4795 | undo a move to the right and find the game animating \e{another} | ||
4796 | move to the right.) | ||
4797 | |||
4798 | \S{writing-conditional-anim} Animating drag operations | ||
4799 | |||
4800 | In Untangle, moves are made by dragging a node from an old position | ||
4801 | to a new position. Therefore, at the time when the move is initially | ||
4802 | made, it should not be animated, because the node has already been | ||
4803 | dragged to the right place and doesn't need moving there. However, | ||
4804 | it's nice to animate the same move if it's later undone or redone. | ||
4805 | This requires a bit of fiddling. | ||
4806 | |||
4807 | The obvious approach is to have a flag in the \c{game_ui} which | ||
4808 | inhibits move animation, and to set that flag in | ||
4809 | \cw{interpret_move()}. The question is, when would the flag be reset | ||
4810 | again? The obvious place to do so is \cw{changed_state()}, which | ||
4811 | will be called once per move. But it will be called \e{before} | ||
4812 | \cw{anim_length()}, so if it resets the flag then \cw{anim_length()} | ||
4813 | will never see the flag set at all. | ||
4814 | |||
4815 | The solution is to have \e{two} flags in a queue. | ||
4816 | |||
4817 | \b Define two flags in \c{game_ui}; let's call them \q{current} and | ||
4818 | \q{next}. | ||
4819 | |||
4820 | \b Set both to \cw{FALSE} in \c{new_ui()}. | ||
4821 | |||
4822 | \b When a drag operation completes in \cw{interpret_move()}, set the | ||
4823 | \q{next} flag to \cw{TRUE}. | ||
4824 | |||
4825 | \b Every time \cw{changed_state()} is called, set the value of | ||
4826 | \q{current} to the value in \q{next}, and then set the value of | ||
4827 | \q{next} to \cw{FALSE}. | ||
4828 | |||
4829 | \b That way, \q{current} will be \cw{TRUE} \e{after} a call to | ||
4830 | \cw{changed_state()} if and only if that call to | ||
4831 | \cw{changed_state()} was the result of a drag operation processed by | ||
4832 | \cw{interpret_move()}. Any other call to \cw{changed_state()}, due | ||
4833 | to an Undo or a Redo or a Restart or a Solve, will leave \q{current} | ||
4834 | \cw{FALSE}. | ||
4835 | |||
4836 | \b So now \cw{anim_length()} can request a move animation if and | ||
4837 | only if the \q{current} flag is \e{not} set. | ||
4838 | |||
4839 | \S{writing-cheating} Inhibiting the victory flash when Solve is used | ||
4840 | |||
4841 | Many games flash when you complete them, as a visual congratulation | ||
4842 | for having got to the end of the puzzle. It often seems like a good | ||
4843 | idea to disable that flash when the puzzle is brought to a solved | ||
4844 | state by means of the Solve operation. | ||
4845 | |||
4846 | This is easily done: | ||
4847 | |||
4848 | \b Add a \q{cheated} flag to the \c{game_state}. | ||
4849 | |||
4850 | \b Set this flag to \cw{FALSE} in \cw{new_game()}. | ||
4851 | |||
4852 | \b Have \cw{solve()} return a move description string which clearly | ||
4853 | identifies the move as a solve operation. | ||
4854 | |||
4855 | \b Have \cw{execute_move()} respond to that clear identification by | ||
4856 | setting the \q{cheated} flag in the returned \c{game_state}. The | ||
4857 | flag will then be propagated to all subsequent game states, even if | ||
4858 | the user continues fiddling with the game after it is solved. | ||
4859 | |||
4860 | \b \cw{flash_length()} now returns non-zero if \c{oldstate} is not | ||
4861 | completed and \c{newstate} is, \e{and} neither state has the | ||
4862 | \q{cheated} flag set. | ||
4863 | |||
4864 | \H{writing-testing} Things to test once your puzzle is written | ||
4865 | |||
4866 | Puzzle implementations written in this framework are self-testing as | ||
4867 | far as I could make them. | ||
4868 | |||
4869 | Textual game and move descriptions, for example, are generated and | ||
4870 | parsed as part of the normal process of play. Therefore, if you can | ||
4871 | make moves in the game \e{at all} you can be reasonably confident | ||
4872 | that the mid-end serialisation interface will function correctly and | ||
4873 | you will be able to save your game. (By contrast, if I'd stuck with | ||
4874 | a single \cw{make_move()} function performing the jobs of both | ||
4875 | \cw{interpret_move()} and \cw{execute_move()}, and had separate | ||
4876 | functions to encode and decode a game state in string form, then | ||
4877 | those functions would not be used during normal play; so they could | ||
4878 | have been completely broken, and you'd never know it until you tried | ||
4879 | to save the game \dash which would have meant you'd have to test | ||
4880 | game saving \e{extensively} and make sure to test every possible | ||
4881 | type of game state. As an added bonus, doing it the way I did leads | ||
4882 | to smaller save files.) | ||
4883 | |||
4884 | There is one exception to this, which is the string encoding of the | ||
4885 | \c{game_ui}. Most games do not store anything permanent in the | ||
4886 | \c{game_ui}, and hence do not need to put anything in its encode and | ||
4887 | decode functions; but if there is anything in there, you do need to | ||
4888 | test game loading and saving to ensure those functions work | ||
4889 | properly. | ||
4890 | |||
4891 | It's also worth testing undo and redo of all operations, to ensure | ||
4892 | that the redraw and the animations (if any) work properly. Failing | ||
4893 | to animate undo properly seems to be a common error. | ||
4894 | |||
4895 | Other than that, just use your common sense. | ||