Crate roxlap_gpu 

WGPU-backed compute-shader renderer scaffold for the roxlap voxel engine. GPU.1 in PORTING-GPU.md.

GPU.1’s job: stand up the device + surface + swapchain on a host window (any raw-window-handle provider), present a clear-to-colour frame each render call, and give the host a one-call opt-in. No voxel marching yet — the examples/probe.rs standalone holds the empirical FPS baseline from GPU.0.

Later sub-substages flesh GpuRenderer::render out: GPU.2 uploads voxel data, GPU.3 dispatches the inner-DDA compute shader, GPU.4 layers in chunk skipping, GPU.5 plugs the renderer into roxlap-scene::Scene, …

Host integration shape (GPU.1)

use std::sync::Arc;
use roxlap_gpu::{GpuRenderer, GpuRendererSettings};
match GpuRenderer::new_blocking(w, size, GpuRendererSettings::default()) {
    Ok(r) => Some(r),
    Err(e) => {
        eprintln!("GPU init failed: {e}; falling back to CPU");
        None
    }
}

Re-exports

pub use camera::Camera;

pub use decompress::decompress_chunk;

pub use decompress::ChunkUpload;

pub use decompress::BEDROCK_RGB;

pub use decompress::CHUNK_Z;

pub use grid::bounding_box_of;

pub use grid::GpuGridResident;

pub use grid::GridUpload;

pub use headless::HeadlessGpu;

pub use resident::GpuChunkResident;

pub use scene::GpuSceneResident;

pub use scene::GridRuntimeTransform;

pub use scene::GridStaticMeta;

pub use scene::RefreshOutcome;

pub use scene::SceneUpload;

pub use sprite_model::build_sprite_model;

pub use sprite_model::build_sprite_model_with_materials;

pub use sprite_model::sprite_model_from_clip_frame;

pub use sprite_model::sprite_model_from_clip_frame_with_materials;

pub use sprite_model::sprite_model_from_voxel_frame;

pub use sprite_model::sprite_model_from_voxel_frame_with_materials;

pub use sprite_model::SpriteInstance;

pub use sprite_model::SpriteInstanceTransform;

pub use sprite_model::SpriteModel;

pub use sprite_model::SpriteModelRegistry;

pub use sprite_model::SpriteRegistryResident;

Modules

camera

World-space camera state passed to crate::GpuRenderer::render_chunk.

decompress

GPU.2 — Vxl → (occupancy bitmap, colour offsets, packed colour array). Pure CPU; no wgpu deps in this module. Shape:

grid

GPU.4 — grid-of-chunks upload + storage layout.

headless

GPU.2 — headless device + queue for tests and offline tools.

resident

GPU.2 — chunk-resident storage buffers + debug read-back.

scene

GPU.5 — multi-grid scene upload + shared storage layout.

sprite_model

GPU.10 — KV6 sprite as a DDA-marchable voxel model.

Structs

GpuImageQuad

A world-space 2D image-sprite quad for GpuRenderer::draw_images_deferred. corners are the four world points TL, TR, BL, BR (UVs (0,0) (1,0) (0,1) (1,1)); image indexes a texture uploaded via GpuRenderer::upload_image; tint is straight RGBA in 0..=1 (multiplied into every texel); depth_test occludes the quad behind nearer marched geometry. The facade resolves orientation + back-face culling, so this is pure geometry.

GpuLight

A point light in a grid’s local space, as handed to GpuRenderer::set_scene_lights. The facade transforms world-space [roxlap_render::PointLight]s into each grid’s frame.

GpuLine

WGPU-backed renderer. Owns the device, queue, and surface bound to the host’s window. [Self::render] is the GPU.1 clear-to-colour path; [Self::render_chunk] is GPU.3’s single-chunk DDA marcher.

GpuLineCamera

World camera basis for projecting GpuLine endpoints — the same pinhole the scene-DDA pass marches with (right/down/forward orthonormal, pos in world voxel units).

GpuRenderer

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.

GridWorldTransform

XS.3 — a grid’s world transform for cross-grid shadows: world origin + the local→world rotation columns (rot_cols[i] = world image of grid-local axis i). Built host-side per frame from the grid’s GridTransform and handed to [SceneRenderer::render_scene] alongside the per-grid cameras.

HeadlessSceneRenderer

GPU.11 — headless scene-DDA renderer for tests + offline visual gates. Owns the scene_dda.wgsl compute pipeline with no surface and no blit pass; renders a GpuSceneResident to an in-memory RGBA framebuffer via texture readback. The per-substage visual gate (render reference scenes, diff PPMs) and the GPU.11.1 mip render-diff both ride on this.

SceneLights

The whole per-frame light environment, already transformed per grid. grid_sun_dirs and grid_point_lights are indexed by grid (outer length == grid_count); empty ⇒ that light type is off. Set each frame via GpuRenderer::set_scene_lights; Default = no lights (the pre-DL render).

Enums

GpuInitError

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

PowerPreference

Constants

MAX_POINT_LIGHTS

Max point lights honoured per frame. Excess are dropped with a warning (never silently truncated). The per-grid buffer is sized grid_count * point_count.

MAX_SHADOW_CASTERS

Max simultaneous shadow casters (the sun counts as one). Lights flagged to cast beyond this are demoted to shadowless with a warning. Enforced in DL.3 (shadow stage); declared here so the budget is one constant.

Functions

pinhole_pixel_ray

World-space view-ray direction (un-normalised) for window pixel (x, y) under a vertical-FOV pinhole — the projection scene_dda.wgsl’s render_scene uses. Shared by GpuRenderer::pixel_ray; standalone so it’s unit-testable without a device. right/down/forward are the camera basis.