3 hexlib - a library for hexagon grids
11 hexagon is a C library for performing calculations on hexagon grids.
12 Hexagons are represented by their canonical ID, which is a single
13 integer representation of their two dimensional coordinates.
14 Algorithms and functions are provided for calculating hexagon
15 centers, vertexes, and distances on the grid. An A* algorithm
16 is also implemented for pathfinding.
18 The canonical integer id of a hexagon is computed from its
19 two dimensional integer coordinates using a modified
20 cantor pairing function. The canonical integer ids are
21 referred to as cantors.
23 =head2 Hexagon grid functions
25 The hexagon grid is constrained to be a vertical grid, with
26 the hexagon at (2,1) being to the right and half a hex below
27 the hex at (1,1). Horizontal grid layouts are not supported.
29 =head3 int HL_cantor(int x, int y)
31 Converts a two dimensional coordinate to a canonical id.
34 hex = HL_cantor(1,1); /* hex == 5 */
36 =head3 int HL_cantor_x(int cantor);
38 Returns the X coordinate of a hex identified by the given cantor id.
40 int x = HL_cantor_x(5); /* x == 1 */
44 The library provides an A* implementation for pathfinding on
47 struct HL_astar *state;
48 state = HL_astar_init(NULL);
49 state->start = HL_cantor_xy(1,1);
50 state->goal = HL_cantor_xy(4,14);
51 int length = HL_astar_findpath(state,0);
54 =head3 struct HL_astar *HL_astar_init(HL_astar *state);
56 Initializes the given state. You can either pass in a pointer to your
57 own data structure, or pass in NULL, in which case the library
58 will use malloc(3) to create a new structure.
60 =head3 void HL_astar_free(HL_astar *state);
62 Frees any memory allocated by the structure.
72 This library was entirely written by Nathan Wagner.
76 This library and the source code for it are released into
77 the public domain. The author asserts no copyright claim