pd.if.org Git - hexagon/blob - hexagon.pod

   1 =head1 NAME
   2
   3         hexlib - a library for hexagon grids
   4
   5 =head1 SYNOPSIS
   6
   7         #include <hexagon.h>
   8
   9 =head1 DESCRIPTION
  10
  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.
  17
  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.
  22
  23 =head2 Hexagon grid functions
  24
  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.
  28
  29 =head3 int HL_cantor(int x, int y)
  30
  31 Converts a two dimensional coordinate to a canonical id.
  32
  33         int hex;
  34         hex = HL_cantor(1,1); /* hex == 5 */
  35
  36 =head3 int HL_cantor_x(int cantor);
  37
  38 Returns the X coordinate of a hex identified by the given cantor id.
  39
  40         int x = HL_cantor_x(5); /* x == 1 */
  41
  42 =head2 Pathfinding
  43
  44 The library provides an A* implementation for pathfinding on
  45 a hex grid.
  46
  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);
  52
  53
  54 =head3 struct HL_astar *HL_astar_init(HL_astar *state);
  55
  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.
  59
  60 =head3 void HL_astar_free(HL_astar *state);
  61
  62 Frees any memory allocated by the structure.
  63
  64 =head1 OPTIONS
  65
  66 =head1 DIAGNOSTICS
  67
  68 =head1 BUGS
  69
  70 =head1 AUTHOR
  71
  72 This library was entirely written by Nathan Wagner.
  73
  74 =head1 COPYRIGHT
  75
  76 This library and the source code for it are released into
  77 the public domain.  The author asserts no copyright claim
  78 of any kind.
  79
  80 =head1