sim_logic/text/settings.rs
1use sim_engine::{
2 FontBudget, FontError, LogicalPixels, PhysicalPerLogical, TextDirection, TextLayoutBudget,
3 TextStyle,
4};
5
6use super::TextAtlasLimits;
7use super::TextError;
8#[cfg(feature = "text")]
9use sim_engine::TextAtlasBudget;
10
11/// Frozen limits for application-owned font registrations.
12///
13/// Source byte Vec capacities are counted, not just initialized lengths.
14/// Parsed dependency metadata, shared-handle control blocks, label strings, and
15/// desktop atlases are separate. Zero values may disable registration.
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub struct TextLimits {
18 max_fonts: usize,
19 max_font_bytes: usize,
20}
21
22impl TextLimits {
23 /// Creates exact registration-count and aggregate source-capacity limits.
24 /// No allocation, parsing, or GPU operation occurs.
25 pub const fn new(max_fonts: usize, max_font_bytes: usize) -> Self {
26 Self {
27 max_fonts,
28 max_font_bytes,
29 }
30 }
31
32 /// Returns the maximum number of distinct immutable font registrations.
33 pub const fn max_fonts(self) -> usize {
34 self.max_fonts
35 }
36
37 /// Returns the maximum sum of registered font source Vec capacities.
38 pub const fn max_font_bytes(self) -> usize {
39 self.max_font_bytes
40 }
41}
42
43impl Default for TextLimits {
44 /// Allows eight font registrations sharing an aggregate 32 MiB source cap.
45 fn default() -> Self {
46 Self::new(8, 32 * 1024 * 1024)
47 }
48}
49
50/// Immutable size, shaping policy, and budgets of one registered font.
51///
52/// Logical size is pixels per em, not a promise that every glyph has that
53/// height. Labels using a registration share this size and direction. Register
54/// another font configuration when a second size is needed. Display DPI is
55/// selected by the desktop runner; it never changes logical text metrics.
56///
57/// Engine budget types here are configuration values, not renderer resources.
58/// Font bytes must come from a trusted application asset. Dependency parsing
59/// and shaping are not an untrusted-font sandbox or an OS OOM guarantee.
60#[derive(Debug, Clone, Copy, PartialEq)]
61pub struct TextSettings {
62 logical_em_size: f32,
63 direction: TextDirection,
64 font_budget: FontBudget,
65 layout_budget: TextLayoutBudget,
66 atlas_limits: TextAtlasLimits,
67 #[cfg(feature = "text")]
68 atlas_budget: TextAtlasBudget,
69}
70
71impl TextSettings {
72 /// Creates a positive normal logical em size with the remaining defaults.
73 ///
74 /// Non-finite, non-positive, or subnormal sizes return an error. Creation
75 /// is headless and does not rasterize or allocate an atlas.
76 pub fn new(logical_em_size: f32) -> Result<Self, TextError> {
77 let settings = Self {
78 logical_em_size,
79 ..Self::default()
80 };
81 settings.style(1.0)?;
82 Ok(settings)
83 }
84
85 /// Selects a single-run shaping direction; this is not bidi paragraph layout.
86 pub const fn with_direction(mut self, direction: TextDirection) -> Self {
87 self.direction = direction;
88 self
89 }
90
91 /// Replaces per-font source-capacity and declared-glyph limits.
92 /// Application-wide source limits still apply independently.
93 pub const fn with_font_budget(mut self, budget: FontBudget) -> Self {
94 self.font_budget = budget;
95 self
96 }
97
98 /// Replaces per-label input/output and per-glyph rasterization work limits.
99 /// Zero limits are valid. A label exceeding a limit is rejected atomically.
100 pub const fn with_layout_budget(mut self, budget: TextLayoutBudget) -> Self {
101 self.layout_budget = budget;
102 self
103 }
104
105 /// Replaces fixed desktop atlas and per-run capacities.
106 ///
107 /// This stores an already validated configuration without allocating GPU
108 /// resources. Device dimensions and raster fit are checked on desktop use.
109 #[cfg(feature = "text")]
110 pub const fn with_atlas_budget(mut self, budget: TextAtlasBudget) -> Self {
111 self.atlas_limits = TextAtlasLimits::from_engine(budget);
112 self.atlas_budget = budget;
113 self
114 }
115
116 /// Returns the fixed logical-pixel em size shared by this registration.
117 pub const fn logical_em_size(self) -> f32 {
118 self.logical_em_size
119 }
120
121 /// Returns the requested direction for one horizontal shaping run.
122 pub const fn direction(self) -> TextDirection {
123 self.direction
124 }
125
126 /// Returns limits applied when taking ownership of font source bytes.
127 pub const fn font_budget(self) -> FontBudget {
128 self.font_budget
129 }
130
131 /// Returns limits applied to each changed label and rasterized glyph.
132 pub const fn layout_budget(self) -> TextLayoutBudget {
133 self.layout_budget
134 }
135
136 /// Returns the fixed physical atlas dimensions and per-run capacities.
137 #[cfg(feature = "text")]
138 pub const fn atlas_budget(self) -> TextAtlasBudget {
139 self.atlas_budget
140 }
141
142 /// Sets GPU-independent atlas/run configuration. Validation failure preserves self.
143 /// Available with both `headless-text` and `text`; desktop conversion is checked.
144 pub fn with_atlas_limits(mut self, limits: TextAtlasLimits) -> Result<Self, TextError> {
145 #[cfg(feature = "text")]
146 {
147 self.atlas_budget = limits.engine_budget()?;
148 }
149 self.atlas_limits = limits;
150 Ok(self)
151 }
152
153 /// Returns the GPU-independent atlas/run configuration used by CPU label validation.
154 pub const fn atlas_limits(self) -> TextAtlasLimits {
155 self.atlas_limits
156 }
157
158 /// Creates Engine's style for an explicit physical-pixels-per-logical scale.
159 ///
160 /// A headless caller can use `1.0`; desktop presentation uses actual DPI.
161 /// Invalid or unrepresentable physical size returns a typed font error.
162 /// This creates a value only and performs no GPU operation.
163 pub fn style(self, scale: f32) -> Result<TextStyle, TextError> {
164 let size = LogicalPixels::new(self.logical_em_size)
165 .map_err(|_| TextError::Font(FontError::InvalidScale))?;
166 let scale =
167 PhysicalPerLogical::new(scale).map_err(|_| TextError::Font(FontError::InvalidScale))?;
168 Ok(TextStyle::new(size, scale)?.with_direction(self.direction))
169 }
170}
171
172impl Default for TextSettings {
173 /// Uses 24 logical pixels per em, automatic direction, an 8 MiB font cap,
174 /// 4096 UTF-8 bytes and 1024 shaped glyphs per label, and Engine's fixed
175 /// 1024 by 1024 RGBA atlas. Raster work is capped per glyph at one million
176 /// coverage pixels and 16384 outline commands.
177 fn default() -> Self {
178 Self {
179 logical_em_size: 24.0,
180 direction: TextDirection::Auto,
181 font_budget: FontBudget::default(),
182 layout_budget: TextLayoutBudget::new(4096, 1024, 1024 * 1024, 16 * 1024),
183 atlas_limits: TextAtlasLimits::default(),
184 #[cfg(feature = "text")]
185 atlas_budget: TextAtlasBudget::default(),
186 }
187 }
188}