Skip to main content

qualia_core_db/render/gpu/
mod.rs

1//! Cross-platform WebGPU viewport for the Qualia renderer SDK.
2//!
3//! Phenomenal viewport: projector (depth write) → ambient → optional T2 Kawase bloom.
4
5mod ao;
6mod atmosphere;
7mod instance_stream;
8mod instance_visibility;
9mod material_draws;
10mod material_textures;
11mod materials;
12mod picking;
13pub use instance_stream::MeshInstanceUploadError;
14mod texture_precomputed;
15mod texture_residency;
16pub use temporal_resolve_gpu::{
17    TemporalProducerAvailability, TemporalProducerViews, TemporalResolveGpu, TemporalResolveInputs,
18    TemporalSubmissionState,
19};
20pub use texture_mips::AlphaCoverageDiagnostics;
21pub use texture_mips::TextureMipSemantic;
22pub use texture_residency::{TextureColorSpace, TextureUploadError};
23mod animated_upload;
24pub mod holographic;
25mod source_frame;
26pub use holographic::{HolographicNodeGpu, HolographicPipelineGpu, HolographicPrimitive};
27pub mod ibl_cubemap;
28pub use ibl_cubemap::{
29    cubemap_face_uv_to_direction, eval_procedural_sky_radiance_zero_heap,
30    integrate_split_sum_brdf_zero_heap, IblCubemapGenerator, IblCubemapParams,
31    IBL_CUBEMAP_CONVOLVE_WGSL,
32};
33pub mod indirect_cull;
34pub use indirect_cull::{
35    build_hzb_mip_chain_zero_heap, cull_and_select_lod_indirect_zero_heap,
36    select_lod_tier_with_hysteresis, CullUniformsGpu, DrawIndexedIndirectCommand, HzbPyramidView,
37    IndirectCullPipelineGpu, IndirectCullStreamCounts, InstanceCullDescriptor,
38    RepresentationPolicy,
39};
40pub mod mesh_slab;
41pub use mesh_slab::{
42    AssetRepresentationKind, MeshSlabArenaDescriptor, MeshSlabArenaGpu, MeshSlabVertex,
43    ProceduralSynthesisGpu, ResidentAssetEntry, SkinAttrVertex, SlabRange, SlabRangeAllocator,
44    SubmeshSlice,
45};
46pub use portal_gpu::lighting_passes::{
47    ClusterGridParamsGpu, ClusterLightPipelineGpu, DeferredSpectralResolvePipelineGpu,
48    DielectricVolumeIopGpu, FoliageLodPipelineGpu,
49};
50pub use shadows::{
51    camera_csm_4_sun_view_projections, compute_csm_4_splits_zero_heap, csm_cascade_blend_factor,
52    Csm4ShadowUniform, ShadowAtlasAllocator, SpotPointShadowAtlasSlot, CSM_4_CASCADE_COUNT,
53};
54pub mod emf_cue_bridge;
55pub mod frame_lock;
56mod mesh_normals;
57mod mesh_upload;
58mod output_pass;
59pub mod residency_budget;
60mod scene_depth;
61mod shadows;
62mod sky;
63mod temporal_producers_gpu;
64mod temporal_resolve_gpu;
65mod texture_mips;
66mod water;
67pub use frame_lock::*;
68
69use crate::gpu_context::{
70    ambient_draw_instances, global_vram_ledger, universe_orchestrator, ComputeUniverse,
71    OperationalMode,
72};
73use crate::render::camera::CameraState;
74use crate::render::pga::{motor_to_mat4_col, Motor};
75use crate::render::physics::{Aabb, Joint};
76use crate::render::telemetry::{
77    AmbientUniforms, CameraUniform, ObserverStandpoint, ParticleInstance, SystemTelemetry,
78};
79use crate::tensor::buffer_export::{read_tensor_at, tensor_node_count, TENSOR_STRIDE};
80
81use std::sync::Arc;
82
83#[cfg(all(target_arch = "wasm32", feature = "portal"))]
84thread_local! {
85    static PORTAL_GPU_INIT_ABORTED: std::cell::Cell<bool> = std::cell::Cell::new(false);
86    static PORTAL_GPU_CANVAS_CLAIMED: std::cell::Cell<bool> = std::cell::Cell::new(false);
87}
88
89#[cfg(all(target_arch = "wasm32", feature = "portal"))]
90/// Resets portal-GPU init flags.
91pub(crate) fn reset_portal_gpu_init_flags() {
92    PORTAL_GPU_INIT_ABORTED.with(|c| c.set(false));
93    PORTAL_GPU_CANVAS_CLAIMED.with(|c| c.set(false));
94}
95
96#[cfg(all(target_arch = "wasm32", feature = "portal"))]
97/// Aborts portal-GPU init.
98pub(crate) fn abort_portal_gpu_init() {
99    PORTAL_GPU_INIT_ABORTED.with(|c| c.set(true));
100}
101
102#[cfg(all(target_arch = "wasm32", feature = "portal"))]
103/// `true` when init was aborted.
104pub(crate) fn portal_gpu_init_aborted() -> bool {
105    PORTAL_GPU_INIT_ABORTED.with(|c| c.get())
106}
107
108#[cfg(all(target_arch = "wasm32", feature = "portal"))]
109/// `true` when the canvas is claimed.
110pub(crate) fn portal_gpu_canvas_claimed() -> bool {
111    PORTAL_GPU_CANVAS_CLAIMED.with(|c| c.get())
112}
113
114#[cfg(all(target_arch = "wasm32", feature = "portal"))]
115/// Marks the canvas claimed.
116pub(crate) fn mark_portal_gpu_canvas_claimed() {
117    PORTAL_GPU_CANVAS_CLAIMED.with(|c| c.set(true));
118}
119
120/// Static ambient SSBO capacity — draw count is throttled per `VramLedger` mode.
121const MAX_AMBIENT_INSTANCES: usize = 50_000;
122
123/// Creates `ao-prepass-camera-layout`.
124pub(super) fn create_ao_prepass_camera_layout(device: &etalon::Device) -> etalon::BindGroupLayout {
125    device.create_bind_group_layout(&etalon::BindGroupLayoutDescriptor {
126        label: Some("qualia-ao-prepass-camera-layout"),
127        entries: &[
128            uniform_128_bind_entry(0, etalon::ShaderStages::VERTEX_FRAGMENT),
129            uniform_128_bind_entry(1, etalon::ShaderStages::VERTEX_FRAGMENT),
130            etalon::BindGroupLayoutEntry {
131                binding: 2,
132                visibility: etalon::ShaderStages::FRAGMENT,
133                ty: etalon::BindingType::Buffer {
134                    ty: etalon::BufferBindingType::Uniform,
135                    has_dynamic_offset: false,
136                    min_binding_size: std::num::NonZeroU64::new(
137                        std::mem::size_of::<ao::AoUniform>() as u64,
138                    ),
139                },
140                count: None,
141            },
142        ],
143    })
144}
145
146/// Creates `ao-prepass-camera-bind`.
147pub(super) fn create_ao_prepass_camera_bind(
148    device: &etalon::Device,
149    layout: &etalon::BindGroupLayout,
150    camera: &etalon::Buffer,
151    observer: &etalon::Buffer,
152    ao: &etalon::Buffer,
153) -> etalon::BindGroup {
154    device.create_bind_group(&etalon::BindGroupDescriptor {
155        label: Some("qualia-ao-prepass-camera-and-uniform"),
156        layout,
157        entries: &[
158            etalon::BindGroupEntry {
159                binding: 0,
160                resource: camera.as_entire_binding(),
161            },
162            etalon::BindGroupEntry {
163                binding: 1,
164                resource: observer.as_entire_binding(),
165            },
166            etalon::BindGroupEntry {
167                binding: 2,
168                resource: ao.as_entire_binding(),
169            },
170        ],
171    })
172}
173
174/// Creates `mesh-frame-layout`.
175pub(super) fn create_mesh_frame_layout(device: &etalon::Device) -> etalon::BindGroupLayout {
176    let uniform_entry = |binding, visibility, size| etalon::BindGroupLayoutEntry {
177        binding,
178        visibility,
179        ty: etalon::BindingType::Buffer {
180            ty: etalon::BufferBindingType::Uniform,
181            has_dynamic_offset: false,
182            min_binding_size: std::num::NonZeroU64::new(size),
183        },
184        count: None,
185    };
186    let depth_texture_entry = |binding| etalon::BindGroupLayoutEntry {
187        binding,
188        visibility: etalon::ShaderStages::FRAGMENT,
189        ty: etalon::BindingType::Texture {
190            sample_type: etalon::TextureSampleType::Depth,
191            view_dimension: etalon::TextureViewDimension::D2,
192            multisampled: false,
193        },
194        count: None,
195    };
196    let float_texture_entry = |binding| etalon::BindGroupLayoutEntry {
197        binding,
198        visibility: etalon::ShaderStages::FRAGMENT,
199        ty: etalon::BindingType::Texture {
200            sample_type: etalon::TextureSampleType::Float { filterable: false },
201            view_dimension: etalon::TextureViewDimension::D2,
202            multisampled: false,
203        },
204        count: None,
205    };
206    let entries = [
207        uniform_128_bind_entry(0, etalon::ShaderStages::VERTEX_FRAGMENT),
208        uniform_128_bind_entry(1, etalon::ShaderStages::VERTEX_FRAGMENT),
209        depth_texture_entry(2),
210        depth_texture_entry(3),
211        etalon::BindGroupLayoutEntry {
212            binding: 4,
213            visibility: etalon::ShaderStages::FRAGMENT,
214            ty: etalon::BindingType::Sampler(etalon::SamplerBindingType::Comparison),
215            count: None,
216        },
217        uniform_entry(
218            5,
219            etalon::ShaderStages::VERTEX_FRAGMENT,
220            std::mem::size_of::<shadows::ShadowUniform>() as u64,
221        ),
222        float_texture_entry(6),
223        float_texture_entry(7),
224        uniform_entry(
225            8,
226            etalon::ShaderStages::FRAGMENT,
227            std::mem::size_of::<ao::AoUniform>() as u64,
228        ),
229        uniform_entry(
230            9,
231            etalon::ShaderStages::FRAGMENT,
232            std::mem::size_of::<atmosphere::AtmosphereUniform>() as u64,
233        ),
234    ];
235    device.create_bind_group_layout(&etalon::BindGroupLayoutDescriptor {
236        label: Some("portal-mesh-frame-lighting-layout"),
237        entries: &entries,
238    })
239}
240
241#[allow(clippy::too_many_arguments)]
242/// Creates `mesh-frame-bind`.
243pub(super) fn create_mesh_frame_bind(
244    device: &etalon::Device,
245    layout: &etalon::BindGroupLayout,
246    camera: &etalon::Buffer,
247    observer: &etalon::Buffer,
248    shadow_views: [&etalon::TextureView; 2],
249    shadow_sampler: &etalon::Sampler,
250    shadow_uniform: &etalon::Buffer,
251    ao_view: &etalon::TextureView,
252    ao_surface_view: &etalon::TextureView,
253    ao_uniform: &etalon::Buffer,
254    atmosphere_uniform: &etalon::Buffer,
255) -> etalon::BindGroup {
256    device.create_bind_group(&etalon::BindGroupDescriptor {
257        label: Some("portal-mesh-frame-lighting-bind"),
258        layout,
259        entries: &[
260            etalon::BindGroupEntry {
261                binding: 0,
262                resource: camera.as_entire_binding(),
263            },
264            etalon::BindGroupEntry {
265                binding: 1,
266                resource: observer.as_entire_binding(),
267            },
268            etalon::BindGroupEntry {
269                binding: 2,
270                resource: etalon::BindingResource::TextureView(shadow_views[0]),
271            },
272            etalon::BindGroupEntry {
273                binding: 3,
274                resource: etalon::BindingResource::TextureView(shadow_views[1]),
275            },
276            etalon::BindGroupEntry {
277                binding: 4,
278                resource: etalon::BindingResource::Sampler(shadow_sampler),
279            },
280            etalon::BindGroupEntry {
281                binding: 5,
282                resource: shadow_uniform.as_entire_binding(),
283            },
284            etalon::BindGroupEntry {
285                binding: 6,
286                resource: etalon::BindingResource::TextureView(ao_view),
287            },
288            etalon::BindGroupEntry {
289                binding: 7,
290                resource: etalon::BindingResource::TextureView(ao_surface_view),
291            },
292            etalon::BindGroupEntry {
293                binding: 8,
294                resource: ao_uniform.as_entire_binding(),
295            },
296            etalon::BindGroupEntry {
297                binding: 9,
298                resource: atmosphere_uniform.as_entire_binding(),
299            },
300        ],
301    })
302}
303
304/// `portal_fixed_buffer_bytes`.
305pub(super) fn portal_fixed_buffer_bytes() -> Option<u64> {
306    [
307        std::mem::size_of::<AmbientUniforms>(),
308        std::mem::size_of::<SystemTelemetry>(),
309        std::mem::size_of::<CameraUniform>(),
310        std::mem::size_of::<ObserverStandpoint>(),
311        std::mem::size_of::<[[f32; 4]; 4]>(),
312        std::mem::size_of::<shadows::ShadowUniform>(),
313        std::mem::size_of::<ao::AoUniform>(),
314    ]
315    .into_iter()
316    .try_fold(0u64, |total, size| total.checked_add(size as u64))
317}
318const HDR_FORMAT: etalon::TextureFormat = etalon::TextureFormat::Rgba16Float;
319type BloomChain = etalon_render::bloom::BloomChain<crate::gpu_context::VramReservation<'static>>;
320/// WebGPU phenomenal viewport — tensor projector + ambient particles.
321/// GPU buffers for an imported triangle mesh (Phase 1.2). Positions are model-space `f32x3`
322/// (already centred + scaled to the orbit frame by the caller); `index_count` is `triangles * 3`.
323struct MeshGpu {
324    buffers: etalon_render::mesh::MeshBuffers<crate::gpu_context::VramReservation<'static>>,
325    material_gpu: materials::MaterialGpu,
326    shadow_draws: Vec<materials::MaterialDraw>,
327    receives_shadows: bool,
328    // Cold-path source geometry retained so pose updates can refresh normals
329    // without allocating or reading back the GPU buffers.
330    cpu_positions: Vec<[f32; 3]>,
331    cpu_indices: Vec<u32>,
332    normal_workspace: mesh_normals::MeshNormalWorkspace,
333}
334
335impl std::ops::Deref for MeshGpu {
336    type Target = etalon_render::mesh::MeshBuffers<crate::gpu_context::VramReservation<'static>>;
337    fn deref(&self) -> &Self::Target {
338        &self.buffers
339    }
340}
341
342fn default_gpu_tangent(normal: [f32; 3]) -> [f32; 4] {
343    let axis = if normal[0].abs() < 0.8 {
344        [1.0, 0.0, 0.0]
345    } else {
346        [0.0, 1.0, 0.0]
347    };
348    let cross = [
349        normal[1] * axis[2] - normal[2] * axis[1],
350        normal[2] * axis[0] - normal[0] * axis[2],
351        normal[0] * axis[1] - normal[1] * axis[0],
352    ];
353    let length = (cross[0] * cross[0] + cross[1] * cross[1] + cross[2] * cross[2]).sqrt();
354    if length > f32::EPSILON {
355        [cross[0] / length, cross[1] / length, cross[2] / length, 1.0]
356    } else {
357        [1.0, 0.0, 0.0, 1.0]
358    }
359}
360
361pub struct PortalGpu {
362    device: Arc<etalon::Device>,
363    queue: Arc<etalon::Queue>,
364    device_lost: Arc<std::sync::atomic::AtomicBool>,
365    surface: Option<etalon::Surface<'static>>,
366    config: Option<etalon::SurfaceConfiguration>,
367    offscreen_texture: Option<etalon::Texture>,
368    /// Cached view of the offscreen texture — avoids `create_view` per frame.
369    /// Invalidated (set to `None`) when the texture is recreated (resize).
370    offscreen_view: Option<etalon::TextureView>,
371    readback_buf: Option<etalon::Buffer>,
372    readback_bytes_per_row: u32,
373    _readback_staging_reservation: Option<crate::gpu_context::VramReservation<'static>>,
374    color_format: etalon::TextureFormat,
375    scene_depth: scene_depth::SceneDepthOwner,
376    temporal_resolve: Option<temporal_resolve_gpu::TemporalResolveGpu>,
377    temporal_producers: Option<temporal_producers_gpu::TemporalProducersGpu>,
378    temporal_reset_pending: bool,
379    previous_camera_view_projection: Option<crate::render::temporal_producers::Mat4ColumnMajor>,
380    picking_texture: etalon::Texture,
381    picking_view: etalon::TextureView,
382    _frame_target_reservation: crate::gpu_context::VramReservation<'static>,
383    _fixed_buffer_reservation: crate::gpu_context::VramReservation<'static>,
384    picking_pipeline: etalon::RenderPipeline,
385    mesh_picking_pipeline: etalon::RenderPipeline,
386    pick_readback: etalon_render::picking_readback::PickingReadback<
387        crate::gpu_context::VramReservation<'static>,
388    >,
389    pick_semantic_result: Option<u64>,
390    ambient_pipeline: etalon::RenderPipeline,
391    projector_pipeline: etalon::RenderPipeline,
392    sky_pipeline: etalon::RenderPipeline,
393    ambient_pipeline_hdr: Option<etalon::RenderPipeline>,
394    projector_pipeline_hdr: Option<etalon::RenderPipeline>,
395    sky_pipeline_hdr: Option<etalon::RenderPipeline>,
396    mesh_pipeline: etalon::RenderPipeline,
397    mesh_pipeline_blend: etalon::RenderPipeline,
398    mesh_pipeline_hdr: Option<etalon::RenderPipeline>,
399    mesh_pipeline_hdr_blend: Option<etalon::RenderPipeline>,
400    mesh_material_layout: etalon::BindGroupLayout,
401    mesh_texture_layout: etalon::BindGroupLayout,
402    mesh_frame_layout: etalon::BindGroupLayout,
403    mesh_frame_bind: etalon::BindGroup,
404    ao_prepass_camera_layout: etalon::BindGroupLayout,
405    ao_prepass_camera_bind: etalon::BindGroup,
406    shadow_target: Option<shadows::ShadowTarget>,
407    shadow_enabled: bool,
408    shadow_map_dirty: bool,
409    shadow_uniform_buf: etalon::Buffer,
410    shadow_uniform_bind: etalon::BindGroup,
411    shadow_sampler: etalon::Sampler,
412    shadow_uniform_cpu: shadows::ShadowUniform,
413    shadow_pipelines: [etalon::RenderPipeline; shadows::SHADOW_CASCADE_COUNT],
414    mesh_model_layout: etalon::BindGroupLayout,
415    mesh_instance_layout: etalon::BindGroupLayout,
416    /// Complete source stream retained for shadow-caster correctness.
417    mesh_instances: instance_stream::GpuInstanceStream,
418    /// Camera-visible compact stream used by the forward and AO passes.
419    visible_mesh_instances: instance_stream::GpuInstanceStream,
420    /// Bounded CPU-side source/scratch storage. These vectors are allocated at renderer creation;
421    /// camera-driven culling and compaction reuse them without frame-time heap growth.
422    mesh_instance_source: Vec<crate::render::instance_culling::GpuInstanceRecord>,
423    visible_instance_indices: Vec<u32>,
424    visible_instance_scratch: Vec<crate::render::instance_culling::GpuInstanceRecord>,
425    last_visibility_key: Option<([[f32; 4]; 4], [[f32; 4]; 4])>,
426    ao_targets: Option<ao::AoTargets>,
427    ao_uniform_buf: etalon::Buffer,
428    atmosphere_uniform_buf: etalon::Buffer,
429    ao_enabled: bool,
430    ao_radius: f32,
431    ao_strength: f32,
432    ao_bias: f32,
433    ao_sample_count: u32,
434    material_texture_defaults: material_textures::MaterialTextureDefaults,
435    mip_generator: texture_mips::MipGenerator,
436    resident_textures: texture_residency::ResidentTextureMap,
437    mesh: Option<MeshGpu>,
438    mesh_generation: u64,
439    source_motion: crate::render::source_frame::SourceFrameState,
440    water: water::WaterGpu,
441    model_buf: etalon::Buffer,
442    mesh_model_bind: etalon::BindGroup,
443    artefact_joint: Option<Joint>,
444    /// Sim-time at which the current joint was engaged; the joint is driven by *elapsed* time
445    /// (`time − artefact_t0`), not absolute sim-time, so a slide/spin always starts from rest when
446    /// armed (set lazily on the first frame after `set_artefact_joint`).
447    artefact_t0: Option<f32>,
448    mesh_base_aabb: Option<Aabb>,
449    artefact_world: Option<Aabb>,
450    last_admitted: Motor,
451    last_refused: bool,
452    bloom: Option<BloomChain>,
453    output_chain: Option<output_pass::OutputChain>,
454    bloom_policy_snapshot: bool,
455    hdr_exposure_ev: f32,
456    white_balance_gains: [f32; 3],
457    ambient_bind_group_layout: etalon::BindGroupLayout,
458    ambient_bind_group: etalon::BindGroup,
459    projector_tensor_layout: etalon::BindGroupLayout,
460    projector_camera_layout: etalon::BindGroupLayout,
461    projector_camera_bind: etalon::BindGroup,
462    projector_tensor_bind: Option<etalon::BindGroup>,
463    holographic: Option<portal_gpu::holograph::RdfHolographGpu>,
464    uniform_buf: etalon::Buffer,
465    telemetry_buf: etalon::Buffer,
466    camera_buf: etalon::Buffer,
467    observer_buf: etalon::Buffer,
468    camera: CameraState,
469    observer: ObserverStandpoint,
470    particle_buf: etalon::Buffer,
471    _particle_reservation: crate::gpu_context::VramReservation<'static>,
472    tensor_raw_buf: Option<etalon::Buffer>,
473    _tensor_field_reservation: Option<crate::gpu_context::VramReservation<'static>>,
474    tensor_node_count: u32,
475    /// Whether semantic Tensor10D nodes are projected as visible sprites.
476    /// The tensor remains resident for picking when this is false.
477    tensor_projection_enabled: bool,
478    particle_count: u32,
479    /// Whether the ambient particle field is drawn. **Off by default** and opt-in: the field is
480    /// the tensor-node particle cloud (`generate_particles` / uploaded tensor); the mixer's
481    /// "ambient" channel (or an explicit `set_ambient_enabled(true)`) turns it on. A Tensor10D
482    /// upload never forces it — hosts that want the particle view enable it explicitly.
483    ambient_enabled: bool,
484    /// WebGPU compute dispatch state: pipeline cache + pending readback slot
485    /// (plan §7.3 W6 — `Render.gpu_compute_dispatch` / `Render.gpu_compute_readback`).
486    compute: compute::ComputeState,
487    /// EMF 5D volumetric visualizer state (plan §7.3 W4).
488    emf: emf_pipeline::EmfState,
489    /// Pre-allocated uniform belt for zero-alloc buffer writes (VC3).
490    /// Replaces per-frame `queue.write_buffer` calls (which each allocate
491    /// a temporary staging buffer) with writes into a pre-mapped ring of
492    /// staging buffers. Pool size 3 ensures the oldest buffer's copy has
493    /// completed by the time we wrap around.
494    uniform_belt: uniform_belt::UniformBelt,
495    width: u32,
496    height: u32,
497    clear_color: [f64; 4],
498    sky_enabled: bool,
499}
500
501impl PortalGpu {
502    #[cfg(test)]
503    /// Writes `data` to the uniform belt and unmaps.
504    pub(crate) fn uniform_belt_write_and_unmap(&mut self, data: &[u8]) {
505        self.uniform_belt.write_and_unmap(data);
506    }
507    #[cfg(test)]
508    /// Records a belt copy.
509    pub(crate) fn uniform_belt_record_copy(
510        &self,
511        encoder: &mut etalon::CommandEncoder,
512        target: &etalon::Buffer,
513        offset: etalon::BufferAddress,
514    ) {
515        self.uniform_belt.record_copy(encoder, target, offset);
516    }
517    #[cfg(test)]
518    /// Advances the belt write head.
519    pub(crate) fn uniform_belt_advance(&mut self) {
520        self.uniform_belt.advance(&self.device);
521    }
522    #[cfg(test)]
523    /// Uniform buffer for tests.
524    pub(crate) fn uniform_buf_test(&self) -> etalon::Buffer {
525        self.uniform_buf.clone()
526    }
527
528    /// Resizes to `width`×`height`.
529    pub fn resize(&mut self, width: u32, height: u32) -> Result<(u32, u32), String> {
530        self.pick_readback.invalidate(false);
531        self.pick_semantic_result = None;
532        if width == 0 || height == 0 {
533            return Ok((self.width, self.height));
534        }
535        let offscreen = self.surface.is_none();
536        let (width, height, frame_target_reservation, readback_staging_reservation) =
537            reserve_view_resources(width, height, offscreen)?;
538        let mut next_offscreen_texture = None;
539        let mut next_offscreen_view = None;
540        let mut next_readback_buf = None;
541        let mut next_readback_bytes_per_row = self.readback_bytes_per_row;
542        if offscreen {
543            let texture = create_offscreen_texture(&self.device, self.color_format, width, height);
544            next_offscreen_view =
545                Some(texture.create_view(&etalon::TextureViewDescriptor::default()));
546            next_offscreen_texture = Some(texture);
547            next_readback_bytes_per_row = checked_padded_bytes_per_row(width)
548                .ok_or_else(|| format!("readback row pitch overflow for width {width}"))?;
549            next_readback_buf = Some(create_readback_buffer(
550                &self.device,
551                next_readback_bytes_per_row,
552                height,
553            ));
554        }
555        let temporal_was_enabled = self.temporal_resolve.take().is_some();
556        self.temporal_producers.take();
557        self.scene_depth.replace(&self.device, width, height);
558        if temporal_was_enabled {
559            self.temporal_resolve = temporal_resolve_gpu::TemporalResolveGpu::try_new(
560                &self.device,
561                width,
562                height,
563                self.color_format,
564                self.color_format,
565            );
566            self.temporal_producers = self.temporal_resolve.as_ref().and_then(|_| {
567                temporal_producers_gpu::TemporalProducersGpu::try_new(
568                    &self.device,
569                    self.scene_depth.view(),
570                    width,
571                    height,
572                )
573            });
574        }
575        let (picking_texture, picking_view) = create_picking_texture(&self.device, width, height);
576        if let (Some(surface), Some(config)) = (self.surface.as_ref(), self.config.as_mut()) {
577            config.width = width;
578            config.height = height;
579            surface.configure(&self.device, config);
580        }
581        self.width = width;
582        self.height = height;
583        if offscreen {
584            self.offscreen_texture = next_offscreen_texture;
585            self.offscreen_view = next_offscreen_view;
586            self.readback_bytes_per_row = next_readback_bytes_per_row;
587            self.readback_buf = next_readback_buf;
588            self._readback_staging_reservation = readback_staging_reservation;
589        }
590        self.picking_texture = picking_texture;
591        self.picking_view = picking_view;
592        self._frame_target_reservation = frame_target_reservation;
593        self.temporal_reset_pending = true;
594        self.previous_camera_view_projection = None;
595        self.rebuild_ao_resources();
596        self.sync_bloom_targets();
597        Ok((width, height))
598    }
599
600    /// Reconcile the HDR bloom or portable SDR output chain with current budgets and policy.
601    pub fn sync_bloom_targets(&mut self) {
602        let bloom_wanted = portal_bloom_enabled() && probe_hdr_format(&self.device);
603        if bloom_wanted {
604            if let Some(ref bloom) = self.bloom {
605                if bloom.hdr_extent() == (self.width, self.height) {
606                    self.output_chain = None;
607                    self.bloom_policy_snapshot = portal_bloom_enabled();
608                    return;
609                }
610            }
611        } else if let Some(ref output) = self.output_chain {
612            if output.extent() == (self.width, self.height) {
613                self.bloom = None;
614                self.bloom_policy_snapshot = portal_bloom_enabled();
615                return;
616            }
617        }
618
619        // Release the alternate path before admitting the replacement. If the
620        // preferred path does not fit, construct the SDR output path below.
621        self.output_chain = None;
622        if bloom_wanted {
623            let mut bloom = create_bloom_chain(
624                &self.device,
625                self.width,
626                self.height,
627                self.color_format,
628                self.hdr_exposure_ev,
629            );
630            if let Some(chain) = bloom.as_mut() {
631                chain.white_balance_gains = self.white_balance_gains;
632            }
633            if let Some(ref chain) = bloom {
634                let (hw, hh) = chain.hdr_extent();
635                let (bw, bh) = chain.blur_extent();
636                debug_assert_eq!(hw, self.width);
637                debug_assert_eq!(hh, self.height);
638                debug_assert_eq!(bw, (self.width / 2).max(1));
639                debug_assert_eq!(bh, (self.height / 2).max(1));
640                let _ = chain.texture_handles();
641            }
642            if bloom.is_some() {
643                self.bloom = bloom;
644                self.bloom_policy_snapshot = portal_bloom_enabled();
645                return;
646            }
647        }
648
649        self.bloom = None;
650        let hdr_scene = self.ambient_pipeline_hdr.is_some()
651            && self.projector_pipeline_hdr.is_some()
652            && self.sky_pipeline_hdr.is_some()
653            && self.mesh_pipeline_hdr.is_some();
654        self.output_chain = output_pass::OutputChain::try_new(
655            &self.device,
656            self.width,
657            self.height,
658            if hdr_scene {
659                HDR_FORMAT
660            } else {
661                self.color_format
662            },
663            self.color_format,
664            self.hdr_exposure_ev,
665            hdr_scene,
666            self.white_balance_gains,
667        );
668        self.bloom_policy_snapshot = portal_bloom_enabled();
669    }
670}
671
672// Phase 0.2a: render/gpu submodules (bloom post-pass, resource builders, particle field).
673mod bloom;
674mod compute;
675mod emf_pipeline;
676#[cfg(target_arch = "wasm32")]
677mod emf_present;
678#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
679mod native_device;
680mod particles;
681mod portal_gpu;
682mod resources;
683mod uniform_belt;
684
685/// Maximum ordered material draws admitted for one resident mesh in the portable renderer.
686pub const MAX_GPU_MATERIAL_DRAWS: usize = 65_536;
687
688use bloom::*;
689pub use compute::{ComputeBinding, ComputeBufferKind};
690pub use emf_pipeline::{
691    checked_field_bytes, checked_grid_cell_count, emf_cells_from_loaded,
692    emf_field_cell_from_display, emf_field_cell_from_optical, emf_field_cell_from_record64,
693    evaluate_display_slice_rgba8, full_spectrum_sigma_to_linear_rgb, EmfFieldCell, EmfPipeline,
694    EmfPipelineDesc, EmfSliceUniform, EMF_VOLUMETRIC_WGSL,
695};
696pub use particles::particle_cap_for_mode;
697use particles::*;
698use resources::*;
699
700#[cfg(all(test, not(target_arch = "wasm32")))]
701#[path = "picking_tests.rs"]
702mod picking_tests;
703
704#[cfg(all(test, not(target_arch = "wasm32")))]
705#[path = "mesh_pixel_tests.rs"]
706mod mesh_pixel_tests;
707
708#[cfg(all(test, not(target_arch = "wasm32")))]
709#[path = "material_pixel_tests.rs"]
710mod material_pixel_tests;
711
712#[cfg(all(test, not(target_arch = "wasm32")))]
713#[path = "material_pixel_portal_tests.rs"]
714mod material_pixel_portal_tests;
715
716#[cfg(all(test, not(target_arch = "wasm32")))]
717#[path = "environment_probe_pixel_tests.rs"]
718mod environment_probe_pixel_tests;
719
720#[cfg(all(test, not(target_arch = "wasm32")))]
721#[path = "water_pixel_tests.rs"]
722mod water_pixel_tests;