Skip to main content

sim_engine/renderer/mesh3d/dynamic/
mod.rs

1//! Scene-owned whole-bundle updates with immutable snapshot isolation.
2
3use super::{
4    Arc, Error, Mesh3d, Mesh3dResourceError, Mesh3dUploadBudget, Mesh3dUploadBudgetResource,
5    Mesh3dUploadLayout, MeshColorGpu, MeshEdgeGpu, MeshNormalGpu, MeshUvGpu, MeshVertexGpu,
6    Object3dId, RetainedMesh3d, Scene3d, Scene3dError, Scene3dStatistics, Texture3dError,
7    WgpuRenderer, allocate_retained_mesh, fmt, is_portable_shader_source,
8    mesh3d_source_is_portable, preflight_mesh3d_source, preflight_mesh3d_upload,
9    submit_pending_uploads, upload, validate_mesh_source_style, write_retained_mesh_uploads,
10};
11
12mod types;
13pub use types::{
14    DynamicMesh3dBudget, DynamicMesh3dBudgetResource, DynamicMesh3dError, DynamicMesh3dUpdateReport,
15};
16
17#[cfg(test)]
18mod tests;
19#[cfg(test)]
20pub(super) use tests::{assert_gpu_dynamic_contract, assert_gpu_dynamic_recovery};
21
22#[derive(Default)]
23pub(super) struct DynamicMesh3dScratch {
24    vertices: Vec<MeshVertexGpu>,
25    edges: Vec<MeshEdgeGpu>,
26    coordinates: Vec<MeshUvGpu>,
27    colors: Vec<MeshColorGpu>,
28    normals: Vec<MeshNormalGpu>,
29}
30
31impl WgpuRenderer {
32    /// Renderer-owned dynamic mesh conversion capacity, separate from scene
33    /// resources and `FrameCacheBudget`. Backend upload staging is excluded.
34    pub fn mesh3d_update_scratch_bytes(&self) -> usize {
35        self.mesh3d_renderer.dynamic_scratch.capacity_bytes()
36    }
37
38    /// Releases retained dynamic conversion scratch without changing scene/GPU
39    /// resources, returning the nominal CPU capacity released. Clear before
40    /// requesting a smaller retained-scratch limit than a previous update used.
41    pub fn clear_mesh3d_update_scratch(&mut self) -> usize {
42        let previous = std::mem::take(&mut self.mesh3d_renderer.dynamic_scratch);
43        previous.capacity_bytes()
44    }
45
46    /// Updates only the selected scene object, reusing unique GPU buffer capacity.
47    ///
48    /// Other objects and exported immutable mesh/instance clones remain unchanged:
49    /// aliases cause one whole-bundle copy-on-write. Once only this scene object
50    /// owns the new bundle, subsequent fitting updates allocate no GPU buffers.
51    /// Growth or an optional-attribute layout change replaces the whole bundle; all live vertices,
52    /// indices, UVs, colors, normals and edges are uploaded even for an identical source.
53    ///
54    /// Limits include retained capacity and old/new overlap. Validation, scene
55    /// accounting and every fallible host preparation complete before GPU writes.
56    /// Returned errors preserve the object's previous geometry and scene state;
57    /// private bounded conversion scratch may warm before a later device failure.
58    /// Asynchronous device loss is separate; recovery restores committed source
59    /// and reserved capacities. Queue ordering protects earlier submitted frames.
60    ///
61    /// Source topology is a validated nonempty `Mesh3d`. Hide/remove an object for
62    /// an empty chunk. Its ID, transform, visibility and material are preserved.
63    /// UV-bearing material cannot be retained after removing source UVs.
64    pub fn update_scene3d_mesh(
65        &mut self,
66        scene: &mut Scene3d,
67        object_id: Object3dId,
68        source: Mesh3d,
69        budget: DynamicMesh3dBudget,
70    ) -> Result<DynamicMesh3dUpdateReport, DynamicMesh3dError> {
71        update_scene_mesh(
72            &self.device,
73            &self.queue,
74            &self.renderer_identity,
75            &mut self.mesh3d_renderer.dynamic_scratch,
76            scene,
77            object_id,
78            source,
79            budget,
80        )
81    }
82}
83
84fn final_limit(
85    resource: Mesh3dUploadBudgetResource,
86    actual: usize,
87    limit: usize,
88) -> Result<(), DynamicMesh3dError> {
89    if actual > limit {
90        return Err(Mesh3dResourceError::BudgetExceeded {
91            resource,
92            actual,
93            limit,
94        }
95        .into());
96    }
97    Ok(())
98}
99
100fn peak_limit(
101    resource: DynamicMesh3dBudgetResource,
102    actual: usize,
103    limit: usize,
104) -> Result<(), DynamicMesh3dError> {
105    if actual > limit {
106        return Err(DynamicMesh3dError::BudgetExceeded {
107            resource,
108            actual,
109            limit,
110        });
111    }
112    Ok(())
113}
114
115fn checked_sum(values: impl IntoIterator<Item = usize>) -> Result<usize, DynamicMesh3dError> {
116    values.into_iter().try_fold(0usize, |sum, value| {
117        sum.checked_add(value)
118            .ok_or_else(|| Mesh3dResourceError::CapacityTooLarge.into())
119    })
120}
121
122fn bundle_is_unique(mesh: &RetainedMesh3d) -> bool {
123    Arc::strong_count(&mesh.vertex_buffer) == 1
124        && [
125            &mesh.index_buffer,
126            &mesh.edge_buffer,
127            &mesh.texture_coordinate_buffer,
128            &mesh.color_buffer,
129            &mesh.normal_buffer,
130        ]
131        .into_iter()
132        .all(|buffer| {
133            buffer
134                .as_ref()
135                .is_none_or(|buffer| Arc::strong_count(buffer) == 1)
136        })
137}
138
139fn planned_allocation(
140    old: Mesh3dUploadLayout,
141    source: &Mesh3d,
142    budget: DynamicMesh3dBudget,
143    max_buffer_size: u64,
144) -> Result<Mesh3dUploadLayout, Mesh3dResourceError> {
145    let vertices = (old.vertex_bytes as usize / std::mem::size_of::<MeshVertexGpu>())
146        .max(source.vertices().len())
147        .max(budget.minimum_vertices);
148    let indices = (old.index_bytes as usize / std::mem::size_of::<u32>())
149        .max(source.triangle_indices().len())
150        .max(budget.minimum_indices);
151    let edges = (old.edge_bytes as usize / std::mem::size_of::<MeshEdgeGpu>())
152        .max(source.display_edges().len())
153        .max(budget.minimum_edges);
154    let mut allocation = preflight_mesh3d_upload(vertices, indices, edges, max_buffer_size)?;
155    if !source.texture_coordinates().is_empty() {
156        allocation.texture_coordinate_bytes = u64::try_from(vertices)
157            .ok()
158            .and_then(|vertices| vertices.checked_mul(std::mem::size_of::<MeshUvGpu>() as u64))
159            .filter(|bytes| *bytes <= max_buffer_size)
160            .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
161        allocation.total_bytes = allocation
162            .total_bytes
163            .checked_add(allocation.texture_coordinate_bytes)
164            .filter(|bytes| usize::try_from(*bytes).is_ok())
165            .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
166    }
167    if !source.vertex_colors().is_empty() {
168        allocation.color_bytes = u64::try_from(vertices)
169            .ok()
170            .and_then(|count| count.checked_mul(std::mem::size_of::<MeshColorGpu>() as u64))
171            .filter(|bytes| *bytes <= max_buffer_size)
172            .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
173        allocation.total_bytes = allocation
174            .total_bytes
175            .checked_add(allocation.color_bytes)
176            .filter(|bytes| usize::try_from(*bytes).is_ok())
177            .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
178    }
179    if !source.normals().is_empty() {
180        allocation.normal_bytes = u64::try_from(vertices)
181            .ok()
182            .and_then(|count| count.checked_mul(std::mem::size_of::<MeshNormalGpu>() as u64))
183            .filter(|bytes| *bytes <= max_buffer_size)
184            .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
185        allocation.total_bytes = allocation
186            .total_bytes
187            .checked_add(allocation.normal_bytes)
188            .filter(|bytes| usize::try_from(*bytes).is_ok())
189            .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
190    }
191    Ok(allocation)
192}
193
194#[allow(clippy::too_many_arguments)]
195pub(super) fn update_scene_mesh(
196    device: &wgpu::Device,
197    queue: &wgpu::Queue,
198    identity: &Arc<()>,
199    scratch: &mut DynamicMesh3dScratch,
200    scene: &mut Scene3d,
201    object_id: Object3dId,
202    source: Mesh3d,
203    budget: DynamicMesh3dBudget,
204) -> Result<DynamicMesh3dUpdateReport, DynamicMesh3dError> {
205    let instance = scene.instance(object_id)?;
206    let old = &instance.mesh;
207    if !Arc::ptr_eq(identity, &old.renderer_identity)
208        || old
209            .material
210            .as_ref()
211            .is_some_and(|material| !material.texture().belongs_to(identity))
212    {
213        return Err(Mesh3dResourceError::RendererMismatch.into());
214    }
215    validate_mesh_source_style(&source, instance.style)?;
216    if old.material.is_some()
217        && (source.texture_coordinates().len() != source.vertices().len()
218            || source.triangle_count() == 0)
219    {
220        return Err(Mesh3dResourceError::Texture(Texture3dError::MissingTextureCoordinates).into());
221    }
222    let live = preflight_mesh3d_source(&source, device.limits().max_buffer_size)?;
223    if !mesh3d_source_is_portable(&source) {
224        return Err(Mesh3dResourceError::NonPortableVertex.into());
225    }
226    if source.texture_coordinates().iter().any(|coordinate| {
227        !is_portable_shader_source(coordinate.u()) || !is_portable_shader_source(coordinate.v())
228    }) {
229        return Err(Mesh3dResourceError::NonPortableTextureCoordinate.into());
230    }
231    let allocation = planned_allocation(
232        old.allocation,
233        &source,
234        budget,
235        device.limits().max_buffer_size,
236    )?;
237    upload::validate_allocation(device, allocation, budget.upload)?;
238    final_limit(
239        Mesh3dUploadBudgetResource::RecoveryBytes,
240        source.recovery_memory_bytes(),
241        budget.upload.max_recovery_bytes(),
242    )?;
243    let detached_aliases = !bundle_is_unique(old);
244    let layout_changed = old.allocation != allocation;
245    let grew_capacity = [
246        (allocation.vertex_bytes, old.allocation.vertex_bytes),
247        (allocation.index_bytes, old.allocation.index_bytes),
248        (allocation.edge_bytes, old.allocation.edge_bytes),
249        (allocation.color_bytes, old.allocation.color_bytes),
250        (allocation.normal_bytes, old.allocation.normal_bytes),
251        (
252            allocation.texture_coordinate_bytes,
253            old.allocation.texture_coordinate_bytes,
254        ),
255    ]
256    .into_iter()
257    .any(|(new, old)| new > old);
258    let replace_buffers = detached_aliases || layout_changed;
259    let peak_gpu_bytes = checked_sum([
260        old.gpu_allocation_bytes(),
261        if replace_buffers {
262            allocation.total_bytes as usize
263        } else {
264            0
265        },
266    ])?;
267    let same_source = old.source.vertices().as_ptr() == source.vertices().as_ptr();
268    let peak_recovery_bytes = checked_sum([
269        old.recovery_memory_bytes(),
270        if same_source {
271            0
272        } else {
273            source.recovery_memory_bytes()
274        },
275    ])?;
276    peak_limit(
277        DynamicMesh3dBudgetResource::PeakGpuBytes,
278        peak_gpu_bytes,
279        budget.peak_gpu,
280    )?;
281    peak_limit(
282        DynamicMesh3dBudgetResource::PeakRecoveryBytes,
283        peak_recovery_bytes,
284        budget.peak_recovery,
285    )?;
286    // This clone is a private candidate, after testing external snapshot aliases.
287    // No caller can acquire another scene alias while its exclusive borrow lasts.
288    let mut candidate = old.clone();
289    candidate.source = source;
290    candidate.index_count = live.index_count;
291    candidate.edge_count = live.edge_count;
292    candidate.budget = budget.upload;
293    let change = scene.prepare_dynamic_mesh_change(
294        object_id,
295        &candidate.source,
296        allocation.total_bytes as usize,
297        replace_buffers,
298    )?;
299    let (scratch_reallocations, peak_staging_bytes) = scratch.prepare(&candidate.source, budget)?;
300    let gpu_allocations = if replace_buffers {
301        let material = candidate.material.take();
302        candidate = allocate_retained_mesh(
303            device,
304            Arc::clone(identity),
305            candidate.source,
306            live,
307            allocation,
308            budget.upload,
309        );
310        candidate.material = material;
311        [
312            allocation.vertex_bytes,
313            allocation.index_bytes,
314            allocation.edge_bytes,
315            allocation.texture_coordinate_bytes,
316            allocation.color_bytes,
317            allocation.normal_bytes,
318        ]
319        .into_iter()
320        .filter(|bytes| *bytes > 0)
321        .count()
322    } else {
323        0
324    };
325    let upload_calls = write_retained_mesh_uploads(
326        queue,
327        &candidate,
328        &scratch.vertices,
329        &scratch.edges,
330        &scratch.coordinates,
331        &scratch.colors,
332        &scratch.normals,
333    );
334    submit_pending_uploads(queue);
335    let scene_statistics = scene.commit_dynamic_mesh_change(change, candidate);
336    Ok(DynamicMesh3dUpdateReport {
337        uploaded_bytes: live.total_bytes as usize,
338        upload_calls,
339        gpu_allocations,
340        detached_aliases,
341        grew_capacity,
342        capacity_gpu_bytes: allocation.total_bytes as usize,
343        scratch_capacity_bytes: scratch.capacity_bytes(),
344        scratch_reallocations,
345        peak_staging_bytes,
346        peak_gpu_bytes,
347        peak_recovery_bytes,
348        scene_statistics,
349    })
350}
351
352impl DynamicMesh3dScratch {
353    fn capacity_bytes(&self) -> usize {
354        self.vertices.capacity() * std::mem::size_of::<MeshVertexGpu>()
355            + self.edges.capacity() * std::mem::size_of::<MeshEdgeGpu>()
356            + self.coordinates.capacity() * std::mem::size_of::<MeshUvGpu>()
357            + self.colors.capacity() * std::mem::size_of::<MeshColorGpu>()
358            + self.normals.capacity() * std::mem::size_of::<MeshNormalGpu>()
359    }
360
361    fn prepare(
362        &mut self,
363        source: &Mesh3d,
364        budget: DynamicMesh3dBudget,
365    ) -> Result<(usize, usize), DynamicMesh3dError> {
366        let counts = [
367            source.vertices().len(),
368            source.display_edges().len(),
369            source.texture_coordinates().len(),
370            source.vertex_colors().len(),
371            source.normals().len(),
372        ];
373        let capacities = [
374            self.vertices.capacity(),
375            self.edges.capacity(),
376            self.coordinates.capacity(),
377            self.colors.capacity(),
378            self.normals.capacity(),
379        ];
380        let strides = [
381            std::mem::size_of::<MeshVertexGpu>(),
382            std::mem::size_of::<MeshEdgeGpu>(),
383            std::mem::size_of::<MeshUvGpu>(),
384            std::mem::size_of::<MeshColorGpu>(),
385            std::mem::size_of::<MeshNormalGpu>(),
386        ];
387        let planned = std::array::from_fn::<_, 5, _>(|index| capacities[index].max(counts[index]));
388        let bytes = |values: [usize; 5]| -> Result<usize, DynamicMesh3dError> {
389            let mut total = 0usize;
390            for (count, stride) in values.into_iter().zip(strides) {
391                total = count
392                    .checked_mul(stride)
393                    .and_then(|bytes| total.checked_add(bytes))
394                    .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
395            }
396            Ok(total)
397        };
398        let final_bytes = bytes(planned)?;
399        let replacing = std::array::from_fn(|index| {
400            if counts[index] > capacities[index] {
401                counts[index]
402            } else {
403                0
404            }
405        });
406        let old_bytes = bytes(capacities)?;
407        let peak = checked_sum([old_bytes, bytes(replacing)?])?;
408        final_limit(
409            Mesh3dUploadBudgetResource::StagingBytes,
410            final_bytes,
411            budget.upload.max_staging_bytes(),
412        )?;
413        peak_limit(
414            DynamicMesh3dBudgetResource::PeakStagingBytes,
415            peak,
416            budget.peak_staging,
417        )?;
418        let vertices = reserve_conversion::<MeshVertexGpu>(capacities[0], counts[0])?;
419        let edges = reserve_conversion::<MeshEdgeGpu>(capacities[1], counts[1])?;
420        let coordinates = reserve_conversion::<MeshUvGpu>(capacities[2], counts[2])?;
421        let colors = reserve_conversion::<MeshColorGpu>(capacities[3], counts[3])?;
422        let normals = reserve_conversion::<MeshNormalGpu>(capacities[4], counts[4])?;
423        let actual = [
424            vertices.as_ref().map_or(capacities[0], Vec::capacity),
425            edges.as_ref().map_or(capacities[1], Vec::capacity),
426            coordinates.as_ref().map_or(capacities[2], Vec::capacity),
427            colors.as_ref().map_or(capacities[3], Vec::capacity),
428            normals.as_ref().map_or(capacities[4], Vec::capacity),
429        ];
430        let actual_new = [
431            vertices.as_ref().map_or(0, Vec::capacity),
432            edges.as_ref().map_or(0, Vec::capacity),
433            coordinates.as_ref().map_or(0, Vec::capacity),
434            colors.as_ref().map_or(0, Vec::capacity),
435            normals.as_ref().map_or(0, Vec::capacity),
436        ];
437        let peak = checked_sum([old_bytes, bytes(actual_new)?])?;
438        final_limit(
439            Mesh3dUploadBudgetResource::StagingBytes,
440            bytes(actual)?,
441            budget.upload.max_staging_bytes(),
442        )?;
443        peak_limit(
444            DynamicMesh3dBudgetResource::PeakStagingBytes,
445            peak,
446            budget.peak_staging,
447        )?;
448        let reallocations = usize::from(vertices.is_some())
449            + usize::from(edges.is_some())
450            + usize::from(coordinates.is_some())
451            + usize::from(colors.is_some())
452            + usize::from(normals.is_some());
453        if let Some(vertices) = vertices {
454            self.vertices = vertices;
455        }
456        if let Some(edges) = edges {
457            self.edges = edges;
458        }
459        if let Some(coordinates) = coordinates {
460            self.coordinates = coordinates;
461        }
462        if let Some(colors) = colors {
463            self.colors = colors;
464        }
465        if let Some(normals) = normals {
466            self.normals = normals;
467        }
468        self.normals.clear();
469        self.normals
470            .extend(source.normals().iter().map(MeshNormalGpu::from_source));
471        self.colors.clear();
472        self.colors
473            .extend(source.vertex_colors().iter().map(|color| MeshColorGpu {
474                color: color.to_array(),
475            }));
476        self.vertices.clear();
477        self.vertices
478            .extend(source.vertices().iter().map(|vertex| MeshVertexGpu {
479                position: [vertex.x(), vertex.y(), vertex.z()],
480            }));
481        self.edges.clear();
482        self.edges.extend(source.display_edges().iter().map(|edge| {
483            let start = source.vertices()[edge.start() as usize];
484            let end = source.vertices()[edge.end() as usize];
485            MeshEdgeGpu {
486                start: [start.x(), start.y(), start.z()],
487                end: [end.x(), end.y(), end.z()],
488            }
489        }));
490        self.coordinates.clear();
491        self.coordinates.extend(
492            source
493                .texture_coordinates()
494                .iter()
495                .map(|coordinate| MeshUvGpu {
496                    coordinate: [coordinate.u(), coordinate.v()],
497                }),
498        );
499        Ok((reallocations, peak))
500    }
501}
502
503fn reserve_conversion<T>(
504    capacity: usize,
505    count: usize,
506) -> Result<Option<Vec<T>>, Mesh3dResourceError> {
507    if count <= capacity {
508        return Ok(None);
509    }
510    let requested_bytes = count
511        .checked_mul(std::mem::size_of::<T>())
512        .and_then(|bytes| u64::try_from(bytes).ok())
513        .ok_or(Mesh3dResourceError::CapacityTooLarge)?;
514    let mut values = Vec::new();
515    values
516        .try_reserve_exact(count)
517        .map_err(|_| Mesh3dResourceError::HostAllocationFailed { requested_bytes })?;
518    Ok(Some(values))
519}