Struct Engine 

pub struct Engine<D: Device> { /* private fields */ }

The rendering engine, generic over the device with no dynamic dispatch on the frame path.

Implementations

impl<D: Device> Engine<D>

pub fn install_brick_atlas( &mut self, catalog: &BrickCatalog, config: BrickAtlasConfig, ) -> Result<usize, BrickAtlasError>

Allocates a bounded atlas for one logical sparse field.

Errors

Returns typed catalog, capacity or GPU limit failures.

pub fn stage_brick( &mut self, atlas: usize, upload: BrickAtlasUpload<'_>, ) -> Result<FenceValue, BrickAtlasError>

Delivers one borrowed provider payload to persistent staging.

Errors

Returns typed atlas index, generation or upload backpressure.

pub fn evict_brick( &mut self, atlas: usize, brick: BrickId, ) -> Result<FenceValue, BrickAtlasError>

Invalidates a page and schedules fence-safe slot release.

Errors

Returns typed atlas index, page or lifecycle failures.

pub fn brick_atlas_metrics(&mut self, atlas: usize) -> Option<BrickAtlasMetrics>

Current bounded memory and lifecycle counters for one atlas.

impl<D: Device> Engine<D>

pub fn set_structure_chunk_placements( &mut self, placements: &[StructureChunkPlacement], ) -> Result<(), ChunkResidencyError>

Replaces the bounded declarative placement set without copying coordinates.

Errors

Rejects invalid transforms, duplicate identities or capacity overflow.

pub fn structure_chunk_placement_status( &self, id: ChunkPlacementId, ) -> ChunkPlacementStatus

Reports whether one declared placement currently enters the indirect batch.

pub fn set_point_chunk_placements( &mut self, placements: &[PointChunkPlacement], ) -> Result<(), ChunkResidencyError>

Replaces the bounded declarative generic point placement set.

Errors

Rejects invalid transforms, duplicate identities or capacity overflow.

pub fn point_chunk_placement_status( &self, id: ChunkPlacementId, ) -> ChunkPlacementStatus

Reports whether one generic point placement enters the indirect batch.

pub fn set_instance_chunk_placements( &mut self, placements: &[InstanceChunkPlacement], ) -> Result<(), ChunkResidencyError>

Replaces the bounded declarative rigid-instance placement set.

Errors

Rejects duplicate identities or capacity overflow.

pub fn instance_chunk_placement_status( &self, id: ChunkPlacementId, ) -> ChunkPlacementStatus

Reports whether one rigid-instance placement enters its analytic batch.

pub fn set_instance_chunk_windows( &mut self, windows: &[InstanceChunkWindow], ) -> Result<(), ChunkResidencyError>

Replaces the bounded two-frame windows sampled by paged instances.

The CPU only updates this compact table; culling and rendering sample exact resident transform pages directly on the GPU.

Errors

Rejects duplicate occurrence windows or capacity overflow atomically.

pub fn set_attribute_chunk_windows( &mut self, windows: &[AttributeChunkWindow], ) -> Result<(), ChunkResidencyError>

Replaces two-frame windows for scene-independent visual columns.

Errors

Rejects duplicate stable columns or capacity overflow atomically.

pub fn set_relation_chunk_placements( &mut self, placements: &[RelationChunkPlacement], ) -> Result<(), ChunkResidencyError>

Replaces the bounded set of globally anchored relation occurrences.

Errors

Rejects duplicate identities or capacity overflow atomically.

pub fn relation_chunk_placement_status( &self, id: ChunkPlacementId, ) -> ChunkPlacementStatus

Reports whether a relation payload and all exact anchor occurrences are resident.

pub fn paged_spatial_anchor_is_resident( &self, anchor: PagedSpatialAnchor, ) -> bool

Reports whether one globally identified spatial anchor currently maps to an exact resident occurrence and chunk-local GPU row.

pub fn set_bond_chunk_placements( &mut self, placements: &[BondChunkPlacement], ) -> Result<(), ChunkResidencyError>

Replaces the bounded declarative analytic bond placement set.

Errors

Rejects invalid radii/transforms, duplicate identities or capacity overflow.

pub fn set_trajectory_chunk_windows( &mut self, windows: &[TrajectoryChunkWindow], ) -> Result<(), ChunkResidencyError>

Replaces the bounded two-frame trajectory windows.

Windows become active only when their exact structure and both exact provider-frame generations are resident. Updating interpolation changes only the compact window table on the CPU.

Errors

Rejects duplicate structure windows or capacity overflow.

pub fn bond_chunk_placement_status( &self, id: ChunkPlacementId, ) -> ChunkPlacementStatus

Reports whether a declared bond generation and all atom endpoints are resident.

pub const fn host_working_set(&self) -> &HostWorkingSet

CPU payloads retained by the engine’s bounded working set.

pub fn request_chunk_into( &mut self, request: ResidencyRequest, output: &mut ResidencyOutput, ) -> Result<ResidencyTicket, ChunkResidencyError>

Emits one caller-owned provider request.

Errors

Returns typed generation or in-flight budget errors.

pub fn deliver_chunk_into( &mut self, ticket: ResidencyTicket, payload: ChunkData, output: &mut ResidencyOutput, ) -> Result<(), ChunkResidencyError>

Accepts an exact provider payload without reimplementing or copying it.

Errors

Rejects stale tickets, identity mismatches and CPU pressure.

pub fn upload_chunk_into( &mut self, ticket: ResidencyTicket, output: &mut ResidencyOutput, ) -> Result<(), ChunkResidencyError>

Explicitly stages and submits one provider-backed structure, bond or topology-aligned trajectory-frame chunk.

Resident is not published until Self::poll_chunk_uploads_into observes the backend completion signal.

Errors

Returns typed host lifecycle, arena, staging, capacity or GPU errors.

pub fn poll_chunk_uploads_into( &mut self, output: &mut ResidencyOutput, ) -> Result<(), ChunkResidencyError>

Polls backend completion and promotes only signalled uploads.

Errors

Device loss and current-generation lifecycle failures are returned.

pub fn cancel_chunk_into( &mut self, ticket: ResidencyTicket, output: &mut ResidencyOutput, ) -> Result<(), ChunkResidencyError>

Cancels one generation and retires submitted bytes only after its fence.

Errors

Rejects stale cancellation tickets.

pub fn set_chunk_budget_into( &mut self, budget: ResidencyBudget, output: &mut ResidencyOutput, ) -> Result<(), ChunkResidencyError>

Applies hard budgets and releases evicted arena pages.

Errors

Returns a stale physical allocation error if ownership diverged.

pub fn chunk_device_lost_into( &mut self, output: &mut ResidencyOutput, ) -> Result<DeviceLossReport, ChunkResidencyError>

Invalidates GPU allocations and preserves provider storage for re-upload.

Errors

Returns generation exhaustion or replacement allocation failure.

pub fn resident_structure_chunk( &self, ticket: ResidencyTicket, ) -> Option<ResidentStructureChunk>

Resolves one global ticket to its chunk-local GPU range.

pub fn resident_trajectory_chunk( &self, ticket: ResidencyTicket, ) -> Option<ResidentTrajectoryChunk>

Resolves one exact provider-frame ticket to its bounded GPU range.

pub fn resident_generic_chunk( &self, ticket: ResidencyTicket, ) -> Option<ResidentGenericChunk>

Resolves one exact generic payload generation to its shared arena range.

pub fn chunk_residency_metrics(&self) -> ChunkResidencyMetrics

Real bounded-storage counters for chunk residency.

impl<D: Device> Engine<D>

pub fn render( &mut self, scene: &Scene, camera: &Camera, ) -> Result<FrameReport, RenderError>

Renders one frame of the scene to the presentation surface.

A lost or outdated surface reconfigures and returns FrameStatus::Skipped; the next frame recovers. Nothing panics on conditions a caller can hit.

Errors

Device loss beyond surface recovery, or graph reconstruction failures.

impl<D: Device> Engine<D>

pub async fn render_hdr_image_async( &mut self, scene: &Scene, camera: &Camera, config: ImageConfig, ) -> Result<HdrImage, RenderError>

Asynchronously renders the resolved scene-linear HDR input that would otherwise enter presentation tone mapping.

Browser callers use this path so mapped-buffer completion yields to the event loop. The capture copies directly from the graph’s RGBA16F resource and does not allocate another full-resolution GPU texture.

Errors

Returns a typed device error, graph allocation failure, or RenderError::InvalidImageSize for invalid dimensions.

pub fn render_hdr_image( &mut self, scene: &Scene, camera: &Camera, config: ImageConfig, ) -> Result<HdrImage, RenderError>

Renders the resolved scene-linear HDR input without opening a window.

The capture copies directly from the graph’s RGBA16F resource and does not allocate another full-resolution GPU texture.

Errors

Returns a typed device error, graph allocation failure, or RenderError::InvalidImageSize for invalid dimensions.

impl<D: Device> Engine<D>

pub async fn render_image_async( &mut self, scene: &Scene, camera: &Camera, config: ImageConfig, ) -> Result<Image, RenderError>

Asynchronously renders a deterministic off-screen image. Browser callers use this path so mapped-buffer completion yields to the event loop.

Errors

Returns a typed device error, graph allocation failure, or RenderError::InvalidImageSize for zero or overflowing dimensions.

pub fn render_image( &mut self, scene: &Scene, camera: &Camera, config: ImageConfig, ) -> Result<Image, RenderError>

Renders one deterministic off-screen frame without opening a window.

Errors

Returns a typed device error, graph allocation failure, or RenderError::InvalidImageSize for zero or overflowing dimensions.

impl<D: Device> Engine<D>

pub async fn new_async( config: &EngineConfig, window: Option<WindowTarget>, ) -> Result<Self, RenderError>

Asynchronously opens a device and builds the realtime graph. Pass a window to render to screen; none for off-screen rendering.

Errors

No compatible adapter, or pipeline construction failed.

pub fn new( config: &EngineConfig, window: Option<WindowTarget>, ) -> Result<Self, RenderError>

Opens a native device synchronously for callers without an async executor. Browser callers use Self::new_async.

Errors

No compatible adapter, or pipeline construction failed.

impl<D: Device> Engine<D>

pub async fn pick_async( &mut self, x: u32, y: u32, ) -> Result<Option<Pick>, RenderError>

Asynchronously resolves the exact visible entity at one top-left-origin pixel. This is the portable browser entry point.

Errors

Returns a typed device error when readback fails. A pixel outside the target or over the background resolves to Ok(None).

pub fn pick(&mut self, x: u32, y: u32) -> Result<Option<Pick>, RenderError>

Resolves the exact visible entity at one top-left-origin pixel in constant time with respect to scene size.

Errors

Returns a typed device error when readback fails. A pixel outside the target or over the background resolves to Ok(None).

impl<D: Device> Engine<D>

pub fn profile_frame_batch( &mut self, scene: &Scene, camera: &Camera, config: ImageConfig, frames: NonZeroU32, ) -> Result<FrameTiming, RenderError>

Measures sustained native throughput with several frames in flight and one completion wait. The returned durations are per-frame averages; unlike Self::profile_frame, the end-to-end value does not charge a blocking buffer map to every frame.

Errors

Returns a capability error when timestamps are unavailable, or a typed rendering/device error.

pub async fn profile_frame_async( &mut self, scene: &Scene, camera: &Camera, config: ImageConfig, ) -> Result<FrameTiming, RenderError>

Asynchronously measures one headless frame using timestamp queries.

Errors

Returns a capability error when the adapter exposes no timestamps, or a typed rendering/device error.

pub fn profile_frame( &mut self, scene: &Scene, camera: &Camera, config: ImageConfig, ) -> Result<FrameTiming, RenderError>

Measures one headless frame using device timestamp queries. Callers should discard warmup frames before applying percentile gates.

Errors

Returns a capability error when the adapter exposes no timestamps, or a typed rendering/device error.

impl<D: Device> Engine<D>

pub fn sequence( &self, config: SequenceConfig, ) -> Result<SequenceRenderer<D>, RenderError>

Opens a bounded history-preserving sequence pipeline.

Errors

Rejects an invalid timebase or in-flight depth.

impl<D: Device> Engine<D>

pub fn resize(&mut self, width: u32, height: u32)

Updates the frame size after a window resize; the surface and pool reconfigure lazily before the next frame.

pub fn capabilities(&self) -> &Capabilities

The opened device’s capability report.

pub fn set_render_mode(&mut self, mode: RenderMode)

Changes rendering strategy without rebuilding the scene or device.

pub const fn quality_tier(&self) -> QualityTier

The adaptive quality tier the next frame presents at.

pub fn explain(&self) -> String

Deterministic description of the adaptive quality loop: the tier it currently holds, the smoothed frame time that drives it, and the resolution that tier selects.

pub const fn render_mode(&self) -> RenderMode

Current rendering strategy.

pub fn set_render_profile( &mut self, profile: RenderProfile, ) -> Result<(), RenderError>

Resolves and applies a reusable presentation recipe. Parameter-only changes preserve scene and pipeline allocations; temporal history is reset so the previous recipe never bleeds into the new presentation.

Errors

Returns a graph error if a topology-changing module cannot be scheduled.

pub fn set_derived_cache_budget(&mut self, budget: DerivedCacheBudget)

Replaces the derived-resource budget.

The new limit takes effect on the next frame, which releases whatever no longer fits; a released resource rebuilds on next use.

pub const fn render_profile(&self) -> &RenderProfile

The caller-authored presentation recipe.

pub const fn resolved_render_plan(&self) -> &ResolvedRenderPlan

The sanitized plan consumed by the frame loop.

impl<D: Device> Engine<D>

pub const fn derived_cache_usage(&self) -> DerivedCacheUsage

Returns current and peak recomputable cache charges in constant time.

pub fn residency_metrics(&self) -> ResidencyMetrics

Returns real workspace and lifecycle counters without scanning scene data.

pub fn residency_counters(&self) -> ResidencyCounters

Returns flat cumulative counters plus the current resident-byte gauge.

pub fn ligand_pose_stats(&self) -> LigandPoseStats

Returns compact ligand workload counters without scanning the scene.

Trait Implementations

impl<D: Debug + Device> Debug for Engine<D>

where D::Queue: Debug, D::Surface: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.