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.

// local variabeles for screen width and height and grid unit size
int const width = 800;
int const height = 600;
int const unit_size = 50;

// Create the window, but make sure it's not resizeable
sf::RenderWindow window{sf::VideoMode(width, height), "tess simple example",
                        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};

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.

sf::ConvexShape hex_shape(const tess::Basis<float>& basis, const tess::Hex<>& hex)
{
    sf::ConvexShape shape{6};

    // calcualte the vertices
    auto verts = basis.vertices(hex);

    // add each vertex to the shape
    for (int i = 0; i < verts.size(); i++) {
        shape.setPoint(i, sf::Vector2f(verts[i].x(), verts[i].y()));
    }
    return shape;
}

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.

// initialize the hexes we're working with
// and set some basic graphical settings
std::vector<sf::ConvexShape> shapes;
for (const auto& hex : tess::hex_range(tess::Hex<>::zero, 3)) {
    auto shape = hex_shape(basis, hex);
    shape.setOutlineColor(sf::Color::Black);
    shape.setOutlineThickness(1.0f);
    shapes.push_back(shape);
}

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.

// draw the hexes
window.clear();
for (const auto& hex : shapes) {
    window.draw(hex);
}
window.display();

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