# fbm/fbm

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

The `fbm` module composes Fractional Brownian Motion on top of any base noise function. It layers `octaves` copies of the base at geometrically increasing frequencies (`lacunarity`) and geometrically decreasing amplitudes (`gain`), yielding the classical cloud/terrain/texture multi-scale roughness pattern that underlies most procedurally generated content.

Because `fbm2`/`fbm3` take the base function as a parameter, you can layer any of `perlin2`, `simplex2`, `value2`, or even Worley distances on top of fBm — the module has no coupling to a specific noise kind.

## Features

- `fbm2(base, x, y, opts?)` — 2D compositor
- `fbm3(base, x, y, z, opts?)` — 3D compositor
- Configurable `octaves`, `lacunarity`, `gain`, `frequency`, `amplitude`
- Argument validation via `NoiseError.ARG.INVALID` / `FBM.INVALID_OCTAVES`

## Usage: Basic Example

```ts
import { fbm2, PerlinNoise } from "@suaveplan/noise";

const p = new PerlinNoise("world");
const h = fbm2((x, y) => p.noise2(x, y), 1.5, 2.3);
```

## Usage: Advanced Example

```ts
import { fbm3, SimplexNoise } from "@suaveplan/noise";

const s = new SimplexNoise("clouds");
const v = fbm3(
  (x, y, z) => s.noise3(x, y, z),
  0.1, 0.2, 0.3,
  { octaves: 6, lacunarity: 2.0, gain: 0.5, frequency: 1, amplitude: 1 },
);
```

## API Reference

- `FbmOptions` — every field optional: `octaves` (default 4, must be an integer 1–32), `lacunarity` (default 2), `gain` (default 0.5, must be in (0, 1]), `frequency` (default 1), `amplitude` (default 1).
- `fbm2(base, x, y, opts?): number`
- `fbm3(base, x, y, z, opts?): number`

## Implementation Notes

Clamping `octaves` to 1–32 avoids pathological input (negative or absurdly large numbers of loop iterations). `gain > 1` would diverge rather than converge, so it's rejected; `gain` exactly 1 means every octave contributes equally, which is useful for certain stylised effects but rejected here to keep the numeric output bounded — if you need that, call the base function manually in a loop.