13 * GNU General Public License for more details. |
13 * GNU General Public License for more details. |
14 * |
14 * |
15 * You should have received a copy of the GNU General Public License |
15 * You should have received a copy of the GNU General Public License |
16 * along with this program; if not, write to the Free Software |
16 * along with this program; if not, write to the Free Software |
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
|
18 */ |
|
19 |
|
20 /** |
|
21 * Functions for querying a map preview from the engine, which includes both a two-color image |
|
22 * and the number of hogs this map is suitable for. |
|
23 * |
|
24 * The general usage is to first create a mapconn object by calling flib_mapconn_create. |
|
25 * That will cause the frontlib to listen on a random port which can be queried using |
|
26 * flib_mapconn_getport(). You should also register your callback functions right at the start |
|
27 * to ensure you don't miss any callbacks. |
|
28 * |
|
29 * Next, start the engine (that part is up to you) with the appropriate command line arguments |
|
30 * for a map preview request. |
|
31 * |
|
32 * In order to allow the mapconn to run, you should regularly call flib_mapconn_tick(), which |
|
33 * performs network I/O and calls your callbacks if the map has been generated or an error |
|
34 * has occurred. Once either the onSuccess or onFailure callback is called, you should destroy |
|
35 * the mapconn and stop calling tick(). |
18 */ |
36 */ |
19 |
37 |
20 #ifndef IPC_MAPCONN_H_ |
38 #ifndef IPC_MAPCONN_H_ |
21 #define IPC_MAPCONN_H_ |
39 #define IPC_MAPCONN_H_ |
22 |
40 |
36 * engine process. Once this connection is established, the required information |
54 * engine process. Once this connection is established, the required information |
37 * will be sent to the engine, and the reply is read. |
55 * will be sent to the engine, and the reply is read. |
38 * |
56 * |
39 * The map must be a regular, maze or drawn map - for a preview of a named map, |
57 * The map must be a regular, maze or drawn map - for a preview of a named map, |
40 * use the preview images in the map's directory, and for the hog count read the |
58 * use the preview images in the map's directory, and for the hog count read the |
41 * map information (flib_mapcfg_read). |
59 * map information (e.g. using flib_mapcfg_read). |
42 * |
60 * |
43 * No NULL parameters allowed, returns NULL on failure. |
61 * No NULL parameters allowed, returns NULL on failure. |
44 * Use flib_mapconn_destroy to free the returned object. |
62 * Use flib_mapconn_destroy to free the returned object. |
45 */ |
63 */ |
46 flib_mapconn *flib_mapconn_create(const flib_map *mapdesc); |
64 flib_mapconn *flib_mapconn_create(const flib_map *mapdesc); |
57 */ |
75 */ |
58 int flib_mapconn_getport(flib_mapconn *conn); |
76 int flib_mapconn_getport(flib_mapconn *conn); |
59 |
77 |
60 /** |
78 /** |
61 * Set a callback which will receive the rendered map if the rendering succeeds. |
79 * Set a callback which will receive the rendered map if the rendering succeeds. |
62 * You can pass callback=NULL to unset a callback. |
|
63 * |
80 * |
64 * Expected callback signature: |
81 * Expected callback signature: |
65 * void handleSuccess(void *context, const uint8_t *bitmap, int numHedgehogs) |
82 * void handleSuccess(void *context, const uint8_t *bitmap, int numHedgehogs) |
66 * |
83 * |
67 * The context passed to the callback is the same pointer you provided when |
84 * The context passed to the callback is the same pointer you provided when |
75 */ |
92 */ |
76 void flib_mapconn_onSuccess(flib_mapconn *conn, void (*callback)(void* context, const uint8_t *bitmap, int numHedgehogs), void *context); |
93 void flib_mapconn_onSuccess(flib_mapconn *conn, void (*callback)(void* context, const uint8_t *bitmap, int numHedgehogs), void *context); |
77 |
94 |
78 /** |
95 /** |
79 * Set a callback which will receive an error message if rendering fails. |
96 * Set a callback which will receive an error message if rendering fails. |
80 * You can pass callback=NULL to unset a callback. |
|
81 * |
97 * |
82 * Expected callback signature: |
98 * Expected callback signature: |
83 * void handleFailure(void *context, const char *errormessage) |
99 * void handleFailure(void *context, const char *errormessage) |
84 * |
100 * |
85 * The context passed to the callback is the same pointer you provided when |
101 * The context passed to the callback is the same pointer you provided when |