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
//! Level-of-detail (LOD) computation for chunk meshing.
//!
//! Distance-based LOD reduces GPU triangle load for chunks that are far from
//! the viewer. Rather than storing separate mesh assets per level, the greedy
//! mesher's `step` parameter is used directly: a step of `2` makes each
//! super-voxel cover a `2×2×2` region, halving linear resolution and roughly
//! quartering the triangle count for typical terrain.
//!
//! # Levels
//!
//! Only two discrete levels are used. More levels were prototyped but
//! discarded because steps larger than `2` produce visually jarring flat quads
//! and make seam-free stitching between neighboring chunks more complex.
//!
//! | Level | Step | Viewer distance |
//! |-------|------|------------------------|
//! | `0` | `1` | < [`LOD0_MAX_DISTANCE`] |
//! | `1` | `2` | ≥ [`LOD0_MAX_DISTANCE`] |
//!
//! # Hysteresis
//!
//! A chunk exactly at the 200-unit boundary would switch LOD level every frame
//! as floating-point distance fluctuates. [`compute_lod_with_hysteresis`]
//! adds a dead band: upgrading to a finer level requires moving *inside* the
//! threshold by at least `hysteresis` units, and downgrading requires moving
//! *outside* by the same amount. The system uses a ±5-unit band.
use Vec3;
/// Distance threshold below which LOD 0 (full detail, step=1) is used.
/// At or beyond this distance LOD 1 (step=2) is used.
pub const LOD0_MAX_DISTANCE: f32 = 200.0;
/// Computes the LOD level for a chunk from its world-space position and the
/// viewer's world-space position.
///
/// The distance is the Euclidean distance between `chunk_world_pos` and
/// `viewer_pos`. Pass the chunk's **center** (minimum corner + half-chunk
/// offset) so that all six faces are equidistant from the viewer; passing the
/// minimum corner biases the result toward finer LOD for large chunks.
///
/// For LOD transitions that should not flicker, use
/// [`compute_lod_with_hysteresis`] instead.
///
/// # Returns
///
/// - `0` — distance < [`LOD0_MAX_DISTANCE`] → step `1` (full detail)
/// - `1` — distance ≥ [`LOD0_MAX_DISTANCE`] → step `2` (half detail)
///
/// # Examples
///
/// ```rust,no_run
/// use bevy::math::Vec3;
/// use voxel_framework::mesh::lod::compute_lod;
///
/// let chunk_center = Vec3::new(150.0, 0.0, 0.0);
/// let viewer = Vec3::ZERO;
/// assert_eq!(compute_lod(chunk_center, viewer), 0); // close chunk, full detail
/// ```
/// Computes the LOD level with a hysteresis dead band to prevent rapid
/// level oscillation as the viewer moves along the threshold boundary.
///
/// The returned level only changes when the viewer has moved `hysteresis` units
/// past the threshold in the direction of the transition:
///
/// - **Upgrade** (`1 → 0`, coarse → fine): requires `distance < LOD0_MAX_DISTANCE − hysteresis`
/// - **Downgrade** (`0 → 1`, fine → coarse): requires `distance > LOD0_MAX_DISTANCE + hysteresis`
///
/// If neither condition is met, `current_lod` is returned unchanged. The
/// [`super::systems::lod_update_system`] uses a `hysteresis` of `5.0` units.
///
/// # Parameters
///
/// - `chunk_world_pos` — world-space position to measure from (typically chunk center).
/// - `viewer_pos` — current viewer world-space position.
/// - `current_lod` — the LOD level currently assigned to this chunk.
/// - `hysteresis` — dead-band width in world units (must be ≥ 0.0).
/// Converts a LOD level to the `step` parameter expected by
/// [`super::generate_chunk_mesh`] and [`super::generate_chunk_mesh_with_neighbors`].
///
/// | LOD | Step | Resolution |
/// |-----|------|------------------------------|
/// | `0` | `1` | Full — one voxel per cell |
/// | ≥ 1 | `2` | Half — `2×2×2` super-voxels |
///
/// Any level above `0` maps to step `2`; the framework currently defines only
/// two levels, but this function is forward-compatible with additional levels.