1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
//! Optional render-thread ownership, materials, and bounded streaming uploads.
mod streaming;
use crate::glam::Vec4;
use crate::meshing::{chunk_bounds, chunk_translation};
use crate::{
BlockPos, ChunkMesh, ChunkPos, MeshDependencies, MeshLayer, MeshStats, SurfaceKey, TileId,
VoxelWorld,
};
use rayengine::{
assets::Assets,
prelude::*,
raylib::prelude::{RaylibDraw, RaylibDraw3D},
render::Canvas3D,
};
use std::collections::{HashMap, HashSet};
pub use streaming::{StreamRenderConfig, StreamRenderReport, StreamRenderer, StreamResources};
/// GLSL 330 fragment shader used by built-in materials. Custom shaders can reuse
/// its per-tile repetition, unwrapped texture gradients and SDK alpha uniforms.
pub const REPEAT_FRAGMENT_SHADER: &str = include_str!("render/repeat.fs");
/// A game-owned image (or atlas region) for one tile key.
#[derive(Clone, Copy, Debug)]
pub struct TileTexture {
/// Game tile key.
pub tile: TileId,
/// Borrowed SDK texture; unloading materials never unloads it.
pub texture: TextureId,
/// Normalized `(left, top, width, height)` within the texture.
/// For filtering/mipmaps, the caller must provide atlas gutters/insets.
pub rect: Vec4,
}
impl TileTexture {
/// Uses the whole image, repeating once per block on merged geometry.
pub fn whole(tile: TileId, texture: TextureId) -> Self {
Self {
tile,
texture,
rect: Vec4::new(0.0, 0.0, 1.0, 1.0),
}
}
fn valid(self) -> bool {
self.rect.is_finite()
&& self.rect.x >= 0.0
&& self.rect.y >= 0.0
&& self.rect.z > 0.0
&& self.rect.w > 0.0
&& self.rect.x + self.rect.z <= 1.0
&& self.rect.y + self.rect.w <= 1.0
}
}
/// Material lookup with explicitly owned built-in materials and repeat shader.
/// Textures and custom bindings are borrowed. Keep this and its textures alive
/// while drawing chunks; unload chunks before unloading materials. Not Clone.
#[derive(Default)]
pub struct VoxelMaterials {
surfaces: HashMap<SurfaceKey, MaterialId>,
owned: Vec<MaterialId>,
shader: Option<ShaderId>,
}
impl VoxelMaterials {
/// Empty mapping for caller-owned custom materials via bind.
pub fn new() -> Self {
Self::default()
}
/// Creates one shared shader and opaque/cutout materials for each tile.
/// Validates tiles before native creation and rolls back on later failure.
/// Zero tiles is valid and allocates no shader. Cutoff must be finite in 0..=1.
/// The repeat shader uses fract(UV), so greedy faces preserve texel density
/// even with clamp wrapping or an atlas. Nearest filtering is recommended;
/// automatic mipmap generation/atlas packing is outside this adapter.
pub fn create(
context: &mut InitContext<'_, '_>,
tiles: &[TileTexture],
cutoff: f32,
) -> Result<Self, Error> {
if !cutoff.is_finite() || !(0.0..=1.0).contains(&cutoff) || tiles.len() > 65536 {
return Err(Error::Config("invalid voxel tiles or alpha cutoff".into()));
}
let mut result = Self::new();
result
.surfaces
.try_reserve(tiles.len() * 2)
.map_err(|_| allocation())?;
result
.owned
.try_reserve_exact(tiles.len() * 2)
.map_err(|_| allocation())?;
let mut seen = HashSet::new();
seen.try_reserve(tiles.len()).map_err(|_| allocation())?;
for tile in tiles {
if !tile.valid() || context.assets.texture(tile.texture).is_none() {
return Err(Error::Config(
"voxel tile needs a valid rectangle and live texture".into(),
));
}
if !seen.insert(tile.tile) {
return Err(Error::Config("duplicate voxel tile key".into()));
}
}
if tiles.is_empty() {
return Ok(result);
}
let setup = (|| {
let shader = context.shader_from_source(None, REPEAT_FRAGMENT_SHADER)?;
result.shader = Some(shader);
let rect = context.uniform(
shader,
"voxelTileRect",
UniformValue::Vec4(Vec4::new(0.0, 0.0, 1.0, 1.0)),
)?;
for tile in tiles {
for (layer, alpha) in [
(MeshLayer::Opaque, AlphaMode::Opaque),
(MeshLayer::Cutout, AlphaMode::Cutout(cutoff)),
] {
let material = context.material(MaterialDesc {
texture: Some(tile.texture),
shader: Some(shader),
alpha,
parameters: vec![MaterialParam {
uniform: rect,
value: UniformValue::Vec4(tile.rect),
}],
..Default::default()
})?;
result.owned.push(material);
result.surfaces.insert(
SurfaceKey {
tile: tile.tile,
layer,
},
material,
);
}
}
Ok::<_, Error>(())
})();
if let Err(error) = setup {
result.unload(context.assets);
return Err(error);
}
Ok(result)
}
/// Borrowed custom surface binding. The caller owns its material and must
/// provide repeating UV semantics when using greedy geometry. Returns the
/// previous binding; alpha/dependency validity is checked during chunk upload.
pub fn bind(
&mut self,
surface: SurfaceKey,
material: MaterialId,
) -> Result<Option<MaterialId>, Error> {
self.surfaces.try_reserve(1).map_err(|_| allocation())?;
Ok(self.surfaces.insert(surface, material))
}
/// Current binding, or None for an undefined tile/layer.
pub fn surface(&self, surface: SurfaceKey) -> Option<MaterialId> {
self.surfaces.get(&surface).copied()
}
/// Releases only internally created descriptions/shader; textures and custom
/// materials stay in Assets. Repeated unload is harmless. Drop alone leaves
/// resources in Assets until the run ends, following the SDK plugin contract.
pub fn unload(&mut self, assets: &mut Assets<'_>) {
for id in self.owned.drain(..) {
assets.unload_material(id);
}
if let Some(shader) = self.shader.take() {
assets.unload_shader(shader);
}
self.surfaces.clear();
}
}
fn allocation() -> Error {
Error::Asset("voxel render allocation failed".into())
}
struct GpuBatch {
mesh: MeshId,
material: MaterialId,
}
/// Successful submissions and missing GPU/material dependencies for one chunk.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct ChunkDraw {
/// Frustum rejected the chunk before any draw calls.
pub culled: bool,
/// Successful mesh submissions (not hardware draw calls).
pub submitted: usize,
/// Failed draws due to externally unloaded resources.
pub unavailable: usize,
}
/// Owned uploaded batches for a single chunk, including its dependency receipt.
/// Game/streamer owns the collection and replacement scheduling. Not Clone.
pub struct RenderedChunk {
position: ChunkPos,
batches: Vec<GpuBatch>,
dependencies: Option<MeshDependencies>,
stats: MeshStats,
}
impl RenderedChunk {
/// World chunk coordinate; local vertices are translated only during drawing.
pub fn position(&self) -> ChunkPos {
self.position
}
/// Creates an empty handle with no GPU allocation; validates the signed grid.
pub fn new(position: ChunkPos) -> Result<Self, crate::VoxelError> {
position.origin()?;
Ok(Self {
position,
batches: Vec::new(),
dependencies: None,
stats: MeshStats::default(),
})
}
/// Accepted receipt; None before upload/after unload.
pub fn dependencies(&self) -> Option<&MeshDependencies> {
self.dependencies.as_ref()
}
/// Installed geometry counts and logical buffer bytes.
pub fn stats(&self) -> MeshStats {
self.stats
}
/// Uploads during game initialization. See replace for transaction semantics.
pub fn upload_init(
&mut self,
world: &VoxelWorld,
mesh: &ChunkMesh,
materials: &VoxelMaterials,
context: &mut InitContext<'_, '_>,
) -> Result<(), Error> {
self.install(world, mesh, materials, context)
}
/// Accepts only current owner/neighbor receipts, validates every material,
/// uploads all new batches, then commits and releases old batches. Any error
/// releases partial new uploads and preserves all old handles/geometry.
/// Empty results deliberately remove old geometry. Old/new buffers coexist
/// during admission; scheduling/time/VRAM budgets belong to the next streamer.
/// Call before a camera pass, on the same run's render thread.
pub fn replace(
&mut self,
world: &VoxelWorld,
mesh: &ChunkMesh,
materials: &VoxelMaterials,
frame: &mut Frame<'_, '_>,
) -> Result<(), Error> {
self.install(world, mesh, materials, frame)
}
fn install<'audio>(
&mut self,
world: &VoxelWorld,
mesh: &ChunkMesh,
materials: &VoxelMaterials,
sink: &mut impl MeshSink<'audio>,
) -> Result<(), Error> {
if mesh.dependencies().position() != self.position || !mesh.dependencies().is_current(world)
{
return Err(Error::Asset("stale or mismatched voxel mesh result".into()));
}
let mut pending: Vec<GpuBatch> = Vec::new();
pending
.try_reserve_exact(mesh.batches().len())
.map_err(|_| allocation())?;
for batch in mesh.batches() {
let key = batch.surface();
let id = materials
.surface(key)
.ok_or_else(|| Error::Asset(format!("undefined voxel surface {key:?}")))?;
let desc = sink
.assets()
.material(id)
.ok_or_else(|| Error::Asset("voxel material is unloaded".into()))?;
if !matches!(
(key.layer, desc.alpha),
(MeshLayer::Opaque, AlphaMode::Opaque) | (MeshLayer::Cutout, AlphaMode::Cutout(_))
) {
return Err(Error::Asset(
"voxel material alpha policy does not match mesh layer".into(),
));
}
sink.assets().validate_material(desc)?;
}
for batch in mesh.batches() {
match sink.upload(batch.data()) {
Ok(id) => pending.push(GpuBatch {
mesh: id,
material: materials.surface(batch.surface()).unwrap(),
}),
Err(error) => {
for batch in pending {
sink.assets_mut().unload_mesh(batch.mesh);
}
return Err(error);
}
}
}
for batch in std::mem::replace(&mut self.batches, pending) {
sink.assets_mut().unload_mesh(batch.mesh);
}
self.dependencies = Some(mesh.dependencies().clone());
self.stats = mesh.stats();
Ok(())
}
/// Draws local vertices at a camera-relative translation. Use a frustum
/// captured from the same relative camera/viewport; no allocation or world
/// lookup occurs here. Missing dependencies are reported rather than hidden.
pub fn draw<D: RaylibDraw + RaylibDraw3D>(
&self,
canvas: &mut Canvas3D<'_, D>,
view: &Frustum3D,
render_origin: BlockPos,
) -> ChunkDraw {
if !view.intersects(chunk_bounds(self.position, render_origin)) {
return ChunkDraw {
culled: true,
..Default::default()
};
}
let transform = Transform3D::at(chunk_translation(self.position, render_origin));
let mut report = ChunkDraw::default();
for batch in &self.batches {
if canvas.mesh_material(batch.mesh, batch.material, transform, Color::WHITE) {
report.submitted += 1;
} else {
report.unavailable += 1;
}
}
report
}
/// Releases owned mesh batches, preserving game-owned materials and textures.
pub fn unload(&mut self, assets: &mut Assets<'_>) {
for batch in self.batches.drain(..) {
assets.unload_mesh(batch.mesh);
}
self.dependencies = None;
self.stats = MeshStats::default();
}
}
trait MeshSink<'audio> {
fn upload(&mut self, data: &MeshData) -> Result<MeshId, Error>;
fn assets(&self) -> &Assets<'audio>;
fn assets_mut(&mut self) -> &mut Assets<'audio>;
}
impl<'audio> MeshSink<'audio> for InitContext<'_, 'audio> {
fn upload(&mut self, data: &MeshData) -> Result<MeshId, Error> {
self.mesh(data)
}
fn assets(&self) -> &Assets<'audio> {
self.assets
}
fn assets_mut(&mut self) -> &mut Assets<'audio> {
self.assets
}
}
impl<'audio> MeshSink<'audio> for Frame<'_, 'audio> {
fn upload(&mut self, data: &MeshData) -> Result<MeshId, Error> {
self.mesh(data)
}
fn assets(&self) -> &Assets<'audio> {
self.assets
}
fn assets_mut(&mut self) -> &mut Assets<'audio> {
self.assets
}
}
#[cfg(test)]
mod native_tests;