1 /*

     2  * Hedgewars, a free turn based strategy game

     3  * Copyright (C) 2012 Simeon Maxein <smaxein@googlemail.com>

     4  *

     5  * This program is free software; you can redistribute it and/or

     6  * modify it under the terms of the GNU General Public License

     7  * as published by the Free Software Foundation; either version 2

     8  * of the License, or (at your option) any later version.

     9  *

    10  * This program is distributed in the hope that it will be useful,

    11  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    13  * GNU General Public License for more details.

    14  *

    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

    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().

    36  */

    37 

    38 #ifndef IPC_MAPCONN_H_

    39 #define IPC_MAPCONN_H_

    40 

    41 #include "../model/map.h"

    42 

    43 #include <stdint.h>

    44 

    45 #define MAPIMAGE_WIDTH 256

    46 #define MAPIMAGE_HEIGHT 128

    47 #define MAPIMAGE_BYTES (MAPIMAGE_WIDTH/8*MAPIMAGE_HEIGHT)

    48 

    49 typedef struct _flib_mapconn flib_mapconn;

    50 

    51 /**

    52  * Start a new map rendering connection (mapconn). This means a listening socket

    53  * will be started on a random unused port, waiting for a connection from the

    54  * engine process. Once this connection is established, the required information

    55  * will be sent to the engine, and the reply is read.

    56  *

    57  * The map must be a regular, maze or drawn map - for a preview of a named map,

    58  * use the preview images in the map's directory, and for the hog count read the

    59  * map information (e.g. using flib_mapcfg_read).

    60  *

    61  * No NULL parameters allowed, returns NULL on failure.

    62  * Use flib_mapconn_destroy to free the returned object.

    63  */

    64 flib_mapconn *flib_mapconn_create(const flib_map *mapdesc);

    65 

    66 /**

    67  * Destroy the mapconn object. Passing NULL is allowed and does nothing.

    68  * flib_mapconn_destroy may be called from inside a callback function.

    69  */

    70 void flib_mapconn_destroy(flib_mapconn *conn);

    71 

    72 /**

    73  * Returns the port on which the mapconn is listening. Only fails if you

    74  * pass NULL (not allowed), in that case 0 is returned.

    75  */

    76 int flib_mapconn_getport(flib_mapconn *conn);

    77 

    78 /**

    79  * Set a callback which will receive the rendered map if the rendering succeeds.

    80  *

    81  * Expected callback signature:

    82  * void handleSuccess(void *context, const uint8_t *bitmap, int numHedgehogs)

    83  *

    84  * The context passed to the callback is the same pointer you provided when

    85  * registering the callback. bitmap is a pointer to a buffer of size MAPIMAGE_BYTES

    86  * containing a bit-packed image of size MAPIMAGE_WIDTH * MAPIMAGE_HEIGHT.

    87  * numHedgehogs is the number of hogs that fit on this map.

    88  *

    89  * The bitmap pointer passed to the callback belongs to the caller,

    90  * so it should not be stored elsewhere. Note that it remains valid

    91  * inside the callback method even if flib_mapconn_destroy is called.

    92  */

    93 void flib_mapconn_onSuccess(flib_mapconn *conn, void (*callback)(void* context, const uint8_t *bitmap, int numHedgehogs), void *context);

    94 

    95 /**

    96  * Set a callback which will receive an error message if rendering fails.

    97  *

    98  * Expected callback signature:

    99  * void handleFailure(void *context, const char *errormessage)

   100  *

   101  * The context passed to the callback is the same pointer you provided when

   102  * registering the callback.

   103  *

   104  * The error message passed to the callback belongs to the caller,

   105  * so it should not be stored elsewhere. Note that it remains valid

   106  * inside the callback method even if flib_mapconn_destroy is called.

   107  */

   108 void flib_mapconn_onFailure(flib_mapconn *conn, void (*callback)(void* context, const char *errormessage), void *context);

   109 

   110 /**

   111  * Perform I/O operations and call callbacks if something interesting happens.

   112  * Should be called regularly.

   113  */

   114 void flib_mapconn_tick(flib_mapconn *conn);

   115 

   116 #endif