Font

High-level font loading and glyph management.

Overview

Typical use cases:

• Loading a font from a TTF file or memory buffer to a SDF atlas

• Retrieving glyph data for rendering text

• Managing font options such as size and type

Header

<RaeptorCogs/IO/Font.hpp>

Metadata

Author

Estorc

Version

v1.0

Copyright

Copyright (c) 2025 Estorc MIT License.

Enums

Enumerations

Enum	Description
RaeptorCogs::FontType	Enumeration of font types.

enum class RaeptorCogs::FontType

Enumeration of font types.

Defines the supported font rendering types.

Values:

enumerator BITMAP

Bitmap font type.

enumerator SDF

Signed Distance Field font type.

Structs

Structures

Struct	Description
RaeptorCogs::Font::OnLoadProxy	Proxy structure for onLoad callback.
RaeptorCogs::FontOptions	Font options structure.

struct OnLoadProxy

Proxy structure for onLoad callback.

Allows setting a callback function that is invoked when the font is loaded.

Public Functions

inline void operator=(std::function<void()> fn)

Assignment operator to set the onLoad callback.

Note

If the font is already loaded, the callback is invoked immediately.

Parameters:

fn – Callback function to be invoked when the font is loaded.

Public Members

std::shared_ptr<FontBase> ptr

Shared pointer to the FontBase instance.

Used to access the onLoad_ member of FontBase.

Note

Used internally by the OnLoadProxy structure.

struct FontOptions

Font options structure.

Used to specify options when loading a font.

FontOptions options;
options.type = FontType::SDF;
options.size = 48;
Font font("path/to/font.ttf", options);

Public Members

FontType type = FontType::SDF

Type of the font.

See also

FontType

Note

Defaults to SDF.

float size = NORMAL_FONT_SIZE

Size of the font in pixels.

Note

Defaults to NORMAL_FONT_SIZE.

int priority = 0

Loading priority of the font.

Priority determines the order in which fonts are loaded when multiple fonts are requested simultaneously.

Classes

Classes

Class	Description
RaeptorCogs::Font	High-level Font handler class.
RaeptorCogs::FontBase	Base class for font handling.
RaeptorCogs::GlyphData	Glyph data structure.

class Font

High-level Font handler class.

Provides a user-friendly interface for loading and managing fonts. Encapsulates a shared pointer to FontBase for resource management.

FontOptions options;
options.type = FontType::SDF;
options.size = 48;
Font font("path/to/font.ttf", options);
font.bind();
uint32_t textureID = font.getID();
GlyphData* glyph = font.getGlyph("A");

Public Functions

inline Font()

Default constructor for Font.

Initializes an empty Font instance.

inline Font(nullptr_t)

Constructor for Font from nullptr.

Initializes an empty Font instance.

inline Font(std::shared_ptr<FontBase> p)

Constructor for Font from a shared pointer to FontBase.

Note

Used internally for advanced use cases.

Parameters:

p – Shared pointer to an existing FontBase instance.

inline Font(const FileData &ttf_buffer, FontOptions options = FontOptions())

Constructor for Font from a TTF buffer.

Note

Loads the font asynchronously.

Parameters:

• ttf_buffer – Buffer containing TTF font data.

• options – Font loading options.

inline Font(std::filesystem::path fontPath, FontOptions options = FontOptions())

Constructor for Font from a TTF file path.

Note

Loads the font asynchronously.

Parameters:

• fontPath – Path to the TTF font file.

• options – Font loading options.

inline const FontBase &get() const

Dereference operators for Font.

Provides access to the underlying FontBase instance.

Returns:

Reference or pointer to the FontBase instance.

inline const FontBase &operator*() const

Dereference operators for Font.

Provides access to the underlying FontBase instance.

Returns:

Reference or pointer to the FontBase instance.

inline const FontBase *operator->() const

Dereference operators for Font.

Provides access to the underlying FontBase instance.

Returns:

Reference or pointer to the FontBase instance.

inline FontBase &get()

Dereference operators for Font.

Provides access to the underlying FontBase instance.

Returns:

Reference or pointer to the FontBase instance.

inline FontBase &operator*()

Dereference operators for Font.

Provides access to the underlying FontBase instance.

Returns:

Reference or pointer to the FontBase instance.

inline FontBase *operator->()

Dereference operators for Font.

Provides access to the underlying FontBase instance.

Returns:

Reference or pointer to the FontBase instance.

inline explicit operator bool() const noexcept

Boolean conversion operator for Font.

Allows checking if the Font instance is valid (i.e., has an associated FontBase).

Returns:

true if the Font instance is valid, false otherwise.

Public Members

OnLoadProxy onLoad = {ptr}

On-load callback proxy.

Allows setting a callback function that is invoked when the font is loaded.

Font font("path/to/font.ttf");
font.onLoad = []() {
   std::cout << "Font loaded!" << std::endl;
};

Private Members

std::shared_ptr<FontBase> ptr

Shared pointer to the underlying FontBase instance.

Manages the lifetime of the FontBase object.

Note

Used internally by the Font class.

struct OnLoadProxy

Proxy structure for onLoad callback.

Allows setting a callback function that is invoked when the font is loaded.

Public Functions

inline void operator=(std::function<void()> fn)

Assignment operator to set the onLoad callback.

Note

If the font is already loaded, the callback is invoked immediately.

Parameters:

fn – Callback function to be invoked when the font is loaded.

Public Members

std::shared_ptr<FontBase> ptr

Shared pointer to the FontBase instance.

Used to access the onLoad_ member of FontBase.

Note

Used internally by the OnLoadProxy structure.

class FontBase

Base class for font handling.

Provides high-level functionality for loading fonts, managing glyphs, and binding font textures.

FontOptions options;
options.type = FontType::SDF;
options.size = 48;
Font font("path/to/font.ttf", options);
font.bind();
uint32_t textureID = font.getID();
GlyphData* glyph = font.getGlyph("A");

See also

Font

Note

Should not be used directly. Use the Font wrapper class instead.

Public Functions

~FontBase()

Destructor for FontBase.

Cleans up OpenGL resources associated with the font.

Note

Automatically called when the FontBase instance is destroyed.

FontBase(const FontBase&) = delete

Deleted copy constructor and assignment operator.

FontBase instances cannot be copied to prevent resource management issues.

FontBase &operator=(const FontBase&) = delete

FontBase(FontBase&&) noexcept = default

Defaulted move constructor and assignment operator.

FontBase instances can be moved to transfer ownership of resources.

FontBase &operator=(FontBase&&) noexcept = default

void bind() const

Bind the font for rendering. Binds the font’s texture to the current OpenGL context.

uint32_t getID() const

Get the OpenGL texture ID of the font atlas.

Note

Returns 0 if the font is not loaded.

Returns:

The OpenGL texture ID.

GlyphData *getGlyph(const U8Char character) const

Retrieve glyph data for a specific character.

Note

Supports Unicode characters via UTF-8 encoding.

Parameters:

character – Pointer to the UTF-8 encoded character.

Returns:

GlyphData* Pointer to the GlyphData for the character, or nullptr if not found.

glm::vec4 getGlyphUVRect(const U8Char character) const

Get the UV rectangle of a specific character’s glyph.

Parameters:

character – Pointer to the UTF-8 encoded character.

Returns:

UV rectangle (u0, v0, u1, v1) of the glyph.

glm::vec2 getGlyphOffset(const U8Char character) const

Get the offset of a specific character’s glyph.

Parameters:

character – Pointer to the UTF-8 encoded character.

Returns:

Offset (x_offset, y_offset) of the glyph in pixels.

glm::vec2 getGlyphSize(const U8Char character) const

Get the size of a specific character’s glyph.

Parameters:

character – Pointer to the UTF-8 encoded character.

Returns:

Size (width, height) of the glyph in pixels

float getGlyphXAdvance(const U8Char character) const

Get the horizontal advance of a specific character’s glyph.

Parameters:

character – Pointer to the UTF-8 encoded character.

Returns:

Horizontal advance (x_advance) of the glyph in pixels.

float getFontSize() const

Get the font size in pixels.

Returns:

Font size in pixels.

bool isLoaded() const

Check if the font is loaded.

Returns:

true if the font is loaded, false otherwise.

Private Functions

inline FontBase()

Private constructor for FontBase.

Use the handler class Font to create and manage FontBase instances.

void GenerateSDFAtlas(const unsigned char *ttf, unsigned char *data, size_t atlas_w, size_t atlas_h, float font_px, size_t num_chars)

Generate a Signed Distance Field (SDF) font atlas.

Note

This function populates the provided data buffer with the generated SDF atlas.

Parameters:

• ttf – Pointer to the TTF font data in memory.

• data – Pointer to the memory buffer where the atlas will be generated.

• atlas_w – Width of the atlas in pixels.

• atlas_h – Height of the atlas in pixels.

• font_px – Font size in pixels.

• num_chars – Number of characters to include in the atlas.

void GenerateBMPAtlas(const unsigned char *ttf, unsigned char *data, size_t atlas_w, size_t atlas_h, float font_px, size_t num_chars)

Generate a Bitmap font atlas.

Note

This function populates the provided data buffer with the generated Bitmap atlas.

Parameters:

• ttf – Pointer to the TTF font data in memory.

• data – Pointer to the memory buffer where the atlas will be generated.

• atlas_w – Width of the atlas in pixels.

• atlas_h – Height of the atlas in pixels.

• font_px – Font size in pixels.

• num_chars – Number of characters to include in the atlas.

void uploadTexture(const unsigned char *data, size_t width, size_t height)

Upload the font atlas texture to OpenGL.

Note

This function creates an OpenGL texture and uploads the provided pixel data.

Parameters:

• data – Pointer to the font atlas pixel data.

• width – Width of the atlas in pixels.

• height – Height of the atlas in pixels.

Private Members

std::function<void()> onLoad_

Callback function invoked when the font is loaded.

Can be set by the user to perform actions once the font is ready.

uint32_t textureID = 0

OpenGL texture ID for the font atlas.

Zero if the font is not loaded.

std::unordered_map<uint32_t, std::unique_ptr<GlyphData>> glyphs

Glyph map storing glyph data indexed by UTF-8 codepoints.

Supports Unicode characters by using a hash map.

float font_size

Font size in pixels.

Used for scaling glyphs appropriately.

Note

Corresponds to FontOptions::size.

FontType font_type

Type of the font.

Indicates whether the font is SDF or Bitmap.

Note

Corresponds to FontOptions::type.

Private Static Functions

static std::shared_ptr<FontBase> create(const FileData &ttf_buffer, FontOptions options = FontOptions())

Factory method to create a FontBase instance from a TTF buffer.

Parameters:

• ttf_buffer – Buffer containing TTF font data.

• options – Font loading options.

Returns:

Shared pointer to the created FontBase instance.

static std::shared_ptr<FontBase> create(const std::filesystem::path &fontPath, FontOptions options = FontOptions())

Factory method to create a FontBase instance from a TTF file path.

Parameters:

• fontPath – Path to the TTF font file.

• options – Font loading options.

Returns:

Shared pointer to the created FontBase instance.

Friends

friend class Font

class GlyphData

Glyph data structure.

Represents the metrics and texture coordinates of a single glyph in a font atlas.

 std::unique_ptr<GlyphData> glyph = std::make_unique<GlyphData>(
     packed_glyphs[i].x0 / (float)atlas_w,
     packed_glyphs[i].y0 / (float)atlas_h,
     packed_glyphs[i].x1 / (float)atlas_w,
     packed_glyphs[i].y1 / (float)atlas_h,
     (packed_glyphs[i].xoff)/2.0f,
     (packed_glyphs[i].yoff)/2.0f,
     (packed_glyphs[i].x1 - packed_glyphs[i].x0)/2.0f,
     (packed_glyphs[i].y1 - packed_glyphs[i].y0)/2.0f,
     packed_glyphs[i].xadvance
 );
glm::vec4 uvRect = glyph.getUVRect();

Public Functions

inline GlyphData()

Default constructor for GlyphData.

Initializes all metrics to zero.

inline GlyphData(float u0, float v0, float u1, float v1, float x_offset, float y_offset, float width, float height, float x_advance)

Parameterized constructor for GlyphData.

Note

All size and offset parameters are in pixels.

Parameters:

• u0 – Left U texture coordinate.

• v0 – Top V texture coordinate.

• u1 – Right U texture coordinate.

• v1 – Bottom V texture coordinate.

• x_offset – Horizontal offset from cursor.

• y_offset – Vertical offset from cursor.

• width – Width of the glyph in pixels.

• height – Height of the glyph in pixels.

• x_advance – Horizontal advance after rendering the glyph.

glm::vec4 getUVRect() const

Get the UV rectangle of the glyph.

Returns:

UV rectangle (u0, v0, u1, v1) of the glyph.

glm::vec2 getOffset() const

Get the offset of the glyph from the cursor position.

Returns:

Offset (x_offset, y_offset) of the glyph in pixels.

glm::vec2 getSize() const

Get the size of the glyph in pixels.

Returns:

Size (width, height) of the glyph in pixels.

float getXAdvance() const

Get the horizontal advance after rendering the glyph.

Returns:

Horizontal advance (x_advance) of the glyph in pixels.

Private Functions

void setUVRect(float u0, float v0, float u1, float v1)

Set the UV rectangle of the glyph.

glyph.setUVRect(0.0f, 0.0f, 0.1f, 0.1f);

Note

All parameters are normalized texture coordinates (0.0 to 1.0).

Parameters:

• u0 – Left U texture coordinate.

• v0 – Top V texture coordinate.

• u1 – Right U texture coordinate.

• v1 – Bottom V texture coordinate.

Private Members

glm::vec4 uv

UV texture coordinates of the glyph.

(u0, v0) is the top-left coordinate, (u1, v1) is the bottom-right coordinate. All coordinates are normalized (0.0 to 1.0).

glm::vec4 uv = glyph.getUVRect();
float u0 = uv.x;
float v0 = uv.y;
float u1 = uv.z;
float v1 = uv.w;

glm::vec2 offset

Offset of the glyph from the cursor position.

Horizontal and vertical offset from cursor position.

glm::vec2 size

Size of the glyph in pixels.

Width and height of the glyph in pixels.

float x_advance

Horizontal advance after rendering the glyph.

Represents how much to move the cursor for the next glyph.

Friends

friend class FontBase

Functions

Functions

Function	Description
std::operator<<(std::ostream &os, const RaeptorCogs::Font &font)	Stream output operator for Font.
std::operator<<(std::ostream &os, const RaeptorCogs::FontBase &font)	Stream output operator for FontBase.
std::operator<<(std::ostream &os, const RaeptorCogs::FontOptions &options)	Stream output operator for FontOptions.
std::operator<<(std::ostream &os, const RaeptorCogs::FontType &type)	Stream output operator for FontType.
std::operator<<(std::ostream &os, const RaeptorCogs::GlyphData &glyph)	Stream output operator for GlyphData.

inline std::ostream &std::operator<<(std::ostream &os, const RaeptorCogs::Font &font)

Stream output operator for Font.

Outputs the Font in a human-readable format.

inline std::ostream &std::operator<<(std::ostream &os, const RaeptorCogs::FontBase &font)

Stream output operator for FontBase.

Outputs the FontBase in a human-readable format.

inline std::ostream &std::operator<<(std::ostream &os, const RaeptorCogs::FontOptions &options)

Stream output operator for FontOptions.

Outputs the FontOptions in a human-readable format.

inline std::ostream &std::operator<<(std::ostream &os, const RaeptorCogs::FontType &type)

Stream output operator for FontType.

Outputs the FontType in a human-readable format.

inline std::ostream &std::operator<<(std::ostream &os, const RaeptorCogs::GlyphData &glyph)

Stream output operator for GlyphData.

Outputs the GlyphData in a human-readable format.

Variables

int RaeptorCogs::FONT_PADDING = 1

Font padding constant.

Represents the padding added around each glyph in the font atlas to prevent texture bleeding.

int RaeptorCogs::NORMAL_FONT_SIZE = 72

Normal font size constant.

Represents the default font size used for scaling glyphs.