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
impl ScreenTextVisual
Sourcepub const fn clip(&self) -> ScreenClip
pub const fn clip(&self) -> ScreenClip
Returns the fixed-screen clip; label placement and alignment do not move it.
Sourcepub fn set_clip(&mut self, clip: ScreenClip)
pub fn set_clip(&mut self, clip: ScreenClip)
Replaces the explicit clip without reshaping or changing typographic metrics.
Sourcepub fn new(
font: TextFont,
text: &str,
position: LogicalScreenPosition,
) -> Result<Self, TextError>
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.
Sourcepub fn new_with_session(
session: &mut TextPreparationSession<'_>,
text: &str,
position: LogicalScreenPosition,
) -> Result<Self, TextError>
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.
Sourcepub const fn font(&self) -> &TextFont
pub const fn font(&self) -> &TextFont
Returns the opaque application font registration shared by this label.
Sourcepub fn text(&self) -> &str
pub fn text(&self) -> &str
Returns the original UTF-8 single line without allocating or reshaping.
Sourcepub fn shaped_line(&self) -> &ShapedLine
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.
Sourcepub fn metrics(&self) -> TextMetrics
pub fn metrics(&self) -> TextMetrics
Returns DPI-independent typographic metrics from the latest successful preparation.
Sourcepub fn glyph_count(&self) -> usize
pub fn glyph_count(&self) -> usize
Returns shaped glyph count, conservatively including whitespace.
Sourcepub fn retained_text_bytes(&self) -> usize
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().
Sourcepub fn retained_layout_bytes(&self) -> usize
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.
Sourcepub const fn position(&self) -> LogicalScreenPosition
pub const fn position(&self) -> LogicalScreenPosition
Returns the logical-pixel baseline anchor before horizontal alignment.
Sourcepub fn baseline_origin(&self) -> LogicalScreenPosition
pub fn baseline_origin(&self) -> LogicalScreenPosition
Returns the actual logical baseline origin after horizontal alignment. Typographic advance, including trailing spaces, determines the offset.
Sourcepub const fn alignment(&self) -> TextAlignment
pub const fn alignment(&self) -> TextAlignment
Returns how the line’s advance is aligned around its baseline anchor.
Sourcepub const fn tint(&self) -> Color
pub const fn tint(&self) -> Color
Returns normalized straight-linear RGBA multiplied by glyph coverage.
Sourcepub const fn layer(&self) -> Layer
pub const fn layer(&self) -> Layer
Returns the primary painter-order layer within screen content.
Sourcepub const fn draw_order_depth(&self) -> f32
pub const fn draw_order_depth(&self) -> f32
Returns finite within-layer ordering depth, not camera projection depth.
Sourcepub fn set_text(&mut self, text: &str) -> Result<(), TextError>
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.
Sourcepub fn set_text_with_session(
&mut self,
session: &mut TextPreparationSession<'_>,
text: &str,
) -> Result<(), TextError>
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.
Sourcepub fn set_font(&mut self, font: TextFont) -> Result<(), TextError>
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.
Sourcepub fn set_position(
&mut self,
position: LogicalScreenPosition,
) -> Result<(), TextError>
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.
Sourcepub fn set_alignment(
&mut self,
alignment: TextAlignment,
) -> Result<(), TextError>
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.
Sourcepub fn set_tint(&mut self, tint: Color) -> Result<(), TextError>
pub fn set_tint(&mut self, tint: Color) -> Result<(), TextError>
Changes normalized straight-linear RGBA tint atomically, without reshaping.
Trait Implementations§
Source§impl Clone for ScreenTextVisual
impl Clone for ScreenTextVisual
Source§impl Component for ScreenTextVisual
impl Component for ScreenTextVisual
Source§const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table
const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table
Source§type Mutability = Mutable
type Mutability = Mutable
Component<Mutability = Mutable>,
while immutable components will instead have Component<Mutability = Immutable>. Read moreSource§fn register_required_components(
_requiree: ComponentId,
required_components: &mut RequiredComponentsRegistrator<'_, '_>,
)
fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )
Source§fn clone_behavior() -> ComponentCloneBehavior
fn clone_behavior() -> ComponentCloneBehavior
Source§fn relationship_accessor() -> Option<ComponentRelationshipAccessor<Self>>
fn relationship_accessor() -> Option<ComponentRelationshipAccessor<Self>>
ComponentRelationshipAccessor required for working with relationships in dynamic contexts. Read moreSource§fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
Source§fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
Source§fn on_discard() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
fn on_discard() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
Source§fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
Source§fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>
Source§fn map_entities<E>(_this: &mut Self, _mapper: &mut E)where
E: EntityMapper,
fn map_entities<E>(_this: &mut Self, _mapper: &mut E)where
E: EntityMapper,
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 moreSource§impl Debug for ScreenTextVisual
impl Debug for ScreenTextVisual
Source§impl PartialEq for ScreenTextVisual
impl PartialEq for ScreenTextVisual
impl StructuralPartialEq for ScreenTextVisual
Auto Trait Implementations§
impl Freeze for ScreenTextVisual
impl RefUnwindSafe for ScreenTextVisual
impl Send for ScreenTextVisual
impl Sync for ScreenTextVisual
impl Unpin for ScreenTextVisual
impl UnsafeUnpin for ScreenTextVisual
impl UnwindSafe for ScreenTextVisual
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<C> Bundle for Cwhere
C: Component,
impl<C> Bundle for Cwhere
C: Component,
fn component_ids( components: &mut ComponentsRegistrator<'_>, ) -> impl Iterator<Item = ComponentId> + use<C>
Source§fn get_component_ids(
components: &Components,
) -> impl Iterator<Item = Option<ComponentId>>
fn get_component_ids( components: &Components, ) -> impl Iterator<Item = Option<ComponentId>>
Source§impl<C> BundleFromComponents for Cwhere
C: Component,
impl<C> BundleFromComponents for Cwhere
C: Component,
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> ConditionalSend for Twhere
T: Send,
Source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
Source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
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>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
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)
fn as_any(&self) -> &(dyn Any + 'static)
&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)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.