tess¶

tess is a library for working with hexagonally tiled maps. It provides functions for working with hexagonal norms as well as converting between hex coordinates and pixel coordinates, and many other utilities. The library is largely inspired by Amit Patel’s blog post on the matter.

installation¶

tess is a template library, so all that really needs to be done is to copy the header files into a directory where your project can see them. This may mean copying the files directly into your project’s include directory, or copying them to a global directory that your project knows to look in when compiling. The source can be found on github.

basic usage¶

This simple example will cover basic usage of the library by using a set of tiles to draw a grid. The example uses the SFML library and its source can be found here.

We’ll start out by declaring some basic settings, then initializing some utilities we’ll need to use. We’ll use Basis to convert pixel coordinates in screen space into hex coordinates in local space and vice versa.

return shape;


main()

// local variabeles for screen width and height and grid unit size
constexpr char window_name[] = "tess simple example";
constexpr int width = 800;
constexpr int height = 600;
constexpr int unit_size = 50;

Next, we’ll need to calculate the vertices of a hex in screen space in order to draw it to the screen. Thankfully, tess has a function just for that, but we still need to translate it into SFML’s interface. So here’s a here’s a helper function to do that.

namespace views = std::views;
namespace ranges = std::ranges;

// convert a hex coordinate to an sfml shape
sf::ConvexShape hex_shape(const tess::Basis<float>& basis,
                          const tess::ihex& h)
{
    sf::ConvexShape shape{6};
    const auto verts = basis.vertices(h);

    // add each vertex to the shape
    for (const int i : views::iota(0, 6)) {
        shape.setPoint(i, sf::Vector2f(verts[i].x, verts[i].y));

Now we can use hex_range to create a set of hex coordinates within a given radius of a center point. We’ll use this with our helper function to draw a hexagonal grid.

sf::RenderWindow window{sf::VideoMode(width, height), window_name,
                        sf::Style::Titlebar | sf::Style::Close};

// Create the basis for the grid, centered in the middle of the screen
tess::Basis<float> basis{ tess::point{ width/2, height/2 },
                          unit_size };

// initialize the hexes we're working with
// and set some basic graphical settings

From here we can just use a trivial SFML event loop to get a working program. After polling the events, we can draw the hexes.

onstexpr std::size_t num_hexes = 37;
td::vector<sf::ConvexShape> shapes;
hapes.reserve(num_hexes);

anges::transform(tess::hex_range(tess::ihex::zero, 3),
                 hex_shape_fn(basis), std::back_inserter(shapes));

The full source code for this example can once again be found here, and a more complex example can be found here. There is also a CMake file to compile these examples.

documentation¶

math functions¶

Warning

doxygenfunction: Cannot find function “tess::norm” in doxygen xml output for project “tess” from directory: doxygen/xml

Warning

doxygenfunction: Cannot find function “tess::normf” in doxygen xml output for project “tess” from directory: doxygen/xml

Warning

doxygenfunction: Cannot find function “tess::sqnorm” in doxygen xml output for project “tess” from directory: doxygen/xml

Warning

doxygenfunction: Cannot find function “tess::hex_norm” in doxygen xml output for project “tess” from directory: doxygen/xml

Warning

doxygenfunction: Cannot find function “tess::hex_round” in doxygen xml output for project “tess” from directory: doxygen/xml

Warning

doxygenfunction: Cannot find function “tess::line” in doxygen xml output for project “tess” from directory: doxygen/xml

Warning

doxygenfunction: Cannot find function “tess::hex_range” in doxygen xml output for project “tess” from directory: doxygen/xml

point¶

Warning

doxygenclass: Cannot find class “tess::Point” in doxygen xml output for project “tess” from directory: doxygen/xml

hex¶

Warning

doxygenclass: Cannot find class “tess::Hex” in doxygen xml output for project “tess” from directory: doxygen/xml

basis¶

Warning

doxygenclass: Cannot find class “tess::Basis” in doxygen xml output for project “tess” from directory: doxygen/xml