fret_core/
render_text.rs

1use crate::FrameId;
2use crate::{FontId, Px, TextOverflow, TextWrap};
3
4/// Per-frame renderer-owned text cache counters.
5///
6/// This is intended for diagnostics bundles and on-screen debug panels. The runner can update it
7/// once per rendered frame to make renderer-level churn (text blobs, glyph atlas pressure) visible
8/// in a single artifact.
9#[derive(Debug, Default, Clone, Copy)]
10pub struct RendererTextPerfSnapshot {
11    pub frame_id: FrameId,
12
13    pub font_stack_key: u64,
14    pub font_db_revision: u64,
15    /// Fingerprint of the effective font fallback policy (locale + family config + injection).
16    ///
17    /// This is intended for diagnostics only.
18    pub fallback_policy_key: u64,
19
20    /// Total count of missing/tofu glyphs observed across text prepared this frame.
21    ///
22    /// Implementation note: this is currently approximated as the number of shaped glyphs whose
23    /// glyph id is `0` (the `.notdef` glyph) across prepared text runs.
24    pub frame_missing_glyphs: u64,
25    /// Count of prepared text blobs that contained at least one missing/tofu glyph.
26    pub frame_texts_with_missing_glyphs: u64,
27
28    pub blobs_live: u64,
29    pub blob_cache_entries: u64,
30    pub shape_cache_entries: u64,
31    pub measure_cache_buckets: u64,
32
33    /// Best-effort heap byte estimates for text caches (CPU-side).
34    ///
35    /// These values are intended for diagnostics only. They are approximate and may under-count
36    /// allocator overhead and shared allocations.
37    pub shape_cache_bytes_estimate_total: u64,
38    pub blob_paint_palette_bytes_estimate_total: u64,
39    pub blob_decorations_bytes_estimate_total: u64,
40
41    pub unwrapped_layout_cache_entries: u64,
42    pub frame_unwrapped_layout_cache_hits: u64,
43    pub frame_unwrapped_layout_cache_misses: u64,
44    pub frame_unwrapped_layouts_created: u64,
45
46    pub frame_cache_resets: u64,
47    pub frame_blob_cache_hits: u64,
48    pub frame_blob_cache_misses: u64,
49    pub frame_blobs_created: u64,
50    pub frame_shape_cache_hits: u64,
51    pub frame_shape_cache_misses: u64,
52    pub frame_shapes_created: u64,
53
54    pub mask_atlas: RendererGlyphAtlasPerfSnapshot,
55    pub color_atlas: RendererGlyphAtlasPerfSnapshot,
56    pub subpixel_atlas: RendererGlyphAtlasPerfSnapshot,
57
58    /// Best-effort process-local font database/cache counters.
59    ///
60    /// These are intended to help attribute CPU-side footprint concerns (e.g. "too many injected
61    /// font blobs") without requiring heap profilers.
62    pub registered_font_blobs_count: u64,
63    pub registered_font_blobs_total_bytes: u64,
64    pub family_id_cache_entries: u64,
65    pub baseline_metrics_cache_entries: u64,
66}
67
68#[derive(Debug, Default, Clone, Copy)]
69pub struct RendererGlyphAtlasPerfSnapshot {
70    pub width: u32,
71    pub height: u32,
72    pub pages: u32,
73    pub entries: u64,
74
75    pub used_px: u64,
76    pub capacity_px: u64,
77
78    pub frame_hits: u64,
79    pub frame_misses: u64,
80    pub frame_inserts: u64,
81    pub frame_evict_glyphs: u64,
82    pub frame_evict_pages: u64,
83    pub frame_out_of_space: u64,
84    pub frame_too_large: u64,
85
86    pub frame_pending_uploads: u64,
87    pub frame_pending_upload_bytes: u64,
88    pub frame_upload_bytes: u64,
89}
90
91/// Per-frame renderer-owned font selection trace, intended for diagnostics bundles.
92///
93/// This is **not** a stable contract for apps; it exists to make font fallback issues auditable and
94/// to help keep refactors fearless (especially around variable fonts and fallback chain semantics).
95#[derive(Debug, Default, Clone)]
96pub struct RendererTextFontTraceSnapshot {
97    pub frame_id: FrameId,
98    /// Bounded list of trace entries for the frame.
99    ///
100    /// Renderers are expected to keep this list small. Typical policies:
101    ///
102    /// - record entries only when missing/tofu glyphs are observed
103    /// - record a small ring of the most recent prepared blobs when explicitly enabled
104    pub entries: Vec<RendererTextFontTraceEntry>,
105}
106
107#[derive(Debug, Clone)]
108pub struct RendererTextFontTraceEntry {
109    /// Human-readable preview of the text (may be truncated).
110    pub text_preview: String,
111    pub text_len_bytes: u32,
112
113    pub font: FontId,
114    pub font_size: Px,
115    pub scale_factor: f32,
116
117    pub wrap: TextWrap,
118    pub overflow: TextOverflow,
119    pub max_width: Option<Px>,
120
121    pub locale_bcp47: Option<String>,
122
123    pub missing_glyphs: u32,
124
125    /// Families used by shaping/rasterization for this blob (best-effort).
126    pub families: Vec<RendererTextFontTraceFamilyUsage>,
127}
128
129#[derive(Debug, Clone, PartialEq, Eq)]
130pub struct RendererTextFontTraceFamilyUsage {
131    pub family: String,
132    pub glyphs: u32,
133    pub missing_glyphs: u32,
134    pub class: RendererTextFontTraceFamilyClass,
135}
136
137#[derive(Debug, Clone, Copy, PartialEq, Eq)]
138pub enum RendererTextFontTraceFamilyClass {
139    Requested,
140    CommonFallback,
141    SystemFallback,
142    Unknown,
143}
144
145/// Snapshot of the effective renderer font fallback policy, intended for diagnostics bundles.
146#[derive(Debug, Default, Clone)]
147pub struct RendererTextFallbackPolicySnapshot {
148    pub frame_id: FrameId,
149    pub font_stack_key: u64,
150    pub font_db_revision: u64,
151    pub fallback_policy_key: u64,
152
153    pub system_fonts_enabled: bool,
154    pub locale_bcp47: Option<String>,
155
156    pub common_fallback_injection: crate::TextCommonFallbackInjection,
157    pub prefer_common_fallback: bool,
158    pub prefer_common_fallback_for_generics: bool,
159
160    pub configured_ui_sans_families: Vec<String>,
161    pub configured_ui_serif_families: Vec<String>,
162    pub configured_ui_mono_families: Vec<String>,
163    pub configured_common_fallback_families: Vec<String>,
164
165    pub default_ui_sans_candidates: Vec<String>,
166    pub default_ui_serif_candidates: Vec<String>,
167    pub default_ui_mono_candidates: Vec<String>,
168    pub default_common_fallback_families: Vec<String>,
169
170    /// The effective suffix appended to named-family stacks when common fallback is preferred.
171    pub common_fallback_stack_suffix: String,
172    /// The effective candidate list used to build `common_fallback_stack_suffix` (trimmed + deduped, preserving order).
173    pub common_fallback_candidates: Vec<String>,
174
175    pub bundled_profile_contract: RendererBundledFontProfileSnapshot,
176}
177
178/// Diagnostics-only view of the bundled font profile contract the renderer knows about.
179#[derive(Debug, Default, Clone)]
180pub struct RendererBundledFontProfileSnapshot {
181    pub name: String,
182    pub provided_roles: Vec<String>,
183    pub expected_family_names: Vec<String>,
184    pub guaranteed_generic_families: Vec<String>,
185    pub ui_sans_families: Vec<String>,
186    pub ui_serif_families: Vec<String>,
187    pub ui_mono_families: Vec<String>,
188    pub common_fallback_families: Vec<String>,
189}
fret_core/render_text.rs

fret_core/
render_text.rs
