Skip to main content

Scene

Struct Scene 

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

Ordered list of visual draw commands for a single frame.

A scene contains renderable primitives only. It does not own simulation entities, domain rules, or time stepping.

Implementations§

Source§

impl Scene

Source

pub fn new(background: Color) -> Result<Self, SceneError>

Creates an empty scene with a normalized linear-RGBA background color.

This compatibility constructor is intentionally unbounded. Production hosts handling externally sized visual state should prefer Scene::with_budget.

Source

pub fn with_budget( background: Color, budget: SceneBudget, ) -> Result<Self, SceneError>

Creates an empty scene with explicit construction and rendering limits.

Source

pub fn background(&self) -> Color

Returns the normalized clear color used before drawing commands.

Source

pub fn set_background(&mut self, background: Color) -> Result<(), SceneError>

Replaces the clear color used before drawing commands.

Source

pub fn clear(&mut self)

Removes all draw commands and active clipping without changing the background color.

Source

pub fn commands(&self) -> &[SceneCommand]

Returns accepted commands in stable layer and insertion order.

Source

pub fn command_count(&self) -> usize

Returns the number of accepted render commands.

Source

pub fn allocation_bytes(&self) -> usize

Returns CPU allocation bytes currently owned by command and polyline storage.

Unlike SceneStatistics::retained_bytes, which is the budgeted payload of accepted commands, this includes spare Vec capacity retained for reuse after insertion or Scene::clear. Allocator bookkeeping is not included.

Source

pub const fn budget(&self) -> Option<SceneBudget>

Returns the explicit work budget, or None for an unbounded scene.

Source

pub const fn statistics(&self) -> SceneStatistics

Returns requested, accepted, rejected, and estimated scene work.

Source

pub fn set_screen_clip( &mut self, screen_clip: Option<ScreenClipRect>, ) -> Result<Option<ScreenClipRect>, SceneError>

Replaces the screen-space clipping rectangle captured by new commands.

The rectangle uses logical screen pixels with the origin at the top-left of the render surface. Existing commands keep the clip they captured when they were appended. None disables clipping for subsequent commands. The previous clip is returned so callers can restore explicit drawing state without tracking it separately. Invalid clips are rejected here, before they can affect a later command insertion.

Source

pub fn with_screen_clip<R>( &mut self, screen_clip: ScreenClipRect, draw: impl FnOnce(&mut Self) -> R, ) -> Result<R, SceneError>

Appends commands from draw using a temporary screen-space clip.

The rectangle uses logical screen pixels. Nested clips are intersected, so inner drawing cannot escape an outer clip. The previous clip is restored after draw returns.

Source

pub fn set_depth(&mut self, depth: f32) -> bool

Replaces the pseudo-depth captured by subsequently appended commands.

Depth is measured in caller-defined units and converted through crate::Projection2d::depth_scale. It affects projection only, not draw order. Non-finite values return false and leave the current depth unchanged.

Source

pub fn try_set_depth(&mut self, depth: f32) -> Result<(), SceneError>

Replaces pseudo-depth and reports why invalid input was rejected.

Source

pub fn with_depth<R>( &mut self, depth: f32, draw: impl FnOnce(&mut Self) -> R, ) -> Result<R, SceneError>

Appends commands with a temporary pseudo-depth value.

The previous depth is restored after draw returns or unwinds. Non-finite depth returns an error without calling draw.

Source

pub fn push(&mut self, command: DrawCommand) -> bool

Appends a valid command to the default layer.

Returns false without changing commands, ordering, or retained allocation when the primitive is invalid. Requested/rejected diagnostic counters still advance for the attempted command.

Source

pub fn try_push(&mut self, command: DrawCommand) -> Result<(), SceneError>

Appends a command to the default layer with structured rejection diagnostics.

Source

pub fn push_to_layer(&mut self, layer: Layer, command: DrawCommand) -> bool

Appends a command to a layer.

Lower layer values are drawn first. Commands on the same layer preserve insertion order. Returns false without changing commands, ordering, or retained allocation when command is invalid. Requested/rejected diagnostic counters still advance for the attempted command.

Source

pub fn try_push_to_layer( &mut self, layer: Layer, command: DrawCommand, ) -> Result<(), SceneError>

Appends a command to a layer with structured rejection diagnostics.

An incoming layer at or above the last layer appends without searching. Out-of-order layers use stable insertion. Both paths perform the same validation, budget checks, statistics updates, and capacity reuse.

Source

pub fn try_extend_to_layers( &mut self, commands: impl IntoIterator<Item = (Layer, DrawCommand)>, ) -> Result<(), SceneError>

Atomically appends many commands and orders the combined scene once.

This is the bounded high-volume construction path for adversarial or frequently alternating layers. Validation and budget accounting happen before the existing command list is changed. On failure, no command from the batch is retained; request and rejection diagnostics still advance. The resulting order is stable by layer and by batch insertion order.

Source

pub fn circle(&mut self, center: Vec2, radius: f32, style: ShapeStyle) -> bool

Appends a circle in world coordinates.

radius is in world units. Returns false for non-positive or non-finite radius, non-finite center, or invalid style values.

Source

pub fn try_circle( &mut self, center: Vec2, radius: f32, style: ShapeStyle, ) -> Result<(), SceneError>

Appends a circle and returns a structured validation error on rejection.

Source

pub fn circle_on_layer( &mut self, layer: Layer, center: Vec2, radius: f32, style: ShapeStyle, ) -> bool

Appends a circle in world coordinates to a layer.

radius is in world units. Returns false for non-positive or non-finite radius, non-finite center, or invalid style values.

Source

pub fn try_circle_on_layer( &mut self, layer: Layer, center: Vec2, radius: f32, style: ShapeStyle, ) -> Result<(), SceneError>

Appends a circle to a layer with structured rejection diagnostics.

Source

pub fn rect( &mut self, rect: Rect, corner_radius: f32, style: ShapeStyle, ) -> bool

Appends an axis-aligned rectangle in world coordinates.

corner_radius is in world units and renderers clamp it to half the rectangle size. Invalid bounds, negative radius, and invalid styles return false without adding a command.

Source

pub fn try_rect( &mut self, rect: Rect, corner_radius: f32, style: ShapeStyle, ) -> Result<(), SceneError>

Appends a rectangle and returns a structured validation error on rejection.

Source

pub fn rect_on_layer( &mut self, layer: Layer, rect: Rect, corner_radius: f32, style: ShapeStyle, ) -> bool

Appends an axis-aligned rectangle in world coordinates to a layer.

corner_radius is in world units and renderers clamp it to half the rectangle size. Invalid bounds, negative radius, and invalid styles return false without adding a command.

Source

pub fn try_rect_on_layer( &mut self, layer: Layer, rect: Rect, corner_radius: f32, style: ShapeStyle, ) -> Result<(), SceneError>

Appends a rectangle to a layer with structured rejection diagnostics.

Source

pub fn line(&mut self, from: Vec2, to: Vec2, width: f32, color: Color) -> bool

Appends a stroked line between world-space points.

width is in logical screen pixels so line thickness stays readable while the camera zooms. Degenerate geometry and invalid width or color return false.

Source

pub fn try_line( &mut self, from: Vec2, to: Vec2, width: f32, color: Color, ) -> Result<(), SceneError>

Appends a line and returns a structured validation error on rejection.

Source

pub fn line_on_layer( &mut self, layer: Layer, from: Vec2, to: Vec2, width: f32, color: Color, ) -> bool

Appends a stroked line between world-space points to a layer.

width is in logical screen pixels so line thickness stays readable while the camera zooms. Degenerate geometry and invalid width or color return false.

Source

pub fn try_line_on_layer( &mut self, layer: Layer, from: Vec2, to: Vec2, width: f32, color: Color, ) -> Result<(), SceneError>

Appends a line to a layer with structured rejection diagnostics.

Source

pub fn styled_line( &mut self, from: Vec2, to: Vec2, style: StrokeStyle2d, ) -> bool

Appends a line with explicit width units, caps, joins, dashes, and markers.

Source

pub fn try_styled_line( &mut self, from: Vec2, to: Vec2, style: StrokeStyle2d, ) -> Result<(), SceneError>

Appends an explicitly styled line with structured rejection diagnostics.

Source

pub fn styled_line_on_layer( &mut self, layer: Layer, from: Vec2, to: Vec2, style: StrokeStyle2d, ) -> bool

Appends an explicitly styled line to a shared draw layer.

Source

pub fn try_styled_line_on_layer( &mut self, layer: Layer, from: Vec2, to: Vec2, style: StrokeStyle2d, ) -> Result<(), SceneError>

Appends an explicitly styled line to a layer with structured rejection.

Source

pub fn polyline(&mut self, points: Vec<Vec2>, width: f32, color: Color) -> bool

Appends connected stroked segments through world-space points.

width is in logical screen pixels. Empty, single-point, non-finite, repeated-adjacent, or numerically ambiguous turn input returns false without adding a command; every consecutive segment must be drawable.

Source

pub fn try_polyline( &mut self, points: Vec<Vec2>, width: f32, color: Color, ) -> Result<(), SceneError>

Appends a polyline and returns a structured validation error on rejection.

Source

pub fn polyline_on_layer( &mut self, layer: Layer, points: Vec<Vec2>, width: f32, color: Color, ) -> bool

Appends connected stroked segments through world-space points to a layer.

width is in logical screen pixels. Empty, single-point, non-finite, repeated-adjacent, or numerically ambiguous turn input returns false without adding a command; every consecutive segment must be drawable.

Source

pub fn try_polyline_on_layer( &mut self, layer: Layer, points: Vec<Vec2>, width: f32, color: Color, ) -> Result<(), SceneError>

Appends a polyline to a layer with structured rejection diagnostics.

Source

pub fn styled_polyline( &mut self, points: Vec<Vec2>, style: StrokeStyle2d, ) -> bool

Appends a connected path with explicit width, caps, joins, dashes, and markers.

Source

pub fn try_styled_polyline( &mut self, points: Vec<Vec2>, style: StrokeStyle2d, ) -> Result<(), SceneError>

Appends an explicitly styled path with structured rejection diagnostics.

Source

pub fn styled_polyline_on_layer( &mut self, layer: Layer, points: Vec<Vec2>, style: StrokeStyle2d, ) -> bool

Appends an explicitly styled path to a shared draw layer.

Source

pub fn try_styled_polyline_on_layer( &mut self, layer: Layer, points: Vec<Vec2>, style: StrokeStyle2d, ) -> Result<(), SceneError>

Appends an explicitly styled path to a layer with structured rejection.

Trait Implementations§

Source§

impl Clone for Scene

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 Debug for Scene

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl Freeze for Scene

§

impl RefUnwindSafe for Scene

§

impl Send for Scene

§

impl Sync for Scene

§

impl Unpin for Scene

§

impl UnsafeUnpin for Scene

§

impl UnwindSafe for Scene

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