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 async fn register_builtins( &mut self, ) -> Result<Vec<EffectId>, ShaderDiagnostics>

Compiles and registers the complete built-in effect and transition catalog.

Built-ins are engine-owned and cannot be removed through the host-effect lifecycle methods.

Errors

Returns diagnostics from the first definition that fails.

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

Compiles and registers the built-in chroma-key effect.

Errors

Returns schema or compiler diagnostics when registration fails.

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

Compiles and registers the public Gaussian blur and its internal pass.

Errors

Returns schema or compiler diagnostics when registration fails.

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

Compiles and registers the built-in 3D LUT effect.

Errors

Returns schema or compiler diagnostics when registration fails.

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

Compiles and registers all built-in transition definitions.

Errors

Returns diagnostics from the first definition that fails. Definitions compiled before that point remain registered.

impl Renderer

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

Uploads or replaces one filterable 3D lookup-table resource.

Errors

Returns RenderError::InvalidEffectResource for an invalid identity, cube shape, sample, or device-incompatible edge length, and RenderError::Gpu when the device cannot make the texture (natively; a browser reports that as an uncaptured error). A resource that fails leaves the registry as it was.

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

Removes one uploaded effect resource and returns whether it existed.

Removing one clears the cached results, since they may have used it.

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>

Returns a deterministic key for the graph and the renderer configuration that changes its pixels: the blend space, the quality controls (as passes take them), and the intermediate format. Two renderers on 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 and folds its sources’ pending presentation work into the same queue submission.

sources are the one-shot presentation passes behind the graph’s source textures, in the order they should be encoded. 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 both workloads and its sources’ pending presentation work in one command buffer.

The graph’s output size must be even for chroma subsampling.

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>

Renders a graph for YUV420 readback and reports where the call went.

This produces exactly what Renderer::render_graph_yuv420p produces; the only difference is that it reads a clock between stages and 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 for shader sampling, into a texture from the renderer’s upload pool.

Errors

Returns RenderError::InvalidImageData when pixels does not contain exactly four bytes per declared pixel.

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

Uploads tightly packed premultiplied linear-light RGBA as IEEE 754 half floats (their bits), in BT.709 primaries with 1.0 at SDR white, for Renderer::prepare_linear_presented.

Errors

Returns RenderError::InvalidImageData when pixels does not contain exactly four halves per declared pixel.

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

Writes rows of little-endian RGBA half floats plane.stride bytes apart into a pooled upload texture.

Errors

Returns 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 host memory.

The returned pixels retain alpha2’s premultiplied-alpha convention.

This blocks on GPU completion, so it exists only for native and test callers. A caller that cannot block uses Renderer::begin_rgba8_readback and maps on its event loop: no browser thread may wait on the device, and a wait would never see the mapping resolve.

Half-float negotiated intermediates are clamped and quantized to RGBA8 by a cached GPU pass before mapping.

Errors

Returns RenderError::TextureReadback for another target format or when the GPU buffer cannot be mapped.

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

Submits a readback copy and returns a handle that has not been mapped.

The copy is already queued when this returns, so the caller only has to wait for Rgba8Readback::map_async to report readiness: mapping can resolve on an event loop instead of blocking, and the result never travels through a presentation surface. RGBA8 readbacks serve stills, thumbnails and golden images. No export reads RGBA8: a browser export reads Renderer::begin_yuv420p_readback’s planes through Yuv420pReadback::map_async and the wgpu interop’s Yuv420pReadback::finish_mapped, and a native one packs YUV or NV12.

Errors

Returns RenderError::TextureReadback for an unsupported target format or a row layout that cannot be represented.

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

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

The output size must be even because both chroma planes are subsampled by two in each dimension. Each chroma sample is filtered for where encoding.chroma sites it: the location the output codec implies (alpha2_media::VideoCodec::chroma_location).

Errors

Returns RenderError::TextureReadback for unsupported formats, odd dimensions, or layouts that cannot be represented.

impl Renderer

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

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

The returned future works on native and browser WebGPU backends because compilation diagnostics are asynchronous in the WebGPU API. It holds the renderer for as long as the device takes to answer; a host that must use 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 definition and creates its shader module and pipeline, without waiting for the device’s verdict on them.

Everything is created, and every error scope pushed and popped, within this call, so registrations that overlap never share a scope.

Errors

Returns schema diagnostics, or refuses an effect already registered 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 compiled on another device, one registered while it compiled, and a registry that filled meanwhile.

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

Returns the generated host uniform layout for a registered effect.

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

Returns the immutable definition for a registered effect.

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

Whether what id draws can change with the frame time alone: whether its body, or for a built-in drawn as several passes the body of any of them, can read time() or time_ticks() (EffectRuntime::time). An effect that is not registered answers true.

The answer comes from the WGSL itself, so it cannot disagree with the shader: a body that never names time, time_ticks or runtime, the uniform they read, cannot reach the frame time, and every other body is taken to read it. A caller may then pass any time to an effect that answers false (the timeline passes zero), so its result is found again in another frame from the same inputs and parameters.

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

Returns whether an exact effect version has been compiled.

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

Returns whether an effect may be referenced by a project document.

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

The identity a project’s reference to effect id version version draws with: the one it is registered under, when a project may reference it (Self::is_effect_project_visible). Looking it up and cloning it allocate nothing, so a frame names its effects without copying their text.

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

Removes one compiled 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 that all requested effect versions have compiled pipelines.

Registration eagerly compiles pipelines, so this operation is deterministic and primarily validates a project’s dependency set.

Errors

Returns a diagnostic naming the first unregistered effect.

impl Renderer

pub fn new(gpu: GpuContext) -> Self

Creates a renderer that owns the supplied GPU context.

pub fn gpu_error_reports(&self) -> GpuErrorReports

Where an embedding reports the GPU errors its device’s uncaptured-error handler receives, on a backend whose error scopes resolve only after a frame has returned: the browser. The renderer then drops the results it kept and the resources it pooled before its next frame, since the error may have come from any of them, and reads a readback canary missing after such a report as that error rather than as a device that drops work.

A native embedding does not need it: there every frame’s own scopes resolve before the frame returns, and fail it (RenderError::Gpu).

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

This renderer, hearing of GPU errors through reports (see Renderer::gpu_error_reports): for an embedding that installs its device’s error handler before the renderer exists.

pub fn gpu_capabilities(&self) -> &Capabilities

What the GPU this renderer drives offers: tier, intermediate format, adapter, and limits.

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

Sets how long a native wait on GPU work may take before it fails with RenderError::GpuTimeout. Readbacks begun afterwards use it.

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

Why this renderer’s device can no longer run work, once it found out: it completed work without running it, which a readback’s missing canary showed (RenderError::GpuWorkDropped), or it could not make the resources a frame needs any more (RenderError::GpuDeviceLost). From then on this renderer’s readbacks and NV12 packs fail with that error; a host should answer what it was doing and start a new process.

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

Waits for every NV12 pack and repack submitted so far and checks that the GPU ran each of them.

Those submissions read nothing back, so a device that completes work without running it (see RenderError::GpuWorkDropped) hands the encoder planes it never wrote. Each frame checks the canaries of the ones before it that have finished; an export calls this after its last frame, so that the last few are checked before it reports success.

It may run while another thread polls the same device, as the macOS VideoToolbox encode worker does: a canary’s mapping then reports on that thread, and this waits for the report.

Errors

Returns RenderError::GpuWorkDropped when a canary is missing, or RenderError::GpuTimeout when the work does not complete, or a canary’s mapping does not report, within the wait timeout.

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.

Waiting on the queue is what makes progress possible: a decoder surface is only returned once the submission sampling it completes, so a caller that has run out of surface budget can call this and retry rather than failing the export. Surfaces held by work that has not been submitted yet are unaffected, so this never waits for something that cannot happen.

A completed submission’s leases are parked by its queue callback, which runs on whichever thread’s poll collected it; this waits, up to the wait timeout, for every submitted one to be parked, then drops them.

Returns how many leases it released.

Errors

Returns a readback error if the device cannot be polled.

Native only: a browser cannot block on the queue, and its external frames are released by the event loop.

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.

Timing is a profiling aid, not part of rendering. While it is off no clock is read, no pass record is taken, and no GPU timestamp resources are created, so the render path carries none of its cost. Turning it off also drops the retained history that Renderer::diagnostics reports, and the GPU timestamp of a pass encoded before then, whose read lands later, is dropped with it.

Every other diagnostic (adapter identity, texture pool and pipeline counters, and frame outcomes) stays available at all times because it costs nothing per pass.

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

Gives back the GPU memory the renderer holds only for reuse: idle intermediate and upload textures, idle readback, uniform and canary buffers, and kept graph results. Each is destroyed, not only dropped, so the browser’s WebGPU frees it now rather than at garbage collection. Nothing a render, a readback, or a caller still holds is released (a kept result the caller also holds stays with the caller), and work already submitted completes first, so this is safe at any point between calls. Later work allocates again what it needs.

Returns the bytes this destroyed. If another thread is recording renderer work at that moment, the destruction waits for that work to be submitted, and is counted here all the same.

pub fn set_texture_budget_bytes(&self, budget_bytes: u64)

Sets the soft byte budget for idle reusable intermediate textures.

Existing idle textures are evicted immediately until the pool is within the new budget. In-flight textures are considered when they return.

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

Applies filter and temporal sampling controls.

The filter sample budget is applied up to Self::filter_sample_limit, since no pass takes more; a reduced budget is reported in Self::diagnostics as crate::CapabilityDiagnostic::FilterSamplesReduced, and the plan, the diagnostics and the result cache all see the applied one. Kept results are dropped only when what is applied changes.

pub fn filter_sample_limit(&self) -> u32

The most filter samples a pass of this renderer takes: RenderQualityControls::MAX_FILTER_SAMPLES, or 16 on a Tier-B device (see crate::filter_sample_limit).

pub fn set_result_cache_budget(&self, budget_bytes: u64)

Lets kept graph results occupy up to budget_bytes (see crate::RenderGraph::set_cache_intent); zero, the default, turns the cache off and drops what it holds. Kept results come out of the same GPU memory as the texture pool, which does not count them.

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

A counter that changes whenever this renderer may draw a graph with an unchanged Self::graph_cache_key differently: on every event that clears the result cache (effects, effect resources, quality controls, an explicit clear) whether or not it held anything, and on every GPU error reported for earlier work. Equal keys under an equal epoch name equal pixels, so a player can keep showing a frame instead of drawing it again.

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 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

Returns RenderError when the generator is unknown, is not a generator, or supplied parameters do not match the registered schema; RenderError::MissingEffectResource when it declares a resource, which Renderer::render_generator_with_resources binds.

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

Returns RenderError when the generator is unknown, is not a generator, supplied parameters do not match the registered schema, or a declared resource is 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 frame consumer, without issuing a queue submission.

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 an uploaded texture of premultiplied linear-light RGBA in BT.709 primaries (Self::upload_linear_rgba16f) for presentation like Self::prepare_rgba_presented. It is filtered in linear light and stored like every presented source, sRGB-encoded and premultiplied, the curve extended to keep values above 1.0 and below 0.0 as far as the intermediate format holds them. Color with zero alpha is not kept.

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 into a pooled texture and prepares its presentation like Self::prepare_rgba_presented.

Errors

Returns an image-data error for a plane shorter than size or invalid presentation metadata.

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

Submits one pending source presentation immediately.

Returns false when another consumer already submitted the work, and also when the source’s lease cannot stage its native synchronization or the submission fails: the work then stays pending, and a later consumer’s frame submits it.

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

Uploads YUV planes and converts them into premultiplied sRGB storage on the GPU, ready for effects, layer composition, and presentation. Transfer decoding happens before sRGB encoding and premultiplication.

Errors

Returns an image-data error for malformed planes or alpha values, and RenderError::UnsupportedHdr when ColorPolicy::RejectHdr meets an HDR source (the other policies tone-map it or skip it, and report which in the diagnostics).

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

Uploads and converts YUV420P while applying crop, sample aspect ratio, rotation, scaling (bilinear, averaged over the footprint when it shrinks), and transparent contain placement on GPU.

Errors

Returns an image-data error for malformed planes, presentation metadata or alpha values, and RenderError::UnsupportedHdr when ColorPolicy::RejectHdr meets an HDR source (the other policies tone-map it or skip it, and report which in the diagnostics).

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

Uploads YUV420 planes and prepares their conversion for the command encoder of the first frame that consumes the result.

Errors

Returns an image-data error for malformed input, and RenderError::UnsupportedHdr when ColorPolicy::RejectHdr meets an HDR source (the other policies tone-map it or skip it, and report which in the diagnostics).

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, and prepares its conversion like Self::prepare_yuv420p_presented.

Samples above eight bits upload as 16-bit normalized textures, or, on a device without them, as the unsigned 16-bit containers they are, which the conversion normalizes on the GPU.

Errors

Returns an image-data error for an unsupported format or malformed planes, and RenderError::UnsupportedHdr when ColorPolicy::RejectHdr meets an HDR source (the other policies tone-map it or skip it, and report which in the diagnostics).

Trait Implementations

impl Debug for Renderer

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

Formats the value using the given formatter.