Crate roxlap_render 

roxlap-render — unified CPU/GPU renderer facade.

One SceneRenderer hides the choice between the CPU opticast path (roxlap-core / roxlap-scene, presented via softbuffer) and the GPU compute-shader path (roxlap-gpu, presented via its own wgpu surface). Construction picks the GPU backend when asked and able, and falls back to CPU automatically when WGPU init fails — so a host never has to branch on GPU availability or carry the Scene→GPU upload/refresh/transform glue itself.

Hosts stay thin: build a Scene, advance it from input, then call SceneRenderer::render each frame. The facade owns the window surface, the framebuffer/z-buffer (CPU) or the resident scene + dirty-chunk tracking (GPU), and presentation.

The per-frame flow is render → (optional overlays) → finish. Between SceneRenderer::render and the finishing SceneRenderer::present / [SceneRenderer::paint_egui] call, a host may overlay depth-tested world-space lines with SceneRenderer::draw_lines (editor gizmos, debug geometry — see Line3); they land in the framebuffer, occluded by the rendered scene, with egui still painting panels on top.

This is the RF.0 skeleton: backend selection + fallback + a clear-to-sky frame. RF.1/RF.2 fill in the real CPU/GPU scene render; RF.3 adds sprites; RF.4 adds framebuffer capture.

Structs

Attachment

One thing a bone draws: a mesh/clip reference, a local offset placing it on the bone, and (for clips) playback parameters (VCL.5).

Character

A parsed rigged-character container.

CharacterId

Stable handle to a registered animated character (VCL.6) — the result of SceneRenderer::add_character, advanced each frame with advance_character and dropped with remove_character. Reset by set_sprites.

ClipMetadata

Public metadata for a registered clip — the inspector view returned by SceneRenderer::clip_metadata.

DecodedClip

A decoded clip: every frame expanded to a full VoxelFrame plus its recomputed dirs (parallel to frames[i].colors) and resolved durations. The runtime flipbook.

DynSpriteTransform

Orientation + position for a dynamic sprite instance — the per-frame pose passed to SceneRenderer::add_sprite_instance_posed and set_sprite_instance_transform.

FrameParams

Per-frame inputs both backends consume. The host builds the OpticastSettings (it owns scan distance etc.); the facade does everything else (pool config, sky fill, render, present).

GpuRendererSettings

Caller-controllable knobs for GpuRenderer::new. Defaults target “highest-performance GPU, prefer Mailbox/Immediate over vsync” — i.e. the same configuration the GPU.0 probe used to measure the FPS ceiling.

ImageId

A handle to an uploaded image-sprite texture, returned by SceneRenderer::upload_image. Positional (like SpriteModelId): it indexes the backend’s texture store. Pass it in an ImageSprite for SceneRenderer::draw_images, or to drop_image to release it. Opaque on purpose — there’s no arithmetic to do on it.

ImagePickHit

Result of SceneRenderer::pick_image — a resolved screen→sprite hit. uv is the normalised position within the quad ((0,0) = top-left corner); texel is the matching source-image pixel; world is the hit point; t is its euclidean distance from the camera.

ImageSprite

One placed 2D image sprite for the current frame: a flat textured quad in world space, composited over the rendered scene with the frame’s depth buffer (so the voxel model can occlude it). Built per frame and passed to SceneRenderer::draw_images, mirroring Line3 / SceneRenderer::draw_lines. The texture is uploaded once via SceneRenderer::upload_image and referenced by image.

KfaSprite

One animated KFA sprite — bones + hinges + per-bone live animation values.

Kv6

Parsed .kv6 model. Round-trips byte-equally via parse + serialize.

Line3

A world-space line segment to draw over a rendered frame via SceneRenderer::draw_lines — editor gizmos (bounding boxes, floor grids, axes, hover wireframes), debug paths, etc.

Material

One material: an opacity and a blend mode, indexed out of a MaterialTable by a per-voxel material id.

PickHit

Result of SceneRenderer::pick — a resolved screen→world voxel hit. world is the surface point (cam.pos + t · normalize(ray)); grid + voxel are the owning grid and its grid-local voxel (transform-correct for rotated / translated grids).

Ray

A world-space view ray: the canonical unproject output of SceneRenderer::view_ray. dir is unit-length. Feed it straight to roxlap_scene::Scene::raycast for depth-free, backend-agnostic voxel picking (scene.raycast(ray.origin, ray.dir, max_dist)), or intersect it with a plane for tile selection.

RenderOptions

Construction-time options for SceneRenderer::new.

SceneRenderer

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

Sprite

A KV6 voxel sprite positioned in world space.

SpriteInstanceDesc

One placed sprite instance: which SpriteSet::models entry and where in the world.

SpriteInstanceId

Stable handle to a dynamically added sprite instance — the result of SceneRenderer::add_sprite_instance, passed to remove_sprite_instance.

SpriteModelId

Stable handle to a registered sprite model, returned (one per SpriteSet::models entry, in order) by SceneRenderer::set_sprites. Pass it to refresh_sprite_model to re-register that model’s geometry after a content edit — so callers never track the positional usize index themselves. Opaque on purpose: there is no arithmetic to do on it.

SpriteSet

Backend-agnostic sprite description. The facade builds the CPU per-instance draw list and the GPU instanced registry from the same data, so both backends show identical sprites. The host owns content (which models, where, recolouring) — building a recoloured variant is just a second Sprite model with edited kv6.voxels.

StreamingClip

A seekable, O(1-frame)-memory cursor over a VoxelClip’s I/P stream — the streaming alternative to DecodedClip, which materialises every frame (and which the GPU/CPU flipbook then holds N volumes for). For a huge clip this keeps one reconstructed frame plus the compact encoded stream instead of N full frames.

StreamingClipId

Stable handle to a registered streaming voxel clip (follow-up #3) — the result of SceneRenderer::add_streaming_clip, advanced with set_streaming_clip_frame and dropped with remove_streaming_clip. Reset by set_sprites.

StreamingInstanceId

Handle to an instance of a streaming clip (add_streaming_clip_instance).

VoxelClip

On-disk animated voxel clip. Construct via VoxelClip::from_frames (the encoder) or VoxelClip::parse; expand to a runtime flipbook via VoxelClip::decode.

VoxelClipId

Stable handle to a registered animated voxel clip (VCL.4) — the result of SceneRenderer::add_voxel_clip, passed to add_clip_instance_posed and remove_voxel_clip. Like SpriteModelId, a removed clip’s handle is stale → a safe no-op. Reset by set_sprites (which drops the dynamic + clip layers).

VoxelFrame

One fully-reconstructed frame in the dense-column layout. Field shapes are validated against the clip’s dims by VoxelFrame::validate.

Enums

Backend

Which renderer a SceneRenderer resolved to at construction.

BlendMode

How a voxel’s colour combines with what is already behind it along a ray.

DecodeError

Why VoxelClip::decode failed.

GpuInitError

Errors GpuRenderer::new surfaces to the host. The host’s expected flow is “try this, fall back to the CPU path on Err”.

ImageFacing

How an ImageSprite’s quad is oriented in the world.

LoopMode

How playback advances past the last frame.

MeshRef

Typed reference to what a bone attachment draws. The on-disk mesh_kind discriminant selects the variant.

PowerPreference

Traits

HasDisplayHandle

A display that acts as a wrapper around a display handle.

HasWindowHandle

A handle to a window.