Skip to main content

sim_engine/renderer/text/
prepared.rs

1use super::*;
2use crate::ShapedLineError;
3
4/// Rejected prepared-text provenance/limits or an underlying atlas/run operation.
5/// Existing UTF-8 APIs retain their original [`TextError`] return type.
6#[derive(Debug)]
7#[non_exhaustive]
8pub enum PreparedTextError {
9    /// The immutable CPU line does not match this font/style or requested limits.
10    Shaped(ShapedLineError),
11    /// Rasterization, atlas capacity, run storage or GPU resource validation failed.
12    Text(TextError),
13}
14
15impl fmt::Display for PreparedTextError {
16    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
17        match self {
18            Self::Shaped(error) => write!(formatter, "prepared text: {error}"),
19            Self::Text(error) => write!(formatter, "prepared text: {error}"),
20        }
21    }
22}
23
24impl Error for PreparedTextError {
25    fn source(&self) -> Option<&(dyn Error + 'static)> {
26        match self {
27            Self::Shaped(error) => Some(error),
28            Self::Text(error) => Some(error),
29        }
30    }
31}
32
33impl From<TextError> for PreparedTextError {
34    fn from(error: TextError) -> Self {
35        Self::Text(error)
36    }
37}
38
39impl From<ShapedLineError> for PreparedTextError {
40    fn from(error: ShapedLineError) -> Self {
41        Self::Shaped(error)
42    }
43}
44
45impl TextAtlas2d {
46    /// Prepares a validated CPU line without invoking the text shaper again.
47    ///
48    /// The line must originate from this exact [`FontFace`] (clones share identity)
49    /// and [`TextStyle`], including DPI and requested direction. Separately loaded
50    /// identical font bytes are intentionally not treated as the same identity.
51    /// Text/glyph limits are checked before placement allocation or cache mutation;
52    /// raster limits apply to uncached glyphs. Run capacity includes whitespace as
53    /// in [`Self::prepare`]. The source line is borrowed, never consumed or modified.
54    /// Failure may warm bounded atlas entries but preserves all existing runs.
55    pub fn prepare_from_shaped(
56        &mut self,
57        renderer: &WgpuRenderer,
58        shaped: &ShapedLine,
59        layout_budget: TextLayoutBudget,
60    ) -> Result<TextRun2d, PreparedTextError> {
61        renderer
62            .validate_image(&self.atlas.image)
63            .map_err(TextError::from)?;
64        shaped.validate_for(&self.font, &self.style, &layout_budget)?;
65        Ok(self.prepare_validated(renderer, shaped, layout_budget)?)
66    }
67
68    /// Atomically updates a retained run from already shaped CPU data.
69    ///
70    /// Atlas/run/device identity and CPU font/style provenance are checked first,
71    /// even if UTF-8 is unchanged. A compatible unchanged line reports zero work
72    /// without consuming or rechecking `layout_budget`, matching [`Self::update`].
73    /// For a changed line, input/output limits are checked without reshaping;
74    /// raster limits apply only to new cached glyphs. An error preserves old UTF-8,
75    /// metrics, instances and drawable GPU contents. A later error may leave newly
76    /// cached glyphs as documented by [`Self::prepare`].
77    pub fn update_from_shaped(
78        &mut self,
79        renderer: &WgpuRenderer,
80        run: &mut TextRun2d,
81        shaped: &ShapedLine,
82        layout_budget: TextLayoutBudget,
83    ) -> Result<TextUpdateReport, PreparedTextError> {
84        self.validate_run(run)?;
85        renderer
86            .validate_glyph_run(&self.atlas, &run.run)
87            .map_err(TextError::from)?;
88        shaped.validate_provenance(&self.font, &self.style)?;
89        if run.text == shaped.text() {
90            return Ok(TextUpdateReport::default());
91        }
92        shaped.validate_for(&self.font, &self.style, &layout_budget)?;
93        Ok(self.update_validated(renderer, run, shaped, layout_budget)?)
94    }
95}