# Dither

Aperveil / Light, shaped for the web.

An ordered Bayer dithering background for React. Adjust tone levels and pixel cell size, then export the animated WGSL effect.

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

## What it does

Dither quantizes a generated field through a computed 4×4 Bayer matrix. Levels controls the tonal steps, while cell size is measured in device pixels.

## Choose it for

Create a restrained retro identity for a small developer tool. Use a mono technical caption and a large, clean heading above the pixel texture.

## Limits

This is ordered dithering of a procedural field, not error-diffusion image processing. Device-pixel sizing can look different at different DPR values.

## Current look

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

[Open editor](https://www.aperveil.com/shaders/dither/edit?look=default)

## 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 Dither from "./Dither";

export default function Hero() {
  return (
    <Dither
      className="hero-shader"
      levels={6} shadowColor="#12101fff"
      fallback={<div className="hero-shader-fallback" />}
    />
  );
}

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

Component props: `shadowColor`, `midColor`, `lightColor`, `levels`, `cellSize`, `ditherAmount`, `scale`, `flowSpeed`, `swellStrength`, `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

- Shadow (`shadowColor`, color): Colour of the darkest of the printed levels.
- Mid (`midColor`, color): Colour of the middle levels between shadow and light.
- Light (`lightColor`, color): Colour of the brightest printed level.
- Levels (`levels`, slider): How many tones the field is crushed to. Fewer is more graphic.
- Pattern size (`cellSize`, slider): Bayer cell size in device pixels.
- Dither (`ditherAmount`, slider): At zero the tones band; the threshold is what trades banding for texture.
- Field scale (`scale`, slider): Density of the soft waves behind the dither; higher values make them smaller.
- Flow speed (`flowSpeed`, slider): How fast the field moves; 0 holds it still.
- Cursor swell (`swellStrength`, slider): How strongly the field brightens and sharpens around the cursor.
- 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

0.426 ms legacy timing (method not recorded; not a pure GPU measurement). 1440x900 @ dpr 2; Metal driver on macOS Version 26.6.2 (Build 25G83); measured 2026-09-02. This is a recorded headless sample, not a browser FPS or mobile-performance guarantee.

## Questions

### Can I choose the number of tone levels?

Yes. Levels is an editor control; the current default is six. The Bayer matrix remains 4×4 while the number of output levels changes.

### What should I not use Dither for?

This is ordered dithering of a procedural field, not error-diffusion image processing. Device-pixel sizing can look different at different DPR values.

### 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

- [Halftone](https://www.aperveil.com/shaders/halftone)
- [Grain Gradient](https://www.aperveil.com/shaders/grain-gradient)
- [Dot Grid](https://www.aperveil.com/shaders/dot-grid)