[gnugo-devel] changed genmove() interface

[Gunnar Farnebäck]

The current interface to the genmove() style functions looks something
like

int i, j;
int value = genmove(&i, &j, color);

where 'color' is the color to move, 'value' is the value of the move,
and 'i', 'j' are the 2D coordinates of the generated move. Afterwards
'value' is tested whether it's negative to see if genmove() wants to
resign, unless (i, j) is a pass move, when it wants to pass.
Unfortunately there are still some pieces of code which don't know
about resign and check value<0 to see if genmove() wants to pass, and
get very confused when it was in fact a resignation signal.

Anyway, this interface isn't very good, for the following reasons:
(1) We should move away from the last few uses of 2D coordinates.
(2) The return value is an int but internally genmove() uses floats.
(3) It makes more sense to return the move rather than the move value.
(4) There's no way to signal resign and simultaneously pass.

The patch gunnar_7_1.15, posted on the web page, changes the interface
to

float value;
int resign;
int move = genmove(color, &value, &resign);

with the following semantics:

1. The recommended move is returned by the function. Check
   move == PASS_MOVE to determine if genmove() wants to pass.
2. Value is the internal value of the move. Don't test this value for
   anything. It is only useful for debug output and in some contexts
   for comparison against other move values. Pass a NULL pointer if
   you don't care about the move value.
3. To determine whether genmove() wants to resign, check if 'resign'
   is true. Pass a NULL pointer if you don't care.

/Gunnar