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 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 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).