class

CArcFontAtlas

Module
Arc
Header
#include "Arc/Text/CArcFont.h"
Namespace
Arcf

Properties

TypeNameDescription
static constexpr uint32_tSUBPIXEL_BUCKETSHorizontal subpixel raster variants for the bitmap atlas: bucket b rasterizes the outline shifted right by b/SUBPIXEL_BUCKETS of a device pixel, so a quad snapped to the device grid still lands the stems where the fractional pen position wanted them. Distance-field modes ignore the bucket (linear interpolation covers it). Quarters, as the export's browser places text: halves left a tenth more of the menu bar's pixels off the reference. Default 4.
static constexpr floatMIN_RASTER_SCALEThe lowest device grid glyphs rasterize for: UI scale bottoms out at 0.25, and nothing below it is legible anyway. Default 0.25f.

Constructors

SignatureNameDescription
CArcFontAtlas()CArcFontAtlas
~CArcFontAtlas()~CArcFontAtlas
CArcFontAtlas(const CArcFontAtlas&) = deleteCArcFontAtlas

Public functions

ReturnsNameDescription
CArcFontAtlas&operator=
boolInitialize
voidShutdown
const CArcGlyphInfo&GetGlyphGet glyph info (rasterizes on-demand if not cached).
const CArcGlyphInfo&GetGlyphByIndex
IArcRHITexture*GetTexture
boolWasRebuiltCheck if atlas was rebuilt this frame (texture changed, need to rebind)
voidClearRebuiltFlag
uint32_tGetGenerationBumped only when cached UVs stop being valid: the atlas grew, was flushed after filling up, or changed its raster factor.
CArcFontAtlas*GetColorAtlasWhere a bitmap atlas puts colour glyphs (emoji): an RGBA8 atlas of its own, so the coverage atlas holds one byte per texel instead of four.
uint8_tCoverageAtThe coverage (or, in a colour atlas, the alpha) of one texel of the CPU copy; 0 outside it.
uint32_tGetBytesPerTexel
voidAdvanceFrameFrame boundary, called once per renderer Begin.
boolIsFlushPendingSet when a glyph did not fit and the atlas is already at its maximum size.
voidSetMaxAtlasSizeUpper bound for growth by doubling; past it the atlas flushes.
uint32_tGetMaxAtlasSize
size_tGetRetiredTextureCountSuperseded textures still alive because a recorded frame may sample them.
voidSetSupersampleHigh-DPI text: rasterize bitmap glyphs at factor× the requested size while reporting 1× metrics — the logical-space renderer then samples them down and text stays crisp on Retina.
floatGetSupersample
boolHasWhiteTexelA reserved block of opaque white inside the atlas.
ArcVec2GetWhiteTexelUV
const std::vector<uint8_t>&GetPixelDataThe CPU copy the texture is uploaded from.
boolValidateWhiteTexelReads back the texel the UV resolves to.
voidFlushIfDirtyFlush pending pixel data to GPU (call once per frame, after all GetGlyph calls)
EFontAtlasModeGetMode
size_tGetPixelBytesBytes the CPU-side atlas currently holds.
uint32_tGetAtlasSize
floatGetGlyphRenderScaleDrawn pixels per atlas pixel at a given font size.
uint32_tGetPackedRowsRows the shelf packer has consumed.
uint32_tGetRasterizedGlyphCountRasterization cost so far.
doubleGetRasterizeMilliseconds

Function details

CArcFontAtlas

C++
CArcFontAtlas()

~CArcFontAtlas

C++
~CArcFontAtlas()

CArcFontAtlas

C++
CArcFontAtlas(const CArcFontAtlas&) = delete

operator=

C++
CArcFontAtlas& operator=(const CArcFontAtlas&) = delete

Initialize

C++
bool Initialize(IArcRHIDevice* device, EFontAtlasMode mode, uint32_t initialSize = 1024)

Shutdown

C++
void Shutdown()

GetGlyph

C++
const CArcGlyphInfo& GetGlyph(FT_Face face, uint32_t codepoint, float fontSize, uint32_t subpixelBucket = 0, float rasterScale = 0.0f)

Get glyph info (rasterizes on-demand if not cached). rasterScale selects the device-pixel grid the bitmap glyph rasterizes for: <= 0 uses the atlas-wide supersample (the main window's scale), a positive value keys a per-scale variant so windows on differently scaled monitors each get correctly rastered glyphs from one atlas.

GetGlyphByIndex

C++
const CArcGlyphInfo& GetGlyphByIndex(FT_Face face, uint32_t glyphIndex, float fontSize, uint32_t subpixelBucket = 0, float rasterScale = 0.0f)

GetTexture

C++
IArcRHITexture* GetTexture() const

WasRebuilt

C++
bool WasRebuilt() const

Check if atlas was rebuilt this frame (texture changed, need to rebind)

ClearRebuiltFlag

C++
void ClearRebuiltFlag()

GetGeneration

C++
uint32_t GetGeneration() const

Bumped only when cached UVs stop being valid: the atlas grew, was flushed after filling up, or changed its raster factor. Adding a glyph does NOT bump it — the glyph lands in free space and every UV already handed out still points at the same texels — because the renderer drops every retained paint slice and descriptor set on a bump, and a bump per new glyph made typing or scrolling a log repaint the shell. A bitmap atlas folds its colour companion's rebuilds in: the glyph UVs every cache keys on this come from both textures.

GetColorAtlas

C++
CArcFontAtlas* GetColorAtlas() const

Where a bitmap atlas puts colour glyphs (emoji): an RGBA8 atlas of its own, so the coverage atlas holds one byte per texel instead of four. Null for the other modes. A glyph with CArcGlyphInfo::Color has UVs into this atlas's texture.

CoverageAt

C++
uint8_t CoverageAt(uint32_t x, uint32_t y) const

The coverage (or, in a colour atlas, the alpha) of one texel of the CPU copy; 0 outside it.

GetBytesPerTexel

C++
uint32_t GetBytesPerTexel() const

AdvanceFrame

C++
void AdvanceFrame()

Frame boundary, called once per renderer Begin. Textures the atlas replaced mid-frame stay alive here until the command lists that may still sample them have retired, and a full atlas is flushed (emptied and re-rasterized on demand) here rather than in the middle of a walk that already resolved UVs against it.

IsFlushPending

C++
bool IsFlushPending() const

Set when a glyph did not fit and the atlas is already at its maximum size. The glyph is missing for the rest of this frame only.

SetMaxAtlasSize

C++
void SetMaxAtlasSize(uint32_t size)

Upper bound for growth by doubling; past it the atlas flushes.

GetMaxAtlasSize

C++
uint32_t GetMaxAtlasSize() const

GetRetiredTextureCount

C++
size_t GetRetiredTextureCount() const

Superseded textures still alive because a recorded frame may sample them.

SetSupersample

C++
void SetSupersample(float factor)

High-DPI text: rasterize bitmap glyphs at factor× the requested size while reporting 1× metrics — the logical-space renderer then samples them down and text stays crisp on Retina. No effect on the distance-field modes (already resolution-independent). Changing the factor drops every cached glyph.

GetSupersample

C++
float GetSupersample() const

HasWhiteTexel

C++
bool HasWhiteTexel() const

A reserved block of opaque white inside the atlas. Untextured UI quads sample it instead of a separate 1x1 texture, so solid geometry and text share one descriptor and stay in one batch.

GetWhiteTexelUV

C++
ArcVec2 GetWhiteTexelUV() const

GetPixelData

C++
const std::vector<uint8_t>& GetPixelData() const

The CPU copy the texture is uploaded from. With no device (Initialize given nullptr) this is the whole atlas: glyphs pack and rasterize the same way, which is what an offline bake or a headless test needs.

ValidateWhiteTexel

C++
bool ValidateWhiteTexel() const

Reads back the texel the UV resolves to. Solid UI geometry is only correct while this is opaque white, so it is worth asserting rather than trusting the packer.

FlushIfDirty

C++
void FlushIfDirty()

Flush pending pixel data to GPU (call once per frame, after all GetGlyph calls)

GetMode

C++
EFontAtlasMode GetMode() const

GetPixelBytes

C++
size_t GetPixelBytes() const

Bytes the CPU-side atlas currently holds. Mirrors the GPU texture exactly, so it doubles as the memory figure for the mode.

GetAtlasSize

C++
uint32_t GetAtlasSize() const

GetGlyphRenderScale

C++
float GetGlyphRenderScale(float fontSize, float rasterScale = 0.0f) const

Drawn pixels per atlas pixel at a given font size. Distance-field modes rasterize at a fixed size and scale down, so a caller that sizes a quad from UV extents has to fold this in. rasterScale must match what the glyphs were fetched with (<= 0 = supersample).

GetPackedRows

C++
uint32_t GetPackedRows() const

Rows the shelf packer has consumed. Distance-field glyphs are packed at their render size, not the drawn size, so this is what decides when the atlas has to double.

GetRasterizedGlyphCount

C++
uint32_t GetRasterizedGlyphCount() const

Rasterization cost so far.

GetRasterizeMilliseconds

C++
double GetRasterizeMilliseconds() const
Generated from Arc/Text/CArcFont.h via arc.json · Nov 5, 2026Version 1.0.0