117 lines
4.8 KiB
Markdown
117 lines
4.8 KiB
Markdown
# 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.
|