pub struct TextShapingSession<'font> { /* private fields */ }Expand description
Caller-owned reusable CPU shaping state for one borrowed font and fixed style.
Available with fonts, without a renderer or GPU dependency.
The parsed rustybuzz face, one exact-property shaping plan and one buffer are
reused. An inferred script/direction change replaces that single plan rather
than growing a cache. Language is unspecified and OpenType features use the
same defaults as FontFace::shape_line; no cross-font/global cache exists.
Self::update_line reuses two bounded UTF-8/glyph allocations transactionally.
Input and output limits remain mandatory. Dependency-owned face/plan/buffer
allocations are excluded from Self::allocation_bytes: rustybuzz does not
expose their capacities or fallible allocation. These are trusted-font work
limits, not an exact process-memory or hostile-font sandbox. Dependency buffer
storage is dropped after a shaping failure; Self::clear_scratch releases
successful-run scratch and the one cached plan on demand.
use sim_engine::{FontBudget, FontFace, LogicalPixels, PhysicalPerLogical,
TextLayoutBudget, TextShapingSession, TextStyle};
let font = FontFace::from_bytes(std::fs::read("assets/Label.ttf")?, FontBudget::default())?;
let style = TextStyle::new(LogicalPixels::new(24.0)?, PhysicalPerLogical::new(1.0)?)?;
let mut session = TextShapingSession::new(&font, style, TextLayoutBudget::default())?;
let mut line = session.shape_line("Count: 100")?;
session.update_line(&mut line, "Count: 101")?;
// Hand `line` to TextAtlas2d::prepare_from_shaped when using the `text` feature.
assert_eq!(line.text(), "Count: 101");Implementations§
Source§impl<'font> TextShapingSession<'font>
impl<'font> TextShapingSession<'font>
Sourcepub fn new(
font: &'font FontFace,
style: TextStyle,
budget: TextLayoutBudget,
) -> Result<Self, FontError>
pub fn new( font: &'font FontFace, style: TextStyle, budget: TextLayoutBudget, ) -> Result<Self, FontError>
Parses the borrowed font once and fixes style and work limits for this session. Does not preallocate the maximum permitted line length.
Sourcepub const fn style(&self) -> &TextStyle
pub const fn style(&self) -> &TextStyle
Returns the immutable style, including requested direction and raster DPI.
Sourcepub const fn budget(&self) -> TextLayoutBudget
pub const fn budget(&self) -> TextLayoutBudget
Returns fixed per-line and per-glyph work limits.
Sourcepub fn shape_line(&mut self, text: &str) -> Result<ShapedLine, FontError>
pub fn shape_line(&mut self, text: &str) -> Result<ShapedLine, FontError>
Shapes a new owned line; later updates can reuse its allocation. Separate returned lines each own their own bounded UTF-8 and glyph vectors.
Sourcepub fn update_line(
&mut self,
line: &mut ShapedLine,
text: &str,
) -> Result<bool, ShapedLineError>
pub fn update_line( &mut self, line: &mut ShapedLine, text: &str, ) -> Result<bool, ShapedLineError>
Replaces a compatible line atomically, returning whether its UTF-8 changed.
Font/style and current line limits are checked even for unchanged text. A successful change swaps the session’s scratch with the previous line’s storage, allowing equal or shorter warmed lengths to avoid engine-owned allocations. The old line’s capacities must also fit this session’s input and output limits so swapping cannot import unbounded retained storage. Any returned error preserves the old text, glyphs, metrics and allocations.
Sourcepub fn allocation_bytes(&self) -> usize
pub fn allocation_bytes(&self) -> usize
Engine-owned scratch capacity in bytes, excluding returned lines, shared source font and dependency-owned face/plan/buffer allocations.
Sourcepub fn cached_plan_count(&self) -> usize
pub fn cached_plan_count(&self) -> usize
Number of retained plans, always zero or one regardless of strings seen.
Sourcepub fn clear_scratch(&mut self)
pub fn clear_scratch(&mut self)
Releases scratch and cached plan while preserving the borrowed parsed face. Previously returned lines remain valid and independent of this session.