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