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}