Forgot to update devel.but in r6417.

[sgt/puzzles] / devel.but

diff --git a/devel.but b/devel.but
index 5017766..4f589da 100644 (file)
--- 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.
 
 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()}
 
 \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.
 
 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].
 
 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
 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
 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


@@ -1402,16 +1398,12 @@ 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)(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).
 
 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;
 \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.
 
 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 +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
 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


@@ -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
 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
 
 When drawing, the puzzle window is indexed by pixel coordinates,
 with the top left pixel defined as \cw{(0,0)} and the bottom right


@@ -3040,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.
 
 \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


@@ -4051,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         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     }
 \c             ds->symbol_at_position[y][x] = value;
 \c         }
 \c     }


@@ -4116,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
 
 \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}.