X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/puzzles/blobdiff_plain/05e50a969fafb13b74b48c08bc1f1deb2f3425fc..9680576d3ac161e2df2454a79e57b9c36314975e:/devel.but

diff --git a/devel.but b/devel.but
index ef43baa..4f589da 100644
--- a/devel.but
+++ b/devel.but
@@ -1104,7 +1104,7 @@ 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.
@@ -1115,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
@@ -1166,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
@@ -1407,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;
@@ -1441,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)}
 
@@ -1478,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
@@ -3044,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