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}