@johnmorrisdotca/chikyu-earth 0.5.0 → 0.8.0

package/dist/realistic/earth.js

@@ -1,14 +1,21 @@
 import { HOME_VIEW, lookAt } from "../view.js";
 import { ATMOSPHERE_FRAG, ATMOSPHERE_VERT, CLOUD_FRAG, SURFACE_FRAG, SURFACE_VERT } from "./shaders.js";
 import { subsolarPoint, unitVector } from "./sun.js";
-import { chooseTier, TIERS } from "./tiers.js";
+import { createTextureSet } from "./textures.js";
 const RAD = Math.PI / 180;
-/** The glow reaches this many radii from the centre; the globe at 1x is drawn to fit inside it. */
+/**
+ * The glow reaches this many radii from the centre; the globe at 1x is drawn to fit inside it.
+ *
+ * @example
+ * ```ts
+ * import { ATMOSPHERE_OUTER } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(ATMOSPHERE_OUTER);
+ * ```
+ */
 export const ATMOSPHERE_OUTER = 1.08;
 const CLOUD_RADIUS = 1.006;
 const LAYERS = ["day", "night", "clouds", "water"];
-/** Milliseconds a lower texture size must be enough before the larger one is let go. */
-const DOWNGRADE_AFTER_MS = 4000;
 export const newModel = () => ({
     centre: { lon: 0, lat: 0 },
     view: { ...HOME_VIEW },
@@ -18,11 +25,25 @@ export const newModel = () => ({
     drawn: null,
     ratio: () => Math.min(globalThis.devicePixelRatio || 1, 2),
 });
-/** The disc's radius in CSS pixels in a box of `width` x `height` at `zoom`: it fits the glow in the box at 1x. */
+/**
+ * The disc's radius in CSS pixels in a box of `width` x `height` at `zoom`: it fits the glow in the box at 1x.
+ *
+ * @param width - The box's width in CSS pixels.
+ * @param height - The box's height in CSS pixels.
+ * @param zoom - The view's zoom, 1 at Fit.
+ * @returns The radius in CSS pixels, at least 1.
+ *
+ * @example
+ * ```ts
+ * import { discRadius } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(discRadius(400, 400, 1).toFixed(1));
+ * ```
+ */
 export const discRadius = (width, height, zoom) => Math.max(1, (Math.min(width, height) / 2 / ATMOSPHERE_OUTER - 1) * zoom);
 export { lookAt };
 /** An equirectangular sphere: +z is longitude 0 on the equator, +x east, +y north; v is 0 at the north pole (the top row of the picture). */
-function sphere(three, columns, rows) {
+export function sphere(three, columns, rows) {
     const positions = new Float32Array((columns + 1) * (rows + 1) * 3);
     const uvs = new Float32Array((columns + 1) * (rows + 1) * 2);
     let p = 0;
@@ -57,89 +78,34 @@ export function createEarthItem(model, deps) {
         key: "chikyu-earth:realistic",
         async build({ three, width, height }) {
             let size = { width, height };
-            let disposed = false;
-            const held = [];
-            const makeTexture = (layer, texels) => {
-                const key = `chikyu-earth:${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 = `chikyu-earth:${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 = makeTexture(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 textures = await createTextureSet(three, LAYERS, {
+                assets: deps.assets,
+                textureBase: deps.textureBase,
+                cap: deps.cap,
+                invalidate: deps.invalidate,
+                ...(deps.onError ? { onError: deps.onError } : {}),
+                ...(deps.onTier ? { onTier: deps.onTier } : {}),
+            });
+            const uniform = textures.uniforms;
             const sunDir = { value: new three.Vector3(1, 0, 0) };
             const grid = sphere(three, 128, 64);
             const surface = new three.ShaderMaterial({
                 vertexShader: SURFACE_VERT,
                 fragmentShader: SURFACE_FRAG,
-                uniforms: { dayMap: slots.get("day").uniform, nightMap: slots.get("night").uniform, waterMap: slots.get("water").uniform, sunDir, lights: { value: 1 } },
+                uniforms: { dayMap: uniform.day, nightMap: uniform.night, waterMap: uniform.water, sunDir, lights: { value: 1 }, ortho: { value: 1 } },
             });
             const cloudShift = { value: 0 };
             const cloudMaterial = new three.ShaderMaterial({
                 vertexShader: SURFACE_VERT,
                 fragmentShader: CLOUD_FRAG,
-                uniforms: { cloudMap: slots.get("clouds").uniform, sunDir, shift: cloudShift, opacity: { value: 0.9 } },
+                uniforms: { cloudMap: uniform.clouds, sunDir, shift: cloudShift, opacity: { value: 0.9 } },
                 transparent: true,
                 depthWrite: false,
             });
             const atmosphere = new three.ShaderMaterial({
                 vertexShader: ATMOSPHERE_VERT,
                 fragmentShader: ATMOSPHERE_FRAG,
-                uniforms: { sunDir, outer: { value: ATMOSPHERE_OUTER } },
+                uniforms: { sunView: sunDir, outer: { value: ATMOSPHERE_OUTER }, ortho: { value: 1 } },
                 transparent: true,
                 depthWrite: false,
                 side: three.BackSide,
@@ -158,60 +124,6 @@ export function createEarthItem(model, deps) {
             scene.add(turned, glow);
             const camera = new three.OrthographicCamera(-1, 1, 1, -1, 0.1, 20);
             camera.position.set(0, 0, 5);
-            const setUniformTexture = (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) {
-                    setUniformTexture(slot, slot.base, texels);
-                    deps.invalidate();
-                    return;
-                }
-                slot.loading = texels;
-                const entry = makeTexture(slot.layer, texels);
-                entry.ready.then(() => {
-                    if (disposed || slot.loading !== texels) {
-                        letGo(slot.layer, texels);
-                        return;
-                    }
-                    slot.loading = undefined;
-                    setUniformTexture(slot, entry, texels);
-                    deps.invalidate();
-                }, (error) => {
-                    letGo(slot.layer, texels);
-                    if (slot.loading === texels)
-                        slot.loading = undefined;
-                    deps.onError?.(error);
-                });
-            };
-            const syncTiers = (radiusCssPx) => {
-                const radius = radiusCssPx * model.ratio();
-                for (const slot of slots.values()) {
-                    const wanted = chooseTier(slot.layer, radius, deps.cap());
-                    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 = chooseTier(slot.layer, discRadius(size.width, size.height, model.view.zoom) * model.ratio(), deps.cap());
-                            if (now < slot.width)
-                                moveTo(slot, now);
-                        }, DOWNGRADE_AFTER_MS);
-                    }
-                }
-            };
             return {
                 scene,
                 camera,
@@ -231,7 +143,7 @@ export function createEarthItem(model, deps) {
                     camera.bottom = (-size.height / 2 + view.panY) / radius;
                     camera.updateProjectionMatrix();
                     model.drawn = { view: { ...view }, time: model.time, radius, centre: { ...model.centre } };
-                    syncTiers(radius);
+                    textures.sync(radius * model.ratio());
                     deps.onPose?.({ lon: look.lon, lat: look.lat, radius, cx: size.width / 2 + view.panX, cy: size.height / 2 + view.panY, width: size.width, height: size.height });
                     return false;
                 },
@@ -239,12 +151,7 @@ export function createEarthItem(model, deps) {
                     size = { width: next, height: nextHeight };
                 },
                 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);
+                    textures.dispose();
                     grid.dispose();
                     surface.dispose();
                     cloudMaterial.dispose();

package/dist/realistic/element.d.ts

@@ -1,13 +1,49 @@
 import type { GeoPoint, GlobeView } from "../types.ts";
-import { type ThreeParts } from "./earth.ts";
+import { setThreeLoader } from "./shared.ts";
+export { setThreeLoader };
 import type { OverlayHost } from "../markers/layer.ts";
 import { type Layer } from "./tiers.ts";
-type Three = ThreeParts;
+type EarthLayer = Extract<Layer, "day" | "night" | "clouds" | "water">;
+/**
+ * What the realistic Earth is doing: `loading` its pictures, `live` and drawing, `unavailable` (no WebGL), `lost` (the GPU took the context; it comes back by itself) or `idle` (another view has the page's one WebGL context; press or focus it to take it).
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuEarthRealistic, EarthState } from "@johnmorrisdotca/chikyu-earth/realistic/element";
+ *
+ * const describe = (earth: ChikyuEarthRealistic): EarthState => earth.stats.state;
+ * console.log(typeof describe);
+ * ```
+ */
 export type EarthState = "loading" | "live" | "unavailable" | "lost" | "idle";
-/** A `time` attribute: "now" (or none) follows the clock, else an ISO date such as 2026-06-21T12:00:00Z. */
+/**
+ * A `time` attribute: "now" (or none) follows the clock, else an ISO date such as 2026-06-21T12:00:00Z.
+ *
+ * @param value - The attribute's text, or `null` when it is not there.
+ * @returns The moment in milliseconds since the Unix epoch, or `"now"` when the value is empty, `"now"` or not a date.
+ *
+ * @example
+ * ```ts no-run
+ * import { readTime } from "@johnmorrisdotca/chikyu-earth/realistic/element";
+ *
+ * console.log(readTime("2026-06-21T12:00:00Z"), readTime(null), readTime("tomorrow"));
+ * ```
+ */
 export declare const readTime: (value: string | null) => number | "now";
-/** Where three.js comes from, if a page wants to hand it over itself (before the first element connects). */
-export declare function setThreeLoader(load: () => Promise<Three>): void;
+/**
+ * The `<chikyu-earth-realistic>` custom element: the Earth from space, drawn with three.js through kazoku-ui's shared renderer (one WebGL context for the page). It takes `center` (`"lon,lat"`), `time` (`now` or an ISO date; the real Sun at that moment), `clouds="off"`, `lights="off"`, `live-seconds` and `texture-base` (where the pictures are served from), and a shared view controller's camera through `setView`. It draws only when something changes, at most 30 times a second, and nothing while it is out of sight or the tab is hidden.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuEarthRealistic } from "@johnmorrisdotca/chikyu-earth/realistic/element";
+ *
+ * const earth = document.createElement("chikyu-earth-realistic") as ChikyuEarthRealistic;
+ * earth.setAttribute("center", "139.7,35.7");
+ * earth.setAttribute("time", "2026-06-21T03:00Z");
+ * earth.setAttribute("texture-base", "/textures/");
+ * document.body.append(earth);
+ * ```
+ */
 export declare class ChikyuEarthRealistic extends HTMLElement {
     #private;
     static observedAttributes: string[];
@@ -29,7 +65,7 @@ export declare class ChikyuEarthRealistic extends HTMLElement {
     /** What the element is doing, for a page or a test: its state, the texture widths held, the draws made. */
     get stats(): {
         state: EarthState;
-        tiers: Record<Layer, number>;
+        tiers: Record<EarthLayer, number>;
         draws: number;
         contexts: number;
         canvas: {
@@ -50,4 +86,8 @@ export declare class ChikyuEarthRealistic extends HTMLElement {
     /** The view as it is (for a page that wants to read it back). */
     get view(): GlobeView;
 }
-export {};
+declare global {
+    interface HTMLElementTagNameMap {
+        "chikyu-earth-realistic": ChikyuEarthRealistic;
+    }
+}

package/dist/realistic/element.js

@@ -1,9 +1,7 @@
-// <chikyu-earth-realistic>: the Earth from space as a web component, drawn by kazoku-ui's shared 3D renderer (one WebGL context for the
-// page) with three.js, which is the page's own. Optional entry point: the flat `<chikyu-earth>` needs neither. It draws only when something
-// changes, at most 30 times a second, and nothing at all while it is out of sight or the tab is hidden.
-import { createSharedRenderer } from "@johnmorrisdotca/kazoku-ui/renderer";
 import { createEarthItem, lookAt, newModel } from "./earth.js";
 import { createGate, frameCap } from "./gate.js";
+import { setThreeLoader, takeRenderer } from "./shared.js";
+export { setThreeLoader };
 import { MAX_TEXTURE, TIERS } from "./tiers.js";
 const RAD = Math.PI / 180;
 /** The Sun and the clouds are re-placed this often while the time is "now": 15 degrees an hour is 0.25 degree a minute. */
@@ -17,33 +15,39 @@ const readCentre = (value) => {
         return null;
     return { lon: lon, lat: lat };
 };
-/** A `time` attribute: "now" (or none) follows the clock, else an ISO date such as 2026-06-21T12:00:00Z. */
+/**
+ * A `time` attribute: "now" (or none) follows the clock, else an ISO date such as 2026-06-21T12:00:00Z.
+ *
+ * @param value - The attribute's text, or `null` when it is not there.
+ * @returns The moment in milliseconds since the Unix epoch, or `"now"` when the value is empty, `"now"` or not a date.
+ *
+ * @example
+ * ```ts no-run
+ * import { readTime } from "@johnmorrisdotca/chikyu-earth/realistic/element";
+ *
+ * console.log(readTime("2026-06-21T12:00:00Z"), readTime(null), readTime("tomorrow"));
+ * ```
+ */
 export const readTime = (value) => {
     if (value === null || value === "" || value === "now")
         return "now";
     const ms = Date.parse(value);
     return Number.isFinite(ms) ? ms : "now";
 };
-// --- one renderer for the page ----------------------------------------------------------------------------------------------------------------------
-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). */
-export function setThreeLoader(load) {
-    loader = load;
-}
-function renderer() {
-    shared ??= createSharedRenderer({
-        load: () => loader(),
-        onContext: (state) => {
-            for (const listener of contextListeners)
-                listener(state);
-        },
-    });
-    return shared;
-}
+/**
+ * The `<chikyu-earth-realistic>` custom element: the Earth from space, drawn with three.js through kazoku-ui's shared renderer (one WebGL context for the page). It takes `center` (`"lon,lat"`), `time` (`now` or an ISO date; the real Sun at that moment), `clouds="off"`, `lights="off"`, `live-seconds` and `texture-base` (where the pictures are served from), and a shared view controller's camera through `setView`. It draws only when something changes, at most 30 times a second, and nothing while it is out of sight or the tab is hidden.
+ *
+ * @example
+ * ```ts no-run
+ * import type { ChikyuEarthRealistic } from "@johnmorrisdotca/chikyu-earth/realistic/element";
+ *
+ * const earth = document.createElement("chikyu-earth-realistic") as ChikyuEarthRealistic;
+ * earth.setAttribute("center", "139.7,35.7");
+ * earth.setAttribute("time", "2026-06-21T03:00Z");
+ * earth.setAttribute("texture-base", "/textures/");
+ * document.body.append(earth);
+ * ```
+ */
 export class ChikyuEarthRealistic extends HTMLElement {
     static observedAttributes = ["center", "time", "clouds", "lights", "live-seconds"];
     #model = newModel();
@@ -53,6 +57,7 @@ export class ChikyuEarthRealistic extends HTMLElement {
     #tick;
     #state = "loading";
     #tiers = { day: TIERS.day[0], night: TIERS.night[0], clouds: TIERS.clouds[0], water: TIERS.water[0] };
+    #taken;
     #stage;
     #overlay;
     #pose = null;
@@ -65,8 +70,6 @@ export class ChikyuEarthRealistic extends HTMLElement {
     #lost = () => this.#set("lost");
     #restored = () => this.#set("live");
     connectedCallback() {
-        clearTimeout(releaseTimer);
-        elements += 1;
         this.#model.centre = readCentre(this.getAttribute("center")) ?? this.#model.centre;
         this.#mode = readTime(this.getAttribute("time"));
         this.#model.time = this.#mode === "now" ? Date.now() : this.#mode;
@@ -89,9 +92,10 @@ export class ChikyuEarthRealistic extends HTMLElement {
             if (!battery.charging && battery.level <= 0.2)
                 this.#gate?.setMinMs(1000 / Math.min(cap, 15));
         }, () => undefined);
-        contextListeners.add(this.#onContext);
+        const taken = takeRenderer(this.#onContext);
+        this.#taken = taken;
         const item = createEarthItem(this.#model, {
-            assets: renderer().assets,
+            assets: taken.renderer.assets,
             textureBase: () => this.#textureBase(),
             cap: () => this.#textureCap(),
             drift: 1.5,
@@ -103,11 +107,12 @@ export class ChikyuEarthRealistic extends HTMLElement {
             },
             onError: (error) => this.#fail(error instanceof Error ? error.message : String(error)),
             onTier: (layer, width) => {
-                this.#tiers[layer] = width;
+                if (layer in this.#tiers)
+                    this.#tiers[layer] = width;
                 this.dispatchEvent(new CustomEvent("chikyu-tier", { detail: { layer, width } }));
             },
         });
-        this.#view = renderer().view(this.#stage, item, { still: null });
+        this.#view = taken.renderer.view(this.#stage, item, { still: null });
         this.#set("loading");
         void this.#view.focus().then((live) => {
             if (live) {
@@ -115,7 +120,7 @@ export class ChikyuEarthRealistic extends HTMLElement {
                 this.dispatchEvent(new CustomEvent("chikyu-ready"));
             }
             else if (this.#state === "loading")
-                this.#set(this.#view?.live === false && renderer().focused !== undefined ? "idle" : "unavailable");
+                this.#set(this.#view?.live === false && taken.renderer.focused !== undefined ? "idle" : "unavailable");
         });
         this.addEventListener("pointerdown", this.#take);
         this.addEventListener("focusin", this.#take);
@@ -130,16 +135,8 @@ export class ChikyuEarthRealistic extends HTMLElement {
         this.#gate?.cancel();
         this.#view?.dispose();
         this.#view = undefined;
-        contextListeners.delete(this.#onContext);
-        elements -= 1;
-        if (elements <= 0) {
-            releaseTimer = setTimeout(() => {
-                if (elements <= 0) {
-                    shared?.dispose();
-                    shared = undefined;
-                }
-            }, 1000);
-        }
+        this.#taken?.release();
+        this.#taken = undefined;
     }
     attributeChangedCallback(name, _old, value) {
         if (name === "center")
@@ -203,8 +200,15 @@ export class ChikyuEarthRealistic extends HTMLElement {
     }
     /** What the element is doing, for a page or a test: its state, the texture widths held, the draws made. */
     get stats() {
-        const stats = renderer().stats;
-        return { state: this.#state, tiers: { ...this.#tiers }, draws: stats.draws, contexts: stats.contexts, canvas: stats.canvas, assets: { entries: stats.assets.entries, refs: stats.assets.refs } };
+        const stats = this.#taken?.renderer.stats;
+        return {
+            state: this.#state,
+            tiers: { ...this.#tiers },
+            draws: stats?.draws ?? 0,
+            contexts: stats?.contexts ?? 0,
+            canvas: stats?.canvas ?? { width: 0, height: 0, pixels: 0 },
+            assets: { entries: stats?.assets.entries ?? 0, refs: stats?.assets.refs ?? 0 },
+        };
     }
     /**
      * Apply a shared view controller's camera (yaw, tilt, zoom, pan). A change under half a pixel is not drawn, a settled change always is,

package/dist/realistic/gate.d.ts

@@ -4,6 +4,18 @@ export interface Timers {
     now(): number;
 }
 export declare const browserTimers: Timers;
+/**
+ * A rate gate for the draw: what `createGate` returns.
+ *
+ * @example
+ * ```ts
+ * import { createGate, type Gate } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const gate: Gate = createGate(33, () => console.log("draw"));
+ * gate.request();
+ * gate.cancel();
+ * ```
+ */
 export interface Gate {
     /** Ask for `fire` to run: now if the last run was `minMs` ago or more, else once, when that time has passed. */
     request(): void;
@@ -12,8 +24,40 @@ export interface Gate {
     /** Change the least time between runs (a lower frame rate on a battery). */
     setMinMs(minMs: number): void;
 }
+/**
+ * A rate gate for the draw: asks that come faster than `minMs` apart become one, and the last ask is never lost, so a burst of changes costs one draw.
+ *
+ * @param minMs - The least time between two runs, in milliseconds.
+ * @param fire - What to run.
+ * @param timers - A clock and timers; the browser's by default (a test passes its own).
+ * @returns The gate: `request()` to ask, `cancel()` to forget a waiting run, `setMinMs()` to change the pace.
+ *
+ * @example
+ * ```ts
+ * import { createGate } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const gate = createGate(30, () => console.log("drawn"));
+ * gate.request();
+ * gate.request();
+ * gate.request();
+ * gate.cancel();
+ * ```
+ */
 export declare function createGate(minMs: number, fire: () => void, timers?: Timers): Gate;
-/** The frame rate cap for this device: `maxFps` (30 by default), lower on a small device. */
+/**
+ * The frame rate cap for this device: `maxFps` (30 by default), lower on a small device.
+ *
+ * @param maxFps - The most frames a second to allow.
+ * @param device - `deviceMemory` in gigabytes and `hardwareConcurrency` in cores, from `navigator`; either may be left out.
+ * @returns The frames a second to allow, at least 1; 20 at most on a small device.
+ *
+ * @example
+ * ```ts
+ * import { frameCap } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(frameCap(), frameCap(30, { deviceMemory: 1 }));
+ * ```
+ */
 export declare function frameCap(maxFps?: number, device?: {
     deviceMemory?: number;
     hardwareConcurrency?: number;

package/dist/realistic/gate.js

@@ -4,6 +4,25 @@ export const browserTimers = {
     clear: (handle) => clearTimeout(handle),
     now: () => performance.now(),
 };
+/**
+ * A rate gate for the draw: asks that come faster than `minMs` apart become one, and the last ask is never lost, so a burst of changes costs one draw.
+ *
+ * @param minMs - The least time between two runs, in milliseconds.
+ * @param fire - What to run.
+ * @param timers - A clock and timers; the browser's by default (a test passes its own).
+ * @returns The gate: `request()` to ask, `cancel()` to forget a waiting run, `setMinMs()` to change the pace.
+ *
+ * @example
+ * ```ts
+ * import { createGate } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * const gate = createGate(30, () => console.log("drawn"));
+ * gate.request();
+ * gate.request();
+ * gate.request();
+ * gate.cancel();
+ * ```
+ */
 export function createGate(minMs, fire, timers = browserTimers) {
     let least = minMs;
     let last = -Infinity;
@@ -33,7 +52,20 @@ export function createGate(minMs, fire, timers = browserTimers) {
         },
     };
 }
-/** The frame rate cap for this device: `maxFps` (30 by default), lower on a small device. */
+/**
+ * The frame rate cap for this device: `maxFps` (30 by default), lower on a small device.
+ *
+ * @param maxFps - The most frames a second to allow.
+ * @param device - `deviceMemory` in gigabytes and `hardwareConcurrency` in cores, from `navigator`; either may be left out.
+ * @returns The frames a second to allow, at least 1; 20 at most on a small device.
+ *
+ * @example
+ * ```ts
+ * import { frameCap } from "@johnmorrisdotca/chikyu-earth/realistic";
+ *
+ * console.log(frameCap(), frameCap(30, { deviceMemory: 1 }));
+ * ```
+ */
 export function frameCap(maxFps = 30, device = {}) {
     const small = (device.deviceMemory !== undefined && device.deviceMemory <= 2) || (device.hardwareConcurrency !== undefined && device.hardwareConcurrency <= 2);
     return Math.max(1, small ? Math.min(maxFps, 20) : maxFps);

package/dist/realistic/shaders.d.ts

@@ -1,5 +1,10 @@
-export declare const SURFACE_VERT = "\nvarying vec2 vUv;\nvarying vec3 vNormal;\nvoid main() {\n  vUv = uv;\n  vNormal = normalize(mat3(modelMatrix) * position);\n  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n}";
-export declare const SURFACE_FRAG = "\nuniform sampler2D dayMap;\nuniform sampler2D nightMap;\nuniform sampler2D waterMap;\nuniform vec3 sunDir;\nuniform float lights;\nvarying vec2 vUv;\nvarying vec3 vNormal;\nvoid main() {\n  vec3 n = normalize(vNormal);\n  float ndl = dot(n, sunDir);\n  float day = smoothstep(-0.10, 0.22, ndl);\n  vec3 albedo = texture2D(dayMap, vUv).rgb;\n  float water = texture2D(waterMap, vUv).r;\n\n  vec3 lit = albedo * (0.07 + 1.0 * pow(max(ndl, 0.0), 0.5));\n  float dusk = smoothstep(-0.14, 0.0, ndl) * (1.0 - smoothstep(0.0, 0.30, ndl));\n  lit += vec3(0.55, 0.28, 0.14) * dusk * 0.30 * (0.35 + 0.65 * albedo.g);\n\n  vec3 h = normalize(sunDir + vec3(0.0, 0.0, 1.0));\n  float glint = pow(max(dot(n, h), 0.0), 220.0) * water * day;\n  lit += vec3(1.0, 0.93, 0.80) * glint * 0.7;\n\n  vec3 night = texture2D(nightMap, vUv).rgb;\n  night = night * night * vec3(1.6, 1.5, 1.3) * lights + night * 0.25;\n  vec3 col = mix(night, lit, day);\n\n  float rim = pow(1.0 - clamp(n.z, 0.0, 1.0), 3.0);\n  float sunSide = 0.12 + 0.88 * smoothstep(-0.25, 0.5, ndl);\n  col += vec3(0.20, 0.45, 1.0) * rim * sunSide * 0.55;\n  gl_FragColor = vec4(col, 1.0);\n}";
+export declare const SURFACE_VERT = "\nvarying vec2 vUv;\nvarying vec3 vNormal;\nvarying vec3 vWorld;\nvoid main() {\n  vUv = uv;\n  vNormal = normalize(mat3(modelMatrix) * position);\n  vWorld = (modelMatrix * vec4(position, 1.0)).xyz;\n  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n}";
+export declare const SURFACE_FRAG = "\nuniform sampler2D dayMap;\nuniform sampler2D nightMap;\nuniform sampler2D waterMap;\nuniform vec3 sunDir;\nuniform float lights;\nuniform float ortho;\nvarying vec2 vUv;\nvarying vec3 vNormal;\nvarying vec3 vWorld;\nvoid main() {\n  vec3 n = normalize(vNormal);\n  vec3 toEye = ortho > 0.5 ? vec3(0.0, 0.0, 1.0) : normalize(cameraPosition - vWorld);\n  float ndl = dot(n, sunDir);\n  float day = smoothstep(-0.10, 0.22, ndl);\n  vec3 albedo = texture2D(dayMap, vUv).rgb;\n  float water = texture2D(waterMap, vUv).r;\n\n  vec3 lit = albedo * (0.07 + 1.0 * pow(max(ndl, 0.0), 0.5));\n  float dusk = smoothstep(-0.14, 0.0, ndl) * (1.0 - smoothstep(0.0, 0.30, ndl));\n  lit += vec3(0.55, 0.28, 0.14) * dusk * 0.30 * (0.35 + 0.65 * albedo.g);\n\n  vec3 h = normalize(sunDir + toEye);\n  float glint = pow(max(dot(n, h), 0.0), 220.0) * water * day;\n  lit += vec3(1.0, 0.93, 0.80) * glint * 0.7;\n\n  vec3 night = texture2D(nightMap, vUv).rgb;\n  night = night * night * vec3(1.6, 1.5, 1.3) * lights + night * 0.25;\n  vec3 col = mix(night, lit, day);\n\n  float rim = pow(1.0 - clamp(dot(n, toEye), 0.0, 1.0), 3.0);\n  float sunSide = 0.12 + 0.88 * smoothstep(-0.25, 0.5, ndl);\n  col += vec3(0.20, 0.45, 1.0) * rim * sunSide * 0.55;\n  gl_FragColor = vec4(col, 1.0);\n}";
 export declare const CLOUD_FRAG = "\nuniform sampler2D cloudMap;\nuniform vec3 sunDir;\nuniform float shift;\nuniform float opacity;\nvarying vec2 vUv;\nvarying vec3 vNormal;\nvoid main() {\n  vec3 n = normalize(vNormal);\n  float ndl = dot(n, sunDir);\n  float c = texture2D(cloudMap, vec2(vUv.x + shift, vUv.y)).r;\n  float a = smoothstep(0.28, 0.88, c) * opacity;\n  float day = smoothstep(-0.10, 0.25, ndl);\n  vec3 col = mix(vec3(0.015, 0.02, 0.04), vec3(1.0), day * (0.18 + 0.82 * pow(max(ndl, 0.0), 0.45)));\n  col += vec3(0.55, 0.28, 0.14) * smoothstep(-0.14, 0.0, ndl) * (1.0 - smoothstep(0.0, 0.25, ndl)) * 0.35;\n  gl_FragColor = vec4(col, a);\n}";
-export declare const ATMOSPHERE_VERT = "\nvarying vec3 vView;\nvoid main() {\n  vec4 view = modelViewMatrix * vec4(position, 1.0);\n  vView = view.xyz;\n  gl_Position = projectionMatrix * view;\n}";
-export declare const ATMOSPHERE_FRAG = "\nuniform vec3 sunDir;\nuniform float outer;\nvarying vec3 vView;\nvoid main() {\n  float rho = length(vView.xy);\n  float t = clamp((rho - 1.0) / (outer - 1.0), 0.0, 1.0);\n  vec2 dir = rho > 0.0 ? vView.xy / rho : vec2(1.0, 0.0);\n  float side = smoothstep(-0.40, 0.55, dot(vec3(dir, 0.0), sunDir));\n  float glow = pow(1.0 - t, 3.0) * (0.10 + 0.90 * side);\n  vec3 col = mix(vec3(0.10, 0.22, 0.60), vec3(0.42, 0.68, 1.0), side);\n  gl_FragColor = vec4(col, glow * 0.9);\n}";
+export declare const ATMOSPHERE_VERT = "\nvarying vec3 vPosView;\nvarying vec3 vNormalView;\nvoid main() {\n  vec4 view = modelViewMatrix * vec4(position, 1.0);\n  vPosView = view.xyz;\n  vNormalView = normalize(normalMatrix * position);\n  gl_Position = projectionMatrix * view;\n}";
+export declare const ATMOSPHERE_FRAG = "\nuniform vec3 sunView;\nuniform float outer;\nuniform float ortho;\nvarying vec3 vPosView;\nvarying vec3 vNormalView;\nvoid main() {\n  vec3 n = normalize(vNormalView);\n  vec3 v = ortho > 0.5 ? vec3(0.0, 0.0, 1.0) : normalize(-vPosView);\n  float nz = clamp(dot(n, v), -1.0, 1.0);\n  float rho = outer * sqrt(max(0.0, 1.0 - nz * nz));\n  float t = clamp((rho - 1.0) / (outer - 1.0), 0.0, 1.0);\n  vec2 dir = normalize(n.xy + vec2(1e-5, 0.0));\n  float side = smoothstep(-0.40, 0.55, dot(vec3(dir, 0.0), sunView));\n  float glow = pow(1.0 - t, 3.0) * (0.10 + 0.90 * side);\n  vec3 col = mix(vec3(0.10, 0.22, 0.60), vec3(0.42, 0.68, 1.0), side);\n  gl_FragColor = vec4(col, glow * 0.9);\n}";
+/** 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 declare const BODY_FRAG = "\nuniform sampler2D map;\nuniform vec3 tint;\nuniform float textured;\nuniform float ambient;\nuniform vec3 sunDir;\nvarying vec2 vUv;\nvarying vec3 vNormal;\nvoid main() {\n  vec3 n = normalize(vNormal);\n  float ndl = dot(n, sunDir);\n  vec3 albedo = textured > 0.5 ? texture2D(map, vUv).rgb : tint;\n  float lit = smoothstep(-0.04, 0.12, ndl) * (0.10 + 0.95 * pow(max(ndl, 0.0), 0.6));\n  gl_FragColor = vec4(albedo * (ambient + lit), 1.0);\n}";
+/** A flat quad facing the camera: the Sun's disc and its glow. */
+export declare const GLOW_VERT = "\nvarying vec2 vUv;\nvoid main() {\n  vUv = uv;\n  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n}";
+export declare const GLOW_FRAG = "\nuniform vec3 tint;\nvarying vec2 vUv;\nvoid main() {\n  float r = length(vUv - 0.5) * 2.0;\n  float core = 1.0 - smoothstep(0.10, 0.14, r);\n  float halo = pow(max(0.0, 1.0 - r), 2.5);\n  vec3 col = mix(tint, vec3(1.0), core);\n  gl_FragColor = vec4(col, clamp(core + halo * 0.85, 0.0, 1.0));\n}";