Struct ViewportRenderer 

pub struct ViewportRenderer { /* private fields */ }

Owns the GPU pipelines and per-frame state for rendering a scene. Call prepare once per frame to upload data, then paint_to (or render) to issue draw calls.

Implementations

impl ViewportRenderer

pub fn pick_scene_gpu( &mut self, device: &Device, queue: &Queue, cursor: Vec2, frame: &FrameData, ) -> Option<GpuPickHit>

GPU object-ID pick: renders the scene to an offscreen R32Uint texture and reads back the single pixel under cursor.

This is O(1) in mesh complexity : every object is rendered with a flat u32 ID, and only one pixel is read back. For triangle-level queries (barycentric scalar probe, exact world position), use the CPU crate::interaction::picking::pick_scene_cpu path instead.

The pipeline is lazily initialized on first call : zero overhead when this method is never invoked.

Arguments

• device : wgpu device
• queue : wgpu queue
• cursor : cursor position in viewport-local pixels (top-left origin)
• frame : current grouped frame data (camera, scene surfaces, viewport size)

Returns

Some(GpuPickHit) if an object is under the cursor, None if empty space.

impl ViewportRenderer

pub fn pick( &self, click_pos: Vec2, viewport_size: Vec2, view_proj: Mat4, mask: PickMask, ) -> Option<PickHit>

Pick the nearest item or sub-element under click_pos.

Dispatches across all item types retained from the last prepare() call. The mask controls which item types and sub-element levels participate.

Returns None if nothing matching the mask is under the cursor.

Arguments

• click_pos - cursor position in viewport pixels (top-left origin)
• viewport_size - viewport width x height in pixels
• view_proj - combined view x projection matrix from the last frame
• mask - which item types and sub-element levels to include

Example

if let Some(hit) = renderer.pick(cursor, vp_size, view_proj, PickMask::FACE) {
    println!("hit face {:?} on object {}", hit.sub_object, hit.id);
}

impl ViewportRenderer

pub fn pick_rect( &self, rect_min: Vec2, rect_max: Vec2, viewport_size: Vec2, view_proj: Mat4, mask: PickMask, ) -> PickRectResult

Pick all items or sub-elements inside a screen-space rectangle.

Dispatches across all item types retained from the last prepare() call. The mask controls which item types and sub-element levels participate.

Arguments

• rect_min - top-left corner of the selection rect in viewport pixels
• rect_max - bottom-right corner of the selection rect in viewport pixels
• viewport_size - viewport width x height in pixels
• view_proj - combined view x projection matrix from the last frame
• mask - which item types and sub-element levels to include

impl ViewportRenderer

pub fn render_offscreen( &mut self, device: &Device, queue: &Queue, frame: &FrameData, width: u32, height: u32, ) -> Vec<u8>

Render a frame to an offscreen texture and return raw RGBA bytes.

Creates a temporary wgpu::Texture render target of the given dimensions, runs all render passes (shadow, scene, post-processing) into it via render(), then copies the result back to CPU memory.

No OS window or wgpu::Surface is required. The caller is responsible for initialising the wgpu adapter with compatible_surface: None and for constructing a valid FrameData (including viewport_size matching width/height).

Returns width * height * 4 bytes in RGBA8 layout. The caller encodes to PNG/EXR independently : no image codec dependency in this crate.

impl ViewportRenderer

pub fn new(device: &Device, target_format: TextureFormat) -> Self

Create a new renderer with default settings (no MSAA). Call once at application startup.

pub fn with_sample_count( device: &Device, target_format: TextureFormat, sample_count: u32, ) -> Self

Create a new renderer with the specified MSAA sample count (1, 2, or 4).

When using MSAA (sample_count > 1), the caller must create multisampled colour and depth textures and use them as render pass attachments with the final surface texture as the resolve target.

pub fn new_with_pipeline_cache( device: &Device, target_format: TextureFormat, pipeline_cache_data: Option<&[u8]>, ) -> Self

Create a renderer, seeding the GPU pipeline cache from previously saved data so shader compilation can be skipped on later launches.

Pass the bytes returned by an earlier pipeline_cache_data call, or None on first run. The cache only takes effect when the device was created with Features::PIPELINE_CACHE; otherwise the data is ignored and this matches new.

pub fn pipeline_cache_data(&self) -> Option<Vec<u8>>

Returns the current contents of the GPU pipeline cache, suitable for persisting and feeding back into new_with_pipeline_cache on the next launch. None when the device lacks Features::PIPELINE_CACHE.

pub fn with_sample_count_and_cache( device: &Device, target_format: TextureFormat, sample_count: u32, pipeline_cache_data: Option<&[u8]>, ) -> Self

Like with_sample_count with an MSAA count and an optional saved pipeline cache.

pub fn resources(&self) -> &ViewportGpuResources

Access the underlying GPU resources (e.g. for mesh uploads).

pub fn last_frame_stats(&self) -> FrameStats

Performance counters from the last completed frame.

pub fn cluster_stats(&self) -> Option<ClusterStats>

Diagnostics from the cluster build pass on the most recent frame that requested them (ViewportFrame::cluster_stats_request). Returns None until a request has been served.

pub fn disable_gpu_driven_culling(&mut self)

Disable GPU-driven culling, reverting to the direct draw path.

Has no effect when the device does not support INDIRECT_FIRST_INSTANCE (culling is already disabled on those devices).

pub fn force_dirty(&mut self)

Force a full instance buffer upload on the next frame.

Normally the renderer skips GPU writes for instanced batches whose data has not changed since the last upload. Call this when you have mutated batch-relevant state through a path the renderer cannot observe (for example, directly modifying GPU buffer contents or scene items after collect_render_items runs). The flag is consumed once and resets automatically after the next prepare call.

pub fn enable_gpu_driven_culling(&mut self)

Re-enable GPU-driven culling after a call to disable_gpu_driven_culling.

Has no effect when the device does not support INDIRECT_FIRST_INSTANCE.

pub fn set_upload_budget(&mut self, budget: Option<Duration>)

Cap the per-frame cost of running upload-job apply closures.

None is the default and matches the historical behaviour: prepare drains every completed upload’s apply step in one shot. Some(d) switches prepare over to process_uploads_with_budget so applies that overflow the budget spill to the next frame. Useful when a stress load lands many heavy completions on the same frame and the bunched apply work shows up as one fat frame at the end of the load.

pub fn upload_budget(&self) -> Option<Duration>

Currently configured upload budget. See set_upload_budget.

pub fn set_runtime_mode(&mut self, mode: RuntimeMode)

Set the runtime mode controlling internal default behavior.

• [RuntimeMode::Interactive]: full picking rate, full quality (default).
• [RuntimeMode::Playback]: picking throttled to reduce CPU overhead during animation.
• [RuntimeMode::Paused]: full picking rate, full quality.
• [RuntimeMode::Capture]: full quality, intended for screenshot/export workflows.

pub fn runtime_mode(&self) -> RuntimeMode

Return the current runtime mode.

pub fn set_cpu_pick_cache(&mut self, enabled: bool)

Enable or disable the CPU pick cache.

When enabled, prepare() retains a copy of the frame’s pickable items so pick() and pick_rect() can run later (e.g. on a mouse click) without the scene data. This copies all inline point/glyph/curve geometry each frame, so it is disabled by default: turn it on only when using the CPU pick()/pick_rect() path. The GPU path (pick_scene_gpu) and the renderer-free interaction::picking functions do not need it.

pub fn cpu_pick_cache(&self) -> bool

Whether the CPU pick cache is enabled. See set_cpu_pick_cache.

pub fn set_performance_policy(&mut self, policy: PerformancePolicy)

Set the performance policy controlling target FPS, render scale bounds, and permitted quality reductions.

The internal adaptation controller activates when policy.allow_dynamic_resolution is true and policy.target_fps is Some. It adjusts render_scale within [min_render_scale, max_render_scale] each frame based on total_frame_ms.

pub fn performance_policy(&self) -> PerformancePolicy

Return the active performance policy.

pub fn set_render_scale(&mut self, scale: f32)

Manually set the render scale.

Effective when performance_policy.allow_dynamic_resolution is false. When dynamic resolution is enabled the adaptation controller overrides this value each frame.

The value is clamped to [policy.min_render_scale, policy.max_render_scale].

Works on both the LDR and HDR render paths. On the HDR path, the scene, bloom, SSAO, tone-map, and FXAA all run at the scaled resolution; the result is upscale-blitted to native resolution before overlays and grid.

pub fn set_target_fps(&mut self, fps: Option<f32>)

Set the target frame rate used to compute [FrameStats::missed_budget].

Convenience wrapper that updates performance_policy.target_fps.

pub fn resources_mut(&mut self) -> &mut ViewportGpuResources

Mutable access to the underlying GPU resources (e.g. for mesh uploads).

pub fn is_using_instanced_path(&self) -> bool

Returns true when the current frame is rendered via the instanced draw path.

When true, edits to mesh.wgsl shadow sampling code have no effect - the active shader is mesh_instanced.wgsl. Check this before testing shader changes.

pub fn instanced_batch_count(&self) -> usize

Returns the number of instanced batches prepared for the current frame.

Zero when using the non-instanced path. Each batch corresponds to a distinct (MeshId, material) combination in the scene.

pub fn submit_cull( &mut self, device: &Device, queue: &Queue, encoder: &mut CommandEncoder, frustum: &Frustum, sub: &CullSubmission<'_>, )

Run the GPU-driven cull compute against a plugin’s CullSubmission.

Encodes two compute passes into encoder:

1. one thread per instance, tests AABB against frustum, claims a visibility slot via atomic add;
2. one thread per batch, writes a DrawIndexedIndirect entry into sub.indirect_out with the final visible count and zeroes the counter for the next call.

After the encoder runs, draw each batch with pass.draw_indexed_indirect(sub.indirect_out, batch_idx * 20) using sub.visible_out as the per-instance lookup buffer.

The cull pipeline is created lazily on the first call. Returns without dispatching if the device does not support INDIRECT_FIRST_INSTANCE (call is_gpu_culling_supported first).

pub fn submit_cull_shadow( &mut self, device: &Device, queue: &Queue, encoder: &mut CommandEncoder, cascade_idx: usize, cascade_frustum: &Frustum, sub: &CullSubmission<'_>, )

Same as submit_cull for one shadow cascade.

Uploads the frustum to the cascade slot (so a single frame can submit the main pass plus every cascade without overwriting an in-flight upload) and forces the cull shader’s shadow flag so InstanceAabb::cast_shadows = 0 entries are skipped.

cascade_idx must be in 0..4; values outside that range panic in debug builds and clamp to 3 in release.

pub fn submit_cull_single_mesh( &mut self, device: &Device, queue: &Queue, encoder: &mut CommandEncoder, frustum: &Frustum, instance_aabbs: &Buffer, instance_count: u32, visible_out: &Buffer, indirect_out: &Buffer, draw: SingleMeshDraw, shadow_pass: bool, )

Convenience wrapper around submit_cull for the common case of one mesh with N instances.

The renderer fills its scratch BatchMeta slot from draw, zeroes its scratch counter, seeds the indirect entry, and runs a one-batch cull. Plugins that only have a single mesh per submission don’t have to allocate either buffer themselves.

indirect_out must hold one DrawIndexedIndirect entry (20 bytes).

pub fn submit_cull_shadow_single_mesh( &mut self, device: &Device, queue: &Queue, encoder: &mut CommandEncoder, cascade_idx: usize, cascade_frustum: &Frustum, instance_aabbs: &Buffer, instance_count: u32, visible_out: &Buffer, indirect_out: &Buffer, draw: SingleMeshDraw, )

Single-mesh shadow variant of submit_cull_single_mesh.

pub fn with_item_type_plugin( &mut self, device: &Device, plugin: Box<dyn ItemTypePlugin>, )

Register an ItemTypePlugin.

Invokes the plugin’s init_gpu against the current device and shared bind layout, then stores it keyed by type_name() for the remainder of the renderer’s lifetime. Registering a second plugin with the same type_name replaces the first.

The renderer will dispatch prepare and paint to the plugin on every frame where SceneFrame::submit_plugin_items has populated a collection under the same name.

pub fn has_item_type_plugin(&self, type_name: &str) -> bool

Returns true when an item-type plugin with type_name is registered.

pub fn is_gpu_culling_supported(&self) -> bool

True when the device supports the features GPU-driven culling needs.

Plugins should gate submit_cull calls on this. If false, the lib silently no-ops the submission and the plugin must fall back to direct draws.

pub fn shadow_debug_stats(&self) -> ShadowDebugStats

Returns per-frame shadow and lighting pipeline statistics for debug inspection.

All fields reflect the most recently completed prepare call (one frame behind the display). Returns default values before the first prepare call.

pub fn read_debug_pixel( &self, device: &Device, queue: &Queue, x: u32, y: u32, ) -> Option<[f32; 4]>

Read the debug values at a specific pixel from the per-fragment storage buffer.

Returns None when debug_vis is inactive (no buffer allocated) or when (x, y) is outside the viewport. The four channels correspond to the current R/G/B channel selectors plus 1.0 for alpha.

This submits a GPU-to-CPU copy and waits synchronously. Only call from outside a render pass (e.g., in the next frame’s prepare step), not inside paint callbacks.

The returned values are from the previous rendered frame.

pub fn upload_gaussian_splats( &mut self, device: &Device, queue: &Queue, data: &GaussianSplatData, ) -> ViewportResult<GaussianSplatId>

Upload a Gaussian splat set to the GPU.

Call once per splat set at startup or when it changes. The returned GaussianSplatId is valid until remove_gaussian_splats is called.

Errors

Returns ViewportError::InvalidGaussianSplatData if data.positions is empty or if positions, scales, rotations, and opacities differ in length.

Examples

let result = renderer.upload_gaussian_splats(device, queue, &GaussianSplatData::default());
assert!(matches!(result, Err(ViewportError::InvalidGaussianSplatData { .. })));

pub fn remove_gaussian_splats(&mut self, id: GaussianSplatId)

Remove an uploaded Gaussian splat set by handle.

After this call the id is invalid and must not be submitted in SceneFrame.

pub fn upload_environment_map( &mut self, device: &Device, queue: &Queue, pixels: &[f32], width: u32, height: u32, ) -> ViewportResult<()>

Upload an equirectangular HDR environment map and precompute IBL textures.

pixels is row-major RGBA f32 data (4 floats per texel), widthxheight. This rebuilds camera bind groups so shaders immediately see the new textures.

Errors

Returns ViewportError::InvalidTextureData if pixels.len() does not equal width * height * 4.

Examples

// 2x2 RGBA image requires exactly 16 floats.
let result = renderer.upload_environment_map(device, queue, &[0.0f32; 12], 2, 2);
assert!(matches!(result, Err(ViewportError::InvalidTextureData { expected: 16, actual: 12 })));

pub fn upload_status(&self, id: JobId) -> UploadStatus

Current state of an in-flight upload job.

pub fn uploads_pending(&self) -> usize

Count of upload jobs still in flight.

pub fn job_duration(&self, id: JobId) -> Option<Duration>

Wall-clock work duration recorded for an async upload job. See ViewportGpuResources::job_duration.

pub fn drop_job_duration(&mut self, id: JobId)

Drop the recorded duration for id after reading it. See ViewportGpuResources::drop_job_duration.

pub fn begin_upload_volume( &mut self, device: &Device, queue: &Queue, data: Vec<f32>, dims: [u32; 3], ) -> ViewportResult<JobId>

Start an asynchronous 3D volume texture upload. See ViewportGpuResources::begin_upload_volume.

pub fn upload_result_volume(&mut self, id: JobId) -> ViewportResult<VolumeId>

Take the volume id produced by a completed begin_upload_volume job.

pub fn begin_upload_volume_for_mc( &mut self, device: &Device, queue: &Queue, vol: VolumeData, ) -> JobId

Start an asynchronous marching-cubes-ready volume upload. See ViewportGpuResources::begin_upload_volume_for_mc.

pub fn upload_result_volume_mc( &mut self, id: JobId, ) -> ViewportResult<VolumeGpuId>

Take the VolumeGpuId produced by a completed begin_upload_volume_for_mc job.

pub fn begin_upload_volume_mesh( &mut self, device: &Device, data: VolumeMeshData, ) -> JobId

Start an asynchronous boundary-only volume mesh upload. See ViewportGpuResources::begin_upload_volume_mesh.

pub fn upload_result_volume_mesh( &mut self, id: JobId, ) -> ViewportResult<VolumeMeshItem>

Take the VolumeMeshItem produced by a completed begin_upload_volume_mesh job.

pub fn begin_upload_clipped_volume_mesh( &mut self, device: &Device, data: VolumeMeshData, clip_planes: Vec<[f32; 4]>, ) -> JobId

Start an asynchronous clipped volume mesh upload. See ViewportGpuResources::begin_upload_clipped_volume_mesh.

pub fn upload_result_clipped_volume_mesh( &mut self, id: JobId, ) -> ViewportResult<VolumeMeshItem>

Take the VolumeMeshItem produced by a completed begin_upload_clipped_volume_mesh job.

pub fn begin_upload_sparse_volume_grid_data( &mut self, device: &Device, data: SparseVolumeGridData, ) -> JobId

Start an asynchronous sparse voxel grid upload. See ViewportGpuResources::begin_upload_sparse_volume_grid_data.

pub fn upload_result_sparse_volume_grid( &mut self, id: JobId, ) -> ViewportResult<MeshId>

Take the MeshId produced by a completed begin_upload_sparse_volume_grid_data job.

pub fn begin_upload_gaussian_splats( &mut self, device: &Device, queue: &Queue, data: GaussianSplatData, ) -> ViewportResult<JobId>

Start an asynchronous Gaussian splat upload. See ViewportGpuResources::begin_upload_gaussian_splats.

pub fn upload_result_gaussian_splats( &mut self, id: JobId, ) -> ViewportResult<GaussianSplatId>

Take the GaussianSplatId produced by a completed begin_upload_gaussian_splats job.

pub fn begin_upload_overlay_texture( &mut self, device: &Device, queue: &Queue, width: u32, height: u32, rgba_data: Vec<u8>, ) -> ViewportResult<JobId>

Start an asynchronous overlay texture upload. See ViewportGpuResources::begin_upload_overlay_texture.

pub fn upload_result_overlay_texture( &mut self, id: JobId, ) -> ViewportResult<OverlayTextureId>

Take the OverlayTextureId produced by a completed begin_upload_overlay_texture job.

pub fn all_uploads_complete(&self) -> bool

True when no upload jobs are in flight.

pub fn on_upload_complete<F>(&mut self, id: JobId, cb: F)

where F: FnOnce(&UploadStatus) + Send + 'static,

Register a callback to fire when an upload job finishes. See ViewportGpuResources::on_upload_complete for the semantics.

pub fn begin_upload_texture( &mut self, device: &Device, queue: &Queue, width: u32, height: u32, rgba: Vec<u8>, ) -> ViewportResult<JobId>

Start an asynchronous albedo texture upload. See ViewportGpuResources::begin_upload_texture for the semantics.

pub fn begin_upload_normal_map( &mut self, device: &Device, queue: &Queue, width: u32, height: u32, rgba: Vec<u8>, ) -> ViewportResult<JobId>

Start an asynchronous normal-map upload. See ViewportGpuResources::begin_upload_normal_map for the semantics.

pub fn upload_result_texture(&mut self, id: JobId) -> ViewportResult<u64>

Take the texture id from a completed async texture upload. See ViewportGpuResources::upload_result_texture for the error semantics.

pub fn begin_upload_mesh_data( &mut self, device: &Device, data: MeshData, ) -> ViewportResult<JobId>

Start an asynchronous mesh upload.

Returns a JobId immediately. The CPU prep (tangent computation, vertex repack, normal-line build) runs on a worker thread; GPU buffer creation and store insertion run on the main thread during the next process_uploads call after the worker finishes. Once the status is Ready, take the produced MeshId with upload_result_mesh.

Ownership of data transfers into the worker; clone at the call site if you need to retain it.

Errors

Same validation errors as upload_mesh_data (empty mesh, length mismatch, invalid vertex index), all reported before the job is submitted.

pub fn upload_result_mesh(&mut self, id: JobId) -> ViewportResult<MeshId>

Take the MeshId produced by a completed begin_upload_mesh_data job. See ViewportGpuResources::upload_result_mesh for the error semantics.

pub fn begin_upload_environment_map( &mut self, device: &Device, queue: &Queue, pixels: Vec<f32>, width: u32, height: u32, ) -> ViewportResult<JobId>

Start an asynchronous environment-map upload.

Returns immediately with a JobId. The caller drives the upload-job runner from the renderer’s prepare path each frame; once the job reports Ready, the IBL textures are live on the renderer and a subsequent call to rebuild_camera_bind_groups makes them visible to shaders.

Ownership of pixels transfers into the background worker.

Errors

Returns ViewportError::InvalidTextureData if pixels.len() != width * height * 4.

pub fn rebuild_camera_bind_groups(&mut self, device: &Device)

Rebuild the primary and per-viewport camera bind groups.

Call after IBL textures are uploaded so the shaders see the new environment. The synchronous upload_environment_map does this internally; consumers driving the async path through begin_upload_environment_map should call this themselves once the matching job reports Ready.

pub fn create_viewport(&mut self, device: &Device) -> ViewportId

Create a new viewport slot and return its handle.

The returned ViewportId is stable for the lifetime of the renderer. Pass it to prepare_viewport, paint_viewport, and render_viewport each frame.

Also set the viewport slot on the camera frame when building the FrameData for this viewport:

let id = renderer.create_viewport(&device);
let frame = FrameData {
    camera: CameraFrame::from_camera(&cam, size).with_viewport_id(id),
    ..Default::default()
};

pub fn destroy_viewport(&mut self, id: ViewportId)

Release the heavy GPU texture memory (HDR targets, OIT, bloom, SSAO) held by id.

The slot index is not reclaimed : future calls with this ViewportId will lazily recreate the texture resources as needed. This is useful when a viewport is hidden or minimised and you want to reduce VRAM pressure without invalidating the handle.

pub fn owned(&mut self) -> OwnedPath<'_>

Returns the owned-encoder rendering path.

Use when you own the window loop and wgpu encoder (winit, raw wgpu). See OwnedPath for available methods.

pub fn pass(&mut self) -> PassPath<'_>

Returns the pass-based rendering path.

Use when a framework provides you with a render pass (eframe, iced). See PassPath for available methods.

pub fn pass_view(&self) -> PassView<'_>

Returns a read-only paint view for framework paint callbacks.

Use this in callbacks where only a shared reference to the renderer is available (e.g. eframe’s CallbackTrait::paint where callback_resources is &CallbackResources). Exposes only the paint methods, not prepare.