Skip to content

Effect instance

Read effect state, update the captured image and release resources.

An effect instance (EffectHandle) is returned immediately by every effect function. Keep it to control animation, check setup results and release resources. Time and intensity are its writable controls. Every typed handle except Burned paper extends ColorEffectHandle: its color property returns normalized rgb(…), or undefined for the effect’s original colors. Frost also exposes mistOpacity, Burned paper exposes emberGlow, and Fire exposes its resolved creation-only emberDensity plus writable rootColor and tipColor, which return normalized rgb(…) or undefined when unset. The pair is exclusive with color: writing one while the other is set throws invalid-fire-parameter and keeps the prior value, so assign undefined first.

These properties are read-only. A paused effect can still have up-to-date, visible output. Check lifecycle, capture status and pause separately.

PropertyType
ready

Resolves after initial setup or cleanup of cancelled setup. Environmental unavailability does not reject it. Check lifecycle and reason afterward.

Promise<void>
lifecycle

Current effect state. Check it after setup or retry.

'active' | 'suspended' | 'unavailable' | 'disposed'
raster

Capture status: fresh is up to date; refreshing means capture is in progress; stale is out of date.

'fresh' | 'refreshing' | 'stale'
reason

Reason code for unavailable output or temporary suspension. Use this for program logic.

EffectReason | undefined
reasonDetail

Diagnostic message. Wording can change; do not use it for program logic.

string | undefined
clock

Animation control selected at creation.

'manual' | 'auto'
seed

Seed selected at creation.

number
paused

Whether domfx automatic animation is paused. Always true with external control or a still effect, including when GSAP is changing time.

boolean

Readiness does not guarantee visible output or completed GPU execution. Inspect lifecycle and reason; keep the original content usable when decoration is unavailable.

MethodReturns
pause()

Pause automatic animation while retaining the attachment and pending control writes.

void
resume()

Resume automatic animation without catching up time spent paused or hidden. Does not advance externally controlled time or a still effect.

void
refresh()

Hide out-of-date output and capture again. Resolves when this or a newer requested capture is accepted; it does not wait for screen presentation. It rejects on failure, invalidation, disposal or an unavailable handle.

Promise<void>
retry()

Start setup again, retaining controls and bindings. Concurrent calls share one attempt. Rejects if already disposed; otherwise inspect state after it settles.

Promise<void>
dispose()

Release resources and detach bindings. Safe to call repeatedly or before setup finishes. Remounting requires a new instance.

void
onDispose(callback)

Register a () => void callback that runs once, immediately if already disposed. Returns an unsubscribe function.

() => void

Refresh and control writes cannot recover an unavailable handle. Correct the condition before calling retry(). Call dispose() on component unmount and handle rejected refresh/retry promises within the component's lifetime.

lifecycle reports whether the effect can render. raster reports whether its captured image is up to date. paused reports only whether domfx’s automatic animation is paused. These values describe different things.

A GSAP-controlled effect has paused: true while its time changes. An effect can have paused: false while temporarily unable to render. A still effect can be active, up to date and visible.

Await ready for the initial setup attempt, refresh() for an updated capture, or retry() for a new setup attempt after correcting a problem. Retry keeps the original ready promise. None of these promises signals animation completion or completed GPU execution/screen presentation; inspect state for availability.