Struct ChunkGpuResources 

pub struct ChunkGpuResources { /* private fields */ }

GPU resources owned by one chunk multimesh.

FIELD ORDER IS THE DROP ORDER (see the DROP-ORDER CONTRACT in gpu::owned): uniform sets → scatter layers (whose own sets come first) → pipelines → shaders → buffers/textures. RD frees dependents together with their parent, so a set/pipeline must go before the shader or buffer it was built from. Nothing enforces this but the declaration order below — do not reshuffle.

Implementations

impl ChunkGpuResources

pub fn new( mm_rid: Rid, budget: u32, res: u32, tile_res: u32, radius: f32, ) -> Self

Construct an (unbuilt) resource set on the MAIN RenderingDevice. mm_rid is the target multimesh, or Rid::Invalid to have ensure_ready create its own (CEL-58 order).

pub fn new_compute_only( budget: u32, res: u32, tile_res: u32, radius: f32, ) -> Self

Compute-only resources (no MultiMesh) on a LOCAL RenderingDevice, for the readback verification. ensure_ready builds just the realize pipeline

• pool; the local device frees its own resources when it dies, so the sink is a no-op.

pub fn with_sink( mm_rid: Rid, budget: u32, res: u32, tile_res: u32, radius: f32, compute_only: bool, sink: Arc<dyn RidSink>, ) -> Self

Construct with an explicit RidSink (tests inject a spy).

pub fn set_bump_enable(&mut self, v: f32)

Set the detail-normal bump enable (1.0 on, 0.0 off) before the params are packed. Takes effect on the next upload_params/bake.

pub fn set_surface(&mut self, enabled: f32, height_scale: f32)

Set the CPU-surface provider params (global toggle + displaced-radius factor per unit) before the params are packed. Takes effect on the next upload_params/bake.

pub fn set_custom_surface( &mut self, source: String, water_height: f32, height_scale: f32, user_params: Vec<f32>, )

Install a custom GPU surface: assembled GLSL source (crate::custom_surface::assemble_source output) plus the layer’s water_height / height_scale. Call before the first ensure_ready; the pipeline is compiled lazily on the render thread. A shader-file change rebuilds the whole job, so this is only ever set once per job.

pub fn set_custom_knobs( &mut self, water_height: f32, height_scale: f32, user_params: Vec<f32>, )

Update the custom surface’s LIVE knobs (water level + geometry scale + generic user params) without recompiling. Picked up by the next upload_custom_params; pair with a cache invalidate_all so resident chunks re-fill with the new values. No-op if no custom surface is installed.

pub fn custom_requested(&self) -> bool

Was a custom GPU surface requested (source installed)?

pub fn custom_ready(&self) -> bool

Is the custom GPU surface compiled and ready to dispatch? false while still building, or permanently after a compile error (fall back to procedural).

pub fn custom_height_scale(&self) -> f32

The custom layer’s geometry displacement multiplier (used as surface_height_scale for the realize displacement).

pub fn set_scatter_configs(&mut self, cfgs: Vec<ScatterConfig>)

Configure the scatter layers (CEL-73). Call before the first ensure_ready; layer resources are built there once every target multimesh’s RD buffers exist.

pub fn ensure_ready(&mut self, rd: &mut Gd<RenderingDevice>) -> bool

Build the pipeline + vertex pool + uniform set + multimesh. Idempotent; returns false (retry next frame) until everything — including the multimesh’s lazily-created command buffer — exists.

pub fn upload_scatter( &mut self, rd: &mut Gd<RenderingDevice>, aux_bytes: &[u8], vis_bytes: &[u8], layer_params: &[Vec<u8>], )

Upload one execute’s scatter staging (CEL-73): the realize batch’s aux paths, the visible {slot, depth} list, and each layer’s fresh params snapshot; zero each layer’s compact counter + indirect draw count so the compact pass rebuilds the draw list from scratch. Also heals any uniform set the renderer invalidated by recreating a multimesh buffer.

pub fn record_scatter_place( &self, rd: &mut Gd<RenderingDevice>, list: i64, li: usize, chunk_count: u32, )

Record layer li’s place dispatch: one thread per candidate of each realize-batch chunk, clamped to the pool capacity (device-loss guard).

pub fn record_scatter_compact( &self, rd: &mut Gd<RenderingDevice>, list: i64, li: usize, vis_count: u32, )

Record layer li’s compact dispatch: one thread per cached candidate of each VISIBLE chunk, clamped to the pool capacity.

pub fn scatter_layer_count(&self) -> usize

Number of built scatter layers.

pub fn scatter_pool_buf(&self, li: usize) -> Rid

Layer li’s cached candidate pool buffer (readback for the debug-only GPU-vs-CPU placement verification).

pub fn upload_descs( &mut self, rd: &mut Gd<RenderingDevice>, bytes: &[u8], count: u32, )

Upload one batch of packed chunk descriptors (count × ChunkGpu).

Guards count <= budget: an over-budget batch is clamped to the desc buffer’s capacity so it can never overrun the descriptor buffer / vertex pool (the stale-oversized-buffer shape that caused a KRACKAN1 device-loss).

pub fn upload_params( &mut self, rd: &mut Gd<RenderingDevice>, chunk_count: u32, terrain: &TerrainGpu, )

Rewrite the whole ChunkParams for a realize batch of chunk_count chunks with the given terrain.

pub fn upload_terrain( &mut self, rd: &mut Gd<RenderingDevice>, terrain: &TerrainGpu, )

Update only the embedded terrain (offset 16, 64 bytes) of ChunkParams.

pub fn upload_surface( &mut self, rd: &mut Gd<RenderingDevice>, slot: u32, color_bytes: &[u8], height: &[f32], normal_bytes: &[u8], )

Upload one chunk’s CPU-surface color + height patch into the per-slot region of the surface storage buffers.

color_bytes is tile_res² rgba8-packed texels (little-endian, 4 bytes each); height is tile_res² elevations in meters. Both are indexed by the linear texel g = slot*tile_texels + ty*tile_res + tx, matching the g ChunkTileBake.slang computes for color_atlas. No-op if slot >= budget, either buffer is unbuilt, or the inputs are empty.

pub fn upload_instances( &mut self, rd: &mut Gd<RenderingDevice>, bytes: &[u8], count: u32, )

Upload per-instance data into the multimesh buffer and set the indirect draw instance count (cmd[1], byte offset 4). Mirrors PlanetGpu::upload_face / validate_instances’ command-buffer write.

pub fn record_realize( &self, rd: &mut Gd<RenderingDevice>, list: i64, vert_threads: u32, )

Record the realize dispatch into list: one thread per pool vertex (vert_threads total), then a barrier so readers see the writes.

pub fn record_bake( &self, rd: &mut Gd<RenderingDevice>, list: i64, texel_threads: u32, )

Record the Phase-4 tile-bake dispatch into list: one thread per tile texel (texel_threads total = realize_count * tile_res²), clamped to the atlas capacity so a stale/over-budget batch can never write past the atlas (the same defensive guard as record_realize).

pub fn upload_custom_params( &self, rd: &mut Gd<RenderingDevice>, chunk_count: u32, )

Refresh the custom-surface params UBO with this batch’s chunk_count (and the live water/height knobs). A buffer transfer — call from the upload node, OUTSIDE any compute list. No-op unless the custom pipeline is ready.

pub fn record_custom_surface( &self, rd: &mut Gd<RenderingDevice>, list: i64, chunk_count: u32, )

Record the custom-surface dispatch into list: one thread per tile texel of each realized chunk (chunk_count · tile_res²), clamped to the surface buffer capacity. No-op unless the custom pipeline is ready.

pub fn verts_per_chunk(&self) -> u32

Vertices per chunk (pool stride per slot).

pub fn tile_res(&self) -> u32

Per-chunk detail-tile resolution (atlas texels per slot = tile_res²).

pub fn color_atlas(&self) -> Rid

The per-chunk colour detail atlas (rgba8) — sampled by the surface shader.

pub fn normal_atlas(&self) -> Rid

The per-chunk world-normal detail atlas (rgba8, encoded *0.5+0.5).

pub fn radius(&self) -> f32

Planet radius (for the verification envelope check).

pub fn pos_buf(&self) -> Rid

The vertex-pool positions buffer (1 float4/vertex: pos+height) — readback.

pub fn attr_tex(&self) -> Rid

The per-vertex attribute texture (color+layer, normal+height).

pub fn pos_tex(&self) -> Rid

The per-vertex SAMPLEABLE world-position texture (rgba32f); the surface material reads VERTEX from this.

pub fn mm_rid(&self) -> Rid

The target multimesh.

pub fn init_failed(&self) -> bool

True once ensure_ready failed permanently (shader/pipeline build error).