=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