Skip to main content

sim_engine/renderer/text/
prepared.rs

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