Skip to main content

sim_logic/platform/desktop/
three_d.rs

1//! One retained cube mesh, bounded scene slots, and one reusable depth target.
2
3use std::{error::Error, fmt, mem::size_of};
4
5use sim_engine::{
6    DynamicMesh3dError, LogicalViewport, LogicalViewportError, Mesh3d, Mesh3dError,
7    Mesh3dRenderBudget, Mesh3dRenderError, Mesh3dRenderReport, Mesh3dResourceError, MeshEdge3d,
8    MeshStyle3d, Object3dId, RenderTarget2d, RenderTarget3d, RetainedMesh3d, Scene3d,
9    Scene3dBudget, Scene3dError, SurfaceRasterization3d, Texture3dError, Texture3dUpdateError,
10    Transform3d, Vec3, WgpuRenderer,
11};
12
13use crate::{
14    identity::LogicEntity,
15    three_d::{
16        CORNERS, CuboidVisualError, MeshVisualError, TRIANGLES, ThreeDLimitResource,
17        ThreeDRenderLimits, ThreeDSnapshot, ThreeDSurfacePolicy, View3dError,
18    },
19};
20
21#[path = "three_d/meshes.rs"]
22mod meshes;
23use meshes::CustomMeshes;
24#[path = "three_d/textures.rs"]
25mod textures;
26
27/// A bounded 3D preparation or separate depth-prepass failure.
28///
29/// Immutable mesh uploads, target allocation, and earlier successful prepasses
30/// may remain cached when later composition fails. No partial surface frame is
31/// presented. Instance-local Engine preflight and object-update failures preserve
32/// their current managed source. Camera, target, and aggregate-capacity failures
33/// remain scene-wide rather than being attributed to an arbitrary cuboid.
34#[derive(Debug)]
35pub enum DesktopThreeDError {
36    /// An independent 3D allowance was exceeded before preparing GPU resources.
37    LimitExceeded {
38        /// Resource exceeding its frozen cap.
39        resource: ThreeDLimitResource,
40        /// Requested resource count.
41        requested: u64,
42        /// Frozen maximum count.
43        limit: u64,
44    },
45    /// Bounded mesh or scene metadata allocation failed.
46    AllocationFailed {
47        /// Minimum additional requested bytes.
48        requested_bytes: usize,
49    },
50    /// The current logical viewport was invalid.
51    Viewport(LogicalViewportError),
52    /// The resize-aware camera could not be represented.
53    View(View3dError),
54    /// Built-in retained topology construction failed.
55    Mesh(Mesh3dError),
56    /// Mesh or target creation failed in the current renderer.
57    Resource(Mesh3dResourceError),
58    /// Retained scene creation or a hidden-slot update failed.
59    Scene(Scene3dError),
60    /// A managed cuboid's validated presentation could not form its GPU style.
61    Cuboid {
62        /// Source requesting the failed value.
63        source: LogicEntity,
64        /// Concrete value error.
65        error: CuboidVisualError,
66    },
67    /// A custom mesh's validated value could not form its GPU style.
68    CustomMesh {
69        /// Source requesting the failed value.
70        source: LogicEntity,
71        /// Concrete value error.
72        error: MeshVisualError,
73    },
74    /// Engine rejected a scene-owned mesh revision before publishing it.
75    DynamicMesh {
76        /// Managed source of the revision.
77        source: LogicEntity,
78        /// Original bounded update error.
79        error: DynamicMesh3dError,
80    },
81    /// Texture creation or material binding failed.
82    Texture {
83        /// Managed source of the texture.
84        source: LogicEntity,
85        /// Original Engine texture error.
86        error: Texture3dError,
87    },
88    /// An isolated texture patch failed before publication.
89    TextureUpdate {
90        /// Managed source of the patch.
91        source: LogicEntity,
92        /// Original Engine update error.
93        error: Texture3dUpdateError,
94    },
95    /// A managed 3D object could not be inserted or updated in the retained scene.
96    Object {
97        /// Source requesting the failed scene update.
98        source: LogicEntity,
99        /// Concrete scene failure.
100        error: Scene3dError,
101    },
102    /// Engine's authoritative preflight rejected one managed 3D object.
103    ObjectRender {
104        /// Current managed source occupying the retained Engine slot.
105        source: LogicEntity,
106        /// Concrete preflight failure, retaining its complete Engine object ID.
107        error: Mesh3dRenderError,
108    },
109    /// Engine rejected the scene or an object with no current managed source.
110    ///
111    /// Camera, ownership, and aggregate-capacity failures are scene-wide. An
112    /// unrecognized Engine object ID remains in the error without guessing its
113    /// source or discarding the original diagnostic.
114    Render(Mesh3dRenderError),
115    /// Private retained cache state was inconsistent.
116    InvalidCache,
117    /// The surface format or target byte count could not be represented.
118    InvalidTargetLayout,
119}
120
121impl fmt::Display for DesktopThreeDError {
122    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
123        match self {
124            Self::LimitExceeded {
125                resource,
126                requested,
127                limit,
128            } => write!(
129                formatter,
130                "desktop 3D {resource:?} requested {requested}, exceeding {limit}"
131            ),
132            Self::AllocationFailed { requested_bytes } => write!(
133                formatter,
134                "desktop 3D could not reserve {requested_bytes} additional bytes"
135            ),
136            Self::Viewport(error) => write!(formatter, "3D target viewport failed: {error}"),
137            Self::View(error) => write!(formatter, "3D camera preparation failed: {error}"),
138            Self::Mesh(error) => write!(formatter, "built-in cube topology failed: {error}"),
139            Self::Resource(error) => write!(formatter, "retained 3D resource failed: {error}"),
140            Self::Scene(error) => write!(formatter, "retained 3D scene failed: {error}"),
141            Self::Cuboid { source, error } => {
142                write!(formatter, "3D cuboid {source:?} style failed: {error}")
143            }
144            Self::CustomMesh { source, error } => {
145                write!(formatter, "3D mesh {source:?} style failed: {error}")
146            }
147            Self::DynamicMesh { source, error } => {
148                write!(formatter, "3D mesh {source:?} update failed: {error}")
149            }
150            Self::Texture { source, error } => {
151                write!(formatter, "3D texture {source:?} failed: {error}")
152            }
153            Self::TextureUpdate { source, error } => {
154                write!(formatter, "3D texture {source:?} patch failed: {error}")
155            }
156            Self::Object { source, error } => write!(
157                formatter,
158                "3D object {source:?} scene update failed: {error}"
159            ),
160            Self::ObjectRender { source, error } => write!(
161                formatter,
162                "3D object {source:?} depth prepass failed: {error}"
163            ),
164            Self::Render(error) => write!(formatter, "3D depth prepass failed: {error}"),
165            Self::InvalidCache => formatter.write_str("retained 3D cache is inconsistent"),
166            Self::InvalidTargetLayout => {
167                formatter.write_str("3D color-target byte layout is unrepresentable")
168            }
169        }
170    }
171}
172
173impl Error for DesktopThreeDError {
174    fn source(&self) -> Option<&(dyn Error + 'static)> {
175        match self {
176            Self::Viewport(error) => Some(error),
177            Self::View(error) => Some(error),
178            Self::Mesh(error) => Some(error),
179            Self::Resource(error) => Some(error),
180            Self::Scene(error) => Some(error),
181            Self::Cuboid { error, .. } => Some(error),
182            Self::CustomMesh { error, .. } => Some(error),
183            Self::DynamicMesh { error, .. } => Some(error),
184            Self::Texture { error, .. } => Some(error),
185            Self::TextureUpdate { error, .. } => Some(error),
186            Self::Object { error, .. } => Some(error),
187            Self::ObjectRender { error, .. } => Some(error),
188            Self::Render(error) => Some(error),
189            _ => None,
190        }
191    }
192}
193
194/// Actual uploads performed by scene-owned updates during one 3D preparation.
195/// Initial resource creation and ordinary frame uniforms are not included.
196#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
197pub struct DesktopThreeDUpdates {
198    /// Accepted mesh revision count, including alias detachment and growth.
199    pub mesh_updates: usize,
200    /// Bytes uploaded by accepted mesh revisions.
201    pub mesh_upload_bytes: usize,
202    /// New GPU buffers allocated by mesh revisions, not initial creation.
203    pub mesh_gpu_allocations: usize,
204    /// Accepted immediate-parent texture patches.
205    pub texture_updates: usize,
206    /// Patch and regenerated lower-mip upload bytes.
207    pub texture_upload_bytes: usize,
208    /// New GPU textures allocated by patches, including alias detachment.
209    pub texture_gpu_allocations: usize,
210}
211
212impl DesktopThreeDUpdates {
213    pub(super) fn accumulate(&mut self, other: Self) {
214        self.mesh_updates = self.mesh_updates.saturating_add(other.mesh_updates);
215        self.mesh_upload_bytes = self
216            .mesh_upload_bytes
217            .saturating_add(other.mesh_upload_bytes);
218        self.mesh_gpu_allocations = self
219            .mesh_gpu_allocations
220            .saturating_add(other.mesh_gpu_allocations);
221        self.texture_updates = self.texture_updates.saturating_add(other.texture_updates);
222        self.texture_upload_bytes = self
223            .texture_upload_bytes
224            .saturating_add(other.texture_upload_bytes);
225        self.texture_gpu_allocations = self
226            .texture_gpu_allocations
227            .saturating_add(other.texture_gpu_allocations);
228    }
229    const fn empty() -> Self {
230        Self {
231            mesh_updates: 0,
232            mesh_upload_bytes: 0,
233            mesh_gpu_allocations: 0,
234            texture_updates: 0,
235            texture_upload_bytes: 0,
236            texture_gpu_allocations: 0,
237        }
238    }
239}
240
241pub(super) struct DesktopThreeD {
242    mesh: Option<RetainedMesh3d>,
243    scene: Option<Scene3d>,
244    slots: Vec<SceneSlot>,
245    custom: CustomMeshes,
246    target: TargetCache<RenderTarget3d>,
247}
248
249impl DesktopThreeD {
250    pub(super) const fn new() -> Self {
251        Self {
252            mesh: None,
253            scene: None,
254            slots: Vec::new(),
255            custom: CustomMeshes::new(),
256            target: TargetCache::new(),
257        }
258    }
259
260    /// Invalidates renderer-bound resources after recovery or renderer creation.
261    pub(super) fn clear(&mut self) {
262        self.mesh = None;
263        self.scene = None;
264        self.slots.clear();
265        self.custom.clear();
266        self.target.clear();
267    }
268
269    pub(super) fn color_target(&self) -> Option<&RenderTarget2d> {
270        self.target.get().map(RenderTarget3d::color_target)
271    }
272
273    pub(super) fn updates(&self) -> DesktopThreeDUpdates {
274        self.custom.updates
275    }
276
277    /// Restore the scene as a unit: Engine preserves IDs, aliases and material
278    /// settings. CPU slot metadata remains valid; targets are recreated lazily.
279    pub(super) fn restore(&mut self, renderer: &WgpuRenderer) -> Result<(), DesktopThreeDError> {
280        if let Some(scene) = &mut self.scene {
281            renderer
282                .restore_scene3d(scene)
283                .map_err(DesktopThreeDError::Resource)?;
284        }
285        if let Some(slot) = self.slots.first() {
286            self.mesh = Some(
287                self.scene
288                    .as_ref()
289                    .ok_or(DesktopThreeDError::InvalidCache)?
290                    .instance(slot.id)
291                    .map_err(DesktopThreeDError::Scene)?
292                    .mesh()
293                    .clone(),
294            );
295        } else if let Some(mesh) = &self.mesh {
296            // This built-in mesh has no scene instance. Custom meshes restore
297            // with their scene so shared resources and stable IDs remain intact.
298            self.mesh = Some(
299                renderer
300                    .restore_mesh3d(mesh)
301                    .map_err(DesktopThreeDError::Resource)?,
302            );
303        }
304        self.target.clear();
305        Ok(())
306    }
307
308    pub(super) fn prepare(
309        &mut self,
310        renderer: &mut WgpuRenderer,
311        snapshot: ThreeDSnapshot<'_>,
312        limits: ThreeDRenderLimits,
313    ) -> Result<Mesh3dRenderReport, DesktopThreeDError> {
314        let (width, height) = renderer.size();
315        check_limits(snapshot.cuboids().len(), width, height, limits)?;
316        let render_budget = snapshot_render_budget(snapshot, limits);
317        let viewport = renderer
318            .logical_viewport()
319            .map_err(DesktopThreeDError::Viewport)?;
320        let camera = snapshot
321            .view()
322            .camera(viewport)
323            .map_err(DesktopThreeDError::View)?;
324        if self.mesh.is_none() {
325            let mesh = unit_cube()?;
326            self.mesh = Some(
327                renderer
328                    .create_mesh3d(mesh)
329                    .map_err(DesktopThreeDError::Resource)?,
330            );
331        }
332        let mesh = self.mesh.as_ref().ok_or(DesktopThreeDError::InvalidCache)?;
333        if self.scene.is_none() {
334            let scene = Scene3d::with_alpha_background_and_budget(
335                snapshot.view().background(),
336                engine_scene_budget(limits)?,
337            )
338            .map_err(DesktopThreeDError::Scene)?;
339            self.scene = Some(scene);
340            // New scene IDs also invalidate every last-applied field together.
341            self.slots.clear();
342            self.custom.clear_slots();
343        }
344        let scene = self
345            .scene
346            .as_mut()
347            .ok_or(DesktopThreeDError::InvalidCache)?;
348        // Clear-color changes must not discard object IDs, dynamic capacities
349        // or texture lineage. Engine validates and mutates this field alone.
350        scene
351            .set_background(snapshot.view().background())
352            .map_err(DesktopThreeDError::Scene)?;
353        scene.set_lighting(snapshot.view().lighting());
354        scene.set_fog(snapshot.view().fog());
355        for (index, record) in snapshot.cuboids().iter().enumerate() {
356            let source = record.source();
357            let style = record
358                .visual()
359                .style()
360                .map_err(|error| DesktopThreeDError::Cuboid { source, error })?;
361            let desired = AppliedState {
362                source,
363                transform: record.transform(),
364                style,
365                visible: true,
366            };
367            if index == self.slots.len() {
368                if self.slots.len() == self.slots.capacity() {
369                    self.slots.try_reserve_exact(1).map_err(|_| {
370                        DesktopThreeDError::AllocationFailed {
371                            requested_bytes: size_of::<SceneSlot>(),
372                        }
373                    })?;
374                }
375                let id = scene
376                    .try_push(mesh, record.transform(), style)
377                    .map_err(|error| DesktopThreeDError::Object { source, error })?;
378                // A successful insertion already applies all three fields.
379                self.slots.push(SceneSlot {
380                    id,
381                    applied: desired,
382                });
383            } else {
384                self.slots[index]
385                    .update(scene, desired)
386                    .map_err(|error| DesktopThreeDError::Object { source, error })?;
387            }
388        }
389        for slot in &mut self.slots[snapshot.cuboids().len()..] {
390            let hidden = AppliedState {
391                visible: false,
392                ..slot.applied
393            };
394            slot.update(scene, hidden)
395                .map_err(DesktopThreeDError::Scene)?;
396        }
397        self.custom
398            .prepare(renderer, scene, snapshot.meshes(), limits)?;
399        let descriptor = TargetDescriptor {
400            width,
401            height,
402            viewport,
403        };
404        if !self.target.matches(descriptor) {
405            // Engine 0.3 composition caches bindings that retain this target's
406            // texture. Release those host references before replacing it, not
407            // only our target handle. Steady-state frames keep their cache.
408            renderer.clear_frame_cache();
409        }
410        self.target.ensure(descriptor, || {
411            renderer
412                .create_render_target3d(width, height, viewport)
413                .map_err(DesktopThreeDError::Resource)
414        })?;
415        let target = self.target.get().ok_or(DesktopThreeDError::InvalidCache)?;
416        renderer
417            .render_scene3d_to_target_with_budget(target, scene, camera, render_budget)
418            .map_err(|error| {
419                if let Some(source) = error
420                    .object_id()
421                    .and_then(|id| find_object_source(id, self.custom.object_sources()))
422                {
423                    DesktopThreeDError::ObjectRender { source, error }
424                } else {
425                    map_render_error(error, &self.slots)
426                }
427            })
428    }
429}
430
431struct SceneSlot {
432    id: Object3dId,
433    applied: AppliedState,
434}
435
436impl SceneSlot {
437    fn update(&mut self, scene: &mut Scene3d, desired: AppliedState) -> Result<(), Scene3dError> {
438        let id = self.id;
439        self.applied.update(desired, |change| match change {
440            SlotChange::Transform(transform) => scene.set_transform(id, transform),
441            SlotChange::Style(style) => scene.set_style(id, style),
442            SlotChange::Visible(visible) => scene.set_visible(id, visible),
443        })
444    }
445}
446
447#[derive(Debug, Clone, Copy, PartialEq)]
448struct AppliedState {
449    source: LogicEntity,
450    transform: Transform3d,
451    style: MeshStyle3d,
452    visible: bool,
453}
454
455#[derive(Debug, Clone, Copy, PartialEq)]
456enum SlotChange {
457    Transform(Transform3d),
458    Style(MeshStyle3d),
459    Visible(bool),
460}
461
462impl AppliedState {
463    fn update<E>(
464        &mut self,
465        desired: Self,
466        mut apply: impl FnMut(SlotChange) -> Result<(), E>,
467    ) -> Result<(), E> {
468        // Engine 0.3 indexes retained IDs, but unchanged fields still avoid
469        // unnecessary validation and setter work, including hidden slots.
470        // Record only successful setters, so a later failed setter never makes
471        // this cache claim a value that the retained scene has not accepted.
472        if self.transform != desired.transform {
473            apply(SlotChange::Transform(desired.transform))?;
474            self.transform = desired.transform;
475        }
476        if self.style != desired.style {
477            apply(SlotChange::Style(desired.style))?;
478            self.style = desired.style;
479        }
480        if self.visible != desired.visible {
481            apply(SlotChange::Visible(desired.visible))?;
482            self.visible = desired.visible;
483        }
484        // Slots are reused by snapshot order, not permanently bound to an ECS
485        // entity. Equal geometry must still refresh attribution after despawn,
486        // reorder, or World replacement. A failed update is not rendered.
487        self.source = desired.source;
488        Ok(())
489    }
490}
491
492fn map_render_error(error: Mesh3dRenderError, slots: &[SceneSlot]) -> DesktopThreeDError {
493    let source = error.object_id().and_then(|id| {
494        find_object_source(
495            id,
496            slots
497                .iter()
498                .map(|slot| (slot.id, slot.applied.source, slot.applied.visible)),
499        )
500    });
501    match source {
502        Some(source) => DesktopThreeDError::ObjectRender { source, error },
503        None => DesktopThreeDError::Render(error),
504    }
505}
506
507fn find_object_source<Id: Eq>(
508    id: Id,
509    slots: impl IntoIterator<Item = (Id, LogicEntity, bool)>,
510) -> Option<LogicEntity> {
511    // Compare complete opaque handles, never their scene-local diagnostic
512    // numbers. This scan runs only on rejected prepasses, not every frame.
513    slots
514        .into_iter()
515        .find_map(|(slot_id, source, visible)| (visible && slot_id == id).then_some(source))
516}
517
518fn engine_scene_budget(limits: ThreeDRenderLimits) -> Result<Scene3dBudget, DesktopThreeDError> {
519    let defaults = Scene3dBudget::default();
520    // Engine requires a nonzero object ceiling even for a background-only
521    // scene. Logic's earlier count check still prohibits objects at a zero cap.
522    // Keep finite Engine geometry ceilings. CPU texture source limits cover
523    // base snapshots; the GPU texel allowance also covers Engine recovery mips.
524    Scene3dBudget::new(
525        limits
526            .max_cuboids()
527            .saturating_add(limits.max_meshes())
528            .max(1),
529        defaults.max_storage_bytes(),
530        defaults.max_mesh_cpu_bytes(),
531        defaults.max_mesh_gpu_bytes(),
532    )
533    .map(|budget| {
534        budget.with_texture_limits(
535            limits.max_texture_gpu_bytes(),
536            limits.max_texture_gpu_bytes(),
537        )
538    })
539    .map_err(DesktopThreeDError::Scene)
540}
541
542#[cfg(test)]
543fn engine_render_budget(count: usize, limits: ThreeDRenderLimits) -> Mesh3dRenderBudget {
544    generated_budget(count != 0, limits)
545}
546
547fn snapshot_render_budget(
548    snapshot: ThreeDSnapshot<'_>,
549    limits: ThreeDRenderLimits,
550) -> Mesh3dRenderBudget {
551    generated_budget(snapshot.source_triangle_count() != 0, limits).with_surface_policy(
552        match snapshot.view().surface_policy() {
553            ThreeDSurfacePolicy::StrictPortable => SurfaceRasterization3d::StrictPortable,
554            ThreeDSurfacePolicy::Native => SurfaceRasterization3d::Native,
555        },
556    )
557}
558
559fn generated_budget(has_objects: bool, limits: ThreeDRenderLimits) -> Mesh3dRenderBudget {
560    let defaults = Mesh3dRenderBudget::default();
561    let triangles = if !has_objects {
562        0
563    } else {
564        limits
565            .max_triangles()
566            .min(defaults.max_generated_triangles())
567    };
568    Mesh3dRenderBudget::new(
569        triangles
570            .saturating_mul(3)
571            .min(defaults.max_generated_vertices()),
572        triangles,
573        // Engine owns its generated vertex/edge layouts. Do not encode their
574        // private byte strides here; retain its explicit finite upload ceiling.
575        defaults.max_generated_upload_bytes(),
576    )
577    .with_max_surface_triangles(limits.max_triangles())
578}
579
580#[derive(Debug, Clone, Copy, PartialEq)]
581struct TargetDescriptor {
582    width: u32,
583    height: u32,
584    viewport: LogicalViewport,
585}
586
587struct TargetCache<T> {
588    entry: Option<(TargetDescriptor, T)>,
589}
590
591impl<T> TargetCache<T> {
592    const fn new() -> Self {
593        Self { entry: None }
594    }
595
596    fn clear(&mut self) {
597        self.entry = None;
598    }
599
600    fn get(&self) -> Option<&T> {
601        self.entry.as_ref().map(|(_, target)| target)
602    }
603
604    fn matches(&self, descriptor: TargetDescriptor) -> bool {
605        self.entry
606            .as_ref()
607            .is_some_and(|(key, _)| *key == descriptor)
608    }
609
610    fn ensure<E>(
611        &mut self,
612        descriptor: TargetDescriptor,
613        create: impl FnOnce() -> Result<T, E>,
614    ) -> Result<(), E> {
615        if self.matches(descriptor) {
616            return Ok(());
617        }
618        // Release obsolete resources before allocation, including failed resize.
619        self.clear();
620        self.entry = Some((descriptor, create()?));
621        Ok(())
622    }
623}
624
625fn check_limits(
626    count: usize,
627    width: u32,
628    height: u32,
629    limits: ThreeDRenderLimits,
630) -> Result<(), DesktopThreeDError> {
631    let triangles = (count as u64)
632        .checked_mul(12)
633        .ok_or(DesktopThreeDError::LimitExceeded {
634            resource: ThreeDLimitResource::Triangles,
635            requested: u64::MAX,
636            limit: limits.max_triangles() as u64,
637        })?;
638    for (resource, requested, limit) in [
639        (
640            ThreeDLimitResource::Cuboids,
641            count as u64,
642            limits.max_cuboids() as u64,
643        ),
644        (
645            ThreeDLimitResource::Triangles,
646            triangles,
647            limits.max_triangles() as u64,
648        ),
649        (
650            ThreeDLimitResource::TargetPixels,
651            u64::from(width) * u64::from(height),
652            limits.max_target_pixels(),
653        ),
654    ] {
655        if requested > limit {
656            return Err(DesktopThreeDError::LimitExceeded {
657                resource,
658                requested,
659                limit,
660            });
661        }
662    }
663    Ok(())
664}
665
666pub(super) fn color_target_bytes(renderer: &WgpuRenderer) -> Result<usize, DesktopThreeDError> {
667    let (width, height) = renderer.size();
668    let bytes_per_texel = renderer
669        .surface_format()
670        .block_copy_size(None)
671        .ok_or(DesktopThreeDError::InvalidTargetLayout)?;
672    let bytes = u64::from(width)
673        .checked_mul(u64::from(height))
674        .and_then(|pixels| pixels.checked_mul(u64::from(bytes_per_texel)))
675        .ok_or(DesktopThreeDError::InvalidTargetLayout)?;
676    usize::try_from(bytes).map_err(|_| DesktopThreeDError::InvalidTargetLayout)
677}
678
679fn reserved<T>(capacity: usize) -> Result<Vec<T>, DesktopThreeDError> {
680    let mut values = Vec::new();
681    values
682        .try_reserve_exact(capacity)
683        .map_err(|_| DesktopThreeDError::AllocationFailed {
684            requested_bytes: capacity.saturating_mul(size_of::<T>()),
685        })?;
686    Ok(values)
687}
688
689fn unit_cube() -> Result<Mesh3d, DesktopThreeDError> {
690    let mut vertices = reserved(8)?;
691    for [x, y, z] in CORNERS {
692        vertices.push(
693            Vec3::new(x, y, z)
694                .map_err(|error| DesktopThreeDError::View(View3dError::Geometry(error)))?,
695        );
696    }
697    let mut triangles = reserved(36)?;
698    triangles.extend_from_slice(&TRIANGLES);
699    let mut edges = reserved(12)?;
700    for (start, end) in [
701        (0, 1),
702        (1, 2),
703        (2, 3),
704        (3, 0),
705        (4, 5),
706        (5, 6),
707        (6, 7),
708        (7, 4),
709        (0, 4),
710        (1, 5),
711        (2, 6),
712        (3, 7),
713    ] {
714        edges.push(MeshEdge3d::new(start, end).map_err(DesktopThreeDError::Mesh)?);
715    }
716    Mesh3d::with_display_edges(vertices, triangles, edges).map_err(DesktopThreeDError::Mesh)
717}
718
719#[cfg(test)]
720mod tests {
721    use super::*;
722    use crate::identity::{ApplicationId, WorldGeneration};
723    use bevy_ecs::entity::Entity;
724    use sim_engine::{Color, Rotation3d, SurfaceStyle3d};
725
726    fn source(sequence: u64, row: u32) -> LogicEntity {
727        let application = ApplicationId::from_raw(1);
728        LogicEntity::new(
729            application,
730            WorldGeneration::new(application, sequence),
731            Entity::from_raw_u32(row).unwrap(),
732        )
733    }
734
735    fn applied_state() -> AppliedState {
736        AppliedState {
737            source: source(1, 0),
738            transform: Transform3d::IDENTITY,
739            style: MeshStyle3d::surface(SurfaceStyle3d::opaque(Color::WHITE).unwrap()),
740            visible: true,
741        }
742    }
743
744    fn changed_state() -> AppliedState {
745        AppliedState {
746            source: source(1, 0),
747            transform: Transform3d::new(
748                Vec3::new(1.0, 2.0, 3.0).unwrap(),
749                Rotation3d::IDENTITY,
750                Vec3::new(2.0, 1.0, 3.0).unwrap(),
751            )
752            .unwrap(),
753            style: MeshStyle3d::surface(SurfaceStyle3d::opaque(Color::BLACK).unwrap()),
754            visible: false,
755        }
756    }
757
758    #[test]
759    fn unchanged_slots_never_invoke_engine_setters() {
760        let mut states = [applied_state(); 64];
761        let mut desired = states;
762        for _ in 0..10 {
763            for (applied, desired) in states.iter_mut().zip(desired) {
764                applied
765                    .update(desired, |_| -> Result<(), ()> {
766                        panic!("unchanged cuboid must not perform an Engine lookup")
767                    })
768                    .unwrap();
769            }
770        }
771        desired[57] = AppliedState {
772            visible: true,
773            ..changed_state()
774        };
775        let mut changes = Vec::new();
776        for (index, (applied, desired)) in states.iter_mut().zip(desired).enumerate() {
777            applied
778                .update(desired, |change| -> Result<(), ()> {
779                    changes.push((index, change));
780                    Ok(())
781                })
782                .unwrap();
783        }
784        assert_eq!(
785            changes,
786            [
787                (57, SlotChange::Transform(desired[57].transform)),
788                (57, SlotChange::Style(desired[57].style)),
789            ]
790        );
791        assert_eq!(states, desired);
792    }
793
794    #[test]
795    fn diff_policy_updates_only_each_changed_field() {
796        let initial = applied_state();
797        let changed = changed_state();
798        for (desired, expected) in [
799            (
800                AppliedState {
801                    transform: changed.transform,
802                    ..initial
803                },
804                SlotChange::Transform(changed.transform),
805            ),
806            (
807                AppliedState {
808                    style: changed.style,
809                    ..initial
810                },
811                SlotChange::Style(changed.style),
812            ),
813            (
814                AppliedState {
815                    visible: false,
816                    ..initial
817                },
818                SlotChange::Visible(false),
819            ),
820        ] {
821            let mut applied = initial;
822            let mut changes = Vec::new();
823            applied
824                .update(desired, |change| -> Result<(), ()> {
825                    changes.push(change);
826                    Ok(())
827                })
828                .unwrap();
829            assert_eq!(changes, [expected]);
830            assert_eq!(applied, desired);
831        }
832    }
833
834    #[test]
835    fn hidden_slots_change_visibility_only_once_then_reactivate() {
836        let initial = applied_state();
837        let hidden = AppliedState {
838            visible: false,
839            ..initial
840        };
841        let mut applied = initial;
842        let mut changes = Vec::new();
843        for desired in [hidden, hidden, hidden, initial, initial] {
844            applied
845                .update(desired, |change| -> Result<(), ()> {
846                    changes.push(change);
847                    Ok(())
848                })
849                .unwrap();
850        }
851        assert_eq!(
852            changes,
853            [SlotChange::Visible(false), SlotChange::Visible(true)]
854        );
855        assert_eq!(applied, initial);
856    }
857
858    #[test]
859    fn partial_failure_records_only_successful_updates_and_retries_the_rest() {
860        let initial = applied_state();
861        let desired = changed_state();
862        let ordered = [
863            SlotChange::Transform(desired.transform),
864            SlotChange::Style(desired.style),
865            SlotChange::Visible(desired.visible),
866        ];
867        for failure_index in 0..ordered.len() {
868            let mut applied = initial;
869            let mut attempted = Vec::new();
870            let failed = applied.update(desired, |change| {
871                attempted.push(change);
872                if change == ordered[failure_index] {
873                    Err("setter failed")
874                } else {
875                    Ok(())
876                }
877            });
878            assert_eq!(failed, Err("setter failed"));
879            assert_eq!(attempted, ordered[..=failure_index]);
880            assert_eq!(
881                applied.transform,
882                if failure_index > 0 {
883                    desired.transform
884                } else {
885                    initial.transform
886                }
887            );
888            assert_eq!(
889                applied.style,
890                if failure_index > 1 {
891                    desired.style
892                } else {
893                    initial.style
894                }
895            );
896            assert_eq!(applied.visible, initial.visible);
897            attempted.clear();
898            applied
899                .update(desired, |change| -> Result<(), ()> {
900                    attempted.push(change);
901                    Ok(())
902                })
903                .unwrap();
904            assert_eq!(attempted, ordered[failure_index..]);
905            assert_eq!(applied, desired);
906        }
907    }
908
909    #[test]
910    fn retained_cube_has_exact_solid_and_outline_topology() {
911        let mesh = unit_cube().unwrap();
912        assert_eq!(mesh.vertices().len(), 8);
913        assert_eq!(mesh.triangle_count(), 12);
914        assert_eq!(mesh.display_edges().len(), 12);
915    }
916
917    #[test]
918    fn independent_prepass_limits_reject_before_gpu_work() {
919        let limits = ThreeDRenderLimits::new(2, 24, 640 * 360);
920        assert!(check_limits(2, 640, 360, limits).is_ok());
921        assert!(matches!(
922            check_limits(3, 640, 360, limits),
923            Err(DesktopThreeDError::LimitExceeded {
924                resource: ThreeDLimitResource::Cuboids,
925                ..
926            })
927        ));
928        assert!(matches!(
929            check_limits(2, 1280, 720, limits),
930            Err(DesktopThreeDError::LimitExceeded {
931                resource: ThreeDLimitResource::TargetPixels,
932                ..
933            })
934        ));
935        assert!(matches!(
936            check_limits(2, 640, 360, ThreeDRenderLimits::new(2, 23, 640 * 360)),
937            Err(DesktopThreeDError::LimitExceeded {
938                resource: ThreeDLimitResource::Triangles,
939                ..
940            })
941        ));
942        assert!(
943            check_limits(
944                0,
945                u32::MAX,
946                u32::MAX,
947                ThreeDRenderLimits::new(0, 0, u64::MAX)
948            )
949            .is_ok()
950        );
951    }
952
953    #[test]
954    fn cache_invalidation_discards_all_renderer_bound_resources() {
955        let mut cache = DesktopThreeD::new();
956        assert_eq!(cache.slots.capacity(), 0);
957        cache.clear();
958        assert!(cache.mesh.is_none());
959        assert!(cache.scene.is_none());
960        assert!(cache.target.get().is_none());
961        assert!(cache.slots.is_empty());
962    }
963
964    #[test]
965    fn target_cache_reuses_then_recreates_after_resize_scale_or_recovery() {
966        let initial = TargetDescriptor {
967            width: 1280,
968            height: 720,
969            viewport: LogicalViewport::new(1280.0, 720.0).unwrap(),
970        };
971        let scaled = TargetDescriptor {
972            viewport: LogicalViewport::new(640.0, 360.0).unwrap(),
973            ..initial
974        };
975        let resized = TargetDescriptor {
976            width: 960,
977            height: 540,
978            viewport: LogicalViewport::new(960.0, 540.0).unwrap(),
979        };
980        let mut cache = TargetCache::new();
981        let mut calls = 0;
982        for descriptor in [initial, initial, scaled, scaled, resized] {
983            cache
984                .ensure(descriptor, || -> Result<usize, ()> {
985                    calls += 1;
986                    Ok(calls)
987                })
988                .unwrap();
989        }
990        assert_eq!(calls, 3);
991        assert_eq!(cache.get(), Some(&3));
992        cache.clear();
993        assert!(cache.get().is_none());
994        cache
995            .ensure(resized, || -> Result<usize, ()> {
996                calls += 1;
997                Ok(calls)
998            })
999            .unwrap();
1000        assert_eq!(calls, 4);
1001        let failed = cache.ensure(initial, || -> Result<usize, &'static str> {
1002            Err("target allocation")
1003        });
1004        assert_eq!(failed, Err("target allocation"));
1005        assert!(cache.get().is_none());
1006    }
1007}
1008
1009#[cfg(test)]
1010#[path = "three_d/migration_tests.rs"]
1011mod migration_tests;
1012
1013#[cfg(all(test, target_os = "linux"))]
1014#[path = "three_d/gpu_tests.rs"]
1015mod gpu_tests;