Skip to main content

sim_engine/renderer/mesh3d/
api.rs

1//! Public renderer entry points for retained 3D resources and frames.
2
3use super::{
4    Arc, Camera3d, LogicalViewport, Mesh3d, Mesh3dPreflightReport, Mesh3dRenderBudget,
5    Mesh3dRenderError, Mesh3dRenderReport, Mesh3dResourceError, RenderTarget3d, RetainedMesh3d,
6    Scene3d, Scene3dRestoreReport, WgpuRenderer, create_depth_texture, create_retained_mesh,
7    restore_retained_mesh, restore_scene3d_resources, target_pixels_per_logical,
8};
9
10impl WgpuRenderer {
11    /// Uploads validated immutable topology into retained GPU buffers.
12    ///
13    /// Counts, byte arithmetic, draw-count representation, and active-device
14    /// buffer limits are checked before conversion staging allocation. Host
15    /// staging reservation failure is returned explicitly; GPU allocation
16    /// itself follows wgpu's device-error model.
17    pub fn create_mesh3d(&self, source: Mesh3d) -> Result<RetainedMesh3d, Mesh3dResourceError> {
18        create_retained_mesh(
19            &self.device,
20            &self.queue,
21            Arc::clone(&self.renderer_identity),
22            source,
23        )
24    }
25
26    /// Restores retained topology and its complete optional texture material
27    /// onto this renderer after device replacement. Attribute/reserved buffer
28    /// capacities, committed mip bytes/options, filtering, tint, UV transform,
29    /// addressing and opaque/alpha-capable rebinding policy are preserved.
30    /// Source handles remain unchanged. Separate calls restore separate GPU
31    /// resources; use `restore_scene3d` to deduplicate shared scene resources.
32    pub fn restore_mesh3d(
33        &self,
34        source: &RetainedMesh3d,
35    ) -> Result<RetainedMesh3d, Mesh3dResourceError> {
36        restore_retained_mesh(
37            &self.device,
38            &self.queue,
39            Arc::clone(&self.renderer_identity),
40            &self.mesh3d_renderer.textures.layout,
41            source,
42        )
43    }
44
45    /// Atomically restores every stale retained mesh referenced by a 3D scene.
46    ///
47    /// Distinct shared mesh and texture resources are uploaded once. Per-handle
48    /// texture/filter/tint choices remain independent when topology is shared.
49    /// Object IDs, insertion
50    /// order, transforms, styles, visibility, scene provenance, and the next ID
51    /// remain unchanged. If any capacity or host-staging allocation fails, the
52    /// original scene is not modified. Targets remain separate resources and
53    /// must be restored with [`WgpuRenderer::restore_render_target3d`].
54    pub fn restore_scene3d(
55        &self,
56        scene: &mut Scene3d,
57    ) -> Result<Scene3dRestoreReport, Mesh3dResourceError> {
58        restore_scene3d_resources(
59            &self.device,
60            &self.queue,
61            &self.mesh3d_renderer.textures.layout,
62            Arc::clone(&self.renderer_identity),
63            scene,
64        )
65    }
66
67    /// Creates color/depth attachments for an explicit logical viewport.
68    ///
69    /// `width` and `height` are physical target texels. Their aspect must match
70    /// `logical_viewport`; the resulting texels-per-logical-pixel ratio controls
71    /// wireframe width independently of the window DPI scale.
72    pub fn create_render_target3d(
73        &self,
74        width: u32,
75        height: u32,
76        logical_viewport: LogicalViewport,
77    ) -> Result<RenderTarget3d, Mesh3dResourceError> {
78        let pixels_per_logical = target_pixels_per_logical(width, height, logical_viewport)
79            .ok_or(Mesh3dResourceError::InvalidViewportAspect)?;
80        let color = self
81            .create_render_target(width, height)
82            .map_err(Mesh3dResourceError::Target)?;
83        let depth_texture = create_depth_texture(&self.device, width, height);
84        let depth_view = depth_texture.create_view(&wgpu::TextureViewDescriptor::default());
85        Ok(RenderTarget3d {
86            renderer_identity: Arc::clone(&self.renderer_identity),
87            color,
88            _depth_texture: depth_texture,
89            depth_view,
90            logical_viewport,
91            pixels_per_logical,
92        })
93    }
94
95    /// Restores empty color/depth attachments with the source dimensions.
96    pub fn restore_render_target3d(
97        &self,
98        source: &RenderTarget3d,
99    ) -> Result<RenderTarget3d, Mesh3dResourceError> {
100        self.create_render_target3d(source.width(), source.height(), source.logical_viewport())
101    }
102
103    /// Draws retained opaque/masked surfaces, sorted blended surfaces, then edges
104    /// into a reusable premultiplied color/depth target.
105    ///
106    /// Object insertion order does not determine visibility. Every surface
107    /// writes and tests hardware depth. Model transforms are uploaded through a
108    /// reusable instance buffer. Wholly inside objects retain their indexed
109    /// topology; crossing surfaces use bounded homogeneous CPU clipping against
110    /// all six frustum planes. Ambiguous classification/orientation produces an
111    /// object-attributed error. Explicit display edges retain their complete
112    /// interval-validated homogeneous shader clipper.
113    pub fn render_scene3d_to_target(
114        &mut self,
115        target: &RenderTarget3d,
116        scene: &Scene3d,
117        camera: Camera3d,
118    ) -> Result<Mesh3dRenderReport, Mesh3dRenderError> {
119        self.render_scene3d_to_target_with_budget(
120            target,
121            scene,
122            camera,
123            Mesh3dRenderBudget::default(),
124        )
125    }
126
127    /// Validates every visible object and exact submitted/generated work without
128    /// changing target pixels, retained resources or submitting GPU work.
129    ///
130    /// This is the same authoritative preflight used by rendering. Private
131    /// bounded scratch may be allocated; the report is not a reusable draw
132    /// authorization after the scene, target or camera changes.
133    /// [`Mesh3dRenderBudget::surface_policy`] controls filled surfaces only.
134    /// Native mode reports no CPU clipped/discarded source counts.
135    pub fn validate_scene3d_for_target(
136        &self,
137        target: &RenderTarget3d,
138        scene: &Scene3d,
139        camera: Camera3d,
140        budget: Mesh3dRenderBudget,
141    ) -> Result<Mesh3dPreflightReport, Mesh3dRenderError> {
142        self.mesh3d_renderer
143            .preflight_scene3d(
144                &self.device,
145                &self.renderer_identity,
146                target,
147                scene,
148                camera,
149                budget,
150            )
151            .map(|(_, frame)| frame.report)
152    }
153
154    /// Draws a scene with explicit surface policy and submitted/generated limits.
155    ///
156    /// All validation, generated counts and host/GPU capacity checks complete
157    /// before the first GPU write or target mutation. Numerical ambiguity is
158    /// attributed to the exact visible object; aggregate capacity remains a
159    /// scene-level error. Wholly inside objects retain their indexed GPU path.
160    /// With [`SurfaceRasterization3d::Native`](crate::SurfaceRasterization3d::Native), all filled surfaces keep their
161    /// original indices and hardware clipping defines boundary coverage. Finite
162    /// shader arithmetic and independent mathematical-edge proofs still apply.
163    pub fn render_scene3d_to_target_with_budget(
164        &mut self,
165        target: &RenderTarget3d,
166        scene: &Scene3d,
167        camera: Camera3d,
168        budget: Mesh3dRenderBudget,
169    ) -> Result<Mesh3dRenderReport, Mesh3dRenderError> {
170        self.mesh3d_renderer.render_scene3d_with_timing(
171            &self.device,
172            &self.queue,
173            &self.renderer_identity,
174            target,
175            scene,
176            camera,
177            budget,
178            Some(&mut self.gpu_timing),
179        )
180    }
181}