import { recordWorkSlice } from '../sources/phaseTiming.js'; import { createWorldAnnotationRenderer } from './worldAnnotationRenderer.js'; import { createScreenAnnotationRenderer } from './screenAnnotationRenderer.js'; /** * Hybrid annotation renderer (Direction C — the recommended production blend). * * Routes each mark to the renderer that does it best: * - `area` footprints → WORLD-space, so the outline/fill drapes onto and * conforms to the real 3D building/ground geometry (screen-space can only * draw a flat polygon that ignores relief and building tops). * - everything else (highlight / pin / arrow / label) → SCREEN-space SVG, for * the hand-drawn "whiteboard" aesthetic: pulsing reticles, bowed arrows, * and glassy callout cards with leader lines. * * The area's text label is also drawn as a SCREEN callout (the world drape is * label-less) so every caption shares one consistent style. * * The hybrid surface honors add/update/remove/sync/destroy; update coordinates the * one route change that spans both sub-renderers. `screen` passes options to the * screen renderer (its store, in tests). */ export function createHybridAnnotationRenderer( viewer, { screen: screenOptions } = {}, ) { const world = createWorldAnnotationRenderer(viewer); const screen = createScreenAnnotationRenderer(viewer, screenOptions); // anno.id -> { worldProxy?, screenProxy? } — proxies own the sub-renderer state. const routed = new Map(); function add(anno, options = {}) { const entry = {}; // Route the entry FIRST, then fill it in. A sub-renderer throw (WebGL loss // mid-add) otherwise stranded whatever the earlier sub-renderer had already // created: `routed` never learned the id, so remove() was a no-op and the // engine's rollback could not reach the orphan — a re-annotate of the same // geometry then stacked a second mark over it. Registered up front, the // partial entry is addressable and remove() cleans exactly what exists. routed.set(anno.id, entry); if (anno.type === 'area' && anno.ring && anno.ring.length >= 3) { // Drape the footprint in world space, but without its own label... entry.worldProxy = liveProxy(anno, { label: null }); const completion = world.add( entry.worldProxy, worldOptions(anno, entry, options), ); if (completion?.then) { if (options.pendingVisible !== false) { entry.screenProxy = liveProxy(anno, { ring: null, pendingOutline: true, }); screen.add(entry.screenProxy); } return finishBuilding(anno, entry, completion, options); } // ...and place the caption as a screen-space callout at the centroid. if (anno.label) { entry.screenProxy = liveProxy(anno, { type: 'label', ring: null }); screen.add(entry.screenProxy); } } else if ( anno.type === 'route' && Array.isArray(anno.path) && anno.path.length >= 2 ) { // Drape the path on the tiles (world), caption it with a screen callout // at the path midpoint. entry.worldProxy = liveProxy(anno, { label: null }); world.add(entry.worldProxy); if (anno.label) { const mid = anno.path[Math.floor(anno.path.length / 2)]; entry.screenProxy = liveProxy(anno, { type: 'label', path: null, anchor: { lon: mid.lon, lat: mid.lat, height: mid.height }, }); screen.add(entry.screenProxy); } } else { entry.screenProxy = anno; screen.add(anno); } } /** * Upgrade a pending area without replacing its existing screen-space group. * World geometry is new, but the reticle's SVG group is converted in place to * the centroid callout so there is no overlapping fade-out/fade-in pair. */ function update(anno, options = {}) { const entry = routed.get(anno.id); if (!entry) { return add(anno, options); } if (anno.type !== 'area' || !anno.ring || anno.ring.length < 3) { if (anno.outlineUnavailable && entry.screenProxy) { entry.screenProxy = liveProxy(anno, { ring: null }); screen.update(entry.screenProxy); } return; } if (!entry.worldProxy) { entry.worldProxy = liveProxy(anno, { label: null }); const completion = world.add( entry.worldProxy, worldOptions(anno, entry, options), ); if (completion?.then) { if (entry.screenProxy) { const pending = liveProxy(anno, { ring: null, pendingOutline: true }); screen.update(pending); entry.screenProxy = pending; } return finishBuilding(anno, entry, completion, options); } } updateCaption(anno, entry); } function updateCaption(anno, entry) { const screenProxy = liveProxy(anno, { type: 'label', ring: null }); if (entry.screenProxy) { screen.update(screenProxy, { empty: !anno.label }); } else if (anno.label) { // Publish before add: a partially created caption must remain removable. entry.screenProxy = screenProxy; screen.add(screenProxy); } entry.screenProxy = entry.screenProxy ? screenProxy : anno.label ? screenProxy : null; } function finishBuilding(anno, entry, completion, options) { const workTrace = options.workTrace; const proxy = entry.worldProxy; return completion .then((result) => { const workStart = workTrace ? performance.now() : 0; try { if ( routed.get(anno.id) !== entry || entry.worldProxy !== proxy || options.signal?.aborted || !(options.isCurrent?.() ?? true) ) { world.remove(proxy); if (routed.get(anno.id) === entry) remove(anno); if (workTrace) workTrace.rendererStatus = 'cancelled'; return { ...result, status: 'cancelled' }; } if (result.status !== 'installed') { world.remove(proxy); entry.worldProxy = null; if (workTrace) workTrace.rendererStatus = result.status; return result; } if (performance.now() >= result.timing.deadlineMs) { world.remove(proxy); entry.worldProxy = null; if (workTrace) workTrace.rendererStatus = 'timeout'; return { ...result, status: 'timeout' }; } const at = performance.now(); try { updateCaption(anno, entry); } finally { const ms = performance.now() - at; result.timing.workMs += ms; result.timing.lastSliceMs += ms; result.timing.maxSliceMs = Math.max( result.timing.maxSliceMs, result.timing.lastSliceMs, ); } if (performance.now() >= result.timing.deadlineMs) { world.remove(proxy); entry.worldProxy = null; if (options.pendingVisible === false) { if (entry.screenProxy) screen.remove(entry.screenProxy); entry.screenProxy = null; } else { // The caption conversion already reshaped the group; redraw the pending point. const pending = liveProxy(anno, { ring: null, pendingOutline: true, }); if (entry.screenProxy) screen.remove(entry.screenProxy); entry.screenProxy = pending; screen.add(pending); } if (workTrace) workTrace.rendererStatus = 'timeout'; return { ...result, status: 'timeout' }; } if (workTrace) workTrace.rendererStatus = result.status; return result; } finally { if (workTrace) recordWorkSlice(workTrace, 'hybrid-complete', workStart); } }) .catch((error) => { const workStart = workTrace ? performance.now() : 0; try { // A later caption throw must roll back the already installed world parts too. if (routed.get(anno.id) === entry) { try { remove(anno); } catch { /* original error wins; failed routes stay addressable */ } } else world.remove(proxy); throw error; } finally { if (workTrace) { workTrace.rendererStatus = 'failed'; recordWorkSlice(workTrace, 'hybrid-rollback', workStart); } } }); } function worldOptions(anno, entry, options) { const proxy = entry.worldProxy; return { ...options, isCurrent: () => routed.get(anno.id) === entry && entry.worldProxy === proxy && (options.isCurrent?.() ?? true), }; } /** * Release both routes. Tolerates PARTIAL state (only one sub-renderer got * its content) and an absent id, so it doubles as the rollback path for a * failed add. * * Both releases are ALWAYS attempted, each clears its own proxy as it * succeeds, and the routing entry is dropped only once nothing is left to * release. A release that throws therefore leaves the id still addressable, * so a retry (or a later clear) can finish the job instead of the orphan * becoming permanently unreachable. The failure is rethrown after both * routes have had their turn. */ function remove(anno) { const entry = routed.get(anno.id); if (!entry) return; let failure = null; if (entry.worldProxy) { try { world.remove(entry.worldProxy); entry.worldProxy = null; } catch (error) { failure = error; // keep the proxy: it still owns live geometry } } if (entry.screenProxy) { try { screen.remove(entry.screenProxy); entry.screenProxy = null; } catch (error) { failure = failure || error; } } if (!entry.worldProxy && !entry.screenProxy) routed.delete(anno.id); if (failure) throw failure; } function sync(annotations) { world.sync(annotations); screen.sync(annotations); } function destroy() { world.destroy(); screen.destroy(); routed.clear(); } return { add, update, remove, sync, destroy }; } /** * A proxy that inherits from `anno` via the prototype chain (so live fields the * engine mutates each tick — `alpha`, `bornAt`, `expiring` — are read through), * with a few own properties overridden. Sub-renderers store their own state * (`_entities`, SVG refs) as own properties on the proxy, isolated per route. */ function liveProxy(anno, overrides) { return Object.assign(Object.create(anno), overrides); }