diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index f95d6fce6..3655a7985 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -48,6 +48,14 @@ optional, so a renderer written before it still conforms: - A line item's `depthFailDash` (`{ length, pattern16? }`) dashes the parts behind the surface in `depthFailColor`, as the Draw tool's rubber band is. A renderer that predates it draws those parts solid. +- 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 + (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 + made in. The Cesium port stacks opaque icons and points by it; + translucent ones blend order-independently there. - A rectangle shape's `rotation` (radians counter-clockwise) turns it about its centre in longitude and latitude, as a KML ground overlay turns, and its image fill turns with it. The Cesium port drapes image fills too, each diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index 82207172a..210db8ec4 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -3155,6 +3155,8 @@ export function createCesiumDraw({ const id = pickId(record, item); const solid = item.extrudeHeight !== undefined || item.geometry.kind === 'box'; + // `lit`: shaded by Cesium's light, or flat; by default solids are lit. + const lit = item.lit ?? solid; if (imageFill && !item.outlineOnly) { const material = ownMaterial( Cesium.Material.fromType('Image', { @@ -3175,8 +3177,7 @@ export function createCesiumDraw({ Cesium.MaterialAppearance.MaterialSupport.TEXTURED, translucent: true, closed: solid, - flat: !solid, - faceForward: !solid, + flat: !lit, }), asynchronous: false, }), @@ -3196,8 +3197,10 @@ export function createCesiumDraw({ appearance: new Cesium.PerInstanceColorAppearance({ translucent: color.alpha < 1, closed: solid, - // Flat shapes unlit: lit, their two triangles shade apart. - flat: !solid, + // Flat shapes unlit by default: lit, their faces shade by + // the light (a lit box's sides differ, an unlit one's match). + flat: !lit, + faceForward: !solid, }), asynchronous: false, }), @@ -3299,10 +3302,17 @@ export function createCesiumDraw({ /** * The Cesium port draws clamped items where it is given them; it does not * drape them onto 3D tiles yet, so over shown tiles it is `overlay`. - * Terrain and the ellipsoid always take draped items. + * Terrain and the ellipsoid take draped items wherever Cesium drapes at + * all: its draped lines and image fills need depth textures, which every + * WebGL 2 context has; without them it says `overlay`. (It still builds + * them as ground primitives there: the overlay drawing itself is not + * built, since only a WebGL 1 context without the extension lacks them.) */ const clampState = () => - tilesets().some((tileset) => tileset.show) ? 'overlay' : 'draped'; + scene.frameState?.context?.depthTexture === false || + tilesets().some((tileset) => tileset.show) + ? 'overlay' + : 'draped'; const clampListeners = listenerList(report); // The state last told, while anyone listens; measured after each drawn // frame, when what the base holds can have changed. diff --git a/src/render/conformance/goldens/visual/manifest.json b/src/render/conformance/goldens/visual/manifest.json index 0adb87527..c5827f8cc 100644 --- a/src/render/conformance/goldens/visual/manifest.json +++ b/src/render/conformance/goldens/visual/manifest.json @@ -15,6 +15,7 @@ "models-oblique.png", "city-orbit.png", "city-city.png", - "city-street.png" + "city-street.png", + "shapes-lit-tilted.png" ] } diff --git a/src/render/conformance/goldens/visual/shapes-lit-tilted.png b/src/render/conformance/goldens/visual/shapes-lit-tilted.png new file mode 100644 index 000000000..d4a634122 Binary files /dev/null and b/src/render/conformance/goldens/visual/shapes-lit-tilted.png differ diff --git a/src/render/conformance/scenes.js b/src/render/conformance/scenes.js index c11353d27..b64877d4d 100644 --- a/src/render/conformance/scenes.js +++ b/src/render/conformance/scenes.js @@ -325,6 +325,53 @@ export const REFERENCE_SCENES = Object.freeze([ { name: 'tilted', view: over(2500, -0.5, 0.3, offset(0, -3600)) }, ], }, + { + // `ShapeItem.lit`: a lit box's faces shade apart, an unlit one's match; + // a flat square lit, beside one drawn flat. Lit, the default renderer + // shades a flat square's two triangles apart (a seam on the diagonal): + // that is its lighting, recorded as it is. + id: 'shapes-lit', + family: 'shapes', + capability: null, + async build(r) { + await bare(r); + const set = r.draw.shapes({ id: 'ref:shapes-lit' }); + const square = (east, north, half) => [ + offset(east - half, north - half, 5), + offset(east + half, north - half, 5), + offset(east + half, north + half, 5), + offset(east - half, north + half, 5), + ]; + const box = (id, east, lit) => ({ + id, + geometry: { + kind: 'box', + center: offset(east, 300, 150), + dimensions: { x: 300, y: 300, z: 300 }, + }, + fill: '#ff9f0a', + lit, + }); + set.set([ + box('lit-box', -400, true), + box('flat-box', 400, false), + { + id: 'lit-square', + geometry: { kind: 'polygon', rings: [square(-400, -500, 200)] }, + fill: '#0a84ff', + lit: true, + }, + { + id: 'flat-square', + geometry: { kind: 'polygon', rings: [square(400, -500, 200)] }, + fill: '#0a84ff', + lit: false, + }, + ]); + return disposeAll(set); + }, + views: [{ name: 'tilted', view: over(2500, -0.5, 0.3, offset(0, -3600)) }], + }, { id: 'models', family: 'models', diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts index 8b715834d..cc96a7ceb 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -228,7 +228,11 @@ export interface LineItem { /** ECEF positions, or packed `x, y, z` triples. */ positions: Ecef[] | Float64Array; widthPx: number; - /** `3d`: straight in space; `geodesic`: along the ellipsoid; `draped`: on the surface. */ + /** + * `3d`: straight in space; `geodesic`: along the ellipsoid; `draped`: on + * the surface. Where the renderer cannot drape at all, it draws `draped` lines + * and clamped shapes as in `overlay`, and `clampState()` says `overlay`. + */ mode: '3d' | 'geodesic' | 'draped'; clampTo?: ClampTarget; style: LineStyle; @@ -322,6 +326,13 @@ export interface ShapeItem { classifyVolume?: boolean; /** Pull toward the eye, metres, to win depth against coplanar surfaces. */ depthBias?: number; + /** + * Shaded by the renderer's fixed light (true) or flat colour (false). + * Omitted: lit for extruded shapes and boxes, flat otherwise. A renderer + * may draw clamped shapes, which drape on the surface, flat whatever it + * says. + */ + lit?: boolean; animate?: Pulse; meta?: Meta; show?: boolean; @@ -560,7 +571,8 @@ export interface DrawPort { * shapes) are draped onto the 3D tiles now (`draped`), or drawn over them * and hidden past the ellipsoid's horizon (`overlay`), the fallback a * renderer uses where it cannot drape. Without tiles in the base it is - * `draped`: clamping to terrain or the ellipsoid always drapes. + * `draped`: clamping to terrain or the ellipsoid always drapes, on a + * renderer that can drape at all (one that cannot is always `overlay`). */ clampState(): 'draped' | 'overlay'; /** Fires when `clampState()` changes (not on subscribing). */