@johnmorrisdotca/chikyu-earth 0.5.0 → 0.8.0

package/dist/realistic/shaders.js

@@ -3,9 +3,11 @@
 export const SURFACE_VERT = /* glsl */ `
 varying vec2 vUv;
 varying vec3 vNormal;
+varying vec3 vWorld;
 void main() {
   vUv = uv;
   vNormal = normalize(mat3(modelMatrix) * position);
+  vWorld = (modelMatrix * vec4(position, 1.0)).xyz;
   gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
 }`;
 export const SURFACE_FRAG = /* glsl */ `
@@ -14,10 +16,13 @@ uniform sampler2D nightMap;
 uniform sampler2D waterMap;
 uniform vec3 sunDir;
 uniform float lights;
+uniform float ortho;
 varying vec2 vUv;
 varying vec3 vNormal;
+varying vec3 vWorld;
 void main() {
   vec3 n = normalize(vNormal);
+  vec3 toEye = ortho > 0.5 ? vec3(0.0, 0.0, 1.0) : normalize(cameraPosition - vWorld);
   float ndl = dot(n, sunDir);
   float day = smoothstep(-0.10, 0.22, ndl);
   vec3 albedo = texture2D(dayMap, vUv).rgb;
@@ -27,7 +32,7 @@ void main() {
   float dusk = smoothstep(-0.14, 0.0, ndl) * (1.0 - smoothstep(0.0, 0.30, ndl));
   lit += vec3(0.55, 0.28, 0.14) * dusk * 0.30 * (0.35 + 0.65 * albedo.g);
 
-  vec3 h = normalize(sunDir + vec3(0.0, 0.0, 1.0));
+  vec3 h = normalize(sunDir + toEye);
   float glint = pow(max(dot(n, h), 0.0), 220.0) * water * day;
   lit += vec3(1.0, 0.93, 0.80) * glint * 0.7;
 
@@ -35,7 +40,7 @@ void main() {
   night = night * night * vec3(1.6, 1.5, 1.3) * lights + night * 0.25;
   vec3 col = mix(night, lit, day);
 
-  float rim = pow(1.0 - clamp(n.z, 0.0, 1.0), 3.0);
+  float rim = pow(1.0 - clamp(dot(n, toEye), 0.0, 1.0), 3.0);
   float sunSide = 0.12 + 0.88 * smoothstep(-0.25, 0.5, ndl);
   col += vec3(0.20, 0.45, 1.0) * rim * sunSide * 0.55;
   gl_FragColor = vec4(col, 1.0);
@@ -58,22 +63,62 @@ void main() {
   gl_FragColor = vec4(col, a);
 }`;
 export const ATMOSPHERE_VERT = /* glsl */ `
-varying vec3 vView;
+varying vec3 vPosView;
+varying vec3 vNormalView;
 void main() {
   vec4 view = modelViewMatrix * vec4(position, 1.0);
-  vView = view.xyz;
+  vPosView = view.xyz;
+  vNormalView = normalize(normalMatrix * position);
   gl_Position = projectionMatrix * view;
 }`;
 export const ATMOSPHERE_FRAG = /* glsl */ `
-uniform vec3 sunDir;
+uniform vec3 sunView;
 uniform float outer;
-varying vec3 vView;
+uniform float ortho;
+varying vec3 vPosView;
+varying vec3 vNormalView;
 void main() {
-  float rho = length(vView.xy);
+  vec3 n = normalize(vNormalView);
+  vec3 v = ortho > 0.5 ? vec3(0.0, 0.0, 1.0) : normalize(-vPosView);
+  float nz = clamp(dot(n, v), -1.0, 1.0);
+  float rho = outer * sqrt(max(0.0, 1.0 - nz * nz));
   float t = clamp((rho - 1.0) / (outer - 1.0), 0.0, 1.0);
-  vec2 dir = rho > 0.0 ? vView.xy / rho : vec2(1.0, 0.0);
-  float side = smoothstep(-0.40, 0.55, dot(vec3(dir, 0.0), sunDir));
+  vec2 dir = normalize(n.xy + vec2(1e-5, 0.0));
+  float side = smoothstep(-0.40, 0.55, dot(vec3(dir, 0.0), sunView));
   float glow = pow(1.0 - t, 3.0) * (0.10 + 0.90 * side);
   vec3 col = mix(vec3(0.10, 0.22, 0.60), vec3(0.42, 0.68, 1.0), side);
   gl_FragColor = vec4(col, glow * 0.9);
 }`;
+/** The Moon and other plain bodies: a picture (or a flat colour) lit by the Sun, with a trace of light on the dark side. */
+export const BODY_FRAG = /* glsl */ `
+uniform sampler2D map;
+uniform vec3 tint;
+uniform float textured;
+uniform float ambient;
+uniform vec3 sunDir;
+varying vec2 vUv;
+varying vec3 vNormal;
+void main() {
+  vec3 n = normalize(vNormal);
+  float ndl = dot(n, sunDir);
+  vec3 albedo = textured > 0.5 ? texture2D(map, vUv).rgb : tint;
+  float lit = smoothstep(-0.04, 0.12, ndl) * (0.10 + 0.95 * pow(max(ndl, 0.0), 0.6));
+  gl_FragColor = vec4(albedo * (ambient + lit), 1.0);
+}`;
+/** A flat quad facing the camera: the Sun's disc and its glow. */
+export const GLOW_VERT = /* glsl */ `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}`;
+export const GLOW_FRAG = /* glsl */ `
+uniform vec3 tint;
+varying vec2 vUv;
+void main() {
+  float r = length(vUv - 0.5) * 2.0;
+  float core = 1.0 - smoothstep(0.10, 0.14, r);
+  float halo = pow(max(0.0, 1.0 - r), 2.5);
+  vec3 col = mix(tint, vec3(1.0), core);
+  gl_FragColor = vec4(col, clamp(core + halo * 0.85, 0.0, 1.0));
+}`;

package/dist/realistic/shared.d.ts

@@ -0,0 +1,23 @@
+import { type SharedRenderer } from "@johnmorrisdotca/kazoku-ui/renderer";
+import type { ThreeParts } from "./textures.ts";
+type Three = ThreeParts;
+export type ContextState = "lost" | "restored" | "unavailable";
+/**
+ * Where three.js comes from, if a page wants to hand it over itself (before the first element connects). A page that hands over a module re-exporting only the parts the Earth and the space view use ships a few hundred kilobytes of three.js instead of all of it.
+ *
+ * @param load - Returns the parts of three.js the Earth and the space view use, as a promise.
+ *
+ * @example
+ * ```ts no-run
+ * import { setThreeLoader } from "@johnmorrisdotca/chikyu-earth/realistic/element";
+ *
+ * setThreeLoader(() => import("three"));
+ * ```
+ */
+export declare function setThreeLoader(load: () => Promise<Three>): void;
+/** The page's renderer, made on first use. Call `release()` (from the result) when the element leaves. */
+export declare function takeRenderer(onContext: (state: ContextState) => void): {
+    renderer: SharedRenderer<Three>;
+    release(): void;
+};
+export {};

package/dist/realistic/shared.js

@@ -0,0 +1,51 @@
+// One shared renderer for the page, whichever element draws with it: the Earth from space and the space view both take it from here, so the page keeps one
+// WebGL context between them. The last element to leave lets it go (after a second, in case it is only moving).
+import { createSharedRenderer } from "@johnmorrisdotca/kazoku-ui/renderer";
+let shared;
+let loader = () => import("three");
+const contextListeners = new Set();
+let elements = 0;
+let releaseTimer;
+/**
+ * Where three.js comes from, if a page wants to hand it over itself (before the first element connects). A page that hands over a module re-exporting only the parts the Earth and the space view use ships a few hundred kilobytes of three.js instead of all of it.
+ *
+ * @param load - Returns the parts of three.js the Earth and the space view use, as a promise.
+ *
+ * @example
+ * ```ts no-run
+ * import { setThreeLoader } from "@johnmorrisdotca/chikyu-earth/realistic/element";
+ *
+ * setThreeLoader(() => import("three"));
+ * ```
+ */
+export function setThreeLoader(load) {
+    loader = load;
+}
+/** The page's renderer, made on first use. Call `release()` (from the result) when the element leaves. */
+export function takeRenderer(onContext) {
+    clearTimeout(releaseTimer);
+    elements += 1;
+    contextListeners.add(onContext);
+    shared ??= createSharedRenderer({
+        load: () => loader(),
+        onContext: (state) => {
+            for (const listener of contextListeners)
+                listener(state);
+        },
+    });
+    return {
+        renderer: shared,
+        release() {
+            contextListeners.delete(onContext);
+            elements -= 1;
+            if (elements <= 0) {
+                releaseTimer = setTimeout(() => {
+                    if (elements <= 0) {
+                        shared?.dispose();
+                        shared = undefined;
+                    }
+                }, 1000);
+            }
+        },
+    };
+}

package/dist/realistic/sun.d.ts

@@ -1,7 +1,44 @@
 import type { GeoPoint } from "../types.ts";
-/** Julian day number of a moment in milliseconds since the Unix epoch. */
+/**
+ * Julian day number of a moment in milliseconds since the Unix epoch.
+ *
+ * @param ms - Milliseconds since 1970-01-01T00:00Z.
+ * @returns The Julian day number, with its fraction.
+ *
+ * @example
+ * ```ts
+ * import { julianDay } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(julianDay(Date.UTC(2000, 0, 1, 12)));
+ * ```
+ */
 export declare const julianDay: (ms: number) => number;
-/** The point where the Sun is at the zenith at `ms`: latitude is the Sun's declination, longitude runs west at 15 degrees an hour. */
+/**
+ * The point where the Sun is at the zenith at `ms`: latitude is the Sun's declination, longitude runs west at 15 degrees an hour.
+ *
+ * @param ms - A moment, in milliseconds since the Unix epoch.
+ * @returns The longitude and latitude on the Earth that has the Sun straight overhead.
+ *
+ * @example
+ * ```ts
+ * import { subsolarPoint } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const sun = subsolarPoint(Date.UTC(2026, 5, 21, 12));
+ * console.log(sun.lat.toFixed(1), sun.lon.toFixed(1));
+ * ```
+ */
 export declare function subsolarPoint(ms: number): GeoPoint;
-/** A point on the globe as a unit vector: +z is longitude 0 on the equator, +x east, +y north. */
+/**
+ * A point on the globe as a unit vector: +z is longitude 0 on the equator, +x east, +y north.
+ *
+ * @param point - A longitude and latitude in degrees.
+ * @returns The `[x, y, z]` of the point on a sphere of radius 1.
+ *
+ * @example
+ * ```ts
+ * import { unitVector } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(unitVector({ lon: 90, lat: 0 }).map((n) => Math.round(n)));
+ * ```
+ */
 export declare function unitVector(point: GeoPoint): [number, number, number];

package/dist/realistic/sun.js

@@ -1,8 +1,33 @@
 const RAD = Math.PI / 180;
 const wrap360 = (degrees) => ((degrees % 360) + 360) % 360;
-/** Julian day number of a moment in milliseconds since the Unix epoch. */
+/**
+ * Julian day number of a moment in milliseconds since the Unix epoch.
+ *
+ * @param ms - Milliseconds since 1970-01-01T00:00Z.
+ * @returns The Julian day number, with its fraction.
+ *
+ * @example
+ * ```ts
+ * import { julianDay } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(julianDay(Date.UTC(2000, 0, 1, 12)));
+ * ```
+ */
 export const julianDay = (ms) => ms / 86_400_000 + 2_440_587.5;
-/** The point where the Sun is at the zenith at `ms`: latitude is the Sun's declination, longitude runs west at 15 degrees an hour. */
+/**
+ * The point where the Sun is at the zenith at `ms`: latitude is the Sun's declination, longitude runs west at 15 degrees an hour.
+ *
+ * @param ms - A moment, in milliseconds since the Unix epoch.
+ * @returns The longitude and latitude on the Earth that has the Sun straight overhead.
+ *
+ * @example
+ * ```ts
+ * import { subsolarPoint } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const sun = subsolarPoint(Date.UTC(2026, 5, 21, 12));
+ * console.log(sun.lat.toFixed(1), sun.lon.toFixed(1));
+ * ```
+ */
 export function subsolarPoint(ms) {
     const jd = julianDay(ms);
     const t = (jd - 2_451_545) / 36_525;
@@ -20,7 +45,19 @@ export function subsolarPoint(ms) {
     const lon = ((wrap360(rightAscension - siderealGreenwich) + 180) % 360) - 180;
     return { lon, lat: declination / RAD };
 }
-/** A point on the globe as a unit vector: +z is longitude 0 on the equator, +x east, +y north. */
+/**
+ * A point on the globe as a unit vector: +z is longitude 0 on the equator, +x east, +y north.
+ *
+ * @param point - A longitude and latitude in degrees.
+ * @returns The `[x, y, z]` of the point on a sphere of radius 1.
+ *
+ * @example
+ * ```ts
+ * import { unitVector } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(unitVector({ lon: 90, lat: 0 }).map((n) => Math.round(n)));
+ * ```
+ */
 export function unitVector(point) {
     const lon = point.lon * RAD;
     const lat = point.lat * RAD;

package/dist/realistic/textures.d.ts

@@ -0,0 +1,43 @@
+import type * as THREE from "three";
+import type { AssetCache } from "@johnmorrisdotca/kazoku-ui/renderer";
+import { type Layer } from "./tiers.ts";
+/**
+ * The parts of three.js the Earth and the space view use. A page can hand over a module that re-exports just these (see `setThreeLoader`) instead of all of three.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ThreeParts } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const load = (): Promise<ThreeParts> => import("three");
+ * console.log(typeof load);
+ * ```
+ */
+export type ThreeParts = {
+    [Name in "Texture" | "BufferGeometry" | "BufferAttribute" | "ShaderMaterial" | "Group" | "Mesh" | "Scene" | "OrthographicCamera" | "PerspectiveCamera" | "Vector3" | "WebGLRenderer" | "RepeatWrapping" | "ClampToEdgeWrapping" | "LinearMipmapLinearFilter" | "LinearFilter" | "BackSide" | "DoubleSide" | "LineLoop" | "LineBasicMaterial" | "Color"]: (typeof THREE)[Name];
+} & {
+    /** Only the satellites use it, so a loader that hands over a subset of three.js without it still draws everything else. */
+    Points?: typeof THREE.Points;
+};
+/** Milliseconds a lower texture size must be enough before the larger one is let go. */
+export declare const DOWNGRADE_AFTER_MS = 4000;
+export interface TextureDeps {
+    assets: AssetCache;
+    /** Ends with a slash. */
+    textureBase: () => string;
+    /** The widest texture, 4096 at most. */
+    cap: () => number;
+    invalidate: () => void;
+    onError?: (error: unknown) => void;
+    onTier?: (layer: Layer, width: number) => void;
+}
+export interface TextureSet {
+    /** The `{ value }` a shader uniform takes, one a layer; the value is the texture now in use. */
+    readonly uniforms: Record<string, {
+        value: THREE.Texture | null;
+    }>;
+    /** Hold the width each layer needs for a disc of this many device pixels across the radius (`radiusPx[layer]`, or one number for all). */
+    sync(radiusPx: number | Partial<Record<Layer, number>>): void;
+    dispose(): void;
+}
+/** Load the base picture of each layer, then hand back the set. Rejects (after freeing what it took) if one will not load. */
+export declare function createTextureSet(three: ThreeParts, layers: readonly Layer[], deps: TextureDeps): Promise<TextureSet>;

package/dist/realistic/textures.js

@@ -0,0 +1,141 @@
+import { chooseTier, TIERS } from "./tiers.js";
+/** Milliseconds a lower texture size must be enough before the larger one is let go. */
+export const DOWNGRADE_AFTER_MS = 4000;
+/** Load the base picture of each layer, then hand back the set. Rejects (after freeing what it took) if one will not load. */
+export async function createTextureSet(three, layers, deps) {
+    let disposed = false;
+    const held = [];
+    const keyOf = (layer, texels) => `chikyu-earth:${layer}:${texels}`;
+    const take = (layer, texels) => {
+        const key = keyOf(layer, texels);
+        const entry = deps.assets.acquire(key, () => {
+            const texture = new three.Texture();
+            texture.wrapS = three.RepeatWrapping;
+            texture.wrapT = three.ClampToEdgeWrapping;
+            texture.minFilter = three.LinearMipmapLinearFilter;
+            texture.magFilter = three.LinearFilter;
+            texture.anisotropy = 8;
+            const controller = new AbortController();
+            const made = { width: texels, texture, closed: false, ready: Promise.resolve(), release: () => undefined };
+            made.ready = fetch(`${deps.textureBase()}${layer}-${texels}.webp`, { signal: controller.signal })
+                .then((response) => {
+                if (!response.ok)
+                    throw new Error(`${layer}-${texels}.webp: ${response.status}`);
+                return response.blob();
+            })
+                .then((blob) => createImageBitmap(blob, { premultiplyAlpha: "none", colorSpaceConversion: "none" }))
+                .then((bitmap) => {
+                if (made.closed)
+                    bitmap.close();
+                else {
+                    texture.image = bitmap;
+                    texture.needsUpdate = true;
+                }
+            });
+            made.ready.catch(() => undefined);
+            made.release = () => {
+                made.closed = true;
+                controller.abort();
+                texture.dispose();
+                texture.image?.close?.();
+            };
+            return made;
+        }, (value) => value.release());
+        held.push(key);
+        return entry;
+    };
+    const letGo = (layer, texels) => {
+        const key = keyOf(layer, texels);
+        const at = held.indexOf(key);
+        if (at >= 0)
+            held.splice(at, 1);
+        deps.assets.release(key);
+    };
+    const slots = new Map();
+    for (const layer of layers) {
+        const baseWidth = TIERS[layer][0];
+        const base = take(layer, baseWidth);
+        slots.set(layer, { layer, uniform: { value: null }, base, baseWidth, entry: base, width: baseWidth, loading: undefined, timer: undefined });
+    }
+    try {
+        await Promise.all([...slots.values()].map((slot) => slot.base.ready));
+    }
+    catch (error) {
+        for (const slot of slots.values())
+            letGo(slot.layer, slot.baseWidth);
+        deps.onError?.(error);
+        throw error;
+    }
+    for (const slot of slots.values())
+        slot.uniform.value = slot.base.texture;
+    const swap = (slot, entry, texels) => {
+        const previous = slot.entry;
+        slot.entry = entry;
+        slot.width = texels;
+        slot.uniform.value = entry.texture;
+        if (previous !== slot.base)
+            letGo(slot.layer, previous.width);
+        deps.onTier?.(slot.layer, texels);
+    };
+    const moveTo = (slot, texels) => {
+        if (disposed || texels === slot.width || slot.loading === texels)
+            return;
+        if (texels === slot.baseWidth) {
+            swap(slot, slot.base, texels);
+            deps.invalidate();
+            return;
+        }
+        slot.loading = texels;
+        const entry = take(slot.layer, texels);
+        entry.ready.then(() => {
+            if (disposed || slot.loading !== texels) {
+                letGo(slot.layer, texels);
+                return;
+            }
+            slot.loading = undefined;
+            swap(slot, entry, texels);
+            deps.invalidate();
+        }, (error) => {
+            letGo(slot.layer, texels);
+            if (slot.loading === texels)
+                slot.loading = undefined;
+            deps.onError?.(error);
+        });
+    };
+    let lastRadius = 0;
+    const wantedFor = (slot, radius) => {
+        const px = typeof radius === "number" ? radius : (radius[slot.layer] ?? 0);
+        return chooseTier(slot.layer, px, deps.cap());
+    };
+    return {
+        uniforms: Object.fromEntries([...slots].map(([layer, slot]) => [layer, slot.uniform])),
+        sync(radiusPx) {
+            lastRadius = radiusPx;
+            for (const slot of slots.values()) {
+                const wanted = wantedFor(slot, radiusPx);
+                if (slot.timer !== undefined && wanted >= slot.width) {
+                    clearTimeout(slot.timer);
+                    slot.timer = undefined;
+                }
+                if (wanted > slot.width)
+                    moveTo(slot, wanted);
+                else if (wanted < slot.width && slot.timer === undefined) {
+                    slot.timer = setTimeout(() => {
+                        slot.timer = undefined;
+                        const now = wantedFor(slot, lastRadius);
+                        if (now < slot.width)
+                            moveTo(slot, now);
+                    }, DOWNGRADE_AFTER_MS);
+                }
+            }
+        },
+        dispose() {
+            disposed = true;
+            for (const slot of slots.values())
+                if (slot.timer !== undefined)
+                    clearTimeout(slot.timer);
+            for (const key of held.splice(0))
+                deps.assets.release(key);
+        },
+    };
+}

package/dist/realistic/tiers.d.ts

@@ -1,20 +1,94 @@
-export type Layer = "day" | "night" | "clouds" | "water";
-/** The widths each layer is shipped in (every picture is 2:1, so the height is half). */
+/**
+ * One of the pictures the realistic Earth and the space view draw with: `day`, `night`, `clouds`, `water` and `moon`.
+ *
+ * @example
+ * ```ts
+ * import { TIERS, type Layer } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const layer: Layer = "clouds";
+ * console.log(TIERS[layer]);
+ * ```
+ */
+export type Layer = "day" | "night" | "clouds" | "water" | "moon";
+/**
+ * The widths each layer is shipped in (every picture is 2:1, so the height is half).
+ *
+ * @example
+ * ```ts
+ * import { TIERS } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(TIERS.day);
+ * ```
+ */
 export declare const TIERS: Record<Layer, readonly number[]>;
-/** The most pixels across a texture the package ever asks the GPU for. */
+/**
+ * The most pixels across a texture the package ever asks the GPU for.
+ *
+ * @example
+ * ```ts
+ * import { MAX_TEXTURE } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(MAX_TEXTURE);
+ * ```
+ */
 export declare const MAX_TEXTURE = 4096;
-/** Texels across the whole circumference wanted per device pixel of the globe's radius: 3 is a little under 2 pi, so a texel is a little larger than a pixel. */
+/**
+ * Texels across the whole circumference wanted per device pixel of the globe's radius: 3 is a little under 2 pi, so a texel is a little larger than a pixel.
+ *
+ * @example
+ * ```ts
+ * import { TEXELS_PER_RADIUS_PIXEL } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(TEXELS_PER_RADIUS_PIXEL);
+ * ```
+ */
 export declare const TEXELS_PER_RADIUS_PIXEL = 3;
 /**
  * The width to hold for a layer when the globe's disc has radius `radiusPx` device pixels: the smallest shipped width that gives
  * `TEXELS_PER_RADIUS_PIXEL` texels per pixel, else the largest, never more than `cap`, never less than the smallest.
+ *
+ * @param layer - Which picture.
+ * @param radiusPx - The disc's radius in device pixels.
+ * @param cap - The most pixels across to ask for; {@link MAX_TEXTURE} by default.
+ * @returns One of the widths in {@link TIERS} for that layer.
+ *
+ * @example
+ * ```ts
+ * import { chooseTier } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(chooseTier("day", 200), chooseTier("day", 900), chooseTier("day", 900, 2048));
+ * ```
  */
 export declare function chooseTier(layer: Layer, radiusPx: number, cap?: number): number;
-/** The cap for this device: low-memory phones stop at 2048, and the GPU's own limit and the option are never passed. */
+/**
+ * The cap for this device: low-memory phones stop at 2048, and the GPU's own limit and the option are never passed.
+ *
+ * @param options - `max` (the page's own limit), `gpuMax` (the GPU's `MAX_TEXTURE_SIZE`) and `deviceMemory` (gigabytes, from `navigator.deviceMemory`); each may be left out.
+ * @returns The most pixels across any picture may have on this device.
+ *
+ * @example
+ * ```ts
+ * import { textureCap } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(textureCap(), textureCap({ deviceMemory: 2 }), textureCap({ gpuMax: 1024 }));
+ * ```
+ */
 export declare function textureCap(options?: {
     max?: number;
     gpuMax?: number;
     deviceMemory?: number;
 }): number;
-/** Bytes of GPU memory a texture of this width costs, with its mipmaps, at 4 bytes a pixel (the most it can be). */
+/**
+ * Bytes of GPU memory a texture of this width costs, with its mipmaps, at 4 bytes a pixel (the most it can be).
+ *
+ * @param width - Pixels across; the picture is 2:1.
+ * @returns The bytes the GPU holds for it.
+ *
+ * @example
+ * ```ts
+ * import { textureBytes } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(textureBytes(4096));
+ * ```
+ */
 export declare const textureBytes: (width: number) => number;

package/dist/realistic/tiers.js

@@ -1,30 +1,94 @@
 // Which size of each picture to hold on the GPU. Small first, sharper on zoom, and never past a cap. Pure.
-/** The widths each layer is shipped in (every picture is 2:1, so the height is half). */
+/**
+ * The widths each layer is shipped in (every picture is 2:1, so the height is half).
+ *
+ * @example
+ * ```ts
+ * import { TIERS } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(TIERS.day);
+ * ```
+ */
 export const TIERS = {
     day: [1024, 2048, 4096],
     night: [1024, 2048],
     clouds: [1024, 2048],
     water: [1024, 2048],
+    moon: [1024, 2048],
 };
-/** The most pixels across a texture the package ever asks the GPU for. */
+/**
+ * The most pixels across a texture the package ever asks the GPU for.
+ *
+ * @example
+ * ```ts
+ * import { MAX_TEXTURE } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(MAX_TEXTURE);
+ * ```
+ */
 export const MAX_TEXTURE = 4096;
-/** Texels across the whole circumference wanted per device pixel of the globe's radius: 3 is a little under 2 pi, so a texel is a little larger than a pixel. */
+/**
+ * Texels across the whole circumference wanted per device pixel of the globe's radius: 3 is a little under 2 pi, so a texel is a little larger than a pixel.
+ *
+ * @example
+ * ```ts
+ * import { TEXELS_PER_RADIUS_PIXEL } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(TEXELS_PER_RADIUS_PIXEL);
+ * ```
+ */
 export const TEXELS_PER_RADIUS_PIXEL = 3;
 /**
  * The width to hold for a layer when the globe's disc has radius `radiusPx` device pixels: the smallest shipped width that gives
  * `TEXELS_PER_RADIUS_PIXEL` texels per pixel, else the largest, never more than `cap`, never less than the smallest.
+ *
+ * @param layer - Which picture.
+ * @param radiusPx - The disc's radius in device pixels.
+ * @param cap - The most pixels across to ask for; {@link MAX_TEXTURE} by default.
+ * @returns One of the widths in {@link TIERS} for that layer.
+ *
+ * @example
+ * ```ts
+ * import { chooseTier } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(chooseTier("day", 200), chooseTier("day", 900), chooseTier("day", 900, 2048));
+ * ```
  */
 export function chooseTier(layer, radiusPx, cap = MAX_TEXTURE) {
     const widths = TIERS[layer].filter((width) => width <= Math.max(cap, TIERS[layer][0]));
     const wanted = radiusPx * TEXELS_PER_RADIUS_PIXEL;
     return widths.find((width) => width >= wanted) ?? widths[widths.length - 1];
 }
-/** The cap for this device: low-memory phones stop at 2048, and the GPU's own limit and the option are never passed. */
+/**
+ * The cap for this device: low-memory phones stop at 2048, and the GPU's own limit and the option are never passed.
+ *
+ * @param options - `max` (the page's own limit), `gpuMax` (the GPU's `MAX_TEXTURE_SIZE`) and `deviceMemory` (gigabytes, from `navigator.deviceMemory`); each may be left out.
+ * @returns The most pixels across any picture may have on this device.
+ *
+ * @example
+ * ```ts
+ * import { textureCap } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(textureCap(), textureCap({ deviceMemory: 2 }), textureCap({ gpuMax: 1024 }));
+ * ```
+ */
 export function textureCap(options = {}) {
     let cap = Math.min(MAX_TEXTURE, options.max ?? MAX_TEXTURE, options.gpuMax ?? MAX_TEXTURE);
     if (options.deviceMemory !== undefined && options.deviceMemory <= 2)
         cap = Math.min(cap, 2048);
     return cap;
 }
-/** Bytes of GPU memory a texture of this width costs, with its mipmaps, at 4 bytes a pixel (the most it can be). */
+/**
+ * Bytes of GPU memory a texture of this width costs, with its mipmaps, at 4 bytes a pixel (the most it can be).
+ *
+ * @param width - Pixels across; the picture is 2:1.
+ * @returns The bytes the GPU holds for it.
+ *
+ * @example
+ * ```ts
+ * import { textureBytes } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(textureBytes(4096));
+ * ```
+ */
 export const textureBytes = (width) => Math.round(width * (width / 2) * 4 * (4 / 3));