X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/puzzles/blobdiff_plain/dafd6cf6826f9bbd27ddd780fab48221d4706556..9680576d3ac161e2df2454a79e57b9c36314975e:/devel.but diff --git a/devel.but b/devel.but index 62ec659..4f589da 100644 --- a/devel.but +++ b/devel.but @@ -1097,9 +1097,14 @@ allocating a blitter (see \k{drawing-blitter}). The parameter \c{dr} is a drawing object (see \k{drawing}), which is required if a blitter needs to be allocated. +Back ends may assume (and may enforce by assertion) that this +function will be called at most once for any \c{game_drawstate}. If +a puzzle needs to be redrawn at a different size, the mid-end will +create a fresh drawstate. + \S{backend-colours} \cw{colours()} -\c float *(*colours)(frontend *fe, game_state *state, int *ncolours); +\c float *(*colours)(frontend *fe, int *ncolours); This function is responsible for telling the front end what colours the puzzle will need to draw itself. @@ -1110,15 +1115,7 @@ array of three times that many \c{float}s, containing the red, green and blue components of each colour respectively as numbers in the range [0,1]. -It is passed a sample \c{game_state} in case it needs one, although -currently no puzzle does need this. (In fact, colours are not -reallocated when the game parameters change or a new game is -started, so you can't reliably use this \c{game_state} to allocate a -different number of colours depending on the game. It is probably -actually a mistake to rely on this parameter at all. I ought to -either remove it or fix it; probably the former.) - -The final parameter passed to this function is a front end handle. +The second parameter passed to this function is a front end handle. The only things it is permitted to do with this handle are to call the front-end function called \cw{frontend_default_colour()} (see \k{frontend-default-colour}) or the utility function called @@ -1161,8 +1158,7 @@ State changes as a result of a Restart operation are never animated; the mid-end will handle them internally and never consult this function at all. State changes as a result of Solve operations are also not animated by default, although you can change this for a -particular game by setting a flag in \c{mouse_priorities} -(\k{backend-mouse-priorities}). +particular game by setting a flag in \c{flags} (\k{backend-flags}). The function is also passed a pointer to the local \c{game_ui}. It may refer to information in here to help with its decision (see @@ -1402,16 +1398,12 @@ whether that should come with a newline or not.) \S{backend-wants-statusbar} \cw{wants_statusbar()} -\c int (*wants_statusbar)(void); +\c int wants_statusbar; -This function returns \cw{TRUE} if the puzzle has a use for a +This boolean field is set to \cw{TRUE} if the puzzle has a use for a textual status line (to display score, completion status, currently active tiles, etc). -(This should probably be a static boolean field rather than a -function. I don't remember why I did it this way. I probably ought -to change it.) - \S{backend-is-timed} \c{is_timed} \c int is_timed; @@ -1436,12 +1428,12 @@ the game was first completed (by setting a flag in freeze the timer thereafter so that the user can undo back through their solution process without altering their time. -\S{backend-mouse-priorities} \c{mouse_priorities} +\S{backend-flags} \c{flags} -\c int mouse_priorities; +\c int flags; -This field is badly named. It is in fact a generic flags word. It -consists of the bitwise OR of the following flags: +This field contains miscellaneous per-backend flags. It consists of +the bitwise OR of some combination of the following: \dt \cw{BUTTON_BEATS(x,y)} @@ -1473,7 +1465,7 @@ otherwise be obvious. If a back end needs random numbers at some point during normal play, it can create a fresh \c{random_state} by first calling \c{get_random_seed} (\k{frontend-get-random-seed}) and then passing -the returned seed data to \cw{random_init()}. +the returned seed data to \cw{random_new()}. This is likely not to be what you want. If a puzzle needs randomness in the middle of play, it's likely to be more sensible to store some @@ -1551,14 +1543,13 @@ functions. This enables a single front end to switch between multiple implementations of the drawing API if necessary. For example, the Windows API supplies a printing mechanism integrated into the same GDI which deals with drawing in windows, and therefore -it is likely (although as yet unimplemented in Puzzles) that the -same API implementation can handle both drawing and printing; but on -Unix, the most common way for applications to print is by producing -PostScript output directly, and although it would be \e{possible} to -write a single (say) \cw{draw_rect()} function which checked a -global flag to decide whether to do GTK drawing operations or output -PostScript to a file, it's much nicer to have two separate functions -and switch between them as appropriate. +the same API implementation can handle both drawing and printing; +but on Unix, the most common way for applications to print is by +producing PostScript output directly, and although it would be +\e{possible} to write a single (say) \cw{draw_rect()} function which +checked a global flag to decide whether to do GTK drawing operations +or output PostScript to a file, it's much nicer to have two separate +functions and switch between them as appropriate. When drawing, the puzzle window is indexed by pixel coordinates, with the top left pixel defined as \cw{(0,0)} and the bottom right @@ -2039,11 +2030,11 @@ colour during printing. \c{r}, \c{g} and \c{b} may each be anywhere in the range from 0 to 1. -If printing in black and white only, the \c{grey} value will not be -used; instead, regions shaded in this colour will be hatched with -parallel lines. The \c{hatch} parameter defines what type of -hatching should be used in place of this colour; see -\k{print-grey-colour} for its definition. +If printing in black and white only, these values will not be used; +instead, regions shaded in this colour will be hatched with parallel +lines. The \c{hatch} parameter defines what type of hatching should +be used in place of this colour; see \k{print-grey-colour} for its +definition. \S{print-line-width} \cw{print_line_width()} @@ -2455,6 +2446,16 @@ previously got it from \cw{midend_fetch_preset()} (\k{midend-fetch-preset}). Thus, this function is usually called in response to the user making a selection from the presets menu. +\H{midend-get-params} \cw{midend_get_params()} + +\c game_params *midend_get_params(midend *me); + +Returns the current game parameters stored in this mid-end. + +The returned value is dynamically allocated, and should be freed +when finished with by passing it to the game's own +\cw{free_params()} function (see \k{backend-free-params}). + \H{midend-size} \cw{midend_size()} \c void midend_size(midend *me, int *x, int *y, int expand); @@ -3030,9 +3031,9 @@ generator has an \e{explicit} state object called a \c{random_state}. One of these is managed by each mid-end, for example, and passed to the back end to generate a game with. -\S{utils-random-init} \cw{random_init()} +\S{utils-random-init} \cw{random_new()} -\c random_state *random_init(char *seed, int len); +\c random_state *random_new(char *seed, int len); Allocates, initialises and returns a new \c{random_state}. The input data is used as the seed for the random number stream (i.e. using @@ -4041,7 +4042,7 @@ Then the main redraw loop will look something like this \c if (x == ui->cursor_x && y == ui->cursor_y) \c value |= CURSOR; \c if (ds->symbol_at_position[y][x] != value) { -\c symbol_drawing_subroutine(fe, ds, x, y, value); +\c symbol_drawing_subroutine(dr, ds, x, y, value); \c ds->symbol_at_position[y][x] = value; \c } \c } @@ -4106,9 +4107,7 @@ piece of saved background needs to be. \b In the game's \cw{set_size()} function, once you know the size of the object you'll be dragging around the display and hence the -required size of the blitter, actually allocate the blitter (making -sure to free a previous one if present \dash it's possible that -\cw{set_size()} might be called twice on the same draw state). +required size of the blitter, actually allocate the blitter. \b In \cw{free_drawstate()}, free the blitter if it's not \cw{NULL}.