API Overview

Grimoire exposes a C ABI through three public headers and a matching DLL export table.

Header Map

• grimoire-pcg/common.h: shared macros, ABI visibility, base seed type
• grimoire-pcg/random.h: opaque RNG lifecycle, sampling, and state persistence
• grimoire-pcg/noise.h: deterministic value/perlin noise and fractal combiners

Export Surface

Export groups:

• Random lifecycle and sampling
• Random state save/restore and cloning
• ValueSharp/ValueSmooth noise (1D/2D/3D)
• Perlin noise (1D/2D/3D)
• Fractal combiners (Grimoire_Fbm, Grimoire_Billow)

Determinism Model

Given identical inputs, Grimoire returns identical outputs:

• same function
• same coordinates and seed
• same settings
• same call order

Documentation Map

• Common Types: ABI macros, C/C++ linkage, and seed typing
• Random API: lifecycle, sampling, state serialization, and cloning semantics
• Noise API: base noise families, fractal composition, and tuning guidance
• Quick Reference: compact signature index
• Recipes: implementation patterns for real projects

Return and Ownership Rules

• Handle-creating APIs can return NULL and must be checked.
• Every successful Create*, Clone, or Deserialize handle must be destroyed.
• Numeric functions return values directly; there is no exception channel.
• Pointer arguments (buffers/settings) must be valid for the full call.

State Persistence

• RNG state serialization currently requires a 228-byte buffer.
• A serialized blob should only be restored against compatible releases.
• For robust save files, store blob size and your own save-format version.

See Recipes for full checkpoint examples.