diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 7ebde9329..dc39e96aa 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -37,6 +37,14 @@ exposes nine ports, each typed in its own file in `src/render/contract/`: | `credits` | `credits.d.ts` | Data credits owed | | `quality` | `quality.d.ts` | Quality knobs, device facts, frame signals | +Version `0` is still being shaped, and not only by additions. Members +were removed or replaced (among them `camera.move`, `look`, +`rotateAround` and `zoom`, now step views placed with `setView`; +`query.sampleHeightNowMany`; `input.ctrlWheelZoom`, now the `ctrlWheel` +zoom input), `depthFailColor` and `depthFailDash` became one `depthFail` +style, and quality settings became detail only. A renderer written against +an earlier `0` follows those changes. + Some members and options were added to version `0` later. Each is optional, so a renderer written before it still conforms: @@ -66,10 +74,11 @@ optional, so a renderer written before it still conforms: says once per spec or `update` that it is drawn, never while hidden. These change `fields` itself rather than add to it, so the renderer follows `fields` before must follow them. The Cesium adapter lists `fields` and - draws `rasterShell` and `windStreamlines`. It draws streamlines only over the whole globe: it reads the grid's samples - as points, the first column at `rectangle.west` and the first row at - `rectangle.north`, rows running south, and traces paths that wrap east - and west, so it refuses a grid short of 360° of longitude. + draws `rasterShell` and `windStreamlines`. It draws streamlines only over + the whole globe: it reads the grid's samples as points, the first column + at `rectangle.west` and the first row at `rectangle.north`, rows running + south, and traces paths that wrap east and west, so it refuses a grid + short of 360° of longitude. - `ModulationSector` gains `radius` and `floor` and says what it modulates: icons, points and models dimmed toward `floor` outside the band, the map, lines and shapes as they are, picks unchanged. Its pass is named @@ -86,8 +95,8 @@ optional, so a renderer written before it still conforms: is 2 px of outline, 4 px of colour and 2 px of outline, as Cesium draws it. The check `draw.lines.outline` pins it. - A shape's `lit` chooses shading by the renderer's fixed light (true) or a - flat colour (false); omitted, extruded shapes and boxes are lit and the - rest flat, as before. The Cesium port lights unclamped shapes only + flat colour (false); omitted, extruded shapes are lit and the rest flat, + as before. The Cesium port lights unclamped shapes only (clamped ones drape unlit). The `shapes-lit` scene draws both. - `SetSpec.drawOrder` stacks sets drawn over depth: a higher one draws over a lower one and is picked first; equal ones keep the order they were @@ -225,7 +234,10 @@ renderer under test: Optional members widen what is checked: `pointer` for synthetic input, `cameraInput` (the camera answers that input: the drag and wheel traces run), `scriptHeights`, `assets.model`, and `assets.missingModel` (a model -url that fails to load, for the `loadFailed` check). +url that fails to load, for the `loadFailed` check). `pixels: false` says +the renderer draws nothing but models into its pixels, as the stub: the +checks that read drawn icons, lines and fields then skip. Without it they +run, and the renderer fails them if it draws nothing there. There are two layers of checks. diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index f0b7cac52..67b85a1fc 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -727,15 +727,17 @@ export function portChecks() { "a shell draws its image, and its 'drawn' comes once per change, never while hidden", async (h, r) => { await overAustin(h, r, 20000); - // The middle of the frame, which the shell below covers whole. + // Around Austin, below the eye, which the shell covers whole; where + // it projects is in the units `readPixels` crops in. + const below = r.query.project(h.toEcef({ ...AUSTIN, height: 0 })); + ok(below, 'the ground below projects'); const middle = async () => { await settled(r); r.frame.renderNow(); - const { width, height } = r.canvas; return r.readPixels({ crop: { - x: Math.round(width / 2) - 6, - y: Math.round(height / 2) - 6, + x: Math.round(below.x) - 6, + y: Math.round(below.y) - 6, width: 13, height: 13, }, @@ -748,25 +750,8 @@ export function portChecks() { if (now[i + 2] - was[i + 2] > 40 && now[i] - was[i] < 20) n++; return n; }; - const empty = await middle(); - // A renderer that draws lines into pixels must draw the shell too; - // one that draws neither (the stub) leaves the pixels unread. - const probe = r.draw.lines({ id: 'conf:shell-probe' }); - const at = (dLon) => - h.toEcef({ lon: AUSTIN.lon + dLon, lat: AUSTIN.lat, height: 0 }); - probe.set([ - { - id: 'l', - positions: [at(-0.02), at(0.02)], - widthPx: 20, - mode: '3d', - style: { kind: 'solid', color: '#0000ff' }, - }, - ]); - await drawn(h, r); - const drawsPixels = bluer(await middle(), empty) >= 20; - probe.dispose(); - await drawn(h, r); + const readsPixels = h.pixels !== false; + const empty = readsPixels ? await middle() : null; const svg = (fill) => ({ svg: ``, }); @@ -791,7 +776,7 @@ export function portChecks() { try { await until(1); equal(drawnCount, 1, 'drawn once made'); - if (drawsPixels) + if (readsPixels) ok( bluer(await middle(), empty) >= 150, 'the shell draws its image over the frame', @@ -1118,8 +1103,9 @@ export function portChecks() { set.set([]); const empty = await patch(); const drawnPixels = differ(shown, empty); - if (drawnPixels < 20) - return { skip: 'this renderer draws no icon pixels' }; + if (h.pixels === false) + return { skip: 'this harness reads no drawn pixels' }; + ok(drawnPixels >= 20, 'the icon draws into pixels'); set.set([icon]); r.effects.screenModulation(sector()); ok( @@ -2099,8 +2085,8 @@ export function portChecks() { : '-'; } lines.dispose(); - if (!column.includes('g') && !column.includes('r')) - return { skip: 'this renderer draws no line pixels' }; + if (h.pixels === false) + return { skip: 'this harness reads no drawn pixels' }; const runs = column.match(/r+|g+/g) ?? []; const sides = runs.filter((run) => run[0] === 'r'); const core = runs.find((run) => run[0] === 'g') ?? ''; diff --git a/src/render/conformance/index.js b/src/render/conformance/index.js index 810a62167..d3f5f2060 100644 --- a/src/render/conformance/index.js +++ b/src/render/conformance/index.js @@ -21,7 +21,8 @@ * Optional harness members widen what is checked: `pointer(r, type, x, y)` * (synthetic input; with `cameraInput`, the camera scripts' drags and * wheels too), `scriptHeights(r, fn)` (heights from a function), - * `wallTime(r)` (the wall clock a `live` motion clock reads), + * `wallTime(r)` (the wall clock a `live` motion clock reads), `pixels` + * (false skips the checks that read drawn pixels), * `assets.model` (a glTF URL). `create` may return null when it cannot * make a renderer with fewer capabilities; those checks are then skipped. */ @@ -50,6 +51,7 @@ import { portChecks } from './checks/ports.js'; * A move's `x, y` is where it started and `extra.endPosition` where it * went; `extra` also has `button` (a move's the one held), `modifiers` * and, for a wheel, `delta` in the input port's lines. + * @property {boolean} [pixels] False when the renderer draws nothing but models into its pixels (the stub): the checks that read drawn icons, lines and fields are then skipped. Otherwise they run, and an empty draw fails them. * @property {boolean} [cameraInput] The renderer's camera moves on pointer input sent through `pointer` (its own gestures, or a camera controller's): the camera scripts with `input` steps run. * @property {(r: object, fn: (point: {lon: number, lat: number}, against?: string) => number|null) => void} [scriptHeights] * @property {(r: object) => number} [wallTime] Epoch ms the renderer's `live` motion clock reads. diff --git a/src/render/stub/harness.js b/src/render/stub/harness.js index 462090044..e444f7b6e 100644 --- a/src/render/stub/harness.js +++ b/src/render/stub/harness.js @@ -20,6 +20,8 @@ export function createStubHarness(name = 'stub') { toEcef, tolerance: DEFAULT_TOLERANCE, flightPaths: 'trace', + // It draws only models into pixels. + pixels: false, pointer: (r, type, x, y, extra) => r.testing.pointer(type, x, y, extra), scriptHeights: (r, fn) => r.testing.setHeights(fn), wallTime: (r) => r.testing.wallTime(),