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
impl Scene
Sourcepub fn new(background: Color) -> Result<Self, SceneError>
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.
Sourcepub fn with_budget(
background: Color,
budget: SceneBudget,
) -> Result<Self, SceneError>
pub fn with_budget( background: Color, budget: SceneBudget, ) -> Result<Self, SceneError>
Creates an empty scene with explicit construction and rendering limits.
Sourcepub fn background(&self) -> Color
pub fn background(&self) -> Color
Returns the normalized clear color used before drawing commands.
Sourcepub fn set_background(&mut self, background: Color) -> Result<(), SceneError>
pub fn set_background(&mut self, background: Color) -> Result<(), SceneError>
Replaces the clear color used before drawing commands.
Sourcepub fn clear(&mut self)
pub fn clear(&mut self)
Removes all draw commands and active clipping without changing the background color.
Sourcepub fn commands(&self) -> &[SceneCommand]
pub fn commands(&self) -> &[SceneCommand]
Returns accepted commands in stable layer and insertion order.
Sourcepub fn command_count(&self) -> usize
pub fn command_count(&self) -> usize
Returns the number of accepted render commands.
Sourcepub fn allocation_bytes(&self) -> usize
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.
Sourcepub const fn budget(&self) -> Option<SceneBudget>
pub const fn budget(&self) -> Option<SceneBudget>
Returns the explicit work budget, or None for an unbounded scene.
Sourcepub const fn statistics(&self) -> SceneStatistics
pub const fn statistics(&self) -> SceneStatistics
Returns requested, accepted, rejected, and estimated scene work.
Sourcepub fn set_screen_clip(
&mut self,
screen_clip: Option<ScreenClipRect>,
) -> Result<Option<ScreenClipRect>, SceneError>
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.
Sourcepub fn with_screen_clip<R>(
&mut self,
screen_clip: ScreenClipRect,
draw: impl FnOnce(&mut Self) -> R,
) -> Result<R, SceneError>
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.
Sourcepub fn set_depth(&mut self, depth: f32) -> bool
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.
Sourcepub fn try_set_depth(&mut self, depth: f32) -> Result<(), SceneError>
pub fn try_set_depth(&mut self, depth: f32) -> Result<(), SceneError>
Replaces pseudo-depth and reports why invalid input was rejected.
Sourcepub fn with_depth<R>(
&mut self,
depth: f32,
draw: impl FnOnce(&mut Self) -> R,
) -> Result<R, SceneError>
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.
Sourcepub fn push(&mut self, command: DrawCommand) -> bool
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.
Sourcepub fn try_push(&mut self, command: DrawCommand) -> Result<(), SceneError>
pub fn try_push(&mut self, command: DrawCommand) -> Result<(), SceneError>
Appends a command to the default layer with structured rejection diagnostics.
Sourcepub fn push_to_layer(&mut self, layer: Layer, command: DrawCommand) -> bool
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.
Sourcepub fn try_push_to_layer(
&mut self,
layer: Layer,
command: DrawCommand,
) -> Result<(), SceneError>
pub fn try_push_to_layer( &mut self, layer: Layer, command: DrawCommand, ) -> Result<(), SceneError>
Appends a command to a layer with structured rejection diagnostics.
Sourcepub fn try_extend_to_layers(
&mut self,
commands: impl IntoIterator<Item = (Layer, DrawCommand)>,
) -> Result<(), SceneError>
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.
Sourcepub fn circle(&mut self, center: Vec2, radius: f32, style: ShapeStyle) -> bool
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.
Sourcepub fn try_circle(
&mut self,
center: Vec2,
radius: f32,
style: ShapeStyle,
) -> Result<(), SceneError>
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.
Sourcepub fn circle_on_layer(
&mut self,
layer: Layer,
center: Vec2,
radius: f32,
style: ShapeStyle,
) -> bool
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.
Sourcepub fn try_circle_on_layer(
&mut self,
layer: Layer,
center: Vec2,
radius: f32,
style: ShapeStyle,
) -> Result<(), SceneError>
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.
Sourcepub fn rect(
&mut self,
rect: Rect,
corner_radius: f32,
style: ShapeStyle,
) -> bool
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.
Sourcepub fn try_rect(
&mut self,
rect: Rect,
corner_radius: f32,
style: ShapeStyle,
) -> Result<(), SceneError>
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.
Sourcepub fn rect_on_layer(
&mut self,
layer: Layer,
rect: Rect,
corner_radius: f32,
style: ShapeStyle,
) -> bool
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.
Sourcepub fn try_rect_on_layer(
&mut self,
layer: Layer,
rect: Rect,
corner_radius: f32,
style: ShapeStyle,
) -> Result<(), SceneError>
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.
Sourcepub fn line(&mut self, from: Vec2, to: Vec2, width: f32, color: Color) -> bool
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.
Sourcepub fn try_line(
&mut self,
from: Vec2,
to: Vec2,
width: f32,
color: Color,
) -> Result<(), SceneError>
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.
Sourcepub fn line_on_layer(
&mut self,
layer: Layer,
from: Vec2,
to: Vec2,
width: f32,
color: Color,
) -> bool
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.
Sourcepub fn try_line_on_layer(
&mut self,
layer: Layer,
from: Vec2,
to: Vec2,
width: f32,
color: Color,
) -> Result<(), SceneError>
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.
Sourcepub fn styled_line(
&mut self,
from: Vec2,
to: Vec2,
style: StrokeStyle2d,
) -> bool
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.
Sourcepub fn try_styled_line(
&mut self,
from: Vec2,
to: Vec2,
style: StrokeStyle2d,
) -> Result<(), SceneError>
pub fn try_styled_line( &mut self, from: Vec2, to: Vec2, style: StrokeStyle2d, ) -> Result<(), SceneError>
Appends an explicitly styled line with structured rejection diagnostics.
Sourcepub fn styled_line_on_layer(
&mut self,
layer: Layer,
from: Vec2,
to: Vec2,
style: StrokeStyle2d,
) -> bool
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.
Sourcepub fn try_styled_line_on_layer(
&mut self,
layer: Layer,
from: Vec2,
to: Vec2,
style: StrokeStyle2d,
) -> Result<(), SceneError>
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.
Sourcepub fn polyline(&mut self, points: Vec<Vec2>, width: f32, color: Color) -> bool
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.
Sourcepub fn try_polyline(
&mut self,
points: Vec<Vec2>,
width: f32,
color: Color,
) -> Result<(), SceneError>
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.
Sourcepub fn polyline_on_layer(
&mut self,
layer: Layer,
points: Vec<Vec2>,
width: f32,
color: Color,
) -> bool
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.
Sourcepub fn try_polyline_on_layer(
&mut self,
layer: Layer,
points: Vec<Vec2>,
width: f32,
color: Color,
) -> Result<(), SceneError>
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.
Sourcepub fn styled_polyline(
&mut self,
points: Vec<Vec2>,
style: StrokeStyle2d,
) -> bool
pub fn styled_polyline( &mut self, points: Vec<Vec2>, style: StrokeStyle2d, ) -> bool
Appends a connected path with explicit width, caps, joins, dashes, and markers.
Sourcepub fn try_styled_polyline(
&mut self,
points: Vec<Vec2>,
style: StrokeStyle2d,
) -> Result<(), SceneError>
pub fn try_styled_polyline( &mut self, points: Vec<Vec2>, style: StrokeStyle2d, ) -> Result<(), SceneError>
Appends an explicitly styled path with structured rejection diagnostics.
Sourcepub fn styled_polyline_on_layer(
&mut self,
layer: Layer,
points: Vec<Vec2>,
style: StrokeStyle2d,
) -> bool
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.
Sourcepub fn try_styled_polyline_on_layer(
&mut self,
layer: Layer,
points: Vec<Vec2>,
style: StrokeStyle2d,
) -> Result<(), SceneError>
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.