Noticed recently that bitcount16() isn't 16-bit clean due to signed

[sgt/puzzles] / devel.but

diff --git a/devel.but b/devel.but
index ed5c914..66413ec 100644 (file)
--- 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.
 
 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);
 \S{backend-colours} \cw{colours()}
 
 \c float *(*colours)(frontend *fe, game_state *state, int *ncolours);


@@ -1161,8 +1166,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
 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
 
 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


@@ -1436,12 +1440,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.
 
 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)}
 
 
 \dt \cw{BUTTON_BEATS(x,y)}
 


@@ -1473,7 +1477,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
 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
 
 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


@@ -3039,9 +3043,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.
 
 \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
 
 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


@@ -4115,9 +4119,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
 
 \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}.
 
 
 \b In \cw{free_drawstate()}, free the blitter if it's not \cw{NULL}.