X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/puzzles/blobdiff_plain/f487468f67fa996caab7de5b08a5da2c25ebd551..35ee200129890bb76d15168c879bb0b0ca622296:/devel.but

diff --git a/devel.but b/devel.but
index d310d2c..ef43baa 100644
--- a/devel.but
+++ b/devel.but
@@ -1097,6 +1097,11 @@ 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);
@@ -1551,14 +1556,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
@@ -2455,6 +2459,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);
@@ -4041,7 +4055,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 +4120,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}.