Skip to main content

sim_engine/renderer/
mesh3d_upload.rs

1//! Explicit immutable mesh replacement budgets and peak accounting.
2
3use super::*;
4
5/// Byte category bounded before immutable mesh upload or replacement.
6#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7pub enum Mesh3dUploadBudgetResource {
8    /// Retained source-topology capacities.
9    RecoveryBytes,
10    /// Vertex/UV/index/display-edge GPU buffer bytes; excludes material texels.
11    GpuBytes,
12    /// Temporary CPU conversion-array bytes.
13    StagingBytes,
14}
15
16/// Per-upload limits checked before caller-scale staging or GPU allocation.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub struct Mesh3dUploadBudget {
19    max_recovery_bytes: usize,
20    max_gpu_bytes: usize,
21    max_staging_bytes: usize,
22}
23
24impl Mesh3dUploadBudget {
25    /// Creates nonzero source-capacity, GPU-buffer and conversion-staging limits.
26    pub fn new(
27        max_recovery_bytes: usize,
28        max_gpu_bytes: usize,
29        max_staging_bytes: usize,
30    ) -> Result<Self, Mesh3dResourceError> {
31        if [max_recovery_bytes, max_gpu_bytes, max_staging_bytes].contains(&0) {
32            return Err(Mesh3dResourceError::InvalidBudget);
33        }
34        Ok(Self {
35            max_recovery_bytes,
36            max_gpu_bytes,
37            max_staging_bytes,
38        })
39    }
40    /// Maximum retained core topology capacity, excluding Arc control blocks.
41    pub const fn max_recovery_bytes(self) -> usize {
42        self.max_recovery_bytes
43    }
44    /// Maximum vertex/UV/index/display-edge bytes for the accepted revision.
45    pub const fn max_gpu_bytes(self) -> usize {
46        self.max_gpu_bytes
47    }
48    /// Maximum temporary CPU vertex/UV/edge conversion bytes.
49    pub const fn max_staging_bytes(self) -> usize {
50        self.max_staging_bytes
51    }
52}
53
54impl Default for Mesh3dUploadBudget {
55    fn default() -> Self {
56        Self {
57            max_recovery_bytes: 256 * 1024 * 1024,
58            max_gpu_bytes: 256 * 1024 * 1024,
59            max_staging_bytes: 256 * 1024 * 1024,
60        }
61    }
62}
63
64/// Nominal buffer/source accounting for an accepted immutable replacement.
65#[derive(Debug, Clone, Copy, PartialEq, Eq)]
66pub struct Mesh3dUploadReport {
67    recovery_bytes: usize,
68    uploaded_bytes: usize,
69    staging_bytes: usize,
70    peak_recovery_bytes: usize,
71    peak_gpu_bytes: usize,
72}
73
74impl Mesh3dUploadReport {
75    /// CPU source topology capacity of the accepted revision.
76    pub const fn recovery_bytes(self) -> usize {
77        self.recovery_bytes
78    }
79    /// Bytes uploaded to new vertex/UV/index/display-edge buffers.
80    pub const fn uploaded_bytes(self) -> usize {
81        self.uploaded_bytes
82    }
83    /// Temporary CPU conversion-array bytes, excluding backend upload staging.
84    pub const fn staging_bytes(self) -> usize {
85        self.staging_bytes
86    }
87    /// Old plus new unique source capacities during replacement.
88    pub const fn peak_recovery_bytes(self) -> usize {
89        self.peak_recovery_bytes
90    }
91    /// Old plus new GPU buffer bytes, not a promise of immediate driver release.
92    pub const fn peak_gpu_bytes(self) -> usize {
93        self.peak_gpu_bytes
94    }
95    /// Immutable replacement always allocates new buffers, even at equal size.
96    pub const fn replaced_buffers(self) -> bool {
97        true
98    }
99}
100
101impl WgpuRenderer {
102    /// Creates an immutable revision with explicit pre-allocation byte limits.
103    pub fn create_mesh3d_with_budget(
104        &self,
105        source: Mesh3d,
106        budget: Mesh3dUploadBudget,
107    ) -> Result<RetainedMesh3d, Mesh3dResourceError> {
108        let prepared = prepare_with_budget(&self.device, source, budget)?;
109        Ok(upload_prepared_retained_mesh(
110            &self.device,
111            &self.queue,
112            Arc::clone(&self.renderer_identity),
113            prepared,
114        ))
115    }
116
117    /// Atomically replaces this retained handle with a newly uploaded revision.
118    ///
119    /// Clones and scene objects referencing the previous revision are unchanged;
120    /// use [`Scene3d::set_mesh`] to rebind selected live objects. This is immutable
121    /// replacement, not a stable-capacity in-place upload. Validation/allocation
122    /// errors preserve the old handle; asynchronous device failure is separate.
123    /// In-flight work keeps its old references. Nominal transient GPU/source
124    /// overlap is at most the old revision plus the incoming configured limits.
125    pub fn replace_mesh3d(
126        &self,
127        mesh: &mut RetainedMesh3d,
128        source: Mesh3d,
129        budget: Mesh3dUploadBudget,
130    ) -> Result<Mesh3dUploadReport, Mesh3dResourceError> {
131        replace_resources(
132            &self.device,
133            &self.queue,
134            &self.renderer_identity,
135            mesh,
136            source,
137            budget,
138        )
139    }
140}
141
142pub(super) fn prepare_with_budget(
143    device: &wgpu::Device,
144    source: Mesh3d,
145    budget: Mesh3dUploadBudget,
146) -> Result<PreparedRetainedMeshUpload, Mesh3dResourceError> {
147    let layout = preflight_mesh3d_source(&source, device.limits().max_buffer_size)?;
148    for (resource, limit, actual) in [
149        (
150            Mesh3dUploadBudgetResource::RecoveryBytes,
151            budget.max_recovery_bytes,
152            source.recovery_memory_bytes(),
153        ),
154        (
155            Mesh3dUploadBudgetResource::GpuBytes,
156            budget.max_gpu_bytes,
157            layout.total_bytes as usize,
158        ),
159        (
160            Mesh3dUploadBudgetResource::StagingBytes,
161            budget.max_staging_bytes,
162            layout
163                .vertex_bytes
164                .saturating_add(layout.edge_bytes)
165                .saturating_add(layout.texture_coordinate_bytes) as usize,
166        ),
167    ] {
168        if actual > limit {
169            return Err(Mesh3dResourceError::BudgetExceeded {
170                resource,
171                limit,
172                actual,
173            });
174        }
175    }
176    let mut prepared = prepare_retained_mesh_upload(device, source)?;
177    prepared.budget = budget;
178    Ok(prepared)
179}
180
181pub(super) fn replace_resources(
182    device: &wgpu::Device,
183    queue: &wgpu::Queue,
184    identity: &Arc<()>,
185    mesh: &mut RetainedMesh3d,
186    source: Mesh3d,
187    budget: Mesh3dUploadBudget,
188) -> Result<Mesh3dUploadReport, Mesh3dResourceError> {
189    if !Arc::ptr_eq(identity, &mesh.renderer_identity) {
190        return Err(Mesh3dResourceError::RendererMismatch);
191    }
192    if mesh.material().is_some()
193        && (source.texture_coordinates().len() != source.vertices().len()
194            || source.triangle_count() == 0)
195    {
196        return Err(Mesh3dResourceError::Texture(
197            Texture3dError::MissingTextureCoordinates,
198        ));
199    }
200    let prepared = prepare_with_budget(device, source, budget)?;
201    let report = Mesh3dUploadReport {
202        recovery_bytes: prepared.source.recovery_memory_bytes(),
203        uploaded_bytes: prepared.layout.total_bytes as usize,
204        staging_bytes: prepared
205            .layout
206            .vertex_bytes
207            .saturating_add(prepared.layout.edge_bytes)
208            .saturating_add(prepared.layout.texture_coordinate_bytes)
209            as usize,
210        peak_recovery_bytes: mesh.recovery_memory_bytes().saturating_add(
211            if mesh.source.vertices().as_ptr() == prepared.source.vertices().as_ptr() {
212                0
213            } else {
214                prepared.source.recovery_memory_bytes()
215            },
216        ),
217        peak_gpu_bytes: mesh
218            .gpu_allocation_bytes()
219            .saturating_add(prepared.layout.total_bytes as usize),
220    };
221    let mut replacement =
222        upload_prepared_retained_mesh(device, queue, Arc::clone(identity), prepared);
223    replacement.material = mesh.material.clone();
224    *mesh = replacement;
225    Ok(report)
226}