Magnum::TextureTools::DistanceField class
#include <Magnum/TextureTools/DistanceField.h>

Create a signed distance field.

Converts a binary black/white image (stored in the red channel of input) to a signed distance field (stored in the red channel of output rectangle). The purpose of this function is to convert a high-resolution binary image (such as vector artwork or font glyphs) to a 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. This functionality is also used inside the magnum-fontconverter utility.

The algorithm

For each pixel inside the output sub-rectangle the algorithm looks at corresponding pixel in the input and tries to find nearest pixel of opposite color in an area defined 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::DistanceFieldVectorGL.

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

Constructors, destructors, conversion operators

DistanceField(UnsignedInt radius) explicit: Constructor.
DistanceField(NoCreateT) explicit noexcept new in Git master: Construct without creating the internal OpenGL state.
DistanceField(const DistanceField&) deleted: Copying is not allowed.
DistanceField(DistanceField&&) noexcept new in Git master: Move constructor.

Public functions

auto operator=(const DistanceField&) -> DistanceField& deleted: Copying is not allowed.
auto operator=(DistanceField&&) -> DistanceField& noexcept: Move constructor.
auto radius() const -> UnsignedInt: Max lookup radius.
void operator()(GL::Texture2D& input, GL::Framebuffer& output, const Range2Di& rectangle, const Vector2i& imageSize = {}) new in Git master: Calculate the distance field to a framebuffer.
void operator()(GL::Texture2D& input, GL::Texture2D& output, const Range2Di& rectangle, const Vector2i& imageSize = {}): Calculate the distance field to a texture.

Function documentation

Magnum::TextureTools::DistanceField::DistanceField(UnsignedInt radius) explicit

Constructor.

Parameters
radius	Max lookup radius in the input texture

Prepares the shader and other internal state for given radius.

Magnum::TextureTools::DistanceField::DistanceField(NoCreateT) explicit noexcept new in Git master

Construct without creating the internal OpenGL state.

The constructed instance is equivalent to moved-from state, i.e. no APIs can be safely called on the object. Useful in cases where you will overwrite the instance later anyway. Move another object over it to make it useful.

This function can be safely used for constructing (and later destructing) objects even without any OpenGL context being active. However note that this is a low-level and a potentially dangerous API, see the documentation of NoCreate for alternatives.

Magnum::TextureTools::DistanceField::DistanceField(DistanceField&&) noexcept new in Git master

Move constructor.

Performs a destructive move, i.e. the original object isn't usable afterwards anymore.

void Magnum::TextureTools::DistanceField::operator()(GL::Texture2D& input, GL::Framebuffer& output, const Range2Di& rectangle, const Vector2i& imageSize = {}) new in Git master

Calculate the distance field to a framebuffer.

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

The output texture is expected to have a framebuffer-drawable GL::TextureFormat. On desktop OpenGL and OpenGL ES 3.0 it's common to render to GL::TextureFormat::R8. On OpenGL ES 2.0 you can use GL::TextureFormat::Red if EXT_texture_rg is available; if not, the smallest but still inefficient supported format is in most cases GL::TextureFormat::RGB. The GL::TextureFormat::Luminance format usually isn't renderable.

Additionally, the ratio of the input size (or imageSize on OpenGL ES) and rectangle size is expected to be a multiple of 2, as that's what the generator shader relies on for correct pixel addressing.

void Magnum::TextureTools::DistanceField::operator()(GL::Texture2D& input, GL::Texture2D& output, const Range2Di& rectangle, const Vector2i& imageSize = {})

Calculate the distance field to a texture.

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

Creates a framebuffer with output attached and calls operator()(GL::Texture2D&, GL::Framebuffer&, const Range2Di&, const Vector2i&).