littlejsengine 1.25.0 → 1.26.1

package/plugins/lightSystem.js

@@ -22,6 +22,8 @@
  *   setShadowTransparent lets its color tint the light
  * - Set light.glow for a soft hazy glow over a light, like a lamp at night; it is added over the lit scene after the
  *   lightmap, so it shows in the dark and sits in front of everything there
+ * - A DirectionalLight is a sun: one per scene, it lights everything from one direction, foreground casters throw long
+ *   shadows and objects with castBackgroundShadow are lit only at their edges facing it
  * - Must be constructed BEFORE PostProcessPlugin so post-process sees lit pixels
  * @namespace LightSystem
  */
@@ -48,7 +50,7 @@ let lightSystem;
  */
 class LightSystemPlugin
 {
-    /** Create the global light system plugin.
+    /** Create the global light system plugin
      *  @param {Vector2} [textureSize]  - Size of the lightmap texture (defaults to following mainCanvasSize, which is css pixels, so the lightmap is not scaled by canvasPixelRatio; pass mainCanvasSize.scale(getCanvasPixelRatio()) for a full resolution lightmap)
      *  @param {Color}   [ambientColor] - Color applied to unlit areas of the scene (defaults to BLACK = pitch dark). Set a small RGB like rgb(0.1,0.1,0.15) for a faint "moonlight" baseline so unlit areas aren't fully black.
      *  @example
@@ -64,6 +66,7 @@ class LightSystemPlugin
 
         /** @property {boolean} - When false, the render pass is skipped entirely */
         this.enabled = true;
+        this.shadersFailed = false; // a shader did not build on this device, so the system draws nothing
         /** @property {Color} - Baseline color applied to unlit areas of the scene. Defaults to BLACK (pitch dark). Set to a small RGB for a faint ambient. The lightmap is cleared to this color each frame, then lights add on top, then the result multiplies the scene. */
         this.ambientColor = (ambientColor || BLACK).copy();
         /** @property {Vector2} - Size of the lightmap texture, follows mainCanvasSize (css pixels, so it is not scaled by canvasPixelRatio) unless a size was passed */
@@ -109,6 +112,10 @@ class LightSystemPlugin
         /** @property {WebGLTexture|undefined} - The shadow map, casters drawn black on white around the camera, read only
          *  @type {WebGLTexture|undefined} */
         this.shadowMap = undefined;
+        /** @property {WebGLTexture|undefined} - The background map, objects with castBackgroundShadow drawn black on
+         *  white, the shadow map's size and place, made by a directional light when something casts into it and kept while the light is, read only
+         *  @type {WebGLTexture|undefined} */
+        this.backgroundMap = undefined;
         /** @property {WebGLTexture|undefined} - One of the two textures each light's shadow is built in
          *  @type {WebGLTexture|undefined} */
         this.shadowTextureA = undefined;
@@ -134,9 +141,34 @@ class LightSystemPlugin
         this.shadowMapOrigin = vec2();
         /** @property {number} - World size the shadow map covers, set each shadow pass */
         this.shadowMapWorldSize = 0;
+        /** @property {DirectionalLight|undefined} - The scene's directional light, a sun, or undefined, read only
+         *  @type {DirectionalLight|undefined} */
+        this.directionalLight = undefined;
+        /** @property {number} - Pixels across the square textures a directional light is built in, covering the
+         *  shadow map's area; larger is sharper and slower; a power of two, as shadowMapSize, so their texels line up */
+        this.directionalTextureSize = 512;
+        /** @property {WebGLTexture|undefined} - The directional light as built this frame, white where it reaches,
+         *  over the shadow map's area, read only
+         *  @type {WebGLTexture|undefined} */
+        this.directionalTexture = undefined;
+        /** @type {WebGLTexture|undefined} */
+        this.directionalTextureA = undefined; // where it is built, ping ponged
+        /** @type {WebGLTexture|undefined} */
+        this.directionalTextureB = undefined;
+        this.directionalTextureSizeAllocated = 0;
+        this.backgroundCasters = false; // anything has castBackgroundShadow, checked each shadow pass
+        /** @type {Object<string, WebGLProgram|WebGLVertexArrayObject>} */
+        this.directionalPrograms = {}; // its programs and their vertex arrays, by name
         this.shadowMapSizeAllocated = 0;     // sizes the textures were made at, to remake them on a change
         this.shadowTextureSizeAllocated = 0;
 
+        // a full texture quad, the vertex shader of the shadow and directional programs
+        const quadVertex =
+            '#version 300 es\n' +
+            'precision highp float;'+
+            'in vec2 p;'+                   // unit quad [0..1]
+            'out vec2 uv;'+
+            'void main(){gl_Position=vec4(p+p-1.,1,1);uv=p;}';
         initLightSystem();
         engineAddPlugin(undefined, lightSystemRender,
             lightSystemContextLost, lightSystemContextRestored);
@@ -206,6 +238,7 @@ class LightSystemPlugin
                 'if(useShadow)c.rgb*=texture(shadowTexture,vUV).rgb;'+
                 '}'
             );
+            if (lightSystemShadersFailed(lightSystem.lightShader)) return;
             // the shadow texture is on unit 1, the engine's tracked texture stays on unit 0
             glContext.useProgram(lightSystem.lightShader);
             glContext.uniform1i(glUniformLocation(lightSystem.lightShader, 'shadowTexture'), 1);
@@ -230,10 +263,23 @@ class LightSystemPlugin
                 '}'
             );
 
+            if (lightSystemShadersFailed(lightSystem.compositeShader)) return;
+
             // one quad VAO per program, the engine's unit triangle strip through the named attribute
             lightSystem.lightVAO = createQuadVAO(lightSystem.lightShader, 'g');
             lightSystem.compositeVAO = createQuadVAO(lightSystem.compositeShader, 'p');
         }
+        // a program that did not build in a release build draws nothing, so the light system turns itself off, said
+        // once, and the scene draws as it would without it; true when it is off
+        function lightSystemShadersFailed(...programs)
+        {
+            if (!lightSystem.shadersFailed && programs.some((program)=> glFailedPrograms.has(program)))
+            {
+                console.error('LightSystemPlugin: its shaders did not build on this device, the scene draws without it');
+                lightSystem.shadersFailed = true;
+            }
+            return lightSystem.shadersFailed;
+        }
         function createQuadVAO(program, attribute)
         {
             const gl = glContext, vao = gl.createVertexArray();
@@ -266,13 +312,8 @@ class LightSystemPlugin
             // put back the texture the engine tracks
             if (glActiveTexture)
                 gl.bindTexture(gl.TEXTURE_2D, glActiveTexture);
-
-            const quadVertex =
-                '#version 300 es\n' +
-                'precision highp float;'+
-                'in vec2 p;'+                   // unit quad [0..1]
-                'out vec2 uv;'+
-                'void main(){gl_Position=vec4(p+p-1.,1,1);uv=p;}';
+            if (ls.shadowCopyShader)
+                return; // the programs are kept while the textures are made again
 
             // copy: the shadow map around the light into the light's texture, light at the center
             ls.shadowCopyShader = glCreateProgram(quadVertex,
@@ -317,6 +358,7 @@ class LightSystemPlugin
                 'c=vec4(min(texture(s,uv).rgb+brightness*mask*b,b),1);'+
                 '}');
 
+            if (lightSystemShadersFailed(ls.shadowCopyShader, ls.shadowStretchShader)) return;
             ls.shadowCopyVAO = createQuadVAO(ls.shadowCopyShader, 'p');
             ls.shadowStretchVAO = createQuadVAO(ls.shadowStretchShader, 'p');
 
@@ -326,22 +368,20 @@ class LightSystemPlugin
             gl.useProgram(ls.shadowStretchShader);
             gl.uniform1i(glUniformLocation(ls.shadowStretchShader, 's'), 1);
         }
-        function freeShadows()
+        // let go of the shadow textures, the programs stay, small, so a new size or a sun made again compiles nothing
+        function freeShadowTextures()
         {
             const gl = glContext, ls = lightSystem;
             gl.deleteTexture(ls.shadowMap);
             gl.deleteTexture(ls.shadowTextureA);
             gl.deleteTexture(ls.shadowTextureB);
-            gl.deleteProgram(ls.shadowCopyShader);
-            gl.deleteProgram(ls.shadowStretchShader);
-            gl.deleteVertexArray(ls.shadowCopyVAO);
-            gl.deleteVertexArray(ls.shadowStretchVAO);
-            clearShadows();
+            gl.deleteTexture(ls.backgroundMap);
+            ls.shadowMap = ls.shadowTextureA = ls.shadowTextureB = ls.backgroundMap = undefined;
         }
         function clearShadows()
         {
             const ls = lightSystem;
-            ls.shadowMap = ls.shadowTextureA = ls.shadowTextureB = undefined;
+            ls.shadowMap = ls.shadowTextureA = ls.shadowTextureB = ls.backgroundMap = undefined;
             ls.shadowCopyShader = ls.shadowStretchShader = undefined;
             ls.shadowCopyVAO = ls.shadowStretchVAO = undefined;
         }
@@ -354,8 +394,9 @@ class LightSystemPlugin
             if (!ls.shadowMap || ls.shadowMapSize !== ls.shadowMapSizeAllocated
                 || ls.shadowTextureSize !== ls.shadowTextureSizeAllocated)
             {
-                ls.shadowMap && freeShadows();
+                ls.shadowMap && freeShadowTextures();
                 initShadows();
+                if (ls.shadersFailed) return;
             }
 
             // a square of world space around the camera, rounded to its own texels so the
@@ -363,7 +404,13 @@ class LightSystemPlugin
             const size = ls.shadowMapSize;
             const view = mainCanvasSize.scale(1/cameraScale);
             const worldSize = ls.shadowMapScale * max(view.x, view.y);
-            const texel = worldSize / size;
+            // with a sun, on the coarser of its texels and the map's, or its area would move by half its texels and a
+            // still caster's shadow edge would jump as the camera pans
+            const grid = ls.directionalLight ? min(size, ls.directionalTextureSize) : size;
+            ASSERT(!ls.directionalLight || max(size, ls.directionalTextureSize) % grid === 0,
+                'with a DirectionalLight, shadowMapSize and directionalTextureSize must each be a whole multiple of the ' +
+                'other, as powers of two are, or the shadows shimmer as the camera pans', size, ls.directionalTextureSize);
+            const texel = worldSize / grid;
             const center = vec2(floor(cameraPos.x/texel)*texel, floor(cameraPos.y/texel)*texel);
             ls.shadowMapOrigin = center.subtract(vec2(worldSize/2));
             ls.shadowMapWorldSize = worldSize;
@@ -377,19 +424,38 @@ class LightSystemPlugin
             cameraScale = size / worldSize;
             cameraAngle = 0;
             canvasClearColor = WHITE;
-            glSetRenderTarget(ls.shadowMap, true);
             glSkipScreenSpace = true; // the map's camera would put them anywhere
             ls.shadowPass = true;
             try
             {
-                for (const o of engineObjects)
+                // the foreground map, then the background map while a directional light needs it, each cleared to
+                // white, every caster black with its alpha kept, set for each object since a render that left
+                // setShadowTransparent on ends with it
+                const drawMap = (target, casts)=>
                 {
-                    if (o.destroyed || !o.castShadow) continue;
-                    // every color black, its alpha kept, set for each object since a render that left
-                    // setShadowTransparent on ends with it
-                    glColorMask = 0xff000000;
-                    setShader(o.shader); // its own Shader as in the main pass, so a snippet that cuts holes casts the same shape
-                    o.renderShadow();
+                    glSetRenderTarget(target, true);
+                    for (const o of engineObjects)
+                    {
+                        if (o.destroyed || !casts(o)) continue;
+                        glColorMask = 0xff000000;
+                        setShader(o.shader); // its own Shader as in the main pass, so a snippet that cuts holes casts the same shape
+                        o.renderShadow();
+                    }
+                    glFlush();
+                };
+                if (ls.shadows || ls.directionalLight?.castShadow)
+                    drawMap(ls.shadowMap, (o)=> o.castShadow); // nothing reads it for a sun that casts no shadows
+                // the background map only when something casts into it, most scenes have nothing there
+                ls.backgroundCasters = !!ls.directionalLight &&
+                    engineObjects.some((o)=> !o.destroyed && o.castBackgroundShadow);
+                if (ls.backgroundCasters)
+                {
+                    if (!ls.backgroundMap)
+                    {
+                        ls.backgroundMap = createTexture(size);
+                        glActiveTexture && glContext.bindTexture(glContext.TEXTURE_2D, glActiveTexture);
+                    }
+                    drawMap(ls.backgroundMap, (o)=> o.castBackgroundShadow);
                 }
             }
             finally
@@ -402,9 +468,218 @@ class LightSystemPlugin
                 [drawContext, mainCanvasSize, cameraPos, cameraScale, cameraAngle, canvasClearColor, glCustomShader] = saved;
             }
         }
+        // the directional light's textures and programs, made when one is first drawn and again when the size changes
+        function initDirectionalTextures()
+        {
+            const gl = glContext, ls = lightSystem, size = ls.directionalTextureSize;
+            ls.directionalTexture = createTexture(size);
+            ls.directionalTextureA = createTexture(size);
+            ls.directionalTextureB = createTexture(size);
+            ls.directionalTextureSizeAllocated = size;
+            glActiveTexture && gl.bindTexture(gl.TEXTURE_2D, glActiveTexture);
+        }
+        function freeDirectionalTextures()
+        {
+            const gl = glContext, ls = lightSystem;
+            for (const texture of [ls.directionalTexture, ls.directionalTextureA, ls.directionalTextureB])
+                gl.deleteTexture(texture);
+            ls.directionalTexture = ls.directionalTextureA = ls.directionalTextureB = undefined;
+            ls.directionalTextureSizeAllocated = 0;
+        }
+        // its programs, made once, a new texture size keeps them
+        function initDirectional()
+        {
+            const gl = glContext, ls = lightSystem, p = ls.directionalPrograms;
+
+            // the maps are stored world up at v=0, the work textures world up at v=1, so a map is read at 1-v
+            const header = '#version 300 es\nprecision highp float;in vec2 uv;out vec4 c;';
+
+            // seed: the darkest of four taps across a work texel, so a caster thinner than a texel still darkens it;
+            // the foreground when useF is on, times the background when useB is
+            p.seed = glCreateProgram(quadVertex, header +
+                'uniform sampler2D f,b;uniform float useF,useB,tap;'+
+                'void main(){vec3 o=vec3(1);'+
+                'for(int i=0;i<4;i++){vec2 m=uv+tap*(vec2(i%2,i/2)*2.-1.);m.y=1.-m.y;'+
+                'vec3 v=mix(vec3(1),texture(f,m).rgb,useF)*mix(vec3(1),texture(b,m).rgb,useB);o=min(o,v);}'+
+                'c=vec4(o,1);}');
+
+            // long shadow pass: the darker of this texel and the one a shift upstream made lighter by fade, so a
+            // shadow lightens with its distance from the caster; past the area upstream is open
+            p.shadow = glCreateProgram(quadVertex, header +
+                'uniform sampler2D s;uniform vec2 shift;uniform float fade;'+
+                'void main(){vec2 u=uv-shift;'+
+                'vec3 b=u==clamp(u,0.,1.)?texture(s,u).rgb+fade:vec3(1);'+
+                'c=vec4(min(texture(s,uv).rgb,b),1);}');
+
+            // background leak pass, the long shadow pass turned around: the brighter of this texel and the light a
+            // shift upstream made dimmer by fade, so light comes into a background area from its edges facing the
+            // light and fades evenly to nothing by backgroundDepth; past the area upstream is open sky
+            p.leak = glCreateProgram(quadVertex, header +
+                'uniform sampler2D s;uniform vec2 shift;uniform float fade;'+
+                'void main(){vec2 u=uv-shift;'+
+                'vec3 b=(u==clamp(u,0.,1.)?texture(s,u).rgb:vec3(1))-fade;'+
+                'c=vec4(max(texture(s,uv).rgb,b),1);}');
+
+            // combine: long shadows times the leak, and a caster's texels take some of the light just upstream
+            // of them, a rim on its side facing the light
+            p.combine = glCreateProgram(quadVertex, header +
+                'uniform sampler2D s,t,f;uniform vec2 rim;uniform float useF,useT;'+
+                'void main(){vec3 l=texture(s,uv).rgb*mix(vec3(1),texture(t,uv).rgb,useT);'+
+                'vec2 u=uv-rim;vec3 up=u==clamp(u,0.,1.)?texture(s,u).rgb*mix(vec3(1),texture(t,u).rgb,useT):vec3(1);'+
+                'vec3 dark=1.-mix(vec3(1),texture(f,vec2(uv.x,1.-uv.y)).rgb,useF);'+
+                'c=vec4(max(l,.8*up*dark),1);}');
+
+            // add: a world space quad over the area, the built light in the light's color, into the lightmap
+            p.add = glCreateProgram(
+                '#version 300 es\nprecision highp float;uniform mat4 m;uniform vec2 origin;uniform float worldSize;'+
+                // three times the area, its edge texels carried on by the clamp, so the sun reaches the whole view however
+                // small the map or turned the camera
+                'in vec2 g;out vec2 uv;void main(){uv=g*3.-1.;gl_Position=m*vec4(origin+uv*worldSize,1,1);}',
+                header + 'uniform sampler2D s;uniform vec4 color;'+
+                'void main(){c=vec4(texture(s,uv).rgb*color.rgb*color.a,1);}');
+
+            if (lightSystemShadersFailed(p.seed, p.shadow, p.leak, p.combine, p.add)) return;
+            p.seedVAO = createQuadVAO(p.seed, 'p');
+            p.shadowVAO = createQuadVAO(p.shadow, 'p');
+            p.leakVAO = createQuadVAO(p.leak, 'p');
+            p.combineVAO = createQuadVAO(p.combine, 'p');
+            p.addVAO = createQuadVAO(p.add, 'g');
+
+            // samplers on units 1, 2 and 3, the engine's tracked texture on unit 0 stays as it is
+            const units = (program, names)=>
+            {
+                gl.useProgram(program);
+                names.forEach((name, i)=> gl.uniform1i(glUniformLocation(program, name), i + 1));
+            };
+            units(p.seed, ['f', 'b']);
+            units(p.shadow, ['s']);
+            units(p.leak, ['s']);
+            units(p.combine, ['s', 't', 'f']);
+            units(p.add, ['s']);
+        }
+        // let go of the textures a directional light made, its work textures and the background map; its programs
+        // stay, small, so a sun made again, as a day and night or a level with its own does, compiles nothing
+        function freeDirectional()
+        {
+            freeDirectionalTextures();
+            glContext.deleteTexture(lightSystem.backgroundMap);
+            lightSystem.backgroundMap = undefined;
+            lightSystem.backgroundCasters = false;
+        }
+        function clearDirectional()
+        {
+            const ls = lightSystem;
+            ls.directionalTexture = ls.directionalTextureA = ls.directionalTextureB = undefined;
+            ls.directionalPrograms = {};
+            ls.directionalTextureSizeAllocated = 0;
+        }
+
+        // build the directional light into directionalTexture, over the shadow map's area: long shadows from the
+        // foreground, times the background leak, with a rim on casters; leaves no framebuffer bound
+        function lightSystemDirectionalPass()
+        {
+            const gl = glContext, ls = lightSystem, light = ls.directionalLight;
+            if (!ls.directionalPrograms.seed)
+            {
+                initDirectional();
+                if (ls.shadersFailed) return;
+            }
+            if (!ls.directionalTexture || ls.directionalTextureSize !== ls.directionalTextureSizeAllocated)
+            {
+                ls.directionalTexture && freeDirectionalTextures();
+                initDirectionalTextures();
+            }
+            const p = ls.directionalPrograms, N = ls.directionalTextureSize, W = ls.shadowMapWorldSize;
+            const d = light.sunDirection.normalize(-1), toUV = (texels)=> vec2(d.x * texels / N, d.y * texels / N);
+            const casts = light.castShadow ? 1 : 0;
+            const cap = ceil(log2(N)) + 1; // passes enough to cross the texture, so a long shadow fades out, never cut off
+
+            gl.bindFramebuffer(gl.FRAMEBUFFER, glFramebuffer);
+            gl.viewport(0, 0, N, N);
+            gl.disable(gl.BLEND);
+            const target = (texture)=> gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+            const bind = (unit, texture)=> { gl.activeTexture(gl.TEXTURE0 + unit); gl.bindTexture(gl.TEXTURE_2D, texture); };
+            const use = (name)=> { gl.useProgram(p[name]); gl.bindVertexArray(p[name + 'VAO']); return p[name]; };
+            const draw = ()=> gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+            const u = glUniformLocation;
+
+            // long shadows: the foreground seeded into A, then passes shifting twice as far each time, ping ponged
+            let program = use('seed');
+            bind(1, ls.shadowMap); bind(2, ls.backgroundMap || ls.shadowMap); // a texture on the unit, though unread
+            gl.uniform1f(u(program, 'useF'), casts);
+            gl.uniform1f(u(program, 'useB'), 0);
+            gl.uniform1f(u(program, 'tap'), .25 / N);
+            target(ls.directionalTextureA); draw();
+            let src = ls.directionalTextureA, dst = ls.directionalTextureB;
+            const L = light.shadowLength * N / W;
+            if (casts && L > 0)
+            {
+                program = use('shadow');
+                const passes = clamp(ceil(log2(max(L, 1))), 1, cap);
+                for (let k = 0; k < passes; ++k)
+                {
+                    const shift = toUV(2**k);
+                    gl.uniform2f(u(program, 'shift'), shift.x, shift.y);
+                    gl.uniform1f(u(program, 'fade'), 2**k / L);
+                    bind(1, src); target(dst); draw();
+                    [src, dst] = [dst, src];
+                }
+            }
+            const shadows = src, free = dst; // the long shadows, and the other work texture
+
+            // the background leak, seeded from the background alone into the free texture, only when something casts
+            // into the background map; with nothing there the combine leaves it out; the foreground is in the long
+            // shadows already, and seeding it here too darkened a see through caster twice, only beside a background
+            const leaks = ls.backgroundCasters;
+            if (leaks)
+            {
+                program = use('seed');
+                bind(1, ls.shadowMap); bind(2, ls.backgroundMap);
+                gl.uniform1f(u(program, 'useF'), 0);
+                gl.uniform1f(u(program, 'useB'), 1);
+                target(free); draw();
+            }
+            let leakSrc = free, leakDst = ls.directionalTexture;
+            const D = light.backgroundDepth * N / W;
+            if (leaks && D > 0)
+            {
+                // passes shifting twice as far each time, as the long shadows, so the light fades in evenly by D
+                program = use('leak');
+                const passes = clamp(ceil(log2(max(D, 1))), 1, cap);
+                for (let k = 0; k < passes; ++k)
+                {
+                    const shift = toUV(2**k);
+                    gl.uniform2f(u(program, 'shift'), shift.x, shift.y);
+                    gl.uniform1f(u(program, 'fade'), 2**k / D);
+                    bind(1, leakSrc); target(leakDst); draw();
+                    [leakSrc, leakDst] = [leakDst, leakSrc];
+                }
+            }
+
+            // combine into the one of the three textures left, long shadows times the leak, with a rim on casters;
+            // it is the built light from now on, the other two its work textures
+            const textures = [ls.directionalTexture, ls.directionalTextureA, ls.directionalTextureB];
+            const built = textures.find((texture)=> texture !== shadows && texture !== leakSrc);
+            program = use('combine');
+            bind(1, shadows); bind(2, leakSrc); bind(3, ls.shadowMap);
+            const rim = toUV(3);
+            gl.uniform2f(u(program, 'rim'), rim.x, rim.y);
+            gl.uniform1f(u(program, 'useF'), casts);
+            gl.uniform1f(u(program, 'useT'), leaks ? 1 : 0);
+            target(built); draw();
+            [ls.directionalTextureA, ls.directionalTextureB] = textures.filter((texture)=> texture !== built);
+            ls.directionalTexture = built;
+
+            // hand the engine its state back: unit 0 active with its texture, no framebuffer
+            bind(1, null); bind(2, null); bind(3, null);
+            gl.activeTexture(gl.TEXTURE0);
+            glActiveTexture && gl.bindTexture(gl.TEXTURE_2D, glActiveTexture);
+            gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+            gl.enable(gl.BLEND);
+        }
         function lightSystemRender()
         {
-            if (headlessMode || !glEnable) return;
+            if (headlessMode || !glEnable || lightSystem.shadersFailed) return;
             if (!lightSystem.enabled) return;
             if (!lightSystem.texture)
             {
@@ -418,9 +693,24 @@ class LightSystemPlugin
             glFlush();
             const prevAdditive = glAdditive;
 
-            // 1b. the shadow pass draws every caster black into the shadow map
-            if (lightSystem.shadows)
+            // 1b. the shadow pass draws every caster black into the shadow map, for shadows or a directional light
+            if (lightSystem.shadows || lightSystem.directionalLight)
                 lightSystemShadowPass();
+            if (lightSystem.shadersFailed) return;
+
+            // 1c. the directional light is built from the maps, before the lightmap is bound
+            const sun = lightSystem.directionalLight;
+            if (sun)
+                lightSystemDirectionalPass();
+            else
+            {
+                // the sun is gone, so are its textures, and the shadow map it made when shadows are off
+                if (lightSystem.directionalTexture || lightSystem.backgroundMap)
+                    freeDirectional();
+                if (!lightSystem.shadows && lightSystem.shadowMap)
+                    freeShadowTextures();
+            }
+            if (lightSystem.shadersFailed) return;
 
             // an automatic size follows the canvas, so reallocate the lightmap when
             // the canvas changed size, after the flush so the batch keeps its texture
@@ -476,6 +766,26 @@ class LightSystemPlugin
                     o.renderLight();
                 }
 
+                // 3a. the directional light, added over the shadow map's area in its color
+                if (sun && lightSystem.directionalTexture)
+                {
+                    glFlush();
+                    const gl = glContext, p = lightSystem.directionalPrograms, as = p.add, c = sun.color;
+                    gl.useProgram(as);
+                    gl.bindVertexArray(p.addVAO);
+                    gl.uniformMatrix4fv(glUniformLocation(as, 'm'), false, glTransform);
+                    gl.uniform2f(glUniformLocation(as, 'origin'), lightSystem.shadowMapOrigin.x, lightSystem.shadowMapOrigin.y);
+                    gl.uniform1f(glUniformLocation(as, 'worldSize'), lightSystem.shadowMapWorldSize);
+                    gl.uniform4f(glUniformLocation(as, 'color'), c.r, c.g, c.b, c.a);
+                    gl.activeTexture(gl.TEXTURE1);
+                    gl.bindTexture(gl.TEXTURE_2D, lightSystem.directionalTexture);
+                    gl.activeTexture(gl.TEXTURE0);
+                    gl.enable(gl.BLEND);
+                    gl.blendFunc(gl.ONE, gl.ONE);
+                    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
+                    glSetInstancedMode(true);
+                }
+
                 // 3b. emissive objects draw their shape in gray at their emissive level, white at 1, adding that much
                 //     light where they are so they show their own colors; text goes to the 1x1 canvas as in the
                 //     shadow pass, so it is not drawn twice
@@ -555,10 +865,12 @@ class LightSystemPlugin
             lightSystem.lightVAO = undefined;
             lightSystem.compositeVAO = undefined;
             clearShadows();
+            clearDirectional();
             LOG('LightSystemPlugin: WebGL context lost');
         }
         function lightSystemContextRestored()
         {
+            lightSystem.shadersFailed = false; // tried again on the new context, as the 3D renderer is
             initLightSystem();
             LOG('LightSystemPlugin: WebGL context restored');
         }
@@ -570,6 +882,9 @@ class LightSystemPlugin
     {
         this.shadowMapSize = glClampTextureSize(this.shadowMapSize);
         this.shadowTextureSize = glClampTextureSize(this.shadowTextureSize);
+        ASSERT(isNumber(this.directionalTextureSize) && this.directionalTextureSize >= 1,
+            'directionalTextureSize is texels, 1 or more, taken down to whole texels', this.directionalTextureSize);
+        this.directionalTextureSize = glClampTextureSize(max(1, floor(this.directionalTextureSize) || 1));
         const size = this.textureSize;
         if (!size) return;
         const x = glClampTextureSize(size.x), y = glClampTextureSize(size.y);
@@ -762,3 +1077,70 @@ class Light extends EngineObject
         drawTile(this.pos, size, this.glowTileInfo, this.color, 0, false, undefined, true, false);
     }
 }
+
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * A DirectionalLight is a sun for the 2D light system: it lights the whole scene from one direction, added into the
+ * lightmap with the point lights
+ * - One at a time, made after the LightSystemPlugin, lightSystem.directionalLight is the one; a debug build asserts on
+ *   a second while the first lives, a release build destroys the first
+ * - Its castShadow lets foreground casters, objects with castShadow, throw long shadows across open space, fading out
+ *   by shadowLength; a light does not need lightSystem.shadows for that
+ * - Objects with castBackgroundShadow, a background layer, are dark to it inside and lit at the edges that face it,
+ *   fading in by backgroundDepth
+ * @extends EngineObject
+ * @memberof LightSystem
+ * @example
+ * new DirectionalLight(vec2(-1, 1), hsl(.1, .3, 1)); // a warm sun up and to the left, shining down and to the right
+ */
+class DirectionalLight extends EngineObject
+{
+    /** Create the scene's directional light
+     *  @param {Vector2} [sunDirection] - Toward the sun, it shines the other way, as render3D.sunDirection
+     *  @param {Color} [color] - Color of the light; alpha modulates intensity */
+    constructor(sunDirection=vec2(-1, 1), color=WHITE)
+    {
+        ASSERT(!!lightSystem, 'make a LightSystemPlugin before a DirectionalLight');
+        ASSERT(isVector2(sunDirection) && !!(sunDirection.x || sunDirection.y),
+            'DirectionalLight: sunDirection is a vec2 that is not zero, toward the sun', sunDirection);
+        ASSERT(!lightSystem?.directionalLight, 'there is one DirectionalLight at a time, destroy the old one first');
+        super(vec2(), vec2(), undefined, 0, color);
+        this.mass = 0; // it does not fall in a game with gravity
+
+        /** @property {Vector2} - Toward the sun, it shines the other way, as render3D.sunDirection */
+        this.sunDirection = sunDirection.copy();
+        /** @property {number} - World units a long shadow reaches before it has faded out; a caster casts only from
+         *  inside the shadow map, shadowMapScale views across, so past (shadowMapScale - 1) / 2 of a view beyond the
+         *  screen it throws none in */
+        this.shadowLength = 20;
+        /** @property {number} - World units the light gets into a background area from its edges facing it */
+        this.backgroundDepth = 3;
+        // castShadow is EngineObject's, true: foreground casters throw long shadows; it draws nothing, so never casts
+        // in a release build, with no assert, a second takes over and the first goes, not left alive doing nothing
+        lightSystem?.directionalLight?.destroy();
+        lightSystem && (lightSystem.directionalLight = this);
+    }
+
+    /** Check its settings, called automatically each frame */
+    update()
+    {
+        ASSERT(isVector2(this.sunDirection) && !!(this.sunDirection.x || this.sunDirection.y),
+            'DirectionalLight: sunDirection is a vec2 that is not zero, toward the sun', this.sunDirection);
+        ASSERT(this.shadowLength >= 0 && this.backgroundDepth >= 0,
+            'DirectionalLight: shadowLength and backgroundDepth are world units, 0 or more', this.shadowLength,
+            this.backgroundDepth);
+    }
+
+    /** A directional light draws nothing of its own, it is added into the lightmap by the plugin */
+    render() {}
+
+    /** Destroy the light, the scene goes without it from the next frame
+     *  @param {boolean} [immediate] */
+    destroy(immediate)
+    {
+        if (lightSystem?.directionalLight === this)
+            lightSystem.directionalLight = undefined;
+        super.destroy(immediate);
+    }
+}

package/plugins/math3d.js

@@ -553,8 +553,10 @@ class Matrix4
         const m = this.m, s = this.getScale();
         const sx = s.x || 1, sy = s.y || 1, sz = s.z || 1;
         const m1 = m[1] / sx, m5 = m[5] / sy, m8 = m[8] / sz, m9 = m[9] / sz, m10 = m[10] / sz;
-        const pitch = Math.asin(clamp(-m9, -1, 1));
-        if (abs(m9) < 1 - 1e-6)
+        // the pitch from its cosine as well as its sine, which stays exact near straight up where the sine alone
+        // loses its precision
+        const c = hypot(m8, m10), pitch = atan2(-m9, c);
+        if (c > 1e-9)
             return new Vector3(pitch, atan2(m8, m10), atan2(m1, m5));
         // straight up or down: yaw and roll turn about the same axis, so the roll is zero and yaw takes it all
         return new Vector3(pitch, atan2(m[4] / sy * -m9, m[0] / sx), 0);