# Instancia de efecto

Consulta el estado del efecto, actualiza la captura y libera recursos.

Cada función devuelve de inmediato una instancia de efecto (`EffectHandle`). Consérvala para controlar la animación, comprobar el resultado de la configuración y liberar recursos. [Tiempo e intensidad](/docs/es/api/shared/#control-playback) son sus controles modificables. Cada instancia tipada salvo Burned paper extiende `ColorEffectHandle`: su propiedad `color` devuelve `rgb(…)` normalizado o `undefined` para los colores originales del efecto. Frost también expone `mistOpacity`, Burned paper expone `emberGlow` y Fire expone su valor de creación resuelto `emberDensity`, además de `rootColor` y `tipColor`, modificables, que devuelven `rgb(…)` normalizado o `undefined` si no están definidos. El par es excluyente con `color`: escribir uno mientras el otro está definido lanza `invalid-fire-parameter` y conserva el valor anterior, así que asigna primero `undefined`.

## Estado de solo lectura

[Sección titulada «Estado de solo lectura»](#estado-de-solo-lectura)

Estas propiedades son de solo lectura. Un efecto pausado puede conservar una salida visible y actualizada. Consulta por separado el ciclo de vida, la captura y la pausa.

| Propiedad                                                                                                                                                                                     | Tipo                                                     |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `ready` Se resuelve después de la configuración inicial o la limpieza de una configuración cancelada. La indisponibilidad del entorno no la rechaza. Consulta lifecycle y reason al terminar. | `Promise<void>`                                          |
| `lifecycle` Estado actual del efecto. Consúltalo después de configurar o reintentar.                                                                                                          | `'active' \| 'suspended' \| 'unavailable' \| 'disposed'` |
| `raster` Estado de captura: fresh está actualizado; refreshing indica una captura en curso; stale está desactualizado.                                                                        | `'fresh' \| 'refreshing' \| 'stale'`                     |
| `reason` Código del motivo de una salida no disponible o suspensión temporal. Úsalo para la lógica del programa.                                                                              | `EffectReason \| undefined`                              |
| `reasonDetail` Mensaje de diagnóstico. Su redacción puede cambiar; no lo uses para la lógica del programa.                                                                                    | `string \| undefined`                                    |
| `clock` Control de animación elegido al crear el efecto.                                                                                                                                      | `'manual' \| 'auto'`                                     |
| `seed` Semilla elegida al crear el efecto.                                                                                                                                                    | `number`                                                 |
| `paused` Indica si la animación automática de domfx está pausada. Siempre es true con control externo o un efecto inmóvil, incluso cuando GSAP cambia el tiempo.                              | `boolean`                                                |

Que termine la configuración no garantiza una salida visible ni una ejecución GPU terminada. Inspecciona `lifecycle` y `reason`; mantén utilizable el contenido original cuando la decoración no esté disponible.

## Métodos

[Sección titulada «Métodos»](#métodos)

| Método                                                                                                                                                                                                                                           | Devuelve        |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| `pause()` Pausa la animación automática sin perder la instancia ni las asignaciones de control pendientes.                                                                                                                                       | `void`          |
| `resume()` Reanuda la animación automática sin avanzar de golpe el tiempo transcurrido mientras estaba en pausa u oculto. No avanza el tiempo controlado externamente ni un efecto inmóvil.                                                      | `void`          |
| `refresh()` Oculta la salida desactualizada y vuelve a capturar. Se resuelve cuando se acepta esta captura u otra posterior; no espera a que aparezca en pantalla. Se rechaza por fallo, invalidación, liberación o una instancia no disponible. | `Promise<void>` |
| `retry()` Vuelve a configurar el efecto conservando controles y enlaces. Las llamadas simultáneas comparten un intento. Se rechaza si la instancia ya se liberó; en otro caso, consulta el estado al terminar.                                   | `Promise<void>` |
| `dispose()` Libera recursos y elimina los enlaces. Se puede llamar varias veces o antes de terminar la configuración. Volver a montar requiere otra instancia.                                                                                   | `void`          |
| `onDispose(callback)` Registra una función `() => void` que se ejecuta una vez, de inmediato si la instancia ya se liberó. Devuelve una función para cancelar la suscripción.                                                                    | `() => void`    |

La actualización de captura y las asignaciones de control no recuperan una instancia no disponible. Corrige la condición antes de llamar a `retry()`. Llama a `dispose()` al desmontar el componente y gestiona las promesas rechazadas de refresh/retry mientras el componente siga activo.

## Comprende el estado informado

[Sección titulada «Comprende el estado informado»](#comprende-el-estado-informado)

`lifecycle` indica si el efecto puede dibujarse. `raster` indica si la imagen capturada está actualizada. `paused` solo indica si la animación automática de domfx está pausada. Estos valores describen aspectos distintos.

Un efecto controlado por GSAP tiene `paused: true` mientras cambia su tiempo. Un efecto puede tener `paused: false` aunque temporalmente no pueda dibujarse. Un efecto inmóvil puede estar activo, actualizado y visible.

Espera a `ready` para el intento de configuración inicial, a `refresh()` para actualizar la captura o a `retry()` para un nuevo intento de configuración después de corregir un problema. El reintento conserva la promesa `ready` original. Ninguna de estas promesas indica que terminó la animación, la ejecución en la GPU o la presentación en pantalla; consulta el estado para saber si está disponible.
