Skip to main content

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}