the current renderer instance
Optionaloptions: {effect options
Optionalintensity?: numberhow much of the gathered light is added back
Optionalradius?: numberhalo reach, in texels
OptionaltextureSize?: number[]dimensions of what is being filtered, [width, height]; defaults to the renderer's size
Optionalthreshold?: numberluminance a pixel must pass before it blooms, 0 (everything blooms) to 1 (only white does)
Readonlydestroyedtrue once destroy has been called. Distinct from
enabled — which also toggles transiently across a context
lost / restored cycle — to give callers a stable signal for
"this effect has been explicitly released."
whether this effect is active (false in Canvas mode, false after
destroy, and false while the WebGL context is suspended
between an ONCONTEXT_LOST and the matching ONCONTEXT_RESTORED
event).
When true, a renderable will NOT auto-destroy this effect when it is
removed from its postEffects (via the shader setter,
Renderable#removePostEffect, Renderable#clearPostEffects)
or when the renderable itself is destroyed. Set this on an effect shared
across several renderables so one of them going away doesn't free the GL
program still used by the others — you then own its lifecycle and call
destroy yourself.
Create an independent copy of this effect, compiled as its own GL program. Use it when several renderables need the same effect with different uniform values — a single instance has a single set of uniforms, shared by everything it is assigned to.
The clone copies the recipe: the fragment source, float precision,
every uniform value set so far, and any extra textures bound via
setTexture (the clone uploads and owns its own GL copies).
It does NOT copy ownership or lifecycle state — in particular the
clone's shared flag is always reset to false, even when
cloning a shared shader (such as one returned by loader.getShader()):
the clone is caller-owned and will be auto-destroyed by the renderable
it is assigned to, exactly like a hand-constructed effect. Set
shared = true on the clone yourself if you intend to reuse it across
several renderables.
a new, caller-owned effect (shared === false)
// the loader's shader is ONE shared program — one uniform state for all
sprite.addPostEffect(loader.getShader("flash"));
// the boss needs its own intensity — clone a private, caller-owned copy
const bossFlash = loader.getShader("flash").clone();
boss.addPostEffect(bossFlash);
bossFlash.setUniform("uIntensity", 0.9);
destroy this shader effect. Idempotent — calling destroy twice is safe. Unsubscribes from the renderer's context-lost / restored events so a destroyed effect is not auto-reactivated.
set how much of the gathered light is added back
0 disables the effect without removing it
set the halo reach
reach in texels
Bind an extra texture to a named sampler2D uniform in this shader, so
a custom effect can read a second texture — a noise map, mask, gradient,
flow/lookup table — besides the sprite/target it post-processes (uSampler).
The engine uploads, caches, and re-binds it to a reserved texture unit each
time the effect draws, and points the sampler uniform at it — no raw WebGL
texture-unit juggling.
Declare the sampler in your fragment (uniform sampler2D <name>;) and pass
that name here. Any engine texture works — a Texture2d asset
(NoiseTexture2d, TextureAtlas, …) can be passed directly, or a raw
drawable source. No-op in Canvas mode.
the sampler2D uniform name declared in the fragment
the texture: an engine texture asset, or a raw drawable source
Optionalrepeat: "repeat" | "no-repeat" | "repeat-x" | "repeat-y" = "no-repeat"
wrap mode; use "repeat" for a tiled/scrolled texture
this effect for chaining
// "water": distort the sprite by a static noise texture scrolled over time
const noise = new me.NoiseTexture2d({ width: 256, height: 256, seamless: true });
const water = new me.ShaderEffect(renderer, `
uniform sampler2D uNoise;
uniform float uTime;
vec4 apply(vec4 color, vec2 uv) {
vec2 flow = texture2D(uNoise, uv + uTime * 0.03).rg - 0.5;
return texture2D(uSampler, uv + flow * 0.02);
}`);
water.setTexture("uNoise", noise, "repeat");
waterSprite.addPostEffect(water);
// each frame, in your Stage's update(dt):
water.setTime(me.timer.getTime() / 1000);
set the dimensions of what is being filtered. The tap offsets are in texels, so a stale size makes the halo the wrong width after a resize.
width in pixels
height in pixels
set the luminance a pixel must pass before it contributes
0 (everything blooms) to 1 (only white does)
Set the shader's uTime uniform (elapsed time, in seconds). A convenience
over setUniform("uTime", ...); call it once per frame from your update
loop to animate a shader that declares uniform float uTime (e.g. scrolling
a static noise texture's UVs, pulsing, waving). Drive it with whatever clock
you like — real time, a paused/scaled/scrubbed one.
No-op if the shader does not declare a uTime uniform (nothing to update),
or in Canvas mode. The engine does NOT call this for you — animation is
opt-in, exactly like re-baking a NoiseTexture2d with update(dt).
elapsed time in seconds
this effect for chaining
// a shader that scrolls a static seamless noise texture over time
const flow = new me.ShaderEffect(renderer, `
uniform float uTime;
vec4 apply(vec4 color, vec2 uv) {
return texture2D(uSampler, uv + vec2(uTime * 0.05, 0.0));
}`);
mySprite.addPostEffect(flow);
// then in your Stage's update(dt):
flow.setTime(me.timer.getTime() / 1000);
A shader effect that adds a bloom: the bright parts of what it is applied to bleed light into the pixels around them.
Reach for it on the CAMERA, where it works on the whole frame and makes emitters, neon, fire and specular highlights read as light rather than as bright paint. It works on a single renderable too, where it blooms only that sprite's own bright pixels.
Not to be confused with GlowEffect, which draws an outline OUTSIDE a sprite's silhouette and does nothing at all on an opaque frame.
textureSizemust match what is being filtered, since the tap offsets are in texels; it defaults to the renderer's own size, which is what a camera effect wants. Call BloomEffect#setTextureSize from an event.ONRESIZE handler, or after applying it to something smaller.See
Renderable#addPostEffect for usage
Example
Example