# Smoke Ring

Aperveil / Light, shaped for the web.

A drifting smoke ring for React, with editable position and local pointer disturbance. Shape the torus, density and glow in the WebGPU editor.

[Aperveil integration guide](https://www.aperveil.com/docs)

## What it does

A bounded torus volume carries rotating multiscale density. Front-to-back transmittance gives depth, while the pointer disturbs a nearby arc without moving the ring center.

## Choose it for

Frame a short statement with a breathing perimeter. Keep the ring center clear and use the surrounding smoke as an accent for an audio or creative studio.

## Limits

Procedural volume integration, not a persistent fluid solver or a combustion simulation.

## Current look

Default. Color Looks change colors only; motion, geometry and typography remain unchanged.

[Open editor](https://www.aperveil.com/shaders/smoke-ring/edit?look=default&scene=landing)

## Landing scene

This preview uses `radius`: 0.3. The editor link carries these settings with your Look. Direct editor visits use the product defaults; Reset all restores those defaults.

## Install

Download the Export Kit from the editor. No shader-specific npm package or CLI is published yet.

```sh
npm install ./vendor/aperveil-runtime-0.1.0.tgz ./vendor/aperveil-react-0.1.0.tgz
```

Every control in the editor is a typed prop. Leave a prop out to keep the value you exported; change one and the running shader updates without restarting. Give the surface a size and pass fallback for browsers without WebGPU.

```tsx
"use client";

import SmokeRing from "./SmokeRing";

export default function Hero() {
  return (
    <SmokeRing
      className="hero-shader"
      radius={0.24} airColor="#08080dff"
      fallback={<div className="hero-shader-fallback" />}
    />
  );
}

// .hero-shader { width: 100%; height: 560px; }
```

Component props: `airColor`, `ashColor`, `emberColor`, `location`, `radius`, `thickness`, `turbulence`, `density`, `dissipation`, `emberGlow`, `pointerDisturbance`, `flowSpeed`, `opacity`, `className`, `style`, `paused`, `fallback`, `onReady`, `onError`.

Raw WGSL is included for a custom WebGPU host; it is not CSS. Keep semantic headings and links in HTML.

## Controls

- Air (`airColor`, color): Colour of the air behind the ring.
- Ash (`ashColor`, color): Colour of the smoke.
- Ember (`emberColor`, color): Warm glow inside the densest smoke.
- Location (`location`, xy): Position the ring without coupling it to the cursor.
- Ring radius (`radius`, slider): Size of the ring.
- Ring thickness (`thickness`, slider): Width stays nearly fixed and turbulence modulates density instead — letting churn drive the width ballooned the annulus until the hole closed.
- Turbulence (`turbulence`, slider): How ragged and full the rolling smoke is.
- Density (`density`, slider): How thick and opaque the smoke is.
- Dissipation (`dissipation`, slider): Carves transparent pockets from low-density turbulence.
- Inner glow (`emberGlow`, slider): How strongly the ember colour glows inside the smoke.
- Pointer disturbance (`pointerDisturbance`, slider): Locally shears and parts the nearby arc.
- Flow speed (`flowSpeed`, slider): How fast the smoke rolls around the ring; 0 holds it still.
- Opacity (`opacity`, slider): Opacity of the complete effect, including its background.

## Compatibility

WebGPU rendering requires a supported browser and secure context. The landing shows a real poster for the selected Look when live rendering is unavailable. The standard exported component does not bundle a poster fallback. Supply your own fallback in the host layout. Text exports also retain readable HTML typography.

## Performance

No published timing sample. Profile this effect on your target devices.

## Questions

### What changes the material?

A bounded torus volume carries rotating multiscale density. Front-to-back transmittance gives depth, while the pointer disturbs a nearby arc without moving the ring center.

### What are its limits?

Procedural volume integration, not a persistent fluid solver or a combustion simulation.

### How do I integrate it?

Open the editor, tune the parameters and download the Export Kit. Use the installation command included in that kit and give its container an explicit size.

### What happens without WebGPU?

This landing shows a still poster of your selected Color Look. The raw WGSL needs a WebGPU host. Landing posters are not bundled in the Export Kit: add your own fallback around the exported component.

### Can I use this shader commercially?

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects. An alpha access grant is not a purchase or a replacement for those license terms.

## License

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects. An alpha access grant is not a purchase or a replacement for those license terms.

## Related shaders

- [Fractal Glass](https://www.aperveil.com/shaders/fractal-glass)
- [Spiral](https://www.aperveil.com/shaders/spiral)
- [Ether Flow](https://www.aperveil.com/shaders/ether-veil)