# Planetary Field Runtime

CultMath owns the deterministic, renderer-independent planetary field. The same
definition can be queried by a CPU simulation, baked into residual pages,
sampled through a map projection, or evaluated by HLSL. Render resources and
gameplay interpretation remain consumer responsibilities.

## Authority

- `PlanetaryFieldDefinition` identifies radius, seed, erosion parameters, and a
  version that includes the consumer-owned base-field version.
- `IPlanetaryBaseField` supplies deterministic application-authored base
  evidence without making CultMath depend on an application.
- `PlanetaryQueryScale` makes the physical footprint and accepted unresolved
  error explicit. There is deliberately no scale-free authoritative
  `HeightAt` call.
- `PlanetarySurfaceSample` carries displacement, tangent gradient, normal,
  slope, ridge/gully evidence, resolved wavelength, and unresolved bound.
- pages, residency, patches, and map tiles are disposable lowerings of that
  contract.

The C# surface targets .NET and Unity-compatible `netstandard2.1`. The matching
HLSL lives in `shaders/Planetary.hlsl` and is included by `CultMath.hlsl`.

## Point and batch queries

```csharp
var erosion = AdvancedErosionParameters.Default with
{
    Scale = radius * 0.075f,
    Strength = 0.12f,
    Octaves = 7,
};
var field = PlanetaryFieldDefinition.Create(
    baseFieldVersion: 17,
    radius,
    seed: 42,
    erosion);
var scale = PlanetaryQueryScale.AtFootprint(
    footprintMeters: 10,
    maximumUnresolvedHeight: 0.5f);

PlanetaryBaseFieldSample basis = source.Sample(direction);
PlanetarySurfaceSample sample = PlanetaryField.Sample(
    field, direction, basis, scale);
```

`PlanetaryField.SampleBatch` writes into a caller-owned span. `SamplePosition`
accepts `double3`, reduces the astronomical position to a stable unit direction,
and then evaluates the same float field contract.

Higher-level CPU queries include bounded ray intersection, segment clearance,
great-circle profiles, and region summaries. Their answers remain field queries;
only a consuming simulation can turn them into committed game consequences.

## Cube-sphere topology and pages

`PlanetaryTopology` owns the tangent/QSC cube-sphere mapping, inverse face
coordinates, tile selection, local page coordinates, and radial-graph surface
normal. `PlanetaryPageSampling` owns bordered directions, nominal spacing,
bilinear sampling, and summaries.

`PlanetaryPageBaker` evaluates a root page at its physical sample spacing. A
child stores `child filtered field - parent filtered field`. A
`PlanetaryPageSetSampling` query adds every containing ancestor contribution
and applies transition weights only to residuals.

`PlanetaryLodSelector` selects six roots plus one camera-facing ancestor chain
from the unresolved-height error. `PlanetaryResidualResidency` owns arrival and
departure presentation weights, content and presentation versions, and nothing
about field truth.

## Patches

`PlanetaryPatch.CreateFace` and `CreateCubeSphere` produce renderer-neutral
coarse meshes from the canonical topology. HLSL calls
`cultmath_planetary_face_direction` for procedural vertices and
`cultmath_planetary_radial_refinement_step` for bounded pixel refinement.

Renderers still own cameras, clip space, depth, materials, buffers, dispatch,
and draw submission.

The optional `CultMath.Unity` assembly converts a canonical face patch into a
Unity `Mesh` and converts a residency snapshot into Unity-native page input and
metadata payloads. It owns no field parameters, page selection, or simulation
state. Unity render code remains responsible for allocating/binding graphics
buffers and dispatching application-specific base-field entry points.

## Maps

`PlanetaryProjection` supplies forward and inverse transforms for:

- equirectangular;
- Web Mercator with an explicit polar cutoff;
- Equal Earth;
- orthographic;
- azimuthal equidistant and equal-area;
- cube atlas;
- local tangent/gnomonic views.

`PlanetaryMapTileBaker` maps each valid tile sample through the inverse
projection and canonical field query. `PlanetaryMapTileKey` includes field,
projection, layer, layout, and query-scale identity. Palettes, contours, labels,
and strategic overlays do not enter CultMath.

## Numeric contract

Integer hashes and published field versions are exact. Basic arithmetic follows
CultMath's matched C#/HLSL semantics. Hardware transcendental functions such as
`atan` and `tan` use measured tolerances rather than fictional bit identity.
Every filtered terrain query carries an unresolved-height bound so consumers can
reject insufficient fidelity explicitly.

Current D3D12 parity evidence covers the advanced erosion kernel and the QSC
forward/inverse topology. The remaining production page and patch shaders use
the common functions and retain their seam, residual, summary, and radial-hit
integration probes in Fensalir.