Skip to main content

sim_engine/renderer/mesh3d/
upload.rs

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