Skip to main content

sim_engine/renderer/
mesh3d_texture_updates.rs

1//! Bounded transactional mip-consistent updates with immutable alias isolation.
2
3use super::*;
4
5#[path = "mesh3d_texture_update_types.rs"]
6mod types;
7pub use types::{
8    Texture3dUpdateBudget, Texture3dUpdateBudgetResource, Texture3dUpdateError,
9    Texture3dUpdateReport,
10};
11
12struct PreparedUpdate {
13    chain: CpuMipChain,
14    packed: Vec<u8>,
15    first_nonopaque: Option<usize>,
16    report: Texture3dUpdateReport,
17}
18
19impl WgpuRenderer {
20    /// Updates this handle only, preserving all existing material/scene aliases.
21    ///
22    /// Input is straight sRGB RGBA8 starting at byte zero; exact required length
23    /// is `(height - 1) * bytes_per_row + width * 4`, with stride at least one row.
24    /// Unique handles reuse GPU storage. Shared handles detach by GPU-copying the
25    /// old chain before uploading the base patch and regenerated lower levels.
26    /// Old materials remain unchanged until explicitly rebound with `with_texture`.
27    /// All lower mips are fully regenerated; only mip-zero upload is region-local.
28    /// Synchronous errors preserve CPU/GPU drawable state; asynchronous device
29    /// loss is separate and recovery restores the last committed complete chain.
30    pub fn update_texture3d_region(
31        &self,
32        texture: &mut Texture3d,
33        region: ImageTexelRect,
34        pixels: &[u8],
35        bytes_per_row: usize,
36        budget: Texture3dUpdateBudget,
37    ) -> Result<Texture3dUpdateReport, Texture3dUpdateError> {
38        update_texture_region(
39            &self.device,
40            &self.queue,
41            &self.renderer_identity,
42            &self.mesh3d_renderer.textures.layout,
43            texture,
44            region,
45            pixels,
46            bytes_per_row,
47            budget,
48        )
49    }
50
51    /// Updates only the selected object's texture, preserving its ID/material and
52    /// every external/other-object snapshot. A uniquely scene-owned texture reuses
53    /// GPU storage; aliases detach. Mesh topology is never copied or uploaded.
54    /// Texture, material alpha policy and final scene budgets are checked before
55    /// writes. Private bounded scene bookkeeping may be prepared before failure.
56    #[allow(clippy::too_many_arguments)]
57    pub fn update_scene3d_texture_region(
58        &self,
59        scene: &mut Scene3d,
60        object_id: Object3dId,
61        region: ImageTexelRect,
62        pixels: &[u8],
63        bytes_per_row: usize,
64        budget: Texture3dUpdateBudget,
65    ) -> Result<Texture3dUpdateReport, Texture3dUpdateError> {
66        update_scene_texture_region(
67            &self.device,
68            &self.queue,
69            &self.renderer_identity,
70            &self.mesh3d_renderer.textures.layout,
71            scene,
72            object_id,
73            region,
74            pixels,
75            bytes_per_row,
76            budget,
77        )
78    }
79}
80
81fn sum(left: usize, right: usize) -> Result<usize, Texture3dUpdateError> {
82    left.checked_add(right)
83        .ok_or(Texture3dUpdateError::CapacityTooLarge)
84}
85fn limit(
86    resource: Texture3dUpdateBudgetResource,
87    actual: usize,
88    maximum: usize,
89) -> Result<(), Texture3dUpdateError> {
90    if actual > maximum {
91        Err(Texture3dUpdateError::BudgetExceeded {
92            resource,
93            limit: maximum,
94            actual,
95        })
96    } else {
97        Ok(())
98    }
99}
100
101fn validate_layout(
102    region: ImageTexelRect,
103    pixels: &[u8],
104    stride: usize,
105) -> Result<(usize, usize), Texture3dUpdateError> {
106    let row = (region.width() as usize)
107        .checked_mul(4)
108        .ok_or(Texture3dUpdateError::CapacityTooLarge)?;
109    let required = (region.height() as usize - 1)
110        .checked_mul(stride)
111        .and_then(|count| count.checked_add(row))
112        .ok_or(Texture3dUpdateError::InvalidSourceLayout)?;
113    if stride < row || pixels.len() != required {
114        return Err(Texture3dUpdateError::InvalidSourceLayout);
115    }
116    let bytes = row
117        .checked_mul(region.height() as usize)
118        .ok_or(Texture3dUpdateError::CapacityTooLarge)?;
119    Ok((row, bytes))
120}
121
122#[allow(clippy::too_many_arguments)]
123fn prepare_update(
124    device: &wgpu::Device,
125    identity: &Arc<()>,
126    source: &Texture3d,
127    region: ImageTexelRect,
128    pixels: &[u8],
129    stride: usize,
130    budget: Texture3dUpdateBudget,
131    require_opaque: bool,
132    detached: bool,
133) -> Result<PreparedUpdate, Texture3dUpdateError> {
134    let started = Instant::now();
135    if !source.belongs_to(identity) {
136        return Err(Texture3dError::RendererMismatch.into());
137    }
138    if !region.fits(source.size().0, source.size().1) {
139        return Err(Texture3dError::InvalidRegion.into());
140    }
141    source
142        .storage
143        .chain
144        .validate_device_limit(device.limits().max_texture_dimension_2d)
145        .map_err(Texture3dError::Image)?;
146    let (row_bytes, base) = validate_layout(region, pixels, stride)?;
147    if require_opaque || !source.preserves_alpha() {
148        for y in 0..region.height() as usize {
149            if let Some(x) = pixels[y * stride..y * stride + row_bytes]
150                .chunks_exact(4)
151                .position(|pixel| pixel[3] != 255)
152            {
153                return Err(Texture3dError::NonOpaquePixel {
154                    texel: (region.y() as usize + y) * source.size().0 as usize
155                        + region.x() as usize
156                        + x,
157                }
158                .into());
159            }
160        }
161    }
162    let gpu = source.gpu_allocation_bytes();
163    let mips = gpu - source.pixels().len();
164    let uploaded = sum(base, mips)?;
165    let copy = if detached { gpu } else { 0 };
166    let peak_gpu = sum(gpu, copy)?;
167    let peak_recovery = sum(source.recovery_memory_bytes(), gpu)?;
168    let staging = sum(base, uploaded)?;
169    for (resource, actual, maximum) in [
170        (
171            Texture3dUpdateBudgetResource::UploadBytes,
172            uploaded,
173            budget.upload,
174        ),
175        (
176            Texture3dUpdateBudgetResource::StagingBytes,
177            staging,
178            budget.staging,
179        ),
180        (
181            Texture3dUpdateBudgetResource::PeakRecoveryBytes,
182            peak_recovery,
183            budget.recovery,
184        ),
185        (
186            Texture3dUpdateBudgetResource::PeakGpuBytes,
187            peak_gpu,
188            budget.gpu,
189        ),
190        (
191            Texture3dUpdateBudgetResource::GpuCopyBytes,
192            copy,
193            budget.copy,
194        ),
195    ] {
196        limit(resource, actual, maximum)?;
197    }
198    let mut packed = Vec::new();
199    packed.try_reserve_exact(base).map_err(|_| {
200        Texture3dError::Image(ImageError::AllocationFailed {
201            requested_bytes: base,
202        })
203    })?;
204    let staging = sum(packed.capacity(), uploaded)?;
205    limit(
206        Texture3dUpdateBudgetResource::StagingBytes,
207        staging,
208        budget.staging,
209    )?;
210    let mut chain = source
211        .storage
212        .chain
213        .try_clone()
214        .map_err(Texture3dError::Image)?;
215    let recovery = chain.recovery_memory_bytes();
216    let peak_recovery = sum(source.recovery_memory_bytes(), recovery)?;
217    limit(
218        Texture3dUpdateBudgetResource::PeakRecoveryBytes,
219        peak_recovery,
220        budget.recovery,
221    )?;
222    for y in 0..region.height() as usize {
223        packed.extend_from_slice(&pixels[y * stride..y * stride + row_bytes]);
224    }
225    chain.patch_base(region, &packed);
226    chain.regenerate();
227    let first_nonopaque = chain
228        .pixels()
229        .chunks_exact(4)
230        .position(|pixel| pixel[3] != 255);
231    let level_count = chain.levels().len();
232    Ok(PreparedUpdate {
233        chain,
234        packed,
235        first_nonopaque,
236        report: Texture3dUpdateReport {
237            base,
238            mips,
239            uploads: level_count,
240            copy,
241            copies: if detached { level_count } else { 0 },
242            allocations: usize::from(detached),
243            submissions: 1 + usize::from(detached),
244            recovery,
245            gpu,
246            staging,
247            peak_recovery,
248            peak_gpu,
249            preparation: started.elapsed(),
250            encode_submit: Duration::ZERO,
251        },
252    })
253}
254
255#[allow(clippy::too_many_arguments)]
256pub(in crate::renderer::mesh3d) fn update_texture_region(
257    device: &wgpu::Device,
258    queue: &wgpu::Queue,
259    identity: &Arc<()>,
260    layout: &wgpu::BindGroupLayout,
261    texture: &mut Texture3d,
262    region: ImageTexelRect,
263    pixels: &[u8],
264    stride: usize,
265    budget: Texture3dUpdateBudget,
266) -> Result<Texture3dUpdateReport, Texture3dUpdateError> {
267    let detached = Arc::strong_count(&texture.storage) != 1;
268    let prepared = prepare_update(
269        device, identity, texture, region, pixels, stride, budget, false, detached,
270    )?;
271    Ok(apply_update(
272        device, queue, layout, texture, region, prepared,
273    ))
274}
275
276#[allow(clippy::too_many_arguments)]
277pub(in crate::renderer::mesh3d) fn update_scene_texture_region(
278    device: &wgpu::Device,
279    queue: &wgpu::Queue,
280    identity: &Arc<()>,
281    layout: &wgpu::BindGroupLayout,
282    scene: &mut Scene3d,
283    object_id: Object3dId,
284    region: ImageTexelRect,
285    pixels: &[u8],
286    stride: usize,
287    budget: Texture3dUpdateBudget,
288) -> Result<Texture3dUpdateReport, Texture3dUpdateError> {
289    let material = scene
290        .instance(object_id)?
291        .mesh
292        .material()
293        .ok_or(Texture3dUpdateError::MissingTexture)?;
294    let source = &material.texture;
295    // No temporary source/material clones may influence the ownership decision.
296    let detached = Arc::strong_count(&source.storage) != 1;
297    let prepared = prepare_update(
298        device,
299        identity,
300        source,
301        region,
302        pixels,
303        stride,
304        budget,
305        material.require_opaque_texture,
306        detached,
307    )?;
308    let change = scene.prepare_dynamic_texture_change(
309        object_id,
310        prepared.report.recovery,
311        prepared.report.gpu,
312        detached,
313    )?;
314    let material = scene.instances[change.object_index()]
315        .mesh
316        .material
317        .as_mut()
318        .ok_or(Texture3dUpdateError::MissingTexture)?;
319    let report = apply_update(
320        device,
321        queue,
322        layout,
323        &mut material.texture,
324        region,
325        prepared,
326    );
327    scene.commit_dynamic_texture_change(change);
328    Ok(report)
329}
330
331fn upload_patch(
332    queue: &wgpu::Queue,
333    texture: &wgpu::Texture,
334    region: ImageTexelRect,
335    prepared: &PreparedUpdate,
336) {
337    queue.write_texture(
338        wgpu::TexelCopyTextureInfo {
339            texture,
340            mip_level: 0,
341            origin: wgpu::Origin3d {
342                x: region.x(),
343                y: region.y(),
344                z: 0,
345            },
346            aspect: wgpu::TextureAspect::All,
347        },
348        &prepared.packed,
349        wgpu::TexelCopyBufferLayout {
350            offset: 0,
351            bytes_per_row: Some(region.width() * 4),
352            rows_per_image: Some(region.height()),
353        },
354        wgpu::Extent3d {
355            width: region.width(),
356            height: region.height(),
357            depth_or_array_layers: 1,
358        },
359    );
360    prepared.chain.upload_levels(queue, texture, 1);
361    submit_pending_uploads(queue);
362}
363
364fn apply_update(
365    device: &wgpu::Device,
366    queue: &wgpu::Queue,
367    layout: &wgpu::BindGroupLayout,
368    target: &mut Texture3d,
369    region: ImageTexelRect,
370    mut prepared: PreparedUpdate,
371) -> Texture3dUpdateReport {
372    let started = Instant::now();
373    if let Some(storage) = Arc::get_mut(&mut target.storage) {
374        upload_patch(queue, &storage.texture, region, &prepared);
375        storage.chain = prepared.chain;
376        storage.first_nonopaque_texel = prepared.first_nonopaque;
377    } else {
378        let texture = prepared.chain.allocate_gpu(device);
379        let bindings = create_bindings(device, layout, &texture, prepared.chain.levels().len());
380        let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
381            label: Some("sim-engine 3D texture alias detachment"),
382        });
383        for (index, level) in prepared.chain.levels().iter().enumerate() {
384            encoder.copy_texture_to_texture(
385                wgpu::TexelCopyTextureInfo {
386                    texture: &target.storage.texture,
387                    mip_level: index as u32,
388                    origin: wgpu::Origin3d::ZERO,
389                    aspect: wgpu::TextureAspect::All,
390                },
391                wgpu::TexelCopyTextureInfo {
392                    texture: &texture,
393                    mip_level: index as u32,
394                    origin: wgpu::Origin3d::ZERO,
395                    aspect: wgpu::TextureAspect::All,
396                },
397                wgpu::Extent3d {
398                    width: level.width,
399                    height: level.height,
400                    depth_or_array_layers: 1,
401                },
402            );
403        }
404        // Pending writes execute before submitted command buffers. Submit the
405        // preservation copy first, then enqueue patches, never in reverse order.
406        queue.submit([encoder.finish()]);
407        upload_patch(queue, &texture, region, &prepared);
408        target.storage = Arc::new(TextureStorage {
409            renderer_identity: Arc::clone(&target.storage.renderer_identity),
410            preserve_alpha: target.storage.preserve_alpha,
411            first_nonopaque_texel: prepared.first_nonopaque,
412            chain: prepared.chain,
413            texture,
414            bindings,
415        });
416    }
417    prepared.report.encode_submit = started.elapsed();
418    prepared.report
419}
420
421#[cfg(test)]
422mod tests {
423    use super::*;
424    #[test]
425    fn region_source_stride_is_checked_without_allocation() {
426        let region = ImageTexelRect::new(1, 1, 2, 2).unwrap();
427        assert_eq!(validate_layout(region, &[0; 20], 12), Ok((8, 16)));
428        for (data, stride) in [
429            (&[0; 19][..], 12),
430            (&[0; 16][..], 7),
431            (&[0; 16][..], usize::MAX),
432        ] {
433            assert!(validate_layout(region, data, stride).is_err());
434        }
435    }
436}