Struct SceneRenderer 

pub struct SceneRenderer { /* private fields */ }

Unified renderer over the CPU and GPU paths. See the crate docs.

Implementations

impl SceneRenderer

pub fn new<W>(window: Arc<W>, size: (u32, u32), opts: &RenderOptions) -> Self

where W: HasWindowHandle + HasDisplayHandle + Send + Sync + 'static,

Build a renderer for window — any raw-window-handle provider (winit, SDL, GLFW, …) in an Arc. size is the window’s initial physical framebuffer size in pixels; thereafter the host reports changes via Self::resize. Passing the size explicitly keeps the facade decoupled from any one windowing library’s size API.

Selects the GPU backend when opts.want_gpu and WGPU initialises; otherwise the CPU backend. Never fails — a missing/incompatible GPU silently yields the CPU path (the message is logged to stderr).

pub fn backend(&self) -> Backend

Which backend was selected.

pub fn adapter_info(&self) -> Option<&str>

The GPU adapter description when on the GPU backend, else None.

pub fn set_sky_panorama(&mut self, rgba: &[u8], w: u32, h: u32)

Upload an equirectangular sky panorama (RGBA8, w×h) for the GPU marcher’s sky sampling. No-op on the CPU backend, which samples the Sky passed in each FrameParams instead.

pub fn resize(&mut self, width: u32, height: u32)

Follow a window resize. CPU resizes its framebuffer lazily, so this only matters to the GPU swapchain — but it’s safe to call for both.

pub fn render( &mut self, scene: &mut Scene, camera: &Camera, frame: &FrameParams<'_>, )

Composite scene from camera with frame params into the backend’s frame buffer — without presenting. The CPU backend fills sky + runs the opticast compositor into an owned buffer; the GPU backend uploads/refreshes the scene, runs the compute marcher + sprite pass, and acquires (but does not present) the swapchain frame.

Finish the frame with exactly one of present (no overlay) or paint_egui (UI overlay). Calling render again without finishing drops the pending frame.

pub fn draw_lines(&mut self, camera: &Camera, lines: &[Line3])

Draw world-space Line3 segments over the frame render composited, using that frame’s camera + projection + depth buffer. Call after render and before present / paint_egui — the lines land in the framebuffer, so a subsequent paint_egui still draws its panels on top.

camera must be the one the last frame rendered with (the projection is taken from that frame). Depth-tested segments (Line3::depth_test) are occluded by nearer rendered geometry; always-on-top segments ignore depth. See Line3 for colour / width / blend semantics.

pub fn upload_image( &mut self, rgba: &[u8], width: u32, height: u32, ) -> Option<ImageId>

Upload (or replace) an RGBA8 image and return a stable ImageId to reference it in draw_images. rgba is row-major, width * height * 4 bytes, straight (un-premultiplied) alpha. The texture is retained until drop_image, so the per-frame draw call stays cheap. Sampling is nearest-neighbour (pixel-art friendly — no blurring).

Returns None for malformed input — a wrong byte count (!= width·height·4) or a zero dimension — so a bad upload can’t be confused with the first valid id (ImageId(0)).

pub fn drop_image(&mut self, id: ImageId)

Release a texture uploaded with upload_image. The id must not be reused afterwards (a later upload_image may hand the slot back out under a fresh id).

pub fn draw_images(&mut self, camera: &Camera, images: &[ImageSprite])

Draw 2D ImageSprites over the frame render composited — flat textured quads placed in world space, using that frame’s camera + projection + depth buffer. Same contract as draw_lines: call after render and before present / paint_egui.

UVs are perspective-correct (no affine warp on an obliquely-viewed quad). Depth-tested sprites are occluded by nearer rendered geometry (with a bias to avoid z-fighting on a coincident face); the texture’s straight alpha + the ImageSprite::tint composite over the scene. camera must be the one the last frame rendered.

pub fn project_point( &self, camera: &Camera, world: [f32; 3], ) -> Option<(f32, f32)>

Project a world point to window pixel coordinates (x, y) under the projection the last frame rendered with — the backend-correct world → screen inverse of view_ray. None before the first frame or for a point at/behind the camera near plane.

Both backends honour their own projection (CPU setcamera hx/hy/hz, GPU vertical-FOV pinhole), so hosts never reconstruct it themselves. The returned (x, y) may fall outside [0, w) × [0, h) for points off-screen but in front of the camera.

pub fn pick_image( &self, camera: &Camera, x: f64, y: f64, sprites: &[ImageSprite], ) -> Option<ImagePickHit>

Screen→sprite pick: the nearest ImageSprite hit under window pixel (x, y), resolving which texel was clicked. sprites is the same list passed to draw_images (image sprites are immediate-mode, so the caller owns the set). None for a miss.

The ray is intersected with each quad’s plane and mapped to its uv / source texel. A texel whose alpha is below the sprite’s ImageSprite::alpha_cutoff (and any fully-transparent texel) is see-through — the pick passes through it to a sprite behind. For depth_test sprites the hit is rejected when nearer scene geometry occludes that pixel (shares the depth convention + bias of pick; on the GPU backend the occlusion test costs a click-time depth readback).

pub fn set_flip_x(&mut self, flip: bool)

Mirror the rendered 3D scene horizontally before display. The flip is applied before any egui overlay, so the UI stays upright while the viewport un-mirrors — a fix for the engine’s left-handed render. Supported on both backends (CPU reverses the framebuffer rows; GPU mirrors the scene blit + line/image overlays). Picking/projection are unchanged, so a host that flips must mirror its cursor X (width - x) for ray casts.

pub fn present(&mut self)

Present the frame render composited, with no UI overlay. Pairs with render; use paint_egui instead to overlay an egui UI before presenting.

pub fn set_sprites(&mut self, set: &SpriteSet) -> Vec<SpriteModelId>

Register sprite models + instances. The CPU backend builds a per-instance draw list; the GPU backend builds an instanced model registry. Call once at setup (or again to replace).

pub fn refresh_sprite_model(&mut self, model: SpriteModelId, kv6: &Kv6)

Re-register one sprite model’s geometry after you’ve edited its content (a carve or recolour of its kv6). model is the SpriteModelId handed back by set_sprites; kv6 is the model’s new geometry — the caller owns the source of truth (e.g. a dense carve grid the surface-only kv6 can’t represent) and supplies the refreshed mesh here.

This is a backend-agnostic content refresh, not a GPU upload: the renderer brings its stored model up to date however its active backend needs to. The instance set is left untouched (an edit never moves or adds an instance), so on the GPU backend only that one model’s voxel data is re-uploaded — through a slack-backed suballocator, one model’s bytes rather than the whole registry — while the CPU backend swaps the cached kv6 into each instance of the model. Use set_sprites to add/remove models or change the instance set.

pub fn add_sprite_instance( &mut self, model: SpriteModelId, pos: [f32; 3], ) -> SpriteInstanceId

Add one sprite instance of an already-registered model at world pos, incrementally — the cheap streaming-spawn path that both backends now share (GPU: append to the instance buffer, growing by powers of two; CPU: push one pre-posed Sprite). Returns a stable SpriteInstanceId for later removal.

model must be a SpriteModelId from the current set_sprites (a model registered there, even with zero initial instances). Dynamic instances live after the static set + any KFA limbs, so register those first.

pub fn add_sprite_instance_posed( &mut self, model: SpriteModelId, xf: DynSpriteTransform, ) -> SpriteInstanceId

Add one sprite instance of an already-registered model, pre-posed with the orientation in xf — the streaming-spawn path for objects that appear mid-flight already rotated (so there’s no one-frame axis-aligned flash before the first set_sprite_instance_transform). Otherwise identical to add_sprite_instance (which is just this with the identity basis). Returns a stable SpriteInstanceId.

A stale/removed model handle spawns nothing and returns a handle that is itself already stale (it resolves to no instance). xf’s basis must be non-singular; a degenerate one makes the instance silently skip drawing (see DynSpriteTransform).

pub fn remove_sprite_instance(&mut self, id: SpriteInstanceId) -> bool

Remove a dynamic sprite instance added by add_sprite_instance. O(1) on both backends (swap-remove); other dynamic handles stay valid. Returns false if the handle is stale / already removed.

pub fn dynamic_sprite_count(&self) -> usize

Number of live dynamic sprite instances (those added via add_sprite_instance).

pub fn add_sprite_model(&mut self, kv6: &Kv6) -> SpriteModelId

Register one new sprite model incrementally from kv6, without rebuilding the existing model set — the streaming-in counterpart to add_sprite_instance for unique generated geometry (procedural asteroids, debris). Returns a stable SpriteModelId usable immediately with add_sprite_instance / add_sprite_instance_posed.

Works before any set_sprites (it establishes residency on the GPU backend’s first model). The GPU backend appends one LOD chain to the resident registry (amortised O(model voxels)); the CPU backend pushes an axis-aligned template.

pub fn remove_sprite_model(&mut self, id: SpriteModelId) -> bool

Remove a registered sprite model, freeing its voxel data. Returns false if id is stale / already removed.

The model’s slot is tombstoned in place: its id is never reused, so every other SpriteModelId stays valid (no remap). Existing instances of the removed model are not dropped here — they linger but draw as nothing on the GPU backend (the CPU backend keeps each instance’s own kv6 clone, so they keep drawing until removed via remove_sprite_instance); remove them when convenient. Call compact_sprite_models afterwards to reclaim the GPU buffer holes.

pub fn compact_sprite_models(&mut self)

Reclaim the GPU buffer space left by remove_sprite_model by repacking the resident registry to its live models only. Model ids are preserved (no remap). O(live voxel volume) — call it when many models have been removed, not every frame. No-op on the CPU backend (which keeps cheap empty placeholders) and when nothing was removed.

pub fn set_sprite_instance_transform( &mut self, id: SpriteInstanceId, xf: DynSpriteTransform, )

Update one dynamic instance’s full pose (position + orientation) for this frame. id is from add_sprite_instance / add_sprite_instance_posed. A stale / removed handle is a no-op.

For many instances per frame prefer set_sprite_instance_transforms: the GPU backend flushes all pending pose changes to the device once per render, so a per-instance call here is still O(1) device work, but the batch variant avoids re-walking the slotmap.

pub fn set_sprite_instance_transforms( &mut self, updates: &[(SpriteInstanceId, DynSpriteTransform)], )

Batch form of set_sprite_instance_transform — apply many (instance, pose) updates in one call. Stale handles in updates are skipped. On the GPU backend this marks the instance buffer dirty once and uploads the new poses a single time at the next render, so spinning a whole cluster of instances per frame is one device upload, not one per instance.

pub fn add_voxel_clip(&mut self, clip: &DecodedClip) -> VoxelClipId

Register an animated voxel clip (“GIF/MP4 for voxels”): decode all its frames and upload the flipbook to the active backend (GPU: one LOD chain per frame; CPU: a cached dense grid per frame). Returns a VoxelClipId to spawn instances of it via add_clip_instance_posed.

Build the DecodedClip from a .rvc via VoxelClip::decode. Like add_sprite_model, this works before any set_sprites; a later set_sprites drops all registered clips (re-register afterwards).

pub fn remove_voxel_clip(&mut self, id: VoxelClipId) -> bool

Remove a registered clip, freeing its per-frame volumes. Instances of it linger but draw nothing until removed via remove_sprite_instance. Returns false if id is stale / already removed.

pub fn add_clip_instance_posed( &mut self, clip: VoxelClipId, xf: DynSpriteTransform, ) -> SpriteInstanceId

Spawn an instance of clip clip, posed by xf, starting on frame 0. Returns a SpriteInstanceId — a clip instance is a dynamic sprite instance, so move it with set_sprite_instance_transform, advance its frame with set_clip_instance_frame, and drop it with remove_sprite_instance. A stale clip handle yields an instance id that resolves to nothing (a safe no-op everywhere).

This instance has no playback clock: drive its frame yourself via set_clip_instance_frame (frame-based scrubbing). For clock-based control — auto-advance, play/pause, or set_clip_instance_clock_ms scrubbing — spawn with add_clip_instance_playing instead (the player-control methods no-op on an instance with no player).

pub fn set_clip_instance_frame(&mut self, id: SpriteInstanceId, frame: u32)

Select which frame a clip instance shows — the per-frame playback step. Cheap on both backends (GPU: swap the instance’s model id; CPU: select the cached frame grid), with no volume re-upload. Drive it from a playback clock via DecodedClip::frame_at. No-op on a stale id or a non-clip instance.

pub fn clip_frame_count(&self, id: VoxelClipId) -> Option<usize>

Frame count of a registered flipbook clip, or None if id is stale. (Same as clip_metadata(id)?.frame_count, without the clone.)

pub fn clip_metadata(&self, id: VoxelClipId) -> Option<ClipMetadata>

Inspector metadata (dims / pivot / scale / loop mode / per-frame durations) of a registered flipbook clip, or None if id is stale — so an editor needn’t shadow the source DecodedClip.

pub fn get_clip_instance_frame(&self, id: SpriteInstanceId) -> Option<u32>

Which frame a clip instance is currently showing (the timeline scrubber’s read-back), or None if id isn’t a live clip instance.

pub fn update_clip_frame( &mut self, id: VoxelClipId, frame: u32, vf: &VoxelFrame, ) -> bool

Re-upload a single frame of registered clip id in place — the editor’s one-voxel paint, O(1 frame) instead of remove_voxel_clip + add_voxel_clip (which rebuilds all N volumes). vf must fit the clip’s fixed dims. Returns false on a stale id, an out-of-range frame, or a frame that fails the clip’s layout (so it can’t corrupt the flipbook).

pub fn add_streaming_clip( &mut self, clip: &VoxelClip, ) -> Result<StreamingClipId, DecodeError>

Register a streaming voxel clip — O(1-frame) memory (one sprite model + the compact encoded stream) rather than the N-volume flipbook add_voxel_clip builds, for huge clips where N frames are too costly to hold resident. Builds the model from frame 0; advance it with set_streaming_clip_frame. Spawn instances with add_streaming_clip_instance — note that, unlike a flipbook, all instances of a streaming clip share its one model and so always show the same (current) frame.

Takes the encoded VoxelClip (not a DecodedClip) — the whole point is to avoid materialising every frame.

Errors

DecodeError if the clip’s frame stream is empty or doesn’t begin with a keyframe.

pub fn add_streaming_clip_instance( &mut self, id: StreamingClipId, xf: DynSpriteTransform, ) -> StreamingInstanceId

Spawn an instance of streaming clip id, posed by xf. Returns a SpriteInstanceId — move it with set_sprite_instance_transform and drop it with remove_sprite_instance, like any dynamic instance. All instances of one streaming clip share its single model. A stale id yields a no-op instance handle.

pub fn set_streaming_instance_transform( &mut self, id: StreamingInstanceId, xf: DynSpriteTransform, )

Re-pose a streaming-clip instance (world transform). No-op on a stale handle.

pub fn remove_streaming_instance(&mut self, id: StreamingInstanceId) -> bool

Remove a streaming-clip instance. Returns false if id is stale.

pub fn set_streaming_clip_frame(&mut self, id: StreamingClipId, frame: u32)

Advance a streaming clip to frame: seek the cursor and re-upload its single model — the per-frame streaming step (one volume re-upload, vs the flipbook’s cheap model-select). Updates every instance of the clip at once. Drive it from a clock via frame_at. No-op on a stale id; frame is clamped to the last.

pub fn remove_streaming_clip(&mut self, id: StreamingClipId) -> bool

Remove a streaming clip: free its model and drop the cursor (the memory win for huge clips). Instances linger but draw nothing until removed. Returns false if id is stale / already removed.

pub fn add_clip_instance_playing( &mut self, clip: VoxelClipId, xf: DynSpriteTransform, speed_q8: i32, start_phase_ms: u32, ) -> SpriteInstanceId

Spawn a flipbook-clip instance that plays itself: like add_clip_instance_posed, but the facade tracks a playback clock so a single advance_voxel_clips call advances every such instance — no per-frame frame_at + set_clip_instance_frame bookkeeping in the host. speed_q8 is the Q8 playback rate (256 = 1×); start_phase_ms offsets the clock (stagger copies of one clip). A stale clip yields a no-op instance handle and no player.

pub fn play_streaming_clip( &mut self, clip: StreamingClipId, speed_q8: i32, start_phase_ms: u32, )

Give a streaming clip (add_streaming_clip) its own playback clock, advanced by advance_voxel_clips. A streaming clip’s frame is per-clip (all its instances share one model), so this is keyed on the clip, not an instance — register instances separately with add_streaming_clip_instance. No-op on a stale clip.

Control the player (play/pause/scrub) via set_streaming_clip_paused / set_streaming_clip_speed / set_streaming_clip_clock_ms, the per-clip analogues of the flipbook set_clip_instance_* methods.

pub fn advance_voxel_clips(&mut self, dt: f64)

Advance every auto-playing clip (add_clip_instance_playing / play_streaming_clip) by dt seconds: tick each clock, resolve its frame via frame_at, and apply it. Players whose instance / clip was removed are pruned. Call once per frame.

pub fn set_clip_instance_paused(&mut self, id: SpriteInstanceId, paused: bool)

Pause / resume the auto-player driving clip instance id (the editor’s play/pause). No-op if id has no player.

pub fn is_clip_instance_paused(&self, id: SpriteInstanceId) -> Option<bool>

Whether clip instance id’s auto-player is paused, or None if it has no player.

pub fn set_clip_instance_speed(&mut self, id: SpriteInstanceId, speed_q8: i32)

Set the playback speed (Q8: 256 = 1×, negative = reverse) of clip instance id’s auto-player. No-op if id has no player.

pub fn set_clip_instance_clock_ms( &mut self, id: SpriteInstanceId, clock_ms: f64, )

Scrub: set clip instance id’s playback clock to clock_ms and immediately show the matching frame (works while paused). No-op if id has no player.

pub fn clip_instance_clock_ms(&self, id: SpriteInstanceId) -> Option<f64>

Clip instance id’s current playback-clock position (ms), or None if it has no player — the scrubber’s read-back.

pub fn set_streaming_clip_paused(&mut self, clip: StreamingClipId, paused: bool)

Pause / resume a streaming clip’s auto-player (play_streaming_clip). No-op if clip has no player.

pub fn is_streaming_clip_paused(&self, clip: StreamingClipId) -> Option<bool>

Whether streaming clip clip’s auto-player is paused, or None if it has no player.

pub fn set_streaming_clip_speed(&mut self, clip: StreamingClipId, speed_q8: i32)

Set the playback speed (Q8: 256 = 1×, negative = reverse) of streaming clip clip’s auto-player. No-op if clip has no player.

pub fn set_streaming_clip_clock_ms( &mut self, clip: StreamingClipId, clock_ms: f64, )

Scrub a streaming clip: set its auto-player’s clock to clock_ms and immediately show the matching frame (works while paused). No-op if clip has no player.

pub fn streaming_clip_clock_ms(&self, clip: StreamingClipId) -> Option<f64>

Streaming clip clip’s current playback-clock position (ms), or None if it has no player — the scrubber’s read-back.

pub fn add_character( &mut self, ch: &Character, clip: Option<usize>, ) -> CharacterId

Register an animated character (RKC v3): upload its meshes as sprite models + its embedded voxel clips as flipbooks, then spawn one renderer instance per bone attachment — a static mesh sits at its bone, a clip attachment plays back on its own clock. clip selects a skeletal animation clip to drive the bones (None = rest pose). Returns a CharacterId; advance it each frame with advance_character.

Like clips, this works before any set_sprites; a later set_sprites drops all registered characters.

pub fn advance_character(&mut self, id: CharacterId, dt: f64)

Advance a character by dt seconds: tick its skeletal animation + each clip attachment’s clock, then re-pose every attachment (bone × local_offset) and select each clip’s current frame. No-op on a stale id.

pub fn set_character_world_transform( &mut self, id: CharacterId, xf: DynSpriteTransform, )

Move/re-orient a character to a new world transform xf (the root limb’s world pose) without ticking its animation or clip clocks — a teleport that holds the current animation frame (e.g. dragging a paused character in an editor). Re-solves the skeleton from the new root + re-poses every attachment; clip frames are left as-is. No-op on a stale id.

pub fn remove_character(&mut self, id: CharacterId) -> bool

Remove a character, dropping all its attachment instances and freeing the sprite models + voxel clips it registered. Returns false if id is stale.

pub fn set_kfa_sprites(&mut self, kfas: &mut [KfaSprite])

Register animated KFA sprites (one or more bone hierarchies). The GPU backend uploads each limb’s kv6 as an instanced model once (appended to the sprite registry) and seeds the limb instances at their current pose; the CPU backend caches the posed limbs for drawing. Call once at setup, after set_sprites, then drive motion per frame with update_kfa_poses.

Limbs are posed from the sprites’ current kfaval (advance animsprite first if using a baked curve), so kfas is taken &mut.

pub fn update_kfa_poses(&mut self, kfas: &mut [KfaSprite])

Re-pose the registered KFA sprites from their current kfaval[]. Call each frame after advancing the animation (kfa.animsprite(dt_ms) or poking kfaval[]). The GPU backend takes the cheap transform-only update (no model-volume re-upload); the CPU backend re-solves limb transforms for the next render. Must follow a set_kfa_sprites with the same sprites.

pub fn carve_active_sprite(&mut self) -> u32

Carve the next z-layer off the SpriteSet::carve_model and re-upload (the demo’s G hotkey + GPU.12 copy-on-modify). GPU only; a no-op on the CPU backend. Returns the voxels removed.

pub fn request_capture(&mut self)

Request that the next render capture its framebuffer for take_capture. CPU only (the GPU swapchain isn’t read back) — a no-op on GPU.

pub fn take_capture(&mut self) -> Option<(Vec<u32>, u32, u32)>

Take the most recently captured frame as packed 0x00RRGGBB pixels + dimensions, or None if no capture is ready / GPU.

pub fn pick_depth(&self, x: u32, y: u32) -> Option<f32>

Screen→world picking input: the world-space hit distance t at window pixel (x, y) from the last rendered frame, or None for out-of-bounds pixels and sky / no-hit. The host reconstructs the world hit point as cam.pos + t * normalize(ray_dir), where ray_dir is the same per-pixel ray the frame was rendered with (see the backend’s projection).

t is the distance to the nearest scene-grid surface (terrain + grids); sprites do not occlude it (the sprite pass reads depth read-only), so a cursor sprite under the pointer is transparent to the pick.

Cost: the CPU backend reads its in-memory z-buffer (free); the GPU backend stages the depth buffer and blocks on a device poll (cheap at click time — do not call every frame). The GPU path only has depth when the last frame drew sprites (write_depth).

pub fn pixel_ray(&self, camera: &Camera, x: f64, y: f64) -> Option<[f64; 3]>

World-space view-ray direction (un-normalised) for window pixel (x, y), under the projection the last frame rendered with. The backends differ (CPU setcamera vs GPU vertical-FOV pinhole), so this hides which one is active. None before the first frame. Intersect it with a plane for tile picking, or feed it to Self::pick for a voxel.

pub fn view_ray(&self, camera: &Camera, x: f64, y: f64) -> Option<Ray>

Canonical screen→world unproject: the full view Ray (camera.pos origin + unit direction) for window pixel (x, y), under whichever projection the last frame used. The one entry point both backends honour — hosts never reconstruct the projection. None before the first frame or for a degenerate ray.

Compose with roxlap_scene::Scene::raycast for depth-free picking that’s identical on CPU and GPU: renderer.view_ray(cam, x, y).and_then(|r| scene.raycast(r.origin, r.dir, max)).

pub fn pick( &self, scene: &Scene, camera: &Camera, x: u32, y: u32, ) -> Option<PickHit>

One-call screen→world voxel pick: unproject pixel (x, y) with the active backend’s projection, read the last frame’s depth there, reconstruct the world hit, and resolve it to the owning grid + grid-local voxel via Scene::resolve_voxel. None on sky / no-hit, or when no grid claims the surface.

scene and camera must be the ones the last frame rendered; the projection (size + FOV / hx,hy,hz) is taken from that frame. Cheap on CPU (in-memory z-buffer); on GPU it stages the depth buffer (a click-time device poll — not per frame).