Added some horizontal grid constants.

[hexagon] / doc / hexagon.pod

diff --git a/doc/hexagon.pod b/doc/hexagon.pod
index 9dfc4ae6074662a00b39e3fe680b1cc50cf49e52..d5a6e4b61a81e6ba1ce2fdec672160193b2c1a6b 100644 (file)
--- a/doc/hexagon.pod
+++ b/doc/hexagon.pod
@@ -44,23 +44,36 @@ above system.
 
 Many games and displays use a positive Y down, rather than the
 usual mathematical positive Y up.  The library uses the mathematical
-convention.  To convert to a positive Y down, you can take the
-negative of the Y coordinate as given by the library.  See the HL_hexbin()
-example below.
+convention.  In general though, this will not matter.  The Y coordinate
+of the hex centers has the same direction as the Y coordinate of the
+hex grid.  If your display is Y down, and your grid is too, you can
+use the coordinates as given.  If your display is Y up and you want
+your grid to be Y down, you will, obviously, need to invert the Y
+coordinates for display, and re-invert them when passing them back to
+the library.
+
+To convert to a positive Y down, you can take the negative of the Y coordinate
+as given by the library.  See the HL_hexbin() example below.
 
 =head3 Horizontal Grids
 
-A horizontal grid layout can be created by either rotating the
-given coordinates by 90 degrees, or, equivalently, swapping the X and
-Y coordinates as given by the library.  Obviously, you will need to
-swap them when passing them into the library also.  You may also
-need to invert the Y coordinate as above for display.
+A horizontal grid layout can be created by either rotating the given
+coordinates by 90 degrees, or, equivalently, swapping the X and Y coordinates
+as given by the library.  Obviously, you will need to swap them when passing
+them into the library also.  You may also need to invert the (resulting) Y
+coordinate as above for display if your display is positive Y down.
 
-=head2 Hexagon grid functions
+=head2 Hexagon IDs
 
-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.
+Two dimensional hex locations are converted into a single integer
+hexagon ID with a pairing function.  A pairing function uniquely
+and reversably maps two integers onto one integer.  At the moment,
+only a modified Cantor's original triangular pairing function,
+extended to handle negative integers,
+is available.
+
+As most hexagon grids will only use positive coordinates, additional
+pairing functions will be provided in the future.
 
 =head3 int HL_cantor(int x, int y)
 
@@ -69,6 +82,12 @@ Converts a two dimensional coordinate to a canonical id.
        int hex;
        hex = HL_cantor(1,1); /* hex == 5 */
 
+=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_x(int cantor);
 
 Returns the X coordinate of a hex identified by the given cantor id.
@@ -104,6 +123,33 @@ is because the X axis passes through the center of the even columns,
 so the negation works, but it passes along the edge of the odd columns,
 and you end up with an off by one error.
 
+=head2 Hexagon data
+
+Some pre-calculated data is available.
+
+=head3 double HL_fand[16]
+
+An array of hexagon coordinates, with the hex center x,y at indexes 0 and
+1 (these are 0.0,0.0), and each vertex following.  The first vertex
+is repeated at the end of the array.  Each vertex takes up two consecutive
+array elements for it's X and Y coordinates.  Thus for hex vertexes 1 to
+6, and hex center C this array is CxCy1x1y2x2y3x3y4x4y5x5y6x6y1x1y.
+This is suitable for passing directly to opengl for drawing a hexagon
+as a triangle fan.
+
+=head3 float HL_fanf[16]
+
+An array of floats, laid out the same way as HL_fand.
+
+=head3 double HL_hfand[16]
+
+This is the same as HL_fand, but will draw a horizontal hex.  The same
+effect could be had by rotating 90 degrees.
+
+=head3 float HL_hfanf[16]
+
+An array of float with horizontal layout.
+
 =head2 Pathfinding
 
 The library provides an A* implementation for pathfinding on