Skip to main content

ScreenTextVisual

Struct ScreenTextVisual 

Source
pub struct ScreenTextVisual { /* private fields */ }
Expand description

One validated single-line label anchored to a logical-screen baseline.

Screen coordinates start at the content area’s top-left and increase down and right. The y coordinate is the baseline, not the upper edge of the letters. World cameras and fixed-step interpolation do not move this label. It requires no world Transform and may coexist with other visual components.

Construction and changed text/font setters use Engine’s CPU font shaper. Cloning shares immutable text and font data; moving, tinting, ordering, and aligning do not shape, rasterize, or upload glyphs. A failed setter leaves every prior field intact. No old string history is retained by this value. Clones held elsewhere can of course retain earlier immutable strings.

Extraction excludes disabled entities and validates font provenance before publishing a complete snapshot. Screen layer, depth, and entity identity determine painter order; a same-entity rectangle/image/text tie uses that order. No wrapping, font fallback, hit testing, input capture, or text editing is implied. Missing glyphs and line separators are errors, not replacements.

Raster size, atlas space, and GPU allocation are checked later by desktop presentation. CPU validation alone cannot guarantee a glyph fits every DPI or device. Desktop preparation passes this retained CPU line directly to Engine at scale 1.0. Other display scales require a DPI-specific line because Engine’s prepared-line provenance includes exact DPI; that line is shaped only on a changed label or resource rebuild, never for an unchanged run.

Implementations§

Source§

impl ScreenTextVisual

Source

pub const fn clip(&self) -> ScreenClip

Returns the fixed-screen clip; label placement and alignment do not move it.

Source

pub fn set_clip(&mut self, clip: ScreenClip)

Replaces the explicit clip without reshaping or changing typographic metrics.

Source

pub fn new( font: TextFont, text: &str, position: LogicalScreenPosition, ) -> Result<Self, TextError>

Prepares a left-aligned white label on the default layer at depth zero.

Position is a finite logical-pixel baseline anchor. Negative/offscreen positions are valid when aligned bounds remain representable. Empty text is valid; whitespace retains advance even if it draws no glyphs. No window, rasterization, or GPU operation occurs here.

Source

pub fn new_with_session( session: &mut TextPreparationSession<'_>, text: &str, position: LogicalScreenPosition, ) -> Result<Self, TextError>

Creates a label using a caller-owned reusable shaping session.

The session fixes one registered font and logical size at scale 1.0. It reuses parsed shaping state, not mutable storage held by older labels. The returned value owns its line and does not borrow the session.

Source

pub const fn font(&self) -> &TextFont

Returns the opaque application font registration shared by this label.

Source

pub fn text(&self) -> &str

Returns the original UTF-8 single line without allocating or reshaping.

Source

pub fn shaped_line(&self) -> &ShapedLine

Returns immutable Engine shaping output, including exact font/style provenance.

Logical labels prepare at scale 1.0. A different-DPI atlas must not consume this line as though its style matched; desktop handles that rebuild itself. The UTF-8 and glyph metadata are shared with every clone and snapshot.

Source

pub fn metrics(&self) -> TextMetrics

Returns DPI-independent typographic metrics from the latest successful preparation.

Source

pub fn glyph_count(&self) -> usize

Returns shaped glyph count, conservatively including whitespace.

Source

pub fn retained_text_bytes(&self) -> usize

Returns a conservative upper bound on retained UTF-8 storage in bytes.

Since Engine 0.4 owns the UTF-8 together with glyph metadata, this includes both capacities, exactly as Self::retained_layout_bytes. It no longer measures the String allocation alone. Font and fixed metadata are excluded. Extraction’s text-byte allowance independently counts text().len().

Source

pub fn retained_layout_bytes(&self) -> usize

Returns retained UTF-8 plus shaped-glyph Vec capacity bytes.

This is Engine’s actual capacity accounting, shared by clones, excluding font storage, allocator overhead and this value’s fixed metadata. It is not a measurement of desktop atlas or GPU memory.

Source

pub const fn position(&self) -> LogicalScreenPosition

Returns the logical-pixel baseline anchor before horizontal alignment.

Source

pub fn baseline_origin(&self) -> LogicalScreenPosition

Returns the actual logical baseline origin after horizontal alignment. Typographic advance, including trailing spaces, determines the offset.

Source

pub const fn alignment(&self) -> TextAlignment

Returns how the line’s advance is aligned around its baseline anchor.

Source

pub const fn tint(&self) -> Color

Returns normalized straight-linear RGBA multiplied by glyph coverage.

Source

pub const fn layer(&self) -> Layer

Returns the primary painter-order layer within screen content.

Source

pub const fn draw_order_depth(&self) -> f32

Returns finite within-layer ordering depth, not camera projection depth.

Source

pub fn set_text(&mut self, text: &str) -> Result<(), TextError>

Replaces the line only after complete bounded shaping and geometry validation.

Exact equal UTF-8 is a no-op. Any failure preserves text, metrics, shared storage, and presentation fields. Old storage is released when no earlier clone or published snapshot references it.

Source

pub fn set_text_with_session( &mut self, session: &mut TextPreparationSession<'_>, text: &str, ) -> Result<(), TextError>

Changes text using reusable shaping state for this exact font registration.

A foreign registration is rejected even when UTF-8 is unchanged. An exact text match with the correct session performs no shaping. Any error preserves all visual fields and earlier snapshots; session scratch may have changed. Successful changes own fresh line storage, so this is not a zero-allocation update promise. The borrowed session never becomes part of the component.

Source

pub fn set_font(&mut self, font: TextFont) -> Result<(), TextError>

Selects a registered font and reparses the current line before swapping.

The same registration is a no-op. Missing glyphs, budgets, or invalid aligned geometry preserve the old font and every other field. Issuing application identity is checked by extraction, not by this standalone value.

Source

pub fn set_position( &mut self, position: LogicalScreenPosition, ) -> Result<(), TextError>

Moves the logical baseline anchor without shaping or changing retained text. Non-finite or unrepresentable aligned bounds leave the value unchanged.

Source

pub fn set_alignment( &mut self, alignment: TextAlignment, ) -> Result<(), TextError>

Changes advance-based alignment without shaping or rasterization. An unrepresentable adjusted baseline leaves every field unchanged.

Source

pub fn set_tint(&mut self, tint: Color) -> Result<(), TextError>

Changes normalized straight-linear RGBA tint atomically, without reshaping.

Source

pub fn set_layer(&mut self, layer: Layer)

Replaces the primary screen painter-order layer without preparing text again.

Source

pub fn set_draw_order_depth(&mut self, depth: f32) -> Result<(), TextError>

Replaces finite within-layer painter depth; negative values are allowed. Non-finite input preserves the current depth and every other field.

Trait Implementations§

Source§

impl Clone for ScreenTextVisual

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Component for ScreenTextVisual
where Self: Send + Sync + 'static,

Source§

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

A constant indicating the storage type used for this component.
Source§

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have Component<Mutability = Mutable>, while immutable components will instead have Component<Mutability = Immutable>. Read more
Source§

fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components. Read more
Source§

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component. Read more
Source§

fn relationship_accessor() -> Option<ComponentRelationshipAccessor<Self>>

Returns ComponentRelationshipAccessor required for working with relationships in dynamic contexts. Read more
Source§

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.
Source§

fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_insert ComponentHook for this Component if one is defined.
Source§

fn on_discard() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_discard ComponentHook for this Component if one is defined.
Source§

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.
Source§

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.
Source§

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)
where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities] Read more
Source§

impl Debug for ScreenTextVisual

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl PartialEq for ScreenTextVisual

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for ScreenTextVisual

Auto Trait Implementations§

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<C> Bundle for C
where C: Component,

Source§

fn component_ids( components: &mut ComponentsRegistrator<'_>, ) -> impl Iterator<Item = ComponentId> + use<C>

Source§

fn get_component_ids( components: &Components, ) -> impl Iterator<Item = Option<ComponentId>>

Return a iterator over this Bundle’s component ids. This will be None if the component has not been registered.
Source§

impl<C> BundleFromComponents for C
where C: Component,

Source§

unsafe fn from_components<T, F>(ctx: &mut T, func: &mut F) -> C
where F: for<'a> FnMut(&'a mut T) -> OwningPtr<'a>, C: Sized,

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> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

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

Source§

impl<T> Downcast for T
where T: Any,

Source§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
Source§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
Source§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
Source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> Downcast<T> for T

Source§

fn downcast(&self) -> &T

Source§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

Source§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync> ⓘ

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
Source§

impl<S, T> Duplex<S> for T
where T: FromSample<S> + ToSample<S>,

Source§

impl<C> DynamicBundle for C
where C: Component,

Source§

type Effect = ()

An operation on the entity that happens after inserting this bundle.
Source§

unsafe fn get_components( ptr: MovingPtr<'_, C>, func: &mut impl FnMut(StorageType, OwningPtr<'_>), ) -> <C as DynamicBundle>::Effect

Moves the components out of the bundle. Read more
Source§

unsafe fn apply_effect( _ptr: MovingPtr<'_, MaybeUninit<C>>, _entity: &mut EntityWorldMut<'_>, )

Applies the after-effects of spawning this bundle. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<S> FromSample<S> for S

Source§

fn from_sample_(s: S) -> S

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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> IntoResult<T> for T

Source§

fn into_result(self) -> Result<T, RunSystemError>

Converts this type into the system output type.
Source§

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

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> ToSample<U> for T
where U: FromSample<T>,

Source§

fn to_sample_(self) -> U

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,

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more