Crate roxlap_render

Expand description

roxlap-render — unified CPU/GPU renderer facade.

New to roxlap? The roxlap book is the guide (quickstart, concepts, rendering, lighting, sprites); this page is the API reference.

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.

Beyond the scene render itself, the facade owns sprites (static + per-instance dynamic), animated voxel clips, billboard sprites + actors, characters (.rkc), materials + transparency, dynamic lighting (FrameParams::lights), screen→world picking, overlay lines / images / egui, and the fixed-resolution post pipeline (SceneRenderer::set_render_resolution / set_ssaa / set_posterize).

Re-exports§

pub use egui;

Modules§

gif_import: Animated-GIF → VoxelClip importer for Doom-style billboard sprites (stage BB). Behind the gif feature; see PORTING-BILLBOARD.md. Animated-GIF → voxel_clip::VoxelClip importer for Doom-style billboard sprites (stage BB). Feature-gated behind gif; see gif_import + PORTING-BILLBOARD.md. Import an animated GIF into a VoxelClip of flat, camera-facing voxel slabs — the authoring bridge for Doom/Build-style billboard sprites (stage BB; see PORTING-BILLBOARD.md). Feature-gated behind the gif feature.
png_import: PNG-sequence / APNG → VoxelClip importer (stage BB). Behind the png feature; see PORTING-BILLBOARD.md. PNG-sequence / APNG → voxel_clip::VoxelClip importer for billboard sprites (stage BB). Feature-gated behind png; see png_import. Import PNG sequences and animated PNG (APNG) into a VoxelClip of flat, camera-facing voxel slabs — the truecolor counterpart of crate::gif_import for Doom/Build-style billboard sprites (stage BB). Feature-gated behind the png feature.

Structs§

ActorState: One animation state of a BillboardActorDef: its name plus the clips for each viewing direction. dirs.len() may be 1 (non-directional), 8 (classic Doom rotations), or any N (uniform angular bins). Index 0 is the view-from-front (camera in the actor’s facing direction), increasing counter-clockwise.
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).
BillboardActorDef: Recipe for add_billboard_actor.
BillboardActorId: Stable handle to a BillboardActor — a high-level directional billboard managed by the renderer (it owns one clip instance, picks the directional clip by view angle, and plays a named-state animation). Reset by set_sprites; a removed actor’s handle is stale → a safe no-op.
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.
ConeDef: Directional cone emission (PS.2) — fountains, muzzle flashes, impact sprays: a random direction within half_angle_deg of axis, at a speed sampled from speed.
DebrisImpact: One landed island, drained via DebrisSystem::drain_impacts: everything the shatter needs.
DebrisSystem: Host-owned falling-island simulation + facade binding. Construct once, Self::spawn_island per detected island, Self::tick per frame, Self::drain_impacts to shatter.
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.
DirectionalLight: The sun — a single directional light for the whole scene. World space.
DynSpriteTransform: Orientation + position for a dynamic sprite instance — the per-frame pose passed to SceneRenderer::add_sprite_instance_posed and set_sprite_instance_transform.
EmitterId: Stable handle to an emitter inside one ParticleSystem — the result of add_emitter, passed to the per-emitter setters and burst. Epoch-generational like every other facade handle family: a removed emitter’s handle resolves to a safe no-op, never to another emitter.
Frame: A frame in flight (QE-B6) — returned by SceneRenderer::frame. Overlays draw into the composited frame with the camera it was rendered with; exactly one present happens, by Self::present / Self::paint_egui or on drop.
FrameParams: Per-frame inputs both backends consume. The host builds the OpticastSettings (it owns scan distance, projection 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. Generational (QE-B6): image slots are reused after drop_image, so each handle carries the slot’s generation — a stale handle (kept across a drop) resolves to a safe no-op instead of aliasing whatever texture re-took the slot. Pass it in an ImageSprite for SceneRenderer::draw_images. 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.
LightRig: The whole per-frame light environment, borrowed into crate::FrameParams. Applied by both backends (GPU since DL, CPU since CPU.1/CPU.2) — see the module docs.
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.
OverlayColor: An overlay colour with real alpha: 0xAA_RR_GG_BB (0xFF = opaque). Used by the overlay-line API (Line3) — the one place in the engine where the high byte genuinely is opacity.
Particle: One live particle — a read-only view for hosts (HUD counters, custom overlays); the system owns the mutation.
ParticleEmitterDef: Recipe for add_emitter. Construct with ParticleEmitterDef::new and override what the effect needs; there is no Default because a def is meaningless without a live SpriteModelId.
ParticleSystem: A self-contained particle simulation: emitters, a shared particle pool with a budget, and a deterministic seeded RNG. Host-owned; per frame call update (pure simulation, no renderer) then — from PS.1 — sync(&mut SceneRenderer) to mirror the pool into dynamic sprite instances.
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).
PointLight: A colored point light. World space, with a hard radius cutoff (it contributes nothing beyond radius).
PosterizeConfig: Reduced-palette post (RP.2), applied at the logical resolution in the resolve step (after the SSAA box-downfilter, before the nearest upscale). Each channel is quantized to its own number of levels; levels <= 1 leaves that channel untouched. None posterize ⇒ the RP.0/RP.1 paths verbatim.
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.
Rgb: A plain 0x00_RR_GG_BB colour: sprite/actor/particle tints, the sky / fog / clear colours, and the colour keys of colour→material maps. No packing surprises — the high byte is unused and must stay zero.
SceneRenderer: Unified renderer over the CPU and GPU paths. See the crate docs.
ShadowFlags: How a sprite instance participates in dynamic-light shadows (QE.7b — replaces the unreadable set_sprite_instance_shadow_flags(id, true, false) bool pair).
SpotLight: A spot (cone) light — a PointLight with a direction and a soft angular cutoff, so it lights only a cone. World space. Internally folded into the point-light path (a point light is the 180°-cone degenerate), so spots share the point-light count + shadow-caster budgets.
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).
Tint: WT.2 — a full-screen tint: every resolved pixel lerps toward color by strength. See FrameParams::tint for where in the pipeline it applies.
VelocityDef: Initial particle velocity: a fixed base, an isotropic spread, and an optional directional cone — the three compose by addition.
VoxColor: A voxel colour in voxlap’s packing: RGB in the low 24 bits, the baked brightness/AO byte on top — 0x80 is neutral (“unlit”), and lighting bakes rewrite it per voxel. NOT alpha: translucency is a material property (see the material palette), never a colour channel.
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.
BackendPreference: Which backend SceneRenderer::try_new should build (QE.7b — replaces RenderOptions.want_gpu: bool, which couldn’t express “GPU or fail”: headless CI rigs and benchmarks silently fell back to a software render and measured the wrong thing).
BillboardLighting: How a sprite/billboard instance derives its shading normal (BB.2b) — a per-instance choice that rides the sprite flags. A camera-facing billboard’s DDA face normal tracks the camera, so its N·L would shift as you orbit; WorldUp / AmbientOnly tame that. Only affects the dynamic lighting path (a disabled rig is unaffected). Set via set_sprite_instance_lighting or BillboardActorDef::lighting.
BillboardMode: How a billboard instance turns to face the camera (BB.2). Set per instance via SceneRenderer::add_billboard_instance / set_billboard_mode; applied each face_billboards_to.
BlendMode: How a voxel’s colour combines with what is already behind it along a ray.
CollisionMode: How particles react to solid voxels (PS.3) — checked only by the _with_scene update/tick variants; the scene-free ones never collide. The test is a point sample of the post-step position, nudged half a voxel along the velocity (Scene::resolve_voxel’s picking nudge, reused): contact registers slightly before visual interpenetration, fast particles can tunnel through walls thinner than one step’s travel, and a resting particle (zero velocity) is never re-tested — all acceptable for effects, none of this is a physics engine.
DecodeError: Why VoxelClip::decode failed.
DitherMode: Dither applied before the posterize quantization (RP.2), to break up banding and turn it into a stable retro pattern instead of crawling edges. Indexed by the logical pixel, so each hard pixel still resolves to one colour.
EmitterShape: Where new particles appear, relative to the emitter position (PS.2).
Feature: A backend-dependent capability, probed via SceneRenderer::supports (QE.7a). Every method below the parity line degrades to a silent no-op on the unsupporting backend; this enum turns the tribal knowledge into a queryable answer.
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: Adapter power class requested at init — mirrors wgpu::PowerPreference without leaking the wgpu type into host signatures.
RenderError: Construction failure from SceneRenderer::try_new (QE.2b).
RenderResolution: Where the per-pixel raycaster actually runs, decoupled from the window size (RP.0). Both backends are per-pixel marchers, so frame cost scales with the pixel count — rendering into a fixed logical target and nearest-upscaling it to the window makes FPS independent of window size and creates the seam for the later posterize / SSAA post (RP.1/RP.2).
SpawnMode: How an emitter produces particles.

Constants§

CARVE_DEBRIS_CAP: Debris cap per ParticleSystem::carve_debris call: bigger carves stride-sample an even spatial subset down to this many particles, so one large explosion can’t monopolise the pool budget.
DEFAULT_MAX_PARTICLES: Default ParticleSystem particle budget.

Traits§

HasDisplayHandle: A display that acts as a wrapper around a display handle.
HasWindowHandle: A handle to a window.