Skip to main content

Crate egui_shader_layers

Crate egui_shader_layers 

Source
Expand description

GPU shader layers for egui: a shape that takes everything already painted beneath a rect and redraws that region through a chain of WGSL filter passes — blur, colour adjustments, refraction, or your own shader.

// Once, at startup (eframe: `cc.gl` in your app creator):
egui_shader_layers::install_glow(ctx, cc_gl).ok();
use egui_shader_layers::{ShaderLayer, presets};
// Every frame, after painting whatever should end up blurred:
let rect = egui::Rect::from_min_size(egui::pos2(40.0, 40.0), egui::vec2(240.0, 160.0));
ShaderLayer::new(rect, presets::gaussian_blur(8.0).then(presets::saturation(1.3)))
    .corner_radius(16)
    .paint(ui.painter());

What the crate offers, each detailed below:

§Semantics

  • “Beneath” means earlier in egui’s paint order: lower layers and the shapes painted earlier into the same layer. Content painted later — later shapes of the same layer, higher egui::Order areas, popups, tooltips — is drawn on top and is not filtered.
  • The filter is view-only: it never touches egui textures or your data.
  • Neighbourhood effects need padding. The capture is the layer rect expanded by the chain’s total sample radius (FilterChain::padding_points), clamped to the screen. At the screen edge, sampling clamps to the last available pixel.
  • Precision: the backdrop is captured as 8-bit, gamma-encoded, premultiplied RGBA — exactly what egui wrote. Intermediate pass textures are RGBA16F where the backend can render to it (wgpu where the adapter supports it, desktop GL 3.3, WebGL2 with EXT_color_buffer_float), otherwise RGBA8; see BackendStatus::Active.
  • With no backend installed, or after a backend failure, layers draw nothing extra (the backdrop stays unfiltered). Nothing panics; check status.

§Writing an effect

An Effect is one WGSL function, validated by naga when you build it:

fn effect(uv: vec2<f32>) -> vec4<f32> {
    let wave = sin(uv.y * 40.0 + fl.time * 3.0) * params(0u).x;
    return src_px(vec2<f32>(wave, 0.0));
}

uv is the position of the pixel being written in the captured region: (0, 0) top-left, (1, 1) bottom-right, y down. The prelude provides:

namemeaning
src(uv)the pass input (bilinear, clamped to the captured region)
src_px(offset)the input at offset pixels OF THE INPUT from the current pixel (physical pixels unless the previous pass is scaled)
src_texel(), out_texel()one pixel of the pass’s input / of its own output, in uv units (both fl.texel at full resolution)
original(uv)the untouched captured backdrop (before any pass), in every pass of the chain
p.<name>a named parameter: member <name> of the snippet’s own struct Params (see below)
params(i)anonymous parameter slot i (0..16) of the Pass, a vec4<f32> (the untyped block; prefer named parameters)
fl.texelsize of one physical pixel in uv units (of the capture, also in scaled passes)
fl.size_pxcaptured region size in physical pixels
fl.rect_uvthe layer rect inside the capture (xy = min, zw = size), in uv units
fl.timeseconds (egui input time); reading it makes the effect animated (see below)
fl.delta_timeseconds since the previous frame: egui’s stable_dt clamped to 0..=0.1 (offline: OfflineOptions::with_delta_time, or the video frame step)
fl.frameframe counter, u32 (egui’s cumulative_frame_nr, wrapping; offline: the video frame index)
fl.pointerthe pointer: xy in uv units (outside 0..1 off the capture), z = 1 while the primary button is down, w = 1 when a pointer exists (w = 0: none, all zero)
fl.pixels_per_pointphysical pixels per layer point (egui’s scale factor × the layer transform’s zoom), to convert point distances to pixels
fl.pass_scalethis pass’s output resolution relative to the capture (Pass::with_scale; 1 = full)
to_linear(c), to_gamma(c)sRGB transfer functions on rgb (alpha untouched)
premultiply(c), unpremultiply(c), luma(rgb)colour helpers
tex(i, uv)user texture i (0..TEXTURE_SLOTS, attached with ShaderLayer::texture) at uv in the TEXTURE’s own 0..1 coordinates (top-left origin), through its own sampler (its egui TextureOptions: filters, wrap mode; mip level 0)
tex_size(i)size of user texture i in texels (vec2<f32>)
tex_load(i, px)the exact texel px (vec2<i32>, clamped to the texture) of user texture i, no filtering
state(uv)the layer’s persistent state at uv (bilinear; see Persistent state); zero without a state pass
state_load(px), state_px(offset)the exact state texel px (vec2<i32>, (0, 0) top-left, clamped) / the one under the current pixel offset by offset texels, no filtering
state_size(), state_texel()the state’s size in texels / one state texel in uv units
fl.pass_indexindex of this pass among the chain’s passes of its kind (state or display), u32: the substep number of consecutive state passes
region(), region_at(uv)the id (u32) of the Region that owns the current pixel / capture uv (its index in Mask::Regions); REGION_NONE outside every region and on layers without regions (see Masks)
REGION_NONE255u, the “no region” id (REGION_NONE in Rust)

An effect whose code reads fl.time is animated: painting a layer that uses it requests an egui repaint every frame, so it keeps moving in an otherwise idle app. The detection walks naga’s IR (a real fl.time access, not a text match); override it with Effect::with_animated. Reading fl.delta_time, fl.frame or fl.pointer does not: pointer changes arrive with input, which repaints anyway, and an effect that must advance every frame on its own reads fl.time or is marked with Effect::with_animated. The three are per frame, not per layer: every layer painted in one frame sees the same values.

§Named parameters

A snippet may declare struct Params { ... }; the crate then binds it as p and the effect reads p.<member>. Each Pass stores its own values, set by name and type-checked against the struct (Pass::set, Pass::with, Pass::set_slice for arrays); a mismatch is a ParamError, never a panic. Effect::params reflects the members (ParamInfo: name, ParamType, offset, array length) so a UI can build its controls from the effect alone. Members start at zero (WGSL has no default values).

use egui_shader_layers::{Effect, ParamError, ParamType, Pass};

let effect = Effect::new("tint", "
struct Params {
    color: vec4<f32>,
    amount: f32,
    stops: array<vec4<f32>, 4>,
}
fn effect(uv: vec2<f32>) -> vec4<f32> {
    return mix(src(uv), p.color, p.amount) + p.stops[0] * 0.0;
}")?;
assert_eq!(effect.params().len(), 3);
assert_eq!(effect.param("amount").map(|info| info.ty), Some(ParamType::F32));

let mut pass = Pass::new(&effect).with("color", [1.0, 0.5, 0.0, 1.0])?.with("amount", 0.25)?;
pass.set_slice("stops", &[[0.0_f32, 0.0, 0.0, 1.0]])?; // the remaining elements become zero
assert!(matches!(pass.set("amount", 1), Err(ParamError::Type { .. }))); // `1` is an i32

Accepted member types: f32, i32, u32, vec2<f32>, vec3<f32>, vec4<f32>, mat4x4<f32> and fixed-size arrays of vec3<f32> / vec4<f32> / mat4x4<f32> (uniform arrays need a 16-byte stride). Anything else (bool, nested structs, array<f32, N>) and a struct over 16 KiB (the WebGL2 uniform block limit) is an EffectError::Interface pointing at the declaration. The snippet must not declare its own module-scope p. Named and anonymous (params(i)) parameters can be used together.

§Textures

A layer attaches up to TEXTURE_SLOTS (3, on every backend) egui textures with ShaderLayer::texture — noise, normal maps, lookup tables, images — which its effects read with tex(i, uv), tex_size(i) and tex_load(i, px). Values are premultiplied gamma RGBA, like src(). Each texture is read through its own sampler only (its TextureOptions); exact reads use tex_load, which needs none.

use egui_shader_layers::{Effect, ShaderLayer, Pass};
// `noise` from `ctx.load_texture(.., egui::TextureOptions::LINEAR_REPEAT)`, kept alive.
let displace = Effect::new("displace", "
fn effect(uv: vec2<f32>) -> vec4<f32> {
    let n = tex(0u, uv * 4.0).rg - vec2<f32>(0.5);
    return src(uv + n * 8.0 * fl.texel);
}")?.with_sample_radius(4.0);
assert!(displace.reads_texture(0) && !displace.reads_texture(1));
ShaderLayer::new(rect, Pass::new(&displace)).texture(0, noise.id()).paint(ui.painter());

Which slots an effect reads is found in naga’s IR (Effect::reads_texture; a slot index that is not a constant counts as every slot). A layer whose effect reads a slot with nothing attached is refused before drawing — ShaderLayer::check_textures returns the TextureError, paint draws nothing and logs it once — never silently fed a dummy. A texture id the renderer does not know (freed: keep the TextureHandle alive) skips the layers attaching it and is listed by failed_textures. Offline runs attach an OfflineTexture with OfflineOptions::with_texture (features image / video).

§Impulses: transient effects from input

Impulses is a small collection you keep in your app state: push an impulse where the user clicked (Impulses::push_point, positions relative to the layer rect), and every frame hand it to presets::click_ripples (rings expanding from each click) or to your own effect through Impulses::apply, which fills the named parameters IMPULSES_PARAM (impulses: array<vec4<f32>, 16>, each (uv.x, uv.y, age_seconds, strength)) and IMPULSE_COUNT_PARAM (impulse_count: u32). Impulses age against the clock you pass (egui’s input.time in the UI, frame time offline), expire after their life, and a full collection drops the oldest first (IMPULSE_SLOTS at most). Such effects are not animated by fl.time: call Impulses::request_repaint_if_alive each frame, so the app repaints while a ring is alive and stays idle afterwards.

Colours are premultiplied-alpha, gamma-space RGBA in and out. Names starting with fl_ and the prelude names above are reserved. An effect cannot declare its own bindings or entry points. If it reads further than the current pixel, declare how far with Effect::with_sample_radius (or per pass with Pass::with_sample_radius).

§Persistent state

A state pass (Effect::new_state) writes the layer’s persistent state instead of the next image: two RGBA textures per layer (ping-pong) that survive from frame to frame — simulations (water, presets::wave_sim), trails (presets::trails), accumulation.

  • Reading. Every pass reads the latest state with state(uv) (bilinear), state_load(px) / state_px(offset) (exact texels) — a display pass sees what the last state pass BEFORE it wrote (or last frame’s state), a state pass the state it steps. Inside a state pass src() is the display chain’s input at that point (a state pass does not advance it), original() the backdrop. N consecutive state passes are N substeps (fl.pass_index = 0..N).
  • Identity. A layer whose chain has a state pass needs ShaderLayer::id: the state is kept per id and viewport. Without an id it is refused (ShaderLayer::check_state: StateError::MissingId; it draws nothing, logged once). Painting one id twice in a frame steps it once (the second paint shows the state as it is).
  • Size. The state spans the whole capture (the padded rect, uv space) at ceil(capture * scale) texels (StateOptions::with_scale); it lives in layer uv, so a moved layer keeps it, and a resized layer reads the previous state stretched (no reset).
  • Format. StateFormat::Rgba16Float by default (signed, unbounded): it must be renderable and filterable on the device, else stateful layers are refused and listed by failed_states (WebGL2 / GLES without EXT_color_buffer_float); never silently downgraded. StateFormat::Rgba8Unorm is an explicit opt-in for effects that pack their state in 8 bits.
  • Lifetime. A state starts at zero; reset_state zeroes it at the id’s next paint that actually runs (a paint that draws nothing, e.g. off screen, keeps the request pending); a state not painted for 120 frames OF ITS OWN VIEWPORT and 2 seconds is freed (so an idle viewport keeps its states while another animates; state_count for debugging); a re-install (or destroy_glow) drops all. It advances only on painted frames: the effect is not animated by itself — repaint while it should move.
  • Offline, the renderer carries the state from one process call to the next (OfflineOptions::with_state, OfflineRenderer::reset_state, a video processor’s frames); stateful chains are never tiled (OfflineError::NotTileable).
use egui_shader_layers::{Effect, FilterChain, ShaderLayer, Pass};
// Accumulates the backdrop's brightness over frames and shows it.
let accumulate = Effect::new_state("glow", "
fn effect(uv: vec2<f32>) -> vec4<f32> {
    return state_px(vec2<i32>(0)) * 0.9 + src(uv) * 0.1;
}")?;
let show = Effect::new("show", "fn effect(uv: vec2<f32>) -> vec4<f32> { return state(uv); }")?;
let chain = FilterChain::new().then(Pass::new(&accumulate)).then(Pass::new(&show));
ShaderLayer::new(rect, chain).id(ui.id().with("glow")).paint(ui.painter());

Reduced-resolution passes. Pass::with_scale runs a pass over ceil(capture * scale) pixels; the next pass (or the final composite, bilinearly) reads that smaller image. uv, src(), original(), fl.texel and fl.size_px keep their capture meaning, so an effect’s distance maths is the same at any scale; kernels that step in pixels use src_px() / src_texel() (input pixels) or out_texel(). presets::kawase_blur and presets::bloom are built from such passes. Offline, a scaled chain refuses tiling.

Masks. A layer filters its whole rect, or a rounded rect (ShaderLayer::corner_radius), or any egui shape: ShaderLayer::mask with Mask::Shape — paths, circles, rects, meshes, text galleys (UI only), in the layer’s points (so it follows layer transforms). The shape’s alpha is the coverage (paint it opaque for a full-strength filter; egui’s feathered edge anti-aliases it); outside it the backdrop stays untouched. It is tessellated when the layer is painted and rasterized into a coverage texture at capture resolution; the coverage of several pieces is the sum of their alphas, capped at 1, so pieces meeting edge to edge leave no seam (their feathered edges add up to full coverage). egui fills convex paths only: build a concave outline from convex pieces (abutting or overlapping) or from a mesh.

use egui_shader_layers::{ShaderLayer, Mask, presets};
let lens = egui::Shape::circle_filled(rect.center(), 60.0, egui::Color32::WHITE);
ShaderLayer::new(rect, presets::gaussian_blur(8.0)).mask(Mask::Shape(lens)).paint(ui.painter());

Regions. One layer can run its chain differently per area: ShaderLayer::regions (a Mask::Regions of up to MAX_REGIONS Regions) masks by the union of the regions (no seam where they abut) and tells every pass which region a pixel belongs to: region() is the region’s index, region_at(uv) the one at another point (a kernel that must not cross into a neighbour compares region_at(uv + d) == region()). Per-region values are named-parameter arrays indexed by it; scalars go four to a vec4 (array<f32, N> is not accepted). Where regions overlap the LATER one wins, and the boundary between two regions is pixel-hard (a soft transition between two parameter sets needs two layers). One capture and one chain run serve every region, which is what makes many small areas cheaper than many layers. Regions run on the wgpu and glow backends and offline (OfflineOptions::with_mask, tiled like any mask).

use egui_shader_layers::{Effect, ShaderLayer, Pass, Region};
let tint = Effect::new("tint", "struct Params { tint: array<vec4<f32>, 2> }
fn effect(uv: vec2<f32>) -> vec4<f32> { return mix(src(uv), p.tint[min(region(), 1u)], 0.5); }")?;
let mut pass = Pass::new(&tint);
pass.set_slice("tint", &[[1.0, 0.0, 0.0, 1.0], [0.0, 0.0, 1.0, 1.0]])?;
let (left, right) = rect.split_left_right_at_fraction(0.5);
ShaderLayer::new(rect, pass).regions([Region::rounded_rect(left, 8), Region::rounded_rect(right, 8)]).paint(ui.painter());

Distances are in layer points. Sample radii, corner radii and every effect distance converted with fl.pixels_per_point are measured in the points of the layer the filter is painted in. Inside a transformed layer (an egui::Scene, Context::set_transform_layer) they scale with its zoom exactly like the painted content: a 4-point blur covers 8 pixels at zoom 2 and 2 pixels at zoom 0.5 (at 1 pixel per point), and the capture padding follows.

§Regions and entries

Three ways to filter many areas:

  • Regions (ShaderLayer::regions): ONE chain, one capture (the layer rect, which must cover the regions) and one run for every area; effects read region() to vary their parameters. Use it for many small areas that share the effect and differ only in parameters (a grid of tinted glass tiles); the boundary between two regions is hard. The capture covers the whole rect, so a few areas far apart pay for the space between them.
  • Entries (Entry, ShaderLayer::from_entries, ShaderLayer::with_entry): each area has its OWN chain, mask, textures and state, and captures ONLY its own padded rect; the entries share one paint callback (and on wgpu one selection and tessellation of the content beneath). Overlap says what a later entry filters where entries overlap: Overlap::Independent (the original backdrop; the later one covers the earlier) or Overlap::Stacked (the earlier entries’ result, like separate layers — on EVERY backend, while separate layers on wgpu cannot see each other). Composites are in list order. The layer-level builders (mask, corner_radius, regions, texture, state) apply to every entry present, the accessors return the first entry’s; a stateful entry keeps its own state under the layer’s id and its index in the list (also while an earlier entry draws nothing), and reset_state resets them all. A layer is drawn or refused as a whole (any failing entry refuses it). Offline: OfflineLayer + OfflineEntry with OfflineRenderer::process_layer (never tiled). Entries run on the wgpu and glow backends and offline, in both overlap modes.
  • Separate layers: one ShaderLayer per area. The most general (each its own position in egui’s paint order), and the costliest on wgpu: every layer selects, tessellates and re-renders the content beneath it again.

Rule of thumb: the same effect with different parameters → regions; different chains, masks or state per area → entries (or regions with one branching chain when there are many dense areas); different paint-order positions → separate layers. Prefer Overlap::Independent unless a later entry must see an earlier entry’s result: on wgpu Stacked adds a hand-off draw into every later entry whose padded capture an earlier one reaches.

Measured by bench_many_elements (N frosted, tinted tiles filling a busy 256x128 backdrop, release build, Ryzen 5 9600X iGPU, Mesa 26.0.3, wall time per frame including egui, GPU completion and readback; ms for N = 4 / 16 / 64; the backdrop alone costs 0.09 ms on wgpu and 0.16 ms on glow):

modewgpu (Vulkan)glow
N layers0.57 / 1.39 / 5.750.50 / 0.80 / 1.64
1 layer, N regions0.41 / 0.42 / 0.530.41 / 0.43 / 0.56
1 layer, N entries0.57 / 1.38 / 5.970.49 / 0.81 / 1.61
1 layer, N entries, stacked0.60 / 2.23 / 9.740.49 / 0.82 / 1.60

Regions stay nearly flat as N grows; layers and entries grow with N, steeply on wgpu. With a few small areas far apart on a large screen the regions capture grows with the screen, while layers and entries stay at their areas’ size.

§Backends

backendhow the backdrop is obtainedstatus
egui_glow (GL 3.3+, GLES 3.0+, WebGL2)copied out of the framebuffer inside the paint callback (MSAA resolved)feature glow
egui_glow on WebGL1 / GL < 3.3—unsupported: InstallError::Unsupported
egui-wgpu (native and web)the content beneath is rendered a second time offscreenfeature wgpu, install_wgpu

Warning — wgpu draws the content under a filter twice. egui-wgpu renders into a surface that cannot be read back mid-pass, so the wgpu backend re-renders everything beneath each shader layer (clipped to its padded rect) into an offscreen texture. The content under a filter is therefore drawn twice per frame on wgpu. Paint callbacks beneath a filter — including a lower shader layer — cannot be re-rendered and are left out of its backdrop. See install_wgpu.

OpenGL objects must be freed explicitly: call destroy_glow from eframe::App::on_exit.

The installed backend is stored in the egui::Context itself (as a hook-less egui plugin), not in egui Memory, so resetting memory does not uninstall it.

§Offline processing

With the image or video feature, an OfflineRenderer (wgpu only, also for glow apps) runs the same chains over ordinary images and video frames and returns the pixels — identical to a layer over that frame in the UI under the conditions listed in the offline module docs. video adds a frame-stream processor, source / sink traits and ffmpeg adapters. See offline.

§Hot reload

With the hot-reload feature (native only; on wasm32 it compiles to nothing), a HotEffect follows a WGSL file on disk: a background thread polls its modification time, recompiles it off the GUI thread, and HotEffect::poll (once per frame, never blocking) swaps in the new effect. While the file is broken the last good effect keeps rendering and the error, with naga’s diagnostic, is available for an overlay. rebind rebuilds a Pass on the reloaded effect, keeping named parameter values whose name and type still match.

Re-exports§

pub use presets::WaveObstacle;
pub use offline::AlphaMode;image or video
pub use offline::FrameRef;image or video
pub use offline::OfflineEntry;image or video
pub use offline::OfflineError;image or video
pub use offline::OfflineLayer;image or video
pub use offline::OfflineOptions;image or video
pub use offline::OfflineRenderer;image or video
pub use offline::OfflineTexture;image or video
pub use offline::PointerState;image or video
pub use offline::RgbaFrame;image or video

Modules§

offlineimage or video
Offline processing: apply a FilterChain to an ordinary image or video frame on wgpu and get the pixels back — the same result a ShaderLayer covering that frame shows in the UI.
presets
Ready-made filters. Each function returns a configured Pass or FilterChain; the underlying effects are compiled once per process and shared by every call.

Structs§

Effect
A validated filter effect: one WGSL function run once per pixel of the filtered region.
EffectFailure
An effect the installed backend could not compile or run. Layers using it are skipped.
Entry
One filtered area of a crate::ShaderLayer: its own rect (points), chain, mask, user textures and state options. A layer built with crate::ShaderLayer::new has exactly one entry; crate::ShaderLayer::from_entries / crate::ShaderLayer::with_entry build layers of several. Every entry captures only ITS OWN padded rect (never the union of the entries), runs its own chain and is composited in list order.
FilterChain
An ordered list of passes. Pass i reads the output of pass i - 1; the first reads the captured backdrop.
HotEffecthot-reload and non-WebAssembly
An effect that follows a WGSL file on disk (feature hot-reload, native only).
HotOptionshot-reload and non-WebAssembly
Options of HotEffect::watch_with.
Impulse
One impulse: where and when it started and how strong it is (output only: made by Impulses::push, read through Impulses::iter).
ImpulsePack
The live impulses packed for a shader: element i < count is [uv.x, uv.y, age_seconds, strength], the rest are zero (output only: Impulses::pack).
Impulses
A bounded, user-owned collection of timed impulses feeding an effect such as presets::click_ripples.
ParamIndexError
A parameter index outside 0..PARAM_SLOTS.
ParamInfo
One member of an effect’s struct Params, as reflected from naga’s layout: enough for a UI to build a control per parameter (crate::Effect::params).
Pass
One filter pass: an Effect and the parameter values it sees this frame.
Reboundhot-reload and non-WebAssembly
A Pass rebuilt on another effect by rebind (output only: read its fields).
Region
One region of a Mask::Regions mask: an egui shape in LAYER points whose alpha is its coverage (as Mask::Shape). Its index in the region list is its id (the prelude’s region()); where regions overlap, the later one in the list owns the pixels.
ShaderLayer
A filter applied to everything painted beneath rect.
SnippetLocation
A location inside the user’s WGSL snippet (not the assembled module).
StateFailure
A state format the installed backend refused (see failed_states). Layers asking for it draw nothing extra; the entry stays for the backend’s lifetime.
StateOptions
How a layer’s persistent state is stored (crate::ShaderLayer::state, OfflineOptions::with_state). Default: full resolution, StateFormat::Rgba16Float.
TextureFailure
An attached user texture the installed backend could not resolve when it painted a layer: the TextureId is unknown to egui’s renderer (freed, or never allocated on this painter). Layers attaching it draw nothing extra. egui never reuses a TextureId, so the entry stays for the backend’s lifetime.
WgpuOptionswgpu
How egui-wgpu’s main render pass is configured, which the filter’s pipelines must match.

Enums§

BackendKind
Which GPU backend a status refers to.
BackendStatus
The state of the filter backend installed on a context. See crate::status.
EffectError
Why an Effect could not be built.
HotReloadErrorhot-reload and non-WebAssembly
Why the watched file currently yields no new effect.
HotReloadEventhot-reload and non-WebAssembly
What one HotEffect::poll observed.
InstallError
Why a backend could not be installed.
Mask
Which part of the layer rect the filter replaces; outside it the backdrop stays untouched. The mask is always intersected with the layer rect.
MaskError
Why a Mask cannot be used.
Overlap
How the entries of one crate::ShaderLayer that overlap see each other. Entries are always composited in list order (a later entry lands over an earlier one, blended by its own mask coverage); the mode decides what a later entry FILTERS.
ParamError
Why setting a named parameter failed. The pass is left unchanged.
ParamType
The type of one struct Params member (of one element, for arrays).
ParamValue
A typed value for one named parameter (one element of an array member).
StateError
Why a layer (or an offline run) with a state pass cannot run.
StateFormat
Storage format of a layer’s persistent state.
TextureError
Why a layer’s user textures cannot serve its effects. Checked before any GPU work: crate::ShaderLayer::check_textures (what ShaderLayer::paint runs; the layer is then skipped and the error logged once per context) and the offline renderer (OfflineError::Texture).

Constants§

DEFAULT_POLL_INTERVALhot-reload and non-WebAssembly
The poll interval HotOptions::default uses: fast enough to feel instant after a save, slow enough to cost nothing (one metadata call per tick).
IMPULSES_PARAM
Named parameter receiving the packed impulses: impulses: array<vec4<f32>, 16> in WGSL, each vec4(uv.x, uv.y, age_seconds, strength) with uv relative to the layer rect.
IMPULSE_COUNT_PARAM
Named parameter receiving how many leading elements of IMPULSES_PARAM are live: impulse_count: u32 in WGSL.
IMPULSE_SLOTS
Most impulses an Impulses holds and packs: the length of the impulses array parameter.
MAX_REGIONS
The largest number of regions a Mask::Regions mask may have: ids are 0..MAX_REGIONS, stored in one byte of the region-id texture, whose value 255 is REGION_NONE.
MIN_PASS_SCALE
The smallest output scale a pass accepts (Pass::with_scale clamps to it): 1/1024 of the capture per axis (a scaled output is never smaller than 1 pixel anyway).
MIN_POLL_INTERVALhot-reload and non-WebAssembly
The shortest poll interval accepted (HotOptions::with_interval clamps to it), so a zero interval cannot turn the watcher into a busy loop.
PARAM_SLOTS
Number of vec4<f32> parameter slots a pass has (params(0) .. params(15)).
REGION_NONE
The region id the prelude’s region() / region_at(uv) return outside every region and on layers without regions (the WGSL prelude’s REGION_NONE).
TEXTURE_SLOTS
How many user textures a layer can attach (ShaderLayer::texture, offline OfflineOptions::with_texture); effects read slot i with tex(i, uv), tex_size(i) and tex_load(i, px). Three on every backend: WebGL2 allows four bind groups and @group(0) is the crate’s.

Functions§

destroy_glowglow
Frees every OpenGL object of the glow backend installed on ctx and uninstalls it.
failed_effects
Effects the installed backend failed to build on the GPU (after they passed naga validation), e.g. because a driver rejected the translated shader. Empty when none failed or none installed.
failed_states
State formats the installed backend refused (the device cannot render or filter them); layers asking for them draw nothing extra. Each is also logged once at error level.
failed_textures
Attached user textures (ShaderLayer::texture) the installed backend could not resolve when painting (freed or foreign TextureIds); layers using them draw nothing extra. Each is also logged once at error level. Empty when none failed or none installed.
install_glowglow
Installs the glow filter backend on ctx. Call once at startup, e.g. from the eframe app creator with cc.gl.
install_wgpuwgpu
Installs the wgpu filter backend on ctx. Call once at startup, e.g. from the eframe app creator with cc.wgpu_render_state.
rebindhot-reload and non-WebAssembly
Rebuilds pass on effect (typically a hot-reloaded version of its effect), keeping what still fits: every named parameter whose name, element type and array-ness match (an array keeps its first min(old, new) elements; the rest start at zero), the anonymous params(i) block and the output scale. A sample-radius override is kept when the old pass had one (its radius differed from its effect’s); otherwise the pass follows the new effect’s radius.
reset_state
Resets the persistent state of the layer id on ctx: the next paint of that id that the backend actually runs (in any viewport, the first one to run it) starts from zero; a paint that draws nothing (the layer out of view) leaves the request pending. Cheap; call it from UI code.
state_count
How many layer states the installed backend currently holds (a debug / leak-check accessor; evicted and reset states are not counted twice). 0 without a backend.
status
The status of the filter backend installed on ctx.

Type Aliases§

Params
The parameter block of one pass: PARAM_SLOTS vec4<f32> values.