# How regions work: The Gory Details
#
# Filled and stroked regions are exactly the same thing, a closed
# path that runs along the edge of a bunch of hexes. The only
# differences are what you set your styles to and whether you call
# $pdf->fill or $pdf->stroke at the end.
#
# With that out of the way, how do we know where to draw the path
# to make it continuous and closed?
#
# First, tell the user *precisely* how to describe a region:
# Draw a line through each hex inside the region that is along the
# outer border, starting at the lowest-numbered hex in the
# lowest-numbered column and going clockwise around the region until
# you're back at the start, recording the hex numbers as you go,
# including duplicates. The list will always end with the starting
# hex.
#
# This procedure gives us a guaranteed starting place for the path.
# By definition, the hexes to the Lower Left (0), Upper Left (1), and
# Above (2) the starting hex cannot be inside the region, so we can
# always draw along those edges, in that order. The next border hex
# must be one of Upper Right (3), Lower Right (4), or Under (5).
#
# If the next border hex is Upper Right (3), then from its point of
# view, the hex in Lower Left (0) is guaranteed to be inside, and
# it should begin checking at Upper Left (1), and draw around clockwise
# until it finds another border hex.
#
# This is a lot easier to follow with pictures, so I'll have to draw
# one and distribute it with the script. Users should be able to get
# by with the text instructions, fortunately.
#
# The "neighbor numbers" work out nicely, such that to your neighbor
# in N, you are the neighbor in (N + 3) % 6, and he should test his
# neighbors starting with (N + 4) % 6, in increasing order until he
# hits his first neighbor (which will always be the next hex on the
# list).
#
# For the starting hex only, we have to keep a bit of extra state,
# to keep the path from overlapping itself. If we're not visiting
# it for the first time, we will stop testing neighbors at (5), no
# matter where we start, because (0) has already been drawn.
