This is a snapshot of a work-in-progress documentation theme. If you feel lost, miss something, or want to see the original Doxygen docs instead, head over to the archived version of this documentation page.

Magnum::TextureTools namespace

Texture tools.

Contents

Tools for generating, compressing and optimizing textures.

This library is built if WITH_TEXTURETOOLS is enabled when building Magnum. To use this library with CMake, you need to request the TextureTools component of the Magnum package in CMake and link to the Magnum::TextureTools target:

find_package(Magnum REQUIRED TextureTools)

# ...
target_link_libraries(your-app Magnum::TextureTools)

See Downloading and building and Usage with CMake for more information.

Functions

auto atlas(const Vector2i& atlasSize, const std::vector<Vector2i>& sizes, const Vector2i& padding = Vector2i()) -> std::vector<Range2Di>
Pack textures into texture atlas.
void distanceField(Texture2D& input, Texture2D& output, const Range2Di& rectangle, Int radius, const Vector2i& imageSize = Vector2i())
Create signed distance field.

Function documentation

std::vector<Range2Di> Magnum::TextureTools::atlas(const Vector2i& atlasSize, const std::vector<Vector2i>& sizes, const Vector2i& padding = Vector2i())

Pack textures into texture atlas.

Parameters
atlasSize Size of resulting atlas
sizes Sizes of all textures in the atlas
padding Padding around each texture

Packs many small textures into one larger. If the textures cannot be packed into required size, empty vector is returned.

Padding is added twice to each size and the atlas is laid out so the padding don't overlap. Returned sizes are the same as original sizes, i.e. without the padding.

void Magnum::TextureTools::distanceField(Texture2D& input, Texture2D& output, const Range2Di& rectangle, Int radius, const Vector2i& imageSize = Vector2i())

Create signed distance field.

Parameters
input Input texture
output Output texture
rectangle Rectangle in output texture where to render
radius Max lookup radius in input texture
imageSize Input texture size. Needed only in OpenGL ES, in desktop OpenGL the information is gathered automatically using Texture2D::imageSize().

Converts binary image (stored in red channel of input) to signed distance field (stored in red channel in rectangle of output). The purpose of this function is to convert high-resolution binary image (such as vector artwork or font glyphs) to low-resolution grayscale image. The image will then occupy much less memory and can be scaled without aliasing issues. Additionally it provides foundation for features like outlining, glow or drop shadow essentially for free.

You can also use the magnum-distancefieldconverter utility to do distance field conversion on command-line. By extension, this functionality is also provided through magnum-fontconverter utility.

The algorithm

For each pixel inside rectangle the algorithm looks at corresponding pixel in input and tries to find nearest pixel of opposite color in area given by radius. Signed distance between the points is then saved as value of given pixel in output. Value of 1.0 means that the pixel was originally colored white and nearest black pixel is farther than radius, value of 0.0 means that the pixel was originally black and nearest white pixel is farther than radius. Values around 0.5 are around edges.

The resulting texture can be used with bilinear filtering. It can be converted back to binary form in shader using e.g. GLSL smoothstep() function with step around 0.5 to create antialiased edges. Or you can exploit the distance field features to create many other effects. See also Shaders::DistanceFieldVector.

Based on: Chris Green - Improved Alpha-Tested Magnification for Vector Textures and Special Effects, SIGGRAPH 2007, http://www.valvesoftware.com/publications/2007/SIGGRAPH2007_AlphaTestedMagnification.pdf