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/color/normal/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/color/normal/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/color/normal/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/color/normal/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)
166                .saturating_add(layout.color_bytes)
167                .saturating_add(layout.normal_bytes) as usize,
168        ),
169    ] {
170        if actual > limit {
171            return Err(Mesh3dResourceError::BudgetExceeded {
172                resource,
173                limit,
174                actual,
175            });
176        }
177    }
178    let mut prepared = prepare_retained_mesh_upload(device, source)?;
179    let actual = prepared.staging_capacity_bytes();
180    if actual > budget.max_staging_bytes {
181        return Err(Mesh3dResourceError::BudgetExceeded {
182            resource: Mesh3dUploadBudgetResource::StagingBytes,
183            limit: budget.max_staging_bytes,
184            actual,
185        });
186    }
187    prepared.budget = budget;
188    Ok(prepared)
189}
190
191pub(super) fn prepare_restoration(
192    device: &wgpu::Device,
193    source: &RetainedMesh3d,
194) -> Result<PreparedRetainedMeshUpload, Mesh3dResourceError> {
195    validate_allocation(device, source.allocation, source.budget)?;
196    let mut prepared = prepare_with_budget(device, source.source.clone(), source.budget)?;
197    prepared.allocation = source.allocation;
198    Ok(prepared)
199}
200
201pub(super) fn validate_allocation(
202    device: &wgpu::Device,
203    allocation: Mesh3dUploadLayout,
204    budget: Mesh3dUploadBudget,
205) -> Result<(), Mesh3dResourceError> {
206    if [
207        allocation.vertex_bytes,
208        allocation.index_bytes,
209        allocation.edge_bytes,
210        allocation.texture_coordinate_bytes,
211        allocation.color_bytes,
212        allocation.normal_bytes,
213    ]
214    .into_iter()
215    .any(|bytes| bytes > device.limits().max_buffer_size)
216        || usize::try_from(allocation.total_bytes).is_err()
217    {
218        return Err(Mesh3dResourceError::CapacityTooLarge);
219    }
220    if allocation.total_bytes as usize > budget.max_gpu_bytes() {
221        return Err(Mesh3dResourceError::BudgetExceeded {
222            resource: Mesh3dUploadBudgetResource::GpuBytes,
223            limit: budget.max_gpu_bytes(),
224            actual: allocation.total_bytes as usize,
225        });
226    }
227    Ok(())
228}
229
230pub(super) fn replace_resources(
231    device: &wgpu::Device,
232    queue: &wgpu::Queue,
233    identity: &Arc<()>,
234    mesh: &mut RetainedMesh3d,
235    source: Mesh3d,
236    budget: Mesh3dUploadBudget,
237) -> Result<Mesh3dUploadReport, Mesh3dResourceError> {
238    if !Arc::ptr_eq(identity, &mesh.renderer_identity) {
239        return Err(Mesh3dResourceError::RendererMismatch);
240    }
241    if mesh.material().is_some()
242        && (source.texture_coordinates().len() != source.vertices().len()
243            || source.triangle_count() == 0)
244    {
245        return Err(Mesh3dResourceError::Texture(
246            Texture3dError::MissingTextureCoordinates,
247        ));
248    }
249    let prepared = prepare_with_budget(device, source, budget)?;
250    let report = Mesh3dUploadReport {
251        recovery_bytes: prepared.source.recovery_memory_bytes(),
252        uploaded_bytes: prepared.layout.total_bytes as usize,
253        staging_bytes: prepared.staging_capacity_bytes(),
254        peak_recovery_bytes: mesh.recovery_memory_bytes().saturating_add(
255            if mesh.source.vertices().as_ptr() == prepared.source.vertices().as_ptr() {
256                0
257            } else {
258                prepared.source.recovery_memory_bytes()
259            },
260        ),
261        peak_gpu_bytes: mesh
262            .gpu_allocation_bytes()
263            .saturating_add(prepared.layout.total_bytes as usize),
264    };
265    let mut replacement =
266        upload_prepared_retained_mesh(device, queue, Arc::clone(identity), prepared);
267    replacement.material = mesh.material.clone();
268    *mesh = replacement;
269    Ok(report)
270}