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

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.

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.

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.

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.

Enums

Backend

Which renderer a SceneRenderer resolved to at construction.

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.

PowerPreference

Traits

HasDisplayHandle

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

HasWindowHandle

A handle to a window.