Improved astar api. Added doc file.

[hexagon] / hexagon.pod

diff --git a/hexagon.pod b/hexagon.pod
new file mode 100644 (file)
index 0000000..4b41483
--- /dev/null
+++ b/hexagon.pod
@@ -0,0 +1,80 @@
+=head1 NAME
+
+       hexlib - a library for hexagon grids
+
+=head1 SYNOPSIS
+
+       #include <hexagon.h>
+
+=head1 DESCRIPTION
+
+hexagon is a C library for performing calculations on hexagon grids.
+Hexagons are represented by their canonical ID, which is a single
+integer representation of their two dimensional coordinates.
+Algorithms and functions are provided for calculating hexagon
+centers, vertexes, and distances on the grid.  An A* algorithm
+is also implemented for pathfinding.
+
+The canonical integer id of a hexagon is computed from its
+two dimensional integer coordinates using a modified
+cantor pairing function.  The canonical integer ids are
+referred to as cantors.
+
+=head2 Hexagon grid functions
+
+The hexagon grid is constrained to be a vertical grid, with
+the hexagon at (2,1) being to the right and half a hex below
+the hex at (1,1).  Horizontal grid layouts are not supported.
+
+=head3 int HL_cantor(int x, int y)
+
+Converts a two dimensional coordinate to a canonical id.
+
+       int hex;
+       hex = HL_cantor(1,1); /* hex == 5 */
+
+=head3 int HL_cantor_x(int cantor);
+
+Returns the X coordinate of a hex identified by the given cantor id.
+
+       int x = HL_cantor_x(5); /* x == 1 */
+
+=head2 Pathfinding
+
+The library provides an A* implementation for pathfinding on
+a hex grid.
+
+       struct HL_astar *state;
+       state = HL_astar_init(NULL);
+       state->start = HL_cantor_xy(1,1);
+       state->goal = HL_cantor_xy(4,14);
+       int length = HL_astar_findpath(state,0);
+
+
+=head3 struct HL_astar *HL_astar_init(HL_astar *state);
+
+Initializes the given state.  You can either pass in a pointer to your
+own data structure, or pass in NULL, in which case the library
+will use malloc(3) to create a new structure.
+
+=head3 void HL_astar_free(HL_astar *state);
+
+Frees any memory allocated by the structure.
+
+=head1 OPTIONS
+
+=head1 DIAGNOSTICS
+
+=head1 BUGS
+
+=head1 AUTHOR
+
+This library was entirely written by Nathan Wagner.
+
+=head1 COPYRIGHT
+
+This library and the source code for it are released into
+the public domain.  The author asserts no copyright claim
+of any kind.
+
+=head1