Struct SpriteItem 

#[non_exhaustive]
pub struct SpriteItem {

    pub texture_id: Option<u64>,
    pub positions: Vec<[f32; 3]>,
    pub colours: Vec<[f32; 4]>,
    pub sizes: Vec<f32>,
    pub rotations: Vec<f32>,
    pub uv_rects: Vec<[f32; 4]>,
    pub default_colour: [f32; 4],
    pub default_size: f32,
    pub size_mode: SpriteSizeMode,
    pub model: [[f32; 4]; 4],
    pub depth_write: bool,
    pub blend: SpriteBlend,
    pub soft_particle_distance: Option<f32>,
    pub soft_particle_distances: Vec<f32>,
    pub refraction_strength: Option<f32>,
    pub orientation: SpriteOrientation,
    pub velocities: Vec<[f32; 3]>,
    pub axis: [f32; 3],
    pub lit: bool,
    pub lit_params: SpriteLitParams,
    pub normal_texture_id: Option<u64>,
    pub settings: ItemSettings,
}

A batch of instanced billboard sprites rendered as camera-facing textured quads.

Each instance is one billboard at a world-space position. All instances in the batch share one texture (or render as solid-colour quads when texture_id is None). Per-instance colour, size, rotation, and atlas UV rect are specified via parallel Vec fields; empty vecs fall back to the batch defaults.

Particle effects

Submit a new SpriteItem each frame with updated positions and colours to animate CPU-simulated particle effects. The host application owns simulation state (velocity, lifetime, emission); the renderer only handles drawing.

Texture atlases

Set uv_rects to select sub-regions of the texture per sprite, enabling flip-book animation or mixed icon sets from a single atlas texture.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

texture_id: Option<u64>

Texture ID from [ViewportGpuResources::upload_texture]. None renders solid-colour quads using colours / default_colour only.

positions: Vec<[f32; 3]>

World-space positions, one per sprite instance.

colours: Vec<[f32; 4]>

Per-instance RGBA colour tints. Empty = use default_colour for all. Multiplied with the texture sample (or used directly when texture_id is None).

sizes: Vec<f32>

Per-instance sizes. Empty = use default_size for all. Interpretation depends on size_mode.

rotations: Vec<f32>

Per-instance rotation angles in radians, CCW around the camera-forward axis. Empty = no rotation applied.

uv_rects: Vec<[f32; 4]>

Per-instance UV rects [u0, v0, u1, v1] selecting atlas sub-regions. Empty = full texture [0.0, 0.0, 1.0, 1.0] for all.

default_colour: [f32; 4]

Fallback RGBA colour tint used when colours is empty. Default: opaque white.

default_size: f32

Default size when sizes is empty. Pixels (ScreenSpace) or world units (WorldSpace).

size_mode: SpriteSizeMode

Whether sizes are in screen-space pixels or world-space units.

model: [[f32; 4]; 4]

World-space model transform applied to all positions. Default: identity.

depth_write: bool

Whether this batch writes to the depth buffer. Default: false.

Set false for transparent or additive particle effects so sprites do not occlude each other based on submission order. Set true for opaque world-space markers that should participate in depth testing normally.

blend: SpriteBlend

GPU blend state for this batch. Default: SpriteBlend::AlphaBlend.

soft_particle_distance: Option<f32>

If Some(d), fades the sprite’s alpha as it approaches opaque scene geometry behind it, over a distance of d world-space units. None disables soft fade.

Useful for transparent particles like smoke or fog to avoid hard intersection lines against walls and ground. Requires a sampleable scene depth resolve; see crate docs for current support status.

Used as the fallback when Self::soft_particle_distances is empty or shorter than positions, or when a per-instance entry is zero.

soft_particle_distances: Vec<f32>

Per-instance soft-fade distances, in world-space units. Lets a single batch mix large smoke puffs (long fade) and small embers (short fade) without splitting the draw. Empty falls back to Self::soft_particle_distance for every instance; a zero entry falls back to the batch default as well.

refraction_strength: Option<f32>

If Some(d), the sprite is drawn as a refractive distortion rather than a normal alpha-blended billboard: the renderer samples the already-resolved scene colour at an offset driven by the sprite’s texture (red/green channels as signed displacement, alpha as mask) and writes the distorted result back to the scene. d scales the displacement in NDC pixels. Use for heat haze, shockwaves, force-field hits, water-splash droplets.

Available on the HDR path only; the direct LDR paint_to cannot resolve scene colour for sampling (same constraint as soft particles). None disables refraction and the sprite draws normally.

orientation: SpriteOrientation

How each billboard is oriented in world space. Default SpriteOrientation::CameraFacing matches the historical behaviour: every quad turns to face the camera.

velocities: Vec<[f32; 3]>

Per-instance velocity vectors. Used by SpriteOrientation::VelocityStretched to align each quad’s long axis with the projected motion direction. Empty disables stretching for that instance (it falls back to a square camera-facing quad).

axis: [f32; 3]

World-space axis used by SpriteOrientation::AxisLocked for the quad’s long axis. Ignored in other orientation modes. Default [0, 0, 1] (world up).

lit: bool

When true, the batch runs through the lit sprite pipeline and participates in the scene’s hemisphere ambient and direct lighting. Default false preserves the emissive billboard look.

lit_params: SpriteLitParams

Lighting parameters used when lit is true. Ignored otherwise.

normal_texture_id: Option<u64>

Texture sampled as a tangent-space normal map when lit_params.normal_mode is SpriteNormalMode::NormalMap. None falls back to the spherical normal even when the mode requests a map.

settings: ItemSettings

Per-item render settings (visibility, appearance, pick identity, selection state).

Trait Implementations

impl Clone for SpriteItem

fn clone(&self) -> SpriteItem

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for SpriteItem

fn default() -> Self

Returns the “default value” for a type.