Skip to main content

sim_engine/renderer/mesh3d/texture/updates/
mod.rs

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