X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/puzzles/blobdiff_plain/2ddfae80641ff95141e3a9e7f0b525b340345862..HEAD:/devel.but diff --git a/devel.but b/devel.but index ea23d52..970a73a 100644 --- a/devel.but +++ b/devel.but @@ -170,7 +170,7 @@ other miscellaneous functions. All of these are documented in There are a number of function call interfaces within Puzzles, and this guide will discuss each one in a chapter of its own. After -that, (\k{writing}) discusses how to design new games, with some +that, \k{writing} discusses how to design new games, with some general design thoughts and tips. \C{backend} Interface to the back end @@ -856,7 +856,7 @@ producing new \c{game_state}s. \S{backend-interpret-move} \cw{interpret_move()} \c char *(*interpret_move)(game_state *state, game_ui *ui, -\c game_drawstate *ds, +\c const game_drawstate *ds, \c int x, int y, int button); This function receives user input and processes it. Its input @@ -868,6 +868,11 @@ indicating an arrow or function key or a mouse event; when coordinates of the mouse pointer relative to the top left of the puzzle's drawing area. +(The pointer to the \c{game_drawstate} is marked \c{const}, because +\c{interpret_move} should not write to it. The normal use of that +pointer will be to read the game's tile size parameter in order to +divide mouse coordinates by it.) + \cw{interpret_move()} may return in three different ways: \b Returning \cw{NULL} indicates that no action whatsoever occurred @@ -1224,6 +1229,34 @@ a mine from the colour it uses when you complete the game. In order to achieve this, its \cw{flash_length()} function has to store a flag in the \c{game_ui} to indicate which flash type is required.) +\S{backend-status} \cw{status()} + +\c int (*status)(game_state *state); + +This function returns a status value indicating whether the current +game is still in play, or has been won, or has been conclusively lost. +The mid-end uses this to implement \cw{midend_status()} +(\k{midend-status}). + +The return value should be +1 if the game has been successfully +solved. If the game has been lost in a situation where further play is +unlikely, the return value should be -1. If neither is true (so play +is still ongoing), return zero. + +Front ends may wish to use a non-zero status as a cue to proactively +offer the option of starting a new game. Therefore, back ends should +not return -1 if the game has been \e{technically} lost but undoing +and continuing is still a realistic possibility. + +(For instance, games with hidden information such as Guess or Mines +might well return a non-zero status whenever they reveal the solution, +whether or not the player guessed it correctly, on the grounds that a +player would be unlikely to hide the solution and continue playing +after the answer was spoiled. On the other hand, games where you can +merely get into a dead end such as Same Game or Inertia might choose +to return 0 in that situation, on the grounds that the player would +quite likely press Undo and carry on playing.) + \S{backend-redraw} \cw{redraw()} \c void (*redraw)(drawing *dr, game_drawstate *ds, @@ -1365,17 +1398,50 @@ called. \H{backend-misc} Miscellaneous -\S{backend-can-format-as-text} \c{can_format_as_text} +\S{backend-can-format-as-text-ever} \c{can_format_as_text_ever} -\c int can_format_as_text; +\c int can_format_as_text_ever; This boolean field is \cw{TRUE} if the game supports formatting a game state as ASCII text (typically ASCII art) for copying to the clipboard and pasting into other applications. If it is \cw{FALSE}, front ends will not offer the \q{Copy} command at all. -If this field is \cw{FALSE}, the function \cw{text_format()} -(\k{backend-text-format}) is not expected to do anything at all. +If this field is \cw{TRUE}, the game does not necessarily have to +support text formatting for \e{all} games: e.g. a game which can be +played on a square grid or a triangular one might only support copy +and paste for the former, because triangular grids in ASCII art are +just too difficult. + +If this field is \cw{FALSE}, the functions +\cw{can_format_as_text_now()} (\k{backend-can-format-as-text-now}) +and \cw{text_format()} (\k{backend-text-format}) are never called. + +\S{backend-can-format-as-text-now} \c{can_format_as_text_now()} + +\c int (*can_format_as_text_now)(game_params *params); + +This function is passed a \c{game_params} and returns a boolean, +which is \cw{TRUE} if the game can support ASCII text output for +this particular game type. If it returns \cw{FALSE}, front ends will +grey out or otherwise disable the \q{Copy} command. + +Games may enable and disable the copy-and-paste function for +different game \e{parameters}, but are currently constrained to +return the same answer from this function for all game \e{states} +sharing the same parameters. In other words, the \q{Copy} function +may enable or disable itself when the player changes game preset, +but will never change during play of a single game or when another +game of exactly the same type is generated. + +This function should not take into account aspects of the game +parameters which are not encoded by \cw{encode_params()} +(\k{backend-encode-params}) when the \c{full} parameter is set to +\cw{FALSE}. Such parameters will not necessarily match up between a +call to this function and a subsequent call to \cw{text_format()} +itself. (For instance, game \e{difficulty} should not affect whether +the game can be copied to the clipboard. Only the actual visible +\e{shape} of the game can affect that.) \S{backend-text-format} \cw{text_format()} @@ -1386,9 +1452,11 @@ allocated C string containing an ASCII representation of that game state. It is used to implement the \q{Copy} operation in many front ends. -This function should only be called if the back end field -\c{can_format_as_text} (\k{backend-can-format-as-text}) is -\cw{TRUE}. +This function will only ever be called if the back end field +\c{can_format_as_text_ever} (\k{backend-can-format-as-text-ever}) is +\cw{TRUE} \e{and} the function \cw{can_format_as_text_now()} +(\k{backend-can-format-as-text-now}) has returned \cw{TRUE} for the +currently selected game parameters. The returned string may contain line endings (and will probably want to), using the normal C internal \cq{\\n} convention. For @@ -1398,7 +1466,7 @@ them internally. (There are currently no puzzles which have a one-line ASCII representation, so there's no precedent yet for whether that should come with a newline or not.) -\S{backend-wants-statusbar} \cw{wants_statusbar()} +\S{backend-wants-statusbar} \cw{wants_statusbar} \c int wants_statusbar; @@ -1606,6 +1674,43 @@ end does any drawing it informs the front end of which parts of the window it has accessed, and hence which parts need repainting. This is done by calling \cw{draw_update()} (\k{drawing-draw-update}). +Persistence of old drawing is convenient. However, a puzzle should +be very careful about how it updates its drawing area. The problem +is that some front ends do anti-aliased drawing: rather than simply +choosing between leaving each pixel untouched or painting it a +specified colour, an antialiased drawing function will \e{blend} the +original and new colours in pixels at a figure's boundary according +to the proportion of the pixel occupied by the figure (probably +modified by some heuristic fudge factors). All of this produces a +smoother appearance for curves and diagonal lines. + +An unfortunate effect of drawing an anti-aliased figure repeatedly +is that the pixels around the figure's boundary come steadily more +saturated with \q{ink} and the boundary appears to \q{spread out}. +Worse, redrawing a figure in a different colour won't fully paint +over the old boundary pixels, so the end result is a rather ugly +smudge. + +A good strategy to avoid unpleasant anti-aliasing artifacts is to +identify a number of rectangular areas which need to be redrawn, +clear them to the background colour, and then redraw their contents +from scratch, being careful all the while not to stray beyond the +boundaries of the original rectangles. The \cw{clip()} function +(\k{drawing-clip}) comes in very handy here. Games based on a square +grid can often do this fairly easily. Other games may need to be +somewhat more careful. For example, Loopy's redraw function first +identifies portions of the display which need to be updated. Then, +if the changes are fairly well localised, it clears and redraws a +rectangle containing each changed area. Otherwise, it gives up and +redraws the entire grid from scratch. + +It is possible to avoid clearing to background and redrawing from +scratch if one is very careful about which drawing functions one +uses: if a function is documented as not anti-aliasing under some +circumstances, you can rely on each pixel in a drawing either being +left entirely alone or being set to the requested colour, with no +blending being performed. + In the following sections I first discuss the drawing API as seen by the back end, and then the \e{almost} identical function-pointer form seen by the front end. @@ -1680,8 +1785,9 @@ the back end function \cw{colours()} (\k{backend-colours}). Some platforms may perform anti-aliasing on this function. Therefore, do not assume that you can erase a line by drawing the -same line over it in the background colour; anti-aliasing might -lead to perceptible ghost artefacts around the vanished line. +same line over it in the background colour; anti-aliasing might lead +to perceptible ghost artefacts around the vanished line. Horizontal +and vertical lines, however, are pixel-perfect and not anti-aliased. This function may be used for both drawing and printing. @@ -1718,7 +1824,8 @@ same polygon over it in the background colour. Also, be prepared for the polygon to extend a pixel beyond its obvious bounding box as a result of this; if you really need it not to do this to avoid interfering with other delicate graphics, you should probably use -\cw{clip()} (\k{drawing-clip}). +\cw{clip()} (\k{drawing-clip}). You can rely on horizontal and +vertical lines not being anti-aliased. This function may be used for both drawing and printing. @@ -1760,6 +1867,32 @@ interfering with other delicate graphics, you should probably use This function may be used for both drawing and printing. +\S{drawing-draw-thick-line} \cw{draw_thick_line()} + +\c void draw_thick_line(drawing *dr, float thickness, +\c float x1, float y1, float x2, float y2, +\c int colour) + +Draws a line in the puzzle window, giving control over the line's +thickness. + +\c{x1} and \c{y1} give the coordinates of one end of the line. +\c{x2} and \c{y2} give the coordinates of the other end. +\c{thickness} gives the thickness of the line, in pixels. + +Note that the coordinates and thickness are floating-point: the +continuous coordinate system is in effect here. It's important to +be able to address points with better-than-pixel precision in this +case, because one can't otherwise properly express the endpoints of +lines with both odd and even thicknesses. + +Some platforms may perform anti-aliasing on this function. The +precise pixels affected by a thick-line drawing operation may vary +between platforms, and no particular guarantees are provided. +Indeed, even horizontal or vertical lines may be anti-aliased. + +This function may be used for both drawing and printing. + \S{drawing-draw-text} \cw{draw_text()} \c void draw_text(drawing *dr, int x, int y, int fonttype, @@ -1813,6 +1946,54 @@ the back end function \cw{colours()} (\k{backend-colours}). This function may be used for both drawing and printing. +The character set used to encode the text passed to this function is +specified \e{by the drawing object}, although it must be a superset +of ASCII. If a puzzle wants to display text that is not contained in +ASCII, it should use the \cw{text_fallback()} function +(\k{drawing-text-fallback}) to query the drawing object for an +appropriate representation of the characters it wants. + +\S{drawing-text-fallback} \cw{text_fallback()} + +\c char *text_fallback(drawing *dr, const char *const *strings, +\c int nstrings); + +This function is used to request a translation of UTF-8 text into +whatever character encoding is expected by the drawing object's +implementation of \cw{draw_text()}. + +The input is a list of strings encoded in UTF-8: \cw{nstrings} gives +the number of strings in the list, and \cw{strings[0]}, +\cw{strings[1]}, ..., \cw{strings[nstrings-1]} are the strings +themselves. + +The returned string (which is dynamically allocated and must be +freed when finished with) is derived from the first string in the +list that the drawing object expects to be able to display reliably; +it will consist of that string translated into the character set +expected by \cw{draw_text()}. + +Drawing implementations are not required to handle anything outside +ASCII, but are permitted to assume that \e{some} string will be +successfully translated. So every call to this function must include +a string somewhere in the list (presumably the last element) which +consists of nothing but ASCII, to be used by any front end which +cannot handle anything else. + +For example, if a puzzle wished to display a string including a +multiplication sign (U+00D7 in Unicode, represented by the bytes C3 +97 in UTF-8), it might do something like this: + +\c static const char *const times_signs[] = { "\xC3\x97", "x" }; +\c char *times_sign = text_fallback(dr, times_signs, 2); +\c sprintf(buffer, "%d%s%d", width, times_sign, height); +\c draw_text(dr, x, y, font, size, align, colour, buffer); +\c sfree(buffer); + +which would draw a string with a times sign in the middle on +platforms that support it, and fall back to a simple ASCII \cq{x} +where there was no alternative. + \S{drawing-clip} \cw{clip()} \c void clip(drawing *dr, int x, int y, int w, int h); @@ -1828,7 +2009,9 @@ inclusive. (These are exactly the same semantics as After this call, no drawing operation will affect anything outside the specified rectangle. The effect can be reversed by calling -\cw{unclip()} (\k{drawing-unclip}). +\cw{unclip()} (\k{drawing-unclip}). The clipping rectangle is +pixel-perfect: pixels within the rectangle are affected as usual by +drawing functions; pixels outside are completely untouched. Back ends should not assume that a clipping rectangle will be automatically cleared up by the front end if it's left lying around; @@ -2108,6 +2291,22 @@ however, that it is a hint only: the central printing system may choose to vary line thicknesses at user request or due to printer capabilities. +\S{print-line-dotted} \cw{print_line_dotted()} + +\c void print_line_dotted(drawing *dr, int dotted); + +This function is called to toggle the drawing of dotted lines during +printing. It is not supported during drawing. + +The parameter \cq{dotted} is a boolean; \cw{TRUE} means that future +lines drawn by \cw{draw_line()}, \cw{draw_circle} and +\cw{draw_polygon()} will be dotted, and \cw{FALSE} means that they +will be solid. + +Some front ends may impose restrictions on the width of dotted +lines. Asking for a dotted line via this front end will override any +line width request if the front end requires it. + \H{drawing-frontend} The drawing API as implemented by the front end This section describes the drawing API in the function-pointer form @@ -2166,6 +2365,20 @@ function; see \k{drawing-draw-polygon}. This function behaves exactly like the back end \cw{draw_circle()} function; see \k{drawing-draw-circle}. +\S{drawingapi-draw-thick-line} \cw{draw_thick_line()} + +\c void draw_thick_line(drawing *dr, float thickness, +\c float x1, float y1, float x2, float y2, +\c int colour) + +This function behaves exactly like the back end +\cw{draw_thick_line()} function; see \k{drawing-draw-thick-line}. + +An implementation of this API which doesn't provide high-quality +rendering of thick lines is permitted to define this function +pointer to be \cw{NULL}. The middleware in \cw{drawing.c} will notice +and provide a low-quality alternative using \cw{draw_polygon()}. + \S{drawingapi-draw-update} \cw{draw_update()} \c void (*draw_update)(void *handle, int x, int y, int w, int h); @@ -2391,6 +2604,19 @@ Implementations of this API which do not provide printing services may define this function pointer to be \cw{NULL}; it will never be called unless printing is attempted. +\S{drawingapi-text-fallback} \cw{text_fallback()} + +\c char *(*text_fallback)(void *handle, const char *const *strings, +\c int nstrings); + +This function behaves exactly like the back end \cw{text_fallback()} +function; see \k{drawing-text-fallback}. + +Implementations of this API which do not support any characters +outside ASCII may define this function pointer to be \cw{NULL}, in +which case the central code in \cw{drawing.c} will provide a default +implementation. + \H{drawingapi-frontend} The drawing API as called by the front end There are a small number of functions provided in \cw{drawing.c} @@ -2493,6 +2719,13 @@ without closing the window...) Frees a mid-end structure and all its associated data. +\H{midend-tilesize} \cw{midend_tilesize()} + +\c int midend_tilesize(midend *me); + +Returns the \cq{tilesize} parameter being used to display the +current puzzle (\k{backend-preferred-tilesize}). + \H{midend-set-params} \cw{midend_set_params()} \c void midend_set_params(midend *me, game_params *params); @@ -2576,6 +2809,9 @@ to use scroll bars for large puzzles), you can pass dimensions of \cw{INT_MAX} as input to this function. You should probably not do that \e{and} set the \c{user_size} flag, though! +The midend relies on the frontend calling \cw{midend_new_game()} +(\k{midend-new-game}) before calling \cw{midend_size()}. + \H{midend-new-game} \cw{midend_new_game()} \c void midend_new_game(midend *me); @@ -2612,7 +2848,8 @@ undo list (so that an accidental restart can be undone). This function automatically causes a redraw, i.e. the front end can expect its drawing API to be called from \e{within} a call to this -function. +function. Some back ends require that \cw{midend_size()} +(\k{midend-size}) is called before \cw{midend_restart_game()}. \H{midend-force-redraw} \cw{midend_force_redraw()} @@ -2623,7 +2860,8 @@ discarding the current \c{game_drawstate} and creating a new one from scratch before calling the game's \cw{redraw()} function. The front end can expect its drawing API to be called from within a -call to this function. +call to this function. Some back ends require that \cw{midend_size()} +(\k{midend-size}) is called before \cw{midend_force_redraw()}. \H{midend-redraw} \cw{midend_redraw()} @@ -2634,7 +2872,8 @@ calling the game's \cw{redraw()} function. (That is, the only things redrawn will be things that have changed since the last redraw.) The front end can expect its drawing API to be called from within a -call to this function. +call to this function. Some back ends require that \cw{midend_size()} +(\k{midend-size}) is called before \cw{midend_redraw()}. \H{midend-process-key} \cw{midend_process_key()} @@ -2852,6 +3091,16 @@ Returns a descriptive game ID (i.e. one in the form \cq{params:description}) describing the game currently active in the mid-end. The returned string is dynamically allocated. +\H{midend-can-format-as-text-now} \cw{midend_can_format_as_text_now()} + +\c int midend_can_format_as_text_now(midend *me); + +Returns \cw{TRUE} if the game code is capable of formatting puzzles +of the currently selected game type as ASCII. + +If this returns \cw{FALSE}, then \cw{midend_text_format()} +(\k{midend-text-format}) will return \cw{NULL}. + \H{midend-text-format} \cw{midend_text_format()} \c char *midend_text_format(midend *me); @@ -2860,8 +3109,9 @@ Formats the current game's current state as ASCII text suitable for copying to the clipboard. The returned string is dynamically allocated. -You should not call this function if the game's -\c{can_format_as_text} flag is \cw{FALSE}. +If the game's \c{can_format_as_text_ever} flag is \cw{FALSE}, or if +its \cw{can_format_as_text_now()} function returns \cw{FALSE}, then +this function will return \cw{NULL}. If the returned string contains multiple lines (which is likely), it will use the normal C line ending convention (\cw{\\n} only). On @@ -2881,7 +3131,40 @@ user. The front end can expect its drawing API and/or \cw{activate_timer()} to be called from within a call to this -function. +function. Some back ends require that \cw{midend_size()} +(\k{midend-size}) is called before \cw{midend_solve()}. + +\H{midend-status} \cw{midend_status()} + +\c int midend_status(midend *me); + +This function returns +1 if the midend is currently displaying a game +in a solved state, -1 if the game is in a permanently lost state, or 0 +otherwise. This function just calls the back end's \cw{status()} +function. Front ends may wish to use this as a cue to proactively +offer the option of starting a new game. + +(See \k{backend-status} for more detail about the back end's +\cw{status()} function and discussion of what should count as which +status code.) + +\H{midend-can-undo} \cw{midend_can_undo()} + +\c int midend_can_undo(midend *me); + +Returns \cw{TRUE} if the midend is currently in a state where the undo +operation is meaningful (i.e. at least one position exists on the undo +chain before the present one). Front ends may wish to use this to +visually activate and deactivate an undo button. + +\H{midend-can-redo} \cw{midend_can_redo()} + +\c int midend_can_redo(midend *me); + +Returns \cw{TRUE} if the midend is currently in a state where the redo +operation is meaningful (i.e. at least one position exists on the redo +chain after the present one). Front ends may wish to use this to +visually activate and deactivate a redo button. \H{midend-serialise} \cw{midend_serialise()} @@ -2964,8 +3247,8 @@ mid-end because there didn't seem much point in doing so: \b fetching the \c{name} field to use in window titles and similar \b reading the \c{can_configure}, \c{can_solve} and -\c{can_format_as_text} fields to decide whether to add those items -to the menu bar or equivalent +\c{can_format_as_text_ever} fields to decide whether to add those +items to the menu bar or equivalent \b reading the \c{winhelp_topic} field (Windows only)