Skip to main content

TextShapingSession

Struct TextShapingSession 

Source
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>

Source

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.

Source

pub const fn style(&self) -> &TextStyle

Returns the immutable style, including requested direction and raster DPI.

Source

pub const fn budget(&self) -> TextLayoutBudget

Returns fixed per-line and per-glyph work limits.

Source

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.

Source

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.

Source

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.

Source

pub fn cached_plan_count(&self) -> usize

Number of retained plans, always zero or one regardless of strings seen.

Source

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.

Auto Trait Implementations§

§

impl<'font> !RefUnwindSafe for TextShapingSession<'font>

§

impl<'font> !UnwindSafe for TextShapingSession<'font>

§

impl<'font> Freeze for TextShapingSession<'font>

§

impl<'font> Send for TextShapingSession<'font>

§

impl<'font> Sync for TextShapingSession<'font>

§

impl<'font> Unpin for TextShapingSession<'font>

§

impl<'font> UnsafeUnpin for TextShapingSession<'font>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> Downcast<T> for T

Source§

fn downcast(&self) -> &T

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> Upcast<T> for T

Source§

fn upcast(&self) -> Option<&T>

Source§

impl<T> WasmNotSend for T
where T: Send,

Source§

impl<T> WasmNotSendSync for T

Source§

impl<T> WasmNotSync for T
where T: Sync,