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