Struct Renderer 

pub struct Renderer { /* private fields */ }

Renders graphs of sources, effects, transitions and composites on one GPU device, and owns the pipelines, pools and caches they use.

Implementations

impl Renderer

pub fn register_builtins(&mut self) -> Result<Vec<EffectId>, ShaderDiagnostics>

Registers the full built-in catalog; pipelines are made on first draw or Self::warmup. Built-ins cannot be removed through the host-effect methods.

Errors

Returns diagnostics from the first definition that fails.

pub fn register_builtin_chroma_key( &mut self, ) -> Result<EffectId, ShaderDiagnostics>

Registers the built-in chroma-key effect.

Errors

Returns schema diagnostics when registration fails.

pub fn register_builtin_gaussian_blur( &mut self, ) -> Result<EffectId, ShaderDiagnostics>

Registers the public Gaussian blur and its internal pass.

Errors

Returns schema diagnostics when registration fails.

pub fn register_builtin_lut_3d(&mut self) -> Result<EffectId, ShaderDiagnostics>

Registers the built-in 3D LUT effect.

Errors

Returns schema diagnostics when registration fails.

pub fn register_builtin_transitions( &mut self, ) -> Result<Vec<EffectId>, ShaderDiagnostics>

Registers all built-in transition definitions.

Errors

Diagnostics from the first failure; earlier definitions stay registered.

impl Renderer

pub fn register_lut3d( &mut self, id: impl Into<String>, data: &Lut3dData, ) -> Result<(), RenderError>

Uploads or replaces one filterable 3D LUT resource; on failure the registry is unchanged.

Errors RenderError::InvalidEffectResource for an invalid id, shape, sample or

device-incompatible edge length, and RenderError::Gpu when the device cannot create the texture (native only; a browser reports it as an uncaptured error).

pub fn unregister_effect_resource(&mut self, id: &str) -> bool

Removes one uploaded resource, clearing cached results; returns whether it existed.

pub fn clear_effect_resources(&mut self)

Removes all uploaded effect resources and clears the cached results.

impl Renderer

pub fn graph_cache_key( &self, graph: &RenderGraph<'_>, ) -> Result<RenderCacheKey, GraphError>

A deterministic key for the graph and the settings that affect its pixels (blend space, applied quality controls, intermediate format). Adapters that store pictures alike give equal keys.

Errors

Returns GraphError::MissingOutput when no output was selected.

pub fn warmup_graph( &self, graph: &RenderGraph<'_>, ) -> Result<WarmupReport, ShaderDiagnostics>

Initializes all pipelines referenced by one graph.

Errors

Returns graph validation errors or diagnostics for an unknown effect.

pub fn warmup_graphs( &self, graphs: &[&RenderGraph<'_>], ) -> Result<WarmupReport, ShaderDiagnostics>

Initializes the deduplicated pipeline set referenced by project graphs.

Errors

Returns diagnostics for a malformed graph or an unknown effect.

pub fn execute_graph( &self, graph: &RenderGraph<'_>, ) -> Result<RenderedTexture, GraphError>

Executes the reachable portion of a graph and returns its owned output.

Errors

Returns a structural error or the first rendering failure.

impl Renderer

pub fn render_graph( &self, graph: &RenderGraph<'_>, sources: &[&PendingSourceWork], ) -> Result<RenderedTexture, RenderError>

Renders a graph, folding its sources’ pending presentation work into the same submission.

sources are in encode order; work another consumer already submitted is skipped.

Errors

Returns RenderError when the graph or a render target is invalid.

pub fn render_graph_yuv420p( &self, graph: &RenderGraph<'_>, sources: &[&PendingSourceWork], encoding: YuvEncoding, ) -> Result<Yuv420pReadback, RenderError>

Renders a graph, converts it to YUV420, and submits it with its sources’ pending work in one command buffer. The output size must be even.

Errors

Returns RenderError for invalid graph, target, or YUV layout data.

pub fn render_graph_yuv420p_timed( &self, graph: &RenderGraph<'_>, sources: &[&PendingSourceWork], encoding: YuvEncoding, timings: &mut FrameSubmitTimings, ) -> Result<Yuv420pReadback, RenderError>

Renderer::render_graph_yuv420p that also writes every span after graph_build to timings.

Errors

Returns RenderError for invalid graph, target, or YUV layout data.

impl Renderer

pub fn render_quad( &self, size: RenderSize, source: [u8; 4], ) -> Result<RenderedTexture, RenderError>

Draws one premultiplied RGBA texel over an opaque clear target.

Errors

Returns RenderError::Gpu when the GPU rejected the draw.

impl Renderer

pub fn upload_rgba8( &self, size: RenderSize, pixels: &[u8], ) -> Result<UploadTexture, RenderError>

Uploads tightly packed premultiplied sRGB RGBA8 pixels into a pooled upload texture.

Errors

RenderError::InvalidImageData when pixels is not four bytes per pixel.

pub fn upload_linear_rgba16f( &self, size: RenderSize, pixels: &[u16], ) -> Result<UploadTexture, RenderError>

Uploads tightly packed premultiplied linear RGBA half floats (BT.709, 1.0 = SDR white) for Renderer::prepare_linear_presented.

Errors

RenderError::InvalidImageData when pixels is not four halves per pixel.

pub fn write_linear_rgba16f( &self, size: RenderSize, plane: SourcePlane<'_>, ) -> Result<UploadTexture, RenderError>

Writes strided little-endian RGBA half-float rows into a pooled upload texture.

Errors

RenderError::InvalidImageData for a plane shorter than size.

pub fn read_rgba8( &self, target: &RenderedTexture, ) -> Result<Vec<u8>, RenderError>

Copies one RGBA8 render result into tightly packed premultiplied host memory.

Blocks on the GPU, so native and test only; callers that cannot block use Renderer::begin_rgba8_readback. Half-float intermediates are quantized to RGBA8 on the GPU first.

Errors

RenderError::TextureReadback for another target format or a failed mapping.

pub fn begin_rgba8_readback( &self, target: &RenderedTexture, ) -> Result<Rgba8Readback, RenderError>

Submits a readback copy and returns an unmapped handle.

The copy is queued on return, so mapping can resolve on an event loop via Rgba8Readback::map_async. Used for stills, thumbnails and goldens; exports use YUV or NV12 readbacks instead.

Errors

RenderError::TextureReadback for an unsupported format or unrepresentable row layout.

pub fn begin_yuv420p_readback( &self, target: &RenderedTexture, encoding: YuvEncoding, ) -> Result<Yuv420pReadback, RenderError>

Converts a render result to 8-bit planar YUV420 on the GPU and submits an async readback.

The size must be even. Chroma is filtered for the siting encoding.chroma names (alpha2_media::VideoCodec::chroma_location).

Errors

RenderError::TextureReadback for unsupported formats, odd dimensions or unrepresentable layouts.

pub fn begin_layout_readback( &self, target: &RenderedTexture, encoding: YuvEncoding, layout: PixelLayout, ) -> Result<Yuv420pReadback, RenderError>

Reads a render result back as stored and packs it into layout on the CPU (Yuv420pReadback::finish_into_planes), for outputs other than 8-bit 4:2:0.

10-bit output requires the rgba16float intermediate.

Errors

RenderError::TextureReadback for an unsupported format, a 10-bit layout over an 8-bit target, or an unrepresentable row layout.

impl Renderer

pub async fn register_effect( &mut self, definition: EffectDef, ) -> Result<EffectId, ShaderDiagnostics>

Validates, compiles and registers a runtime effect: Self::compile_effect, PendingEffect::compiled, then Self::register_compiled.

Holds the renderer until the device answers; a host that needs the renderer meanwhile calls the three steps itself.

Errors

Returns schema or WGSL diagnostics without mutating the registry.

pub fn compile_effect( &self, definition: EffectDef, ) -> Result<PendingEffect, ShaderDiagnostics>

Validates a runtime effect and creates its shader module and pipeline without waiting for the verdict.

All error scopes open and close within this call, so overlapping registrations never share one.

Errors

Schema diagnostics, a duplicate id or a full registry, without touching the device.

pub fn register_compiled( &mut self, compiled: CompiledEffect, ) -> Result<EffectId, ShaderDiagnostics>

Adds an effect this renderer compiled.

Errors

Refuses an effect from another device, one registered meanwhile, or a full registry.

pub fn effect_uniform_layout(&self, id: &EffectId) -> Option<&UniformLayout>

The generated host uniform layout of a registered effect.

pub fn effect_definition(&self, id: &EffectId) -> Option<&EffectDef>

The definition of a registered effect.

pub fn effect_reads_time(&self, id: &EffectId) -> bool

Whether id’s output can change with frame time alone; true for unknown effects.

Derived from the WGSL of every pass: a body that never names time, time_ticks or runtime cannot read it. Callers may pass any time to an effect answering false, so its result can be reused across frames.

pub fn is_effect_registered(&self, id: &EffectId) -> bool

Whether an exact effect version is registered.

pub fn is_effect_project_visible(&self, id: &EffectId) -> bool

Whether a project document may reference the effect.

pub fn project_effect_id(&self, id: &str, version: u32) -> Option<&EffectId>

The registered identity a project reference to id@version draws with, if the project may reference it. Allocation-free.

pub fn unregister_effect(&mut self, id: &EffectId) -> bool

Removes one runtime effect and releases its GPU resources.

pub fn clear_effects(&mut self)

Removes every host-registered runtime effect.

pub fn warmup(&self, effects: &[EffectId]) -> Result<(), ShaderDiagnostics>

Confirms the effects are registered and creates pending built-in pipelines (including their passes) so the first frame does not wait on the compiler.

Errors

Names the first unregistered effect.

impl Renderer

pub fn new(gpu: GpuContext) -> Self

Creates a renderer that owns the supplied GPU context.

pub fn take_frame_gpu_times(&self) -> Result<FrameGpuTimes, &'static str>

GPU time of the export frames sampled since the last call, then resets the totals.

Every eighth frame of Self::render_graph_nv12_timed or Self::render_graph_yuv420p_timed is timed and read back later without waiting.

Errors

The device has no timestamp queries.

pub fn gpu_error_reports(&self) -> GpuErrorReports

Where an embedding reports errors from its uncaptured-error handler.

Needed only in a browser, where error scopes resolve after the frame returns. After a report the renderer drops its cached results and pooled resources, and treats a missing readback canary as that error rather than as dropped work.

pub fn with_gpu_error_reports(self, reports: GpuErrorReports) -> Self

This renderer, using reports for GPU errors the embedding saw before it existed.

pub fn gpu_capabilities(&self) -> &Capabilities

Tier, intermediate format, adapter and limits of the GPU.

pub fn set_gpu_wait_timeout(&mut self, timeout: Duration)

Sets how long a native GPU wait may take before RenderError::GpuTimeout.

pub fn gpu_lost(&self) -> Option<RenderError>

Why the device can no longer run work, once known.

Either a readback canary showed dropped work (RenderError::GpuWorkDropped) or resources could no longer be created (RenderError::GpuDeviceLost). Later readbacks and NV12 packs fail with this error; a host should report it and restart the process.

pub fn mark_frame(&self, frame: Option<FrameMark>)

Marks the frame later submissions render, for RenderError::GpuDeviceHung reports.

pub fn longest_submission(&self) -> Option<SubmissionReport>

The recent submission, possibly still running, that kept the GPU busy longest.

pub fn classify_loss(&self, error: RenderError) -> RenderError

Classifies error using this renderer’s submission times.

A device loss or timeout becomes RenderError::GpuDeviceHung when a recent submission ran for at least half the GPU watchdog (alpha2_gpu::hung_threshold_ms). Other errors pass through.

pub fn loss_classifier(&self) -> LossClassifier

Renderer::classify_loss as an owned handle, for readbacks finished on an event loop.

pub fn confirm_gpu_work(&self) -> Result<(), RenderError>

Waits for every submitted NV12 pack and repack and checks that the GPU ran it.

These submissions read nothing back, so a canary is the only proof the planes were written. Exports call this after the last frame. Safe while another thread polls the device (the macOS VideoToolbox worker does).

Errors

RenderError::GpuWorkDropped when a canary is missing, or RenderError::GpuTimeout when work or a mapping report does not arrive in time.

pub const fn gpu_wait_timeout(&self) -> Duration

How long a native wait on GPU work may take.

pub fn reclaim_external_leases(&self) -> Result<usize, RenderError>

Releases every native lease whose GPU work has finished, returning how many.

A decoder surface returns only after the submission sampling it completes, so a caller out of surface budget can call this and retry. Unsubmitted work is not waited on.

Errors

A readback error if the device cannot be polled.

pub fn take_frame_submissions(&self) -> Option<FrameSubmissions>

How the last frame was submitted; each frame’s is returned once.

pub fn take_gpu_submission_stats(&self) -> GpuSubmissionStats

Submission split counts since the last call, then resets them.

pub fn pass_timing_enabled(&self) -> bool

Returns whether per-pass timing is being collected.

pub fn set_pass_timing_enabled(&self, enabled: bool)

Enables or disables per-pass timing collection. Disabled by default.

While off, no clock is read and no timestamp resources are created. Turning it off drops the retained timing history. Other diagnostics are always available.

pub fn texture_pool_stats(&self) -> TexturePoolStats

Returns allocation and reuse counters for intermediate render targets.

pub fn clear_texture_pool(&self)

Destroys all currently idle intermediate textures.

pub fn release_idle_memory(&self) -> u64

Destroys GPU memory held only for reuse (idle pools and kept graph results) and returns the bytes freed.

Resources are destroyed rather than dropped so browser WebGPU frees them immediately. Nothing still in use is released, and submitted work completes first, so this is safe between calls.

pub fn set_texture_budget_bytes(&self, budget_bytes: u64)

Sets the soft byte budget for idle intermediate textures, evicting down to it now.

pub fn set_gpu_memory_budget(&self, budget_bytes: Option<u64>) -> bool

Records the adapter’s memory budget (None if unreported) and caps idle pools at a quarter of it. Returns whether a pool budget was lowered.

pub fn gpu_memory_budget(&self) -> Option<u64>

The adapter’s device memory budget, when reported.

pub fn set_quality_controls( &self, max_filter_samples: u32, motion_blur_subframes: u32, )

Applies filter and temporal sampling controls.

The filter budget is capped at Self::filter_sample_limit; a reduction is reported as crate::CapabilityDiagnostic::FilterSamplesReduced. Kept results are dropped only when the applied values change.

pub fn filter_sample_limit(&self) -> u32

RenderQualityControls::MAX_FILTER_SAMPLES, or 16 on a Tier-B device.

pub fn set_result_cache_budget(&self, budget_bytes: u64)

Lets kept graph results use up to budget_bytes (see crate::RenderGraph::set_cache_intent); zero, the default, disables the cache. The texture pool budget does not count these results.

pub fn clear_result_cache(&self)

Drops every kept graph result.

pub fn result_cache_stats(&self) -> ResultCacheStats

The result cache’s counters.

pub fn content_epoch(&self) -> u64

Changes whenever a graph with an unchanged Self::graph_cache_key may render differently (any result-cache clear or reported GPU error). Equal keys under an equal epoch mean equal pixels.

pub fn quality_controls(&self) -> RenderQualityControls

Returns the active render quality controls.

pub fn diagnostics(&self) -> RenderDiagnostics

Returns a stable snapshot for telemetry or benchmark output.

pub fn take_pipeline_creations(&self) -> Vec<PipelineCreation>

Pipeline creations since the last call, oldest first (at most 256), with start and end times.

pub fn record_frame_outcome(&self, presented: bool, repeated: bool)

Records a host presentation outcome without imposing a product clock.

pub fn record_decoder_wait(&self, duration: Duration)

Adds time spent waiting for a host decoder or refill operation.

pub fn pipeline_cache_stats(&self) -> PipelineCacheStats

Returns the number of cached runtime and built-in pipelines.

pub const fn with_blend_space(self, blend_space: BlendSpace) -> Self

Selects the single color space used by all layer blending.

pub const fn blend_space(&self) -> BlendSpace

Returns the configured layer-compositing color space.

pub fn render_solid( &self, size: RenderSize, color: Color, ) -> Result<RenderedTexture, RenderError>

Clears an offscreen RGBA texture and submits it to the GPU queue.

Errors

Returns RenderError for an invalid size or color.

impl Renderer

pub fn render_generator( &self, id: &EffectId, size: RenderSize, params: &EffectParams<'_>, runtime: EffectRuntime, ) -> Result<RenderedTexture, RenderError>

Draws a registered generator at size.

Errors

RenderError for an unknown or non-generator effect or mismatched parameters; RenderError::MissingEffectResource when it declares a resource (use Renderer::render_generator_with_resources).

pub fn render_generator_with_resources( &self, id: &EffectId, size: RenderSize, params: &EffectParams<'_>, resources: &EffectResources, runtime: EffectRuntime, ) -> Result<RenderedTexture, RenderError>

Draws a registered generator at size with named external resources.

Errors

RenderError for an unknown or non-generator effect, mismatched parameters, or a resource not bound to a registered one of its kind.

impl Renderer

pub fn prepare_rgba_presented( &self, source: UploadTexture, source_size: RenderSize, presentation: SourcePresentation, alpha: SourceAlpha, ) -> Result<PreparedSourceTexture, RenderError>

Prepares an uploaded RGBA texture for presentation by its first consumer, without submitting.

Errors

Returns an image-data error for invalid presentation metadata.

pub fn prepare_linear_presented( &self, source: UploadTexture, source_size: RenderSize, presentation: SourcePresentation, ) -> Result<PreparedSourceTexture, RenderError>

Prepares premultiplied linear BT.709 RGBA (Self::upload_linear_rgba16f) like Self::prepare_rgba_presented.

Filtered in linear light, then stored sRGB-encoded and premultiplied with the curve extended beyond [0, 1] as far as the intermediate holds. Color under zero alpha is dropped.

Errors

Returns an image-data error for invalid presentation metadata.

pub fn prepare_rgba8_presented( &self, pixels: SourcePlane<'_>, size: RenderSize, presentation: SourcePresentation, ) -> Result<PreparedSourceTexture, RenderError>

Uploads a straight-alpha RGBA8 plane and prepares it like Self::prepare_rgba_presented.

Errors

Returns an image-data error for a short plane or invalid presentation metadata.

pub fn submit_pending_source(&self, pending: &PendingSourceWork) -> bool

Submits one pending source presentation now.

Returns false when another consumer already did, or when staging or submission fails; the work then stays pending for a later frame.

pub fn render_yuv420p( &self, frame: Yuv420Frame<'_>, policy: ColorPolicy, ) -> Result<(RenderedTexture, Vec<ColorDiagnostic>), RenderError>

Uploads YUV planes and converts them on the GPU to premultiplied sRGB storage. Transfer decoding precedes sRGB encoding and premultiplication.

Errors

An image-data error for malformed planes or alpha, and RenderError::UnsupportedHdr when ColorPolicy::RejectHdr meets an HDR source.

pub fn render_yuv420p_presented( &self, frame: Yuv420Frame<'_>, presentation: SourcePresentation, policy: ColorPolicy, ) -> Result<(RenderedTexture, Vec<ColorDiagnostic>), RenderError>

Uploads and converts YUV420P with crop, sample aspect, rotation, scaling (bilinear, footprint-averaged when shrinking) and transparent contain placement on the GPU.

Errors

An image-data error for malformed planes, metadata or alpha, and RenderError::UnsupportedHdr when ColorPolicy::RejectHdr meets an HDR source.

pub fn prepare_yuv420p_presented( &self, frame: Yuv420Frame<'_>, presentation: SourcePresentation, policy: ColorPolicy, ) -> Result<(PreparedSourceTexture, Vec<ColorDiagnostic>), RenderError>

Uploads YUV420 planes and defers their conversion to the first consuming frame’s encoder.

Errors

An image-data error for malformed input, and RenderError::UnsupportedHdr when ColorPolicy::RejectHdr meets an HDR source.

pub fn prepare_yuv_presented( &self, frame: YuvFrame<'_>, presentation: SourcePresentation, policy: ColorPolicy, ) -> Result<(PreparedSourceTexture, Vec<ColorDiagnostic>), RenderError>

Uploads planar or semi-planar YCbCr of any supported subsampling and depth, prepared like Self::prepare_yuv420p_presented.

Samples above 8 bits upload as 16-bit normalized textures, or as u16 containers the GPU normalizes on devices without them.

Errors

An image-data error for an unsupported format or malformed planes, and RenderError::UnsupportedHdr when ColorPolicy::RejectHdr meets an HDR source.

Trait Implementations

impl Debug for Renderer

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

Formats the value using the given formatter.

impl EffectCatalog for Renderer

fn effect_definition(&self, id: &EffectId) -> Option<&EffectDef>

The definition registered as id.

fn effect_reads_time(&self, id: &EffectId) -> bool

Whether id’s output can change with frame time alone; true for unknown effects.

fn project_effect_id(&self, id: &str, version: u32) -> Option<&EffectId>

The identity a project’s effect id@version draws under; None if this renderer cannot draw it or it is internal.

impl RenderControls for Renderer

fn set_quality_controls( &self, max_filter_samples: u32, motion_blur_subframes: u32, )

Sets the filter sample budget (possibly capped lower) and motion blur subframe count.

fn set_texture_budget_bytes(&self, budget_bytes: u64)

Sets the byte budget of pooled pictures kept for reuse.

fn content_epoch(&self) -> u64

Changes whenever earlier results may differ from what the same graph draws now.

fn record_frame_outcome(&self, presented: bool, repeated: bool)

Records whether a frame was presented and whether it repeated the previous one.

fn graph_cache_key( &self, graph: &RenderGraph<'_>, ) -> Result<RenderCacheKey, GraphError>

A deterministic key for what graph draws on this renderer.