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