CArcFontAtlas
- Module
- Arc
- Header
#include "Arc/Text/CArcFont.h"- Namespace
Arcf
Properties
| Type | Name | Description |
|---|---|---|
static constexpr uint32_t | SUBPIXEL_BUCKETS | Horizontal 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 float | MIN_RASTER_SCALE | The lowest device grid glyphs rasterize for: UI scale bottoms out at 0.25, and nothing below it is legible anyway. Default 0.25f. |
Constructors
| Signature | Name | Description |
|---|---|---|
CArcFontAtlas() | CArcFontAtlas | |
~CArcFontAtlas() | ~CArcFontAtlas | |
CArcFontAtlas(const CArcFontAtlas&) = delete | CArcFontAtlas |
Public functions
| Returns | Name | Description |
|---|---|---|
CArcFontAtlas& | operator= | |
bool | Initialize | |
void | Shutdown | |
const CArcGlyphInfo& | GetGlyph | Get glyph info (rasterizes on-demand if not cached). |
const CArcGlyphInfo& | GetGlyphByIndex | |
IArcRHITexture* | GetTexture | |
bool | WasRebuilt | Check if atlas was rebuilt this frame (texture changed, need to rebind) |
void | ClearRebuiltFlag | |
uint32_t | GetGeneration | Bumped only when cached UVs stop being valid: the atlas grew, was flushed after filling up, or changed its raster factor. |
CArcFontAtlas* | GetColorAtlas | 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. |
uint8_t | CoverageAt | The coverage (or, in a colour atlas, the alpha) of one texel of the CPU copy; 0 outside it. |
uint32_t | GetBytesPerTexel | |
void | AdvanceFrame | Frame boundary, called once per renderer Begin. |
bool | IsFlushPending | Set when a glyph did not fit and the atlas is already at its maximum size. |
void | SetMaxAtlasSize | Upper bound for growth by doubling; past it the atlas flushes. |
uint32_t | GetMaxAtlasSize | |
size_t | GetRetiredTextureCount | Superseded textures still alive because a recorded frame may sample them. |
void | SetSupersample | 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. |
float | GetSupersample | |
bool | HasWhiteTexel | A reserved block of opaque white inside the atlas. |
ArcVec2 | GetWhiteTexelUV | |
const std::vector<uint8_t>& | GetPixelData | The CPU copy the texture is uploaded from. |
bool | ValidateWhiteTexel | Reads back the texel the UV resolves to. |
void | FlushIfDirty | Flush pending pixel data to GPU (call once per frame, after all GetGlyph calls) |
EFontAtlasMode | GetMode | |
size_t | GetPixelBytes | Bytes the CPU-side atlas currently holds. |
uint32_t | GetAtlasSize | |
float | GetGlyphRenderScale | Drawn pixels per atlas pixel at a given font size. |
uint32_t | GetPackedRows | Rows the shelf packer has consumed. |
uint32_t | GetRasterizedGlyphCount | Rasterization cost so far. |
double | GetRasterizeMilliseconds |
Function details
CArcFontAtlas
CArcFontAtlas()~CArcFontAtlas
~CArcFontAtlas()CArcFontAtlas
CArcFontAtlas(const CArcFontAtlas&) = deleteoperator=
CArcFontAtlas& operator=(const CArcFontAtlas&) = deleteInitialize
bool Initialize(IArcRHIDevice* device, EFontAtlasMode mode, uint32_t initialSize = 1024)Shutdown
void Shutdown()GetGlyph
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
const CArcGlyphInfo& GetGlyphByIndex(FT_Face face, uint32_t glyphIndex, float fontSize, uint32_t subpixelBucket = 0, float rasterScale = 0.0f)GetTexture
IArcRHITexture* GetTexture() constWasRebuilt
bool WasRebuilt() constCheck if atlas was rebuilt this frame (texture changed, need to rebind)
ClearRebuiltFlag
void ClearRebuiltFlag()GetGeneration
uint32_t GetGeneration() constBumped 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
CArcFontAtlas* GetColorAtlas() constWhere 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
uint8_t CoverageAt(uint32_t x, uint32_t y) constThe coverage (or, in a colour atlas, the alpha) of one texel of the CPU copy; 0 outside it.
GetBytesPerTexel
uint32_t GetBytesPerTexel() constAdvanceFrame
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
bool IsFlushPending() constSet 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
void SetMaxAtlasSize(uint32_t size)Upper bound for growth by doubling; past it the atlas flushes.
GetMaxAtlasSize
uint32_t GetMaxAtlasSize() constGetRetiredTextureCount
size_t GetRetiredTextureCount() constSuperseded textures still alive because a recorded frame may sample them.
SetSupersample
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
float GetSupersample() constHasWhiteTexel
bool HasWhiteTexel() constA 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
ArcVec2 GetWhiteTexelUV() constGetPixelData
const std::vector<uint8_t>& GetPixelData() constThe 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
bool ValidateWhiteTexel() constReads 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
void FlushIfDirty()Flush pending pixel data to GPU (call once per frame, after all GetGlyph calls)
GetMode
EFontAtlasMode GetMode() constGetPixelBytes
size_t GetPixelBytes() constBytes the CPU-side atlas currently holds. Mirrors the GPU texture exactly, so it doubles as the memory figure for the mode.
GetAtlasSize
uint32_t GetAtlasSize() constGetGlyphRenderScale
float GetGlyphRenderScale(float fontSize, float rasterScale = 0.0f) constDrawn 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
uint32_t GetPackedRows() constRows 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
uint32_t GetRasterizedGlyphCount() constRasterization cost so far.
GetRasterizeMilliseconds
double GetRasterizeMilliseconds() const