/**
 * Procedural atmosphere shell — translucent BackSide corona halo
 * mounted just outside the planet's silhouette on rocky / metallic
 * bodies.
 *
 * Orchestrator only — the heavy bits live in dedicated modules:
 *   - {@link ATMO_SHELL_FRAGMENT_SHADER} (in `atmoShellShaders`) carries the
 *     procedural look (FBm + bands + storms + clouds + rim-only mode).
 *   - {@link createAtmoShellPainter} (in `atmoShellPaint`) stamps per-tile
 *     RGB onto the vertex colour buffer via a K-NN blend.
 *   - {@link createAtmoShellHaloMode} (in `atmoShellHaloMode`) collapses the
 *     volumetric shell to a thin rim liseré for the playable-sol view.
 *
 * Gas giants don't use this shell — their smooth sphere already carries
 * the atmospheric look.
 */
import * as THREE from 'three';
import type { BodyConfig } from '../../types/body.types';
import type { Tile } from '../../geometry/hexasphere.types';
import { type RenderQuality } from '../quality/renderQuality';
import { type AtmoShellRGB } from './atmoShellPaint';
export type { AtmoShellRGB };
/**
 * Tunable scalar parameters consumed by the atmo shell's procedural
 * fragment shader. Every field is optional; omitted fields keep their
 * current value when passed through {@link AtmoShellHandle.setParams}.
 */
export interface AtmoShellParams {
    /** Overall opacity in `[0, 1]`. */
    opacity?: number;
    /**
     * Strength of multi-scale turbulence — domain-warping FBm distortion
     * applied to the latitude bands. `0` keeps the bands purely
     * latitudinal; `1` shreds them into roiling cells. Defaults to `0.6`.
     */
    turbulence?: number;
    /**
     * Mix factor between latitude bands and free-form turbulence in `[0, 1]`.
     * `1` = pure horizontal bands (gas-giant classic); `0` = pure swirling
     * cells (volcanic / nebula look). Defaults to `0.55`.
     */
    bandiness?: number;
    /**
     * Latitudinal band frequency — `5` = ~5 belts north-to-south. Higher
     * values pack tighter bands. Defaults to `5`.
     */
    bandFreq?: number;
    /**
     * Animation speed multiplier for the drift / turbulence advection.
     * `0` freezes the shell; `2` doubles the rate. Defaults to `1`.
     */
    driftSpeed?: number;
    /**
     * Storm-spot intensity in `[0, 1]` — sprinkles a few rotating
     * Jupiter-style storm cells. `0` disables them. Defaults to `0.25`.
     */
    storms?: number;
    /**
     * High-altitude cloud cover in `[0, 1]`. The cloud layer rides on the
     * atmo shell (formerly painted on the rocky surface itself), so the
     * playable sol stays clean while the cloud cover modulates the
     * atmosphere. `0` disables clouds. Defaults to `0`.
     */
    cloudAmount?: number;
    /** Cloud tint, hex string. Defaults to `'#e8eaf0'` (cool overcast white). */
    cloudColor?: string;
    /** Cloud-noise scale (≥ 0.1). Higher = more, smaller clouds. Defaults to `1.2`. */
    cloudScale?: number;
    /**
     * Per-tile colour mix in `[0, 1]` — strength of the painted-tile
     * colour over the body-level tint. `0` keeps the procedural tint
     * pure; `1` lets painted resources fully replace it. Defaults to
     * `0.85`.
     */
    tileColorMix?: number;
    /**
     * Body-relative halo tint (hex string, `'#rrggbb'`). Drives the
     * shell's `uTint` uniform — Mars rust, Venus yellow, Pluto glacial
     * blue. Live-patchable via {@link AtmoShellHandle.setParams}.
     */
    tint?: string;
}
/** Handle returned by {@link buildAtmoShell}. */
export interface AtmoShellHandle {
    mesh: THREE.Mesh;
    /** Advances the procedural drift animation. */
    tick: (elapsed: number) => void;
    /** Live-update the shell opacity in `[0, 1]` (no rebuild). */
    setOpacity: (value: number) => void;
    /** Toggles visibility without rebuilding. */
    setVisible: (value: boolean) => void;
    /** Live-tune the procedural shader params. Unspecified fields keep their value. */
    setParams: (params: AtmoShellParams) => void;
    /** Updates `uLightDir` so the day/night terminator tracks the scene's sun. */
    setLight: (direction: THREE.Vector3) => void;
    /** `true` flattens diffuse to uniform brightness (Sol-view dome look). */
    setFlatLighting: (enabled: boolean) => void;
    /**
     * Toggles "halo mode" — collapses the volumetric shell to a thin
     * fresnel-driven liseré at the atmosphere's outer silhouette, in the
     * pure body tint. See `createAtmoShellHaloMode` for the full contract
     * (baseline restoration semantics).
     */
    setHaloMode: (enabled: boolean) => void;
    /**
     * Stamps per-tile RGB into the shell's vertex colour buffer using a
     * K-nearest blend. See `createAtmoShellPainter`.
     *
     * No-op when the shell was built without `tiles` (decorative shell —
     * no gameplay link).
     */
    paintFromTiles: (colors: Map<number, AtmoShellRGB>) => void;
    /** Disposes geometry + material. Idempotent. */
    dispose: () => void;
}
/** Configuration accepted by {@link buildAtmoShell}. */
export interface AtmoShellConfig {
    config: BodyConfig;
    /** World radius the shell sits at — typically `config.radius`. */
    radius: number;
    /** Initial alpha in `[0, 1]`. */
    opacity: number;
    /**
     * Optional override for the body-relative tint (hex string). When
     * omitted, falls back to a neutral pale-blue default. Callers that
     * want a climate-driven hue derive it caller-side and pass it here.
     */
    tint?: string;
    /**
     * Body's hexasphere tiles — when provided, enables the `paintFromTiles`
     * bridge that projects per-tile gas colours from the playable atmo
     * grid onto the shell. Omit for a purely procedural shell with no
     * gameplay link.
     */
    tiles?: readonly Tile[];
    /**
     * Initial procedural params. Defaults are tuned for a generic temperate
     * atmosphere; gas-giant callers typically push `bandiness` and
     * `bandFreq` higher, while rocky callers push `turbulence` higher and
     * `bandiness` lower so the halo reads as soft cells rather than hard
     * belts.
     */
    params?: AtmoShellParams;
    /** Optional render-quality bag — bumps the icosphere detail in `'high'`. */
    quality?: RenderQuality;
}
/**
 * Builds the procedural atmosphere shell.
 */
export declare function buildAtmoShell(input: AtmoShellConfig): AtmoShellHandle;
//# sourceMappingURL=buildAtmoShell.d.ts.map