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:
- Presets (
presets): blurs (Gaussian, dual-Kawasepresets::kawase_blur), colour adjustments, sharpen, pixelate, lens, vignette, frosted glass,presets::bloom, animated ripples, input-drivenpresets::click_ripples, and the statefulpresets::trailsand water (presets::wave_sim+presets::wave_displayaroundWaveObstacles). - Custom effects (
Effect): one WGSL function with a prelude (the pass input, the untouched backdroporiginal(), time, frame, pointer, user textures, persistent state), validated by naga with errors located in your snippet; typed named parameters from astruct Params(Pass::set). - Chains (
FilterChain) of passes, each optionally at reduced resolution (Pass::with_scale). - Input:
Impulsesturns clicks into transient animations that repaint only while alive. - User textures (
ShaderLayer::texture), persistent per-layer state (Effect::new_state,ShaderLayer::id) and shape masks (ShaderLayer::mask). - Many areas in one layer: per-area parameters of one chain (
ShaderLayer::regions) or several independent areas, each with its own chain (Entry,ShaderLayer::from_entries); see Regions and entries. - Backends:
egui_glowandegui-wgpu; offline processing of images and video (featuresimage/video); hot reload of WGSL files (featurehot-reload).
§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::Orderareas, 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; seeBackendStatus::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:
| name | meaning |
|---|---|
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.texel | size of one physical pixel in uv units (of the capture, also in scaled passes) |
fl.size_px | captured region size in physical pixels |
fl.rect_uv | the layer rect inside the capture (xy = min, zw = size), in uv units |
fl.time | seconds (egui input time); reading it makes the effect animated (see below) |
fl.delta_time | seconds since the previous frame: egui’s stable_dt clamped to 0..=0.1 (offline: OfflineOptions::with_delta_time, or the video frame step) |
fl.frame | frame counter, u32 (egui’s cumulative_frame_nr, wrapping; offline: the video frame index) |
fl.pointer | the 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_point | physical pixels per layer point (egui’s scale factor × the layer transform’s zoom), to convert point distances to pixels |
fl.pass_scale | this 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_index | index 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_NONE | 255u, 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 i32Accepted 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 passsrc()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,
uvspace) atceil(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::Rgba16Floatby default (signed, unbounded): it must be renderable and filterable on the device, else stateful layers are refused and listed byfailed_states(WebGL2 / GLES withoutEXT_color_buffer_float); never silently downgraded.StateFormat::Rgba8Unormis an explicit opt-in for effects that pack their state in 8 bits. - Lifetime. A state starts at zero;
reset_statezeroes 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_countfor debugging); a re-install (ordestroy_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
processcall 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 readregion()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).Overlapsays what a later entry filters where entries overlap:Overlap::Independent(the original backdrop; the later one covers the earlier) orOverlap::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), andreset_stateresets them all. A layer is drawn or refused as a whole (any failing entry refuses it). Offline:OfflineLayer+OfflineEntrywithOfflineRenderer::process_layer(never tiled). Entries run on the wgpu and glow backends and offline, in both overlap modes. - Separate layers: one
ShaderLayerper 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):
| mode | wgpu (Vulkan) | glow |
|---|---|---|
| N layers | 0.57 / 1.39 / 5.75 | 0.50 / 0.80 / 1.64 |
| 1 layer, N regions | 0.41 / 0.42 / 0.53 | 0.41 / 0.43 / 0.56 |
| 1 layer, N entries | 0.57 / 1.38 / 5.97 | 0.49 / 0.81 / 1.61 |
| 1 layer, N entries, stacked | 0.60 / 2.23 / 9.74 | 0.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
| backend | how the backdrop is obtained | status |
|---|---|---|
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 offscreen | feature 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;imageorvideopub use offline::FrameRef;imageorvideopub use offline::OfflineEntry;imageorvideopub use offline::OfflineError;imageorvideopub use offline::OfflineLayer;imageorvideopub use offline::OfflineOptions;imageorvideopub use offline::OfflineRenderer;imageorvideopub use offline::OfflineTexture;imageorvideopub use offline::PointerState;imageorvideopub use offline::RgbaFrame;imageorvideo
Modules§
- offline
imageorvideo - Offline processing: apply a
FilterChainto an ordinary image or video frame on wgpu and get the pixels back — the same result aShaderLayercovering that frame shows in the UI. - presets
- Ready-made filters. Each function returns a configured
PassorFilterChain; 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.
- Effect
Failure - 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 withcrate::ShaderLayer::newhas exactly one entry;crate::ShaderLayer::from_entries/crate::ShaderLayer::with_entrybuild 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. - Filter
Chain - An ordered list of passes. Pass
ireads the output of passi - 1; the first reads the captured backdrop. - HotEffect
hot-reloadand non-WebAssembly - An effect that follows a WGSL file on disk (feature
hot-reload, native only). - HotOptions
hot-reloadand 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 throughImpulses::iter). - Impulse
Pack - The live impulses packed for a shader: element
i < countis[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. - Param
Index Error - A parameter index outside
0..PARAM_SLOTS. - Param
Info - 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
Effectand the parameter values it sees this frame. - Rebound
hot-reloadand non-WebAssembly - A
Passrebuilt on another effect byrebind(output only: read its fields). - Region
- One region of a
Mask::Regionsmask: an egui shape in LAYER points whose alpha is its coverage (asMask::Shape). Its index in the region list is its id (the prelude’sregion()); where regions overlap, the later one in the list owns the pixels. - Shader
Layer - A filter applied to everything painted beneath
rect. - Snippet
Location - A location inside the user’s WGSL snippet (not the assembled module).
- State
Failure - 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. - State
Options - How a layer’s persistent state is stored (
crate::ShaderLayer::state,OfflineOptions::with_state).Default: full resolution,StateFormat::Rgba16Float. - Texture
Failure - An attached user texture the installed backend could not resolve when it painted a layer:
the
TextureIdis unknown to egui’s renderer (freed, or never allocated on this painter). Layers attaching it draw nothing extra. egui never reuses aTextureId, so the entry stays for the backend’s lifetime. - Wgpu
Options wgpu - How egui-wgpu’s main render pass is configured, which the filter’s pipelines must match.
Enums§
- Backend
Kind - Which GPU backend a status refers to.
- Backend
Status - The state of the filter backend installed on a context. See
crate::status. - Effect
Error - Why an
Effectcould not be built. - HotReload
Error hot-reloadand non-WebAssembly - Why the watched file currently yields no new effect.
- HotReload
Event hot-reloadand non-WebAssembly - What one
HotEffect::pollobserved. - Install
Error - 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.
- Mask
Error - Why a
Maskcannot be used. - Overlap
- How the entries of one
crate::ShaderLayerthat 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. - Param
Error - Why setting a named parameter failed. The pass is left unchanged.
- Param
Type - The type of one
struct Paramsmember (of one element, for arrays). - Param
Value - A typed value for one named parameter (one element of an array member).
- State
Error - Why a layer (or an offline run) with a state pass cannot run.
- State
Format - Storage format of a layer’s persistent state.
- Texture
Error - Why a layer’s user textures cannot serve its effects. Checked before any GPU work:
crate::ShaderLayer::check_textures(whatShaderLayer::paintruns; the layer is then skipped and the error logged once per context) and the offline renderer (OfflineError::Texture).
Constants§
- DEFAULT_
POLL_ INTERVAL hot-reloadand non-WebAssembly - The poll interval
HotOptions::defaultuses: fast enough to feel instant after a save, slow enough to cost nothing (onemetadatacall per tick). - IMPULSES_
PARAM - Named parameter receiving the packed impulses:
impulses: array<vec4<f32>, 16>in WGSL, eachvec4(uv.x, uv.y, age_seconds, strength)withuvrelative to the layer rect. - IMPULSE_
COUNT_ PARAM - Named parameter receiving how many leading elements of
IMPULSES_PARAMare live:impulse_count: u32in WGSL. - IMPULSE_
SLOTS - Most impulses an
Impulsesholds and packs: the length of theimpulsesarray parameter. - MAX_
REGIONS - The largest number of regions a
Mask::Regionsmask may have: ids are0..MAX_REGIONS, stored in one byte of the region-id texture, whose value 255 isREGION_NONE. - MIN_
PASS_ SCALE - The smallest output scale a pass accepts (
Pass::with_scaleclamps to it): 1/1024 of the capture per axis (a scaled output is never smaller than 1 pixel anyway). - MIN_
POLL_ INTERVAL hot-reloadand non-WebAssembly - The shortest poll interval accepted (
HotOptions::with_intervalclamps 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’sREGION_NONE). - TEXTURE_
SLOTS - How many user textures a layer can attach (
ShaderLayer::texture, offlineOfflineOptions::with_texture); effects read slotiwithtex(i, uv),tex_size(i)andtex_load(i, px). Three on every backend: WebGL2 allows four bind groups and@group(0)is the crate’s.
Functions§
- destroy_
glow glow - Frees every OpenGL object of the glow backend installed on
ctxand 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
errorlevel. - failed_
textures - Attached user textures (
ShaderLayer::texture) the installed backend could not resolve when painting (freed or foreignTextureIds); layers using them draw nothing extra. Each is also logged once aterrorlevel. Empty when none failed or none installed. - install_
glow glow - Installs the glow filter backend on
ctx. Call once at startup, e.g. from the eframe app creator withcc.gl. - install_
wgpu wgpu - Installs the wgpu filter backend on
ctx. Call once at startup, e.g. from the eframe app creator withcc.wgpu_render_state. - rebind
hot-reloadand non-WebAssembly - Rebuilds
passoneffect(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 firstmin(old, new)elements; the rest start at zero), the anonymousparams(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
idonctx: 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_SLOTSvec4<f32>values.