@solidtv/renderer 1.5.0-1 → 1.5.1

package/src/core/lib/textureCompression.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, vi } from 'vitest';
+import { uploadCompressedTexture } from './textureCompression.js';
+import type { WebGlContextWrapper } from './WebGlContextWrapper.js';
+import type { CompressedData } from '../textures/Texture.js';
+
+/**
+ * A compressed format enum is only valid in compressedTexImage2D after its
+ * owning extension has been enabled via getExtension; otherwise the driver
+ * rejects it with GL_INVALID_ENUM (1280). These tests pin that every upload
+ * path enables its extension *before* uploading, and fails loudly when the
+ * device exposes none of the candidates.
+ */
+
+interface MockGlw {
+  glw: WebGlContextWrapper;
+  order: string[];
+  getExtension: ReturnType<typeof vi.fn>;
+  compressedTexImage2D: ReturnType<typeof vi.fn>;
+}
+
+function makeGlw(supported: Set<string>): MockGlw {
+  const order: string[] = [];
+  const getExtension = vi.fn((name: string) => {
+    order.push(`getExtension:${name}`);
+    return supported.has(name) === true ? {} : null;
+  });
+  const compressedTexImage2D = vi.fn(() => {
+    order.push('compressedTexImage2D');
+  });
+  const glw = {
+    getExtension,
+    compressedTexImage2D,
+    bindTexture: vi.fn(),
+    texParameteri: vi.fn(),
+    TEXTURE_WRAP_S: 0,
+    TEXTURE_WRAP_T: 0,
+    TEXTURE_MAG_FILTER: 0,
+    TEXTURE_MIN_FILTER: 0,
+    CLAMP_TO_EDGE: 0,
+    LINEAR: 0,
+    LINEAR_MIPMAP_LINEAR: 0,
+  } as unknown as WebGlContextWrapper;
+  return { glw, order, getExtension, compressedTexImage2D };
+}
+
+function makeData(
+  type: 'ktx' | 'pvr' | 'astc',
+  glInternalFormat: number,
+): CompressedData {
+  return {
+    type,
+    glInternalFormat,
+    w: 4,
+    h: 4,
+    mipmaps: [new ArrayBuffer(16)],
+    blockInfo: { width: 4, height: 4, bytes: 16 },
+  };
+}
+
+const texture = {} as WebGLTexture;
+
+// COMPRESSED_RGBA_S3TC_DXT5_EXT
+const S3TC_DXT5 = 0x83f3;
+// COMPRESSED_RGB_PVRTC_4BPPV1_IMG
+const PVRTC_4BPP = 0x8c00;
+// COMPRESSED_RGB_ETC1_WEBGL
+const ETC1 = 0x8d64;
+// COMPRESSED_RGBA_ASTC_4x4_KHR
+const ASTC_4x4 = 0x93b0;
+
+describe('compressed texture extension guards', () => {
+  it('KTX enables the s3tc extension before uploading', () => {
+    const m = makeGlw(new Set(['WEBGL_compressed_texture_s3tc']));
+    uploadCompressedTexture.ktx!(m.glw, texture, makeData('ktx', S3TC_DXT5));
+
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBGL_compressed_texture_s3tc',
+    );
+    expect(m.compressedTexImage2D).toHaveBeenCalled();
+    // getExtension must precede the first compressedTexImage2D call
+    expect(m.order.indexOf('getExtension:WEBGL_compressed_texture_s3tc')).toBe(
+      0,
+    );
+    expect(
+      m.order.indexOf('getExtension:WEBGL_compressed_texture_s3tc') <
+        m.order.indexOf('compressedTexImage2D'),
+    ).toBe(true);
+  });
+
+  it('KTX throws (no silent 1280) when the s3tc extension is unavailable', () => {
+    const m = makeGlw(new Set());
+    expect(() =>
+      uploadCompressedTexture.ktx!(m.glw, texture, makeData('ktx', S3TC_DXT5)),
+    ).toThrow(/not supported/);
+    expect(m.compressedTexImage2D).not.toHaveBeenCalled();
+  });
+
+  it('KTX enables the etc1 extension for ETC1 formats', () => {
+    const m = makeGlw(new Set(['WEBGL_compressed_texture_etc1']));
+    uploadCompressedTexture.ktx!(m.glw, texture, makeData('ktx', ETC1));
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBGL_compressed_texture_etc1',
+    );
+    expect(m.compressedTexImage2D).toHaveBeenCalled();
+  });
+
+  it('PVR enables the pvrtc extension before uploading', () => {
+    const m = makeGlw(new Set(['WEBGL_compressed_texture_pvrtc']));
+    uploadCompressedTexture.pvr!(m.glw, texture, makeData('pvr', PVRTC_4BPP));
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBGL_compressed_texture_pvrtc',
+    );
+    expect(
+      m.order.indexOf('getExtension:WEBGL_compressed_texture_pvrtc') <
+        m.order.indexOf('compressedTexImage2D'),
+    ).toBe(true);
+  });
+
+  it('PVR falls back to the WebKit-prefixed pvrtc extension', () => {
+    const m = makeGlw(new Set(['WEBKIT_WEBGL_compressed_texture_pvrtc']));
+    uploadCompressedTexture.pvr!(m.glw, texture, makeData('pvr', PVRTC_4BPP));
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBGL_compressed_texture_pvrtc',
+    );
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBKIT_WEBGL_compressed_texture_pvrtc',
+    );
+    expect(m.compressedTexImage2D).toHaveBeenCalled();
+  });
+
+  it('PVR throws when neither pvrtc extension is available', () => {
+    const m = makeGlw(new Set());
+    expect(() =>
+      uploadCompressedTexture.pvr!(m.glw, texture, makeData('pvr', PVRTC_4BPP)),
+    ).toThrow(/not supported/);
+    expect(m.compressedTexImage2D).not.toHaveBeenCalled();
+  });
+
+  it('ASTC enables the astc extension before uploading', () => {
+    const m = makeGlw(new Set(['WEBGL_compressed_texture_astc']));
+    uploadCompressedTexture.astc!(m.glw, texture, makeData('astc', ASTC_4x4));
+    expect(m.getExtension).toHaveBeenCalledWith(
+      'WEBGL_compressed_texture_astc',
+    );
+    expect(
+      m.order.indexOf('getExtension:WEBGL_compressed_texture_astc') <
+        m.order.indexOf('compressedTexImage2D'),
+    ).toBe(true);
+  });
+
+  it('ASTC throws when the astc extension is unavailable', () => {
+    const m = makeGlw(new Set());
+    expect(() =>
+      uploadCompressedTexture.astc!(m.glw, texture, makeData('astc', ASTC_4x4)),
+    ).toThrow(/not supported/);
+    expect(m.compressedTexImage2D).not.toHaveBeenCalled();
+  });
+});

package/src/core/lib/textureCompression.ts

@@ -171,18 +171,90 @@ const loadASTC = async function (view: DataView): Promise<TextureData> {
   };
 };
 
+// Candidate extension name lists, hoisted to module constants so the per-upload
+// resolver returns a shared reference instead of allocating a new array each
+// call (zero GC pressure on the texture-upload path).
+const EXT_ASTC = ['WEBGL_compressed_texture_astc'];
+const EXT_S3TC = ['WEBGL_compressed_texture_s3tc'];
+const EXT_ETC1 = ['WEBGL_compressed_texture_etc1'];
+const EXT_ETC = ['WEBGL_compressed_texture_etc'];
+// WebKit-prefixed name is the legacy fallback.
+const EXT_PVRTC = [
+  'WEBGL_compressed_texture_pvrtc',
+  'WEBKIT_WEBGL_compressed_texture_pvrtc',
+];
+const EXT_NONE: string[] = [];
+
+/**
+ * Resolve the WebGL extension(s) that must be enabled before a given compressed
+ * GL internal format may be used.
+ *
+ * @remarks
+ * `getExtension` is the call that actually enables a compressed format on a
+ * context — until it is called, the format enum is rejected by
+ * `compressedTexImage2D` with `GL_INVALID_ENUM` (1280). Listed in priority
+ * order; the first name the device exposes is used.
+ */
+const requiredExtensionsForFormat = (glInternalFormat: number): string[] => {
+  // ASTC (incl. sRGB variants): 0x93b0–0x93d5
+  if (glInternalFormat >= 0x93b0 && glInternalFormat <= 0x93d5) {
+    return EXT_ASTC;
+  }
+  // S3TC / DXTn: 0x83f0–0x83f3
+  if (glInternalFormat >= 0x83f0 && glInternalFormat <= 0x83f3) {
+    return EXT_S3TC;
+  }
+  // ETC1: 0x8d64
+  if (glInternalFormat === 0x8d64) {
+    return EXT_ETC1;
+  }
+  // ETC2 / EAC: 0x9274–0x9279
+  if (glInternalFormat >= 0x9274 && glInternalFormat <= 0x9279) {
+    return EXT_ETC;
+  }
+  // PVRTC: 0x8c00–0x8c03
+  if (glInternalFormat >= 0x8c00 && glInternalFormat <= 0x8c03) {
+    return EXT_PVRTC;
+  }
+  return EXT_NONE;
+};
+
+/**
+ * Enable the extension owning `glInternalFormat` so the format enum is valid in
+ * `compressedTexImage2D`, throwing a clear error if the device exposes none of
+ * the candidate extensions (instead of leaking a silent `GL_INVALID_ENUM`).
+ */
+const ensureCompressedFormatEnabled = (
+  glw: WebGlContextWrapper,
+  glInternalFormat: number,
+): void => {
+  const names = requiredExtensionsForFormat(glInternalFormat);
+  const len = names.length;
+  if (len === 0) {
+    return;
+  }
+  for (let i = 0; i < len; i++) {
+    if (glw.getExtension(names[i]!) !== null) {
+      return;
+    }
+  }
+  throw new Error(
+    `Compressed texture format 0x${glInternalFormat.toString(
+      16,
+    )} is not supported by this device (requires ${names.join(' or ')})`,
+  );
+};
+
 const uploadASTC = function (
   glw: WebGlContextWrapper,
   texture: WebGLTexture,
   data: CompressedData,
 ) {
-  if (glw.getExtension('WEBGL_compressed_texture_astc') === null) {
-    throw new Error('ASTC compressed textures not supported by this device');
-  }
+  const { glInternalFormat, mipmaps, w, h } = data;
+  ensureCompressedFormatEnabled(glw, glInternalFormat);
 
   glw.bindTexture(texture);
 
-  const { glInternalFormat, mipmaps, w, h } = data;
   if (mipmaps === undefined) {
     return;
   }
@@ -277,6 +349,7 @@ const uploadKTX = function (
   data: CompressedData,
 ) {
   const { glInternalFormat, mipmaps, w: width, h: height, blockInfo } = data;
+  ensureCompressedFormatEnabled(glw, glInternalFormat);
   if (mipmaps === undefined) {
     return;
   }
@@ -415,6 +488,7 @@ const uploadPVR = function (
   data: CompressedData,
 ) {
   const { glInternalFormat, mipmaps, w: width, h: height } = data;
+  ensureCompressedFormatEnabled(glw, glInternalFormat);
   if (mipmaps === undefined) {
     return;
   }

package/src/core/renderers/CoreRenderer.ts

@@ -11,6 +11,7 @@ export interface CoreRendererOptions {
   canvas: HTMLCanvasElement | OffscreenCanvas;
   contextSpy: ContextSpy | null;
   forceWebGL2: boolean;
+  disableVertexArrayObject: boolean;
 }
 
 export interface BufferInfo {

package/src/core/renderers/canvas/CanvasRenderer.ts

@@ -52,7 +52,13 @@ export class CanvasRenderer extends CoreRenderer {
     const ctx = this.context;
     const { tx, ty, ta, tb, tc, td } = node.globalTransform!;
     const clippingRect = node.clippingRect;
-    let texture = (node.props.texture || this.stage.defaultTexture) as Texture;
+    // While a placeholder is showing, render the color-rect path (the default
+    // ColorTexture) tinted by the node's premultiplied placeholder color.
+    let texture = (
+      node.placeholderActive === true
+        ? this.stage.defaultTexture
+        : node.props.texture || this.stage.defaultTexture
+    ) as Texture;
     // The Canvas2D renderer only supports image textures, no textures are used for color blocks
     if (texture !== null) {
       const textureType = texture.type;

package/src/core/renderers/webgl/WebGlRenderer.ts

@@ -48,6 +48,19 @@ const GL_OUT_OF_MEMORY = 0x0505;
  */
 const MAX_DRAINED_GL_ERRORS = 8;
 
+/**
+ * Dirty-ratio cutoff that flips the per-frame quad upload from surgical
+ * `bufferSubData` (one call per changed node) to a single full `bufferData`.
+ *
+ * The surgical path wins when few nodes change per frame (typical UI), but
+ * degrades to one GL call per node when most of the scene moves at once
+ * (full-screen animation, scroll, zoom). At that point a single bulk upload is
+ * cheaper than N driver round-trips, so when the number of nodes we would
+ * `bufferSubData` exceeds this fraction of the render list we upload everything
+ * in one call instead. Range 0..1; ~0.4 balances the two regimes.
+ */
+const FULL_UPLOAD_DIRTY_RATIO = 0.4;
+
 export type WebGlRenderOp = CoreNode | SdfRenderOp;
 
 export class WebGlRenderer extends CoreRenderer {
@@ -161,6 +174,14 @@ export class WebGlRenderer extends CoreRenderer {
    * capacity, requiring a full re-upload even when needsFullUpload is false.
    */
   lastUploadedBufferSize = 0;
+  /**
+   * Count of main-scene nodes whose quad data changed this frame and which
+   * own a buffer slot. Accumulated for free during the addQuad pass (which
+   * already branches on isQuadDirty) and consumed in render() to choose
+   * between surgical bufferSubData uploads and a single full bufferData,
+   * avoiding a separate counting loop. Reset each frame in reset().
+   */
+  dirtyQuadCount = 0;
   /**
    * Whether the renderer is currently rendering to a texture.
    */
@@ -187,7 +208,10 @@ export class WebGlRenderer extends CoreRenderer {
       options.forceWebGL2,
       options.contextSpy,
     );
-    const glw = (this.glw = new WebGlContextWrapper(gl));
+    const glw = (this.glw = new WebGlContextWrapper(
+      gl,
+      options.disableVertexArrayObject,
+    ));
     glw.viewport(0, 0, options.canvas.width, options.canvas.height);
 
     this.attachContextLossListeners(options.canvas);
@@ -346,6 +370,7 @@ export class WebGlRenderer extends CoreRenderer {
     }
     this.curRenderOp = null;
     this.curSdfRenderOp = null;
+    this.dirtyQuadCount = 0;
     this.sdfBufferIdx = 0;
     this.sdfQuadCount = 0;
     this.renderOps.length = 0;
@@ -446,7 +471,12 @@ export class WebGlRenderer extends CoreRenderer {
     }
 
     const props = node.props;
-    let tx = props.texture || this.stage.defaultTexture!;
+    // While a placeholder is showing, the quad samples the shared 1x1 white
+    // texture tinted by the node's premultiplied placeholder color.
+    let tx =
+      node.placeholderActive === true
+        ? this.stage.defaultTexture!
+        : props.texture || this.stage.defaultTexture!;
 
     if (tx.type === TextureType.subTexture) {
       tx = (tx as SubTexture).parentTexture;
@@ -496,6 +526,14 @@ export class WebGlRenderer extends CoreRenderer {
     // The GPU upload is deferred to render().
     // During RTT, always write since the buffer is rebuilt from scratch.
     if (!DIRTY_QUAD_BUFFER || isRTT || node.isQuadDirty) {
+      // Count main-scene dirty nodes here, while we already have the node in
+      // hand, so render() can pick full vs. surgical upload without a second
+      // pass over the render list. Slot is guaranteed assigned at this point
+      // (i = quadBufferIndex above), so no quadBufferIndex !== -1 guard needed.
+      if (DIRTY_QUAD_BUFFER && isRTT === false && node.isQuadDirty === true) {
+        this.dirtyQuadCount++;
+      }
+
       const rc = node.renderCoords!;
       const tc = node.textureCoords || this.defaultTextureCoords;
 
@@ -966,31 +1004,41 @@ export class WebGlRenderer extends CoreRenderer {
     const BYTES = Float32Array.BYTES_PER_ELEMENT;
 
     if (DIRTY_QUAD_BUFFER) {
-      if (
-        this.needsFullUpload ||
-        this.curBufferIdx > this.lastUploadedBufferSize
-      ) {
-        // Full GPU re-allocation: covers new nodes and structural reorders.
-        // Also triggered when curBufferIdx has grown beyond the last uploaded
-        // size (e.g. after RTT rendering consumed needsFullUpload and then
-        // the main scene added more quads).
-        // Uses DYNAMIC_DRAW to signal to the driver that the buffer will be
-        // updated frequently in smaller pieces going forward.
+      const renderList = this.stage.renderList;
+      const len = renderList.length;
+
+      // Growth/realloc always forces a full upload (new nodes, structural
+      // reorders, or curBufferIdx grown past the last uploaded size).
+      let fullUpload =
+        this.needsFullUpload || this.curBufferIdx > this.lastUploadedBufferSize;
+
+      // Otherwise decide adaptively: if the number of nodes we would upload
+      // surgically exceeds FULL_UPLOAD_DIRTY_RATIO of the render list, a single
+      // bufferData is cheaper than that many bufferSubData calls. The count was
+      // accumulated for free during the addQuad pass (dirtyQuadCount), so no
+      // separate counting loop is needed here.
+      if (fullUpload === false) {
+        fullUpload = this.dirtyQuadCount > len * FULL_UPLOAD_DIRTY_RATIO;
+      }
+
+      if (fullUpload === true) {
+        // Full GPU re-allocation: covers the growth/realloc cases above and the
+        // "most of the scene changed" case where one bulk upload beats N
+        // per-node uploads. Uses DYNAMIC_DRAW to signal to the driver that the
+        // buffer will be updated frequently going forward.
         const arr = new Float32Array(quadBuffer, 0, this.curBufferIdx);
         glw.arrayBufferData(buffer, arr, glw.DYNAMIC_DRAW);
         this.needsFullUpload = false;
         this.lastUploadedBufferSize = this.curBufferIdx;
 
         // Clear dirty flags since we just uploaded everything.
-        const renderList = this.stage.renderList;
-        for (let i = 0, len = renderList.length; i < len; i++) {
+        for (let i = 0; i < len; i++) {
           renderList[i]!.isQuadDirty = false;
         }
       } else {
         // Surgical per-node uploads: only write the 20 float32s for nodes
         // whose quad data changed since the last frame.
-        const renderList = this.stage.renderList;
-        for (let i = 0, len = renderList.length; i < len; i++) {
+        for (let i = 0; i < len; i++) {
           const node = renderList[i]!;
           if (node.isQuadDirty && node.quadBufferIndex !== -1) {
             const byteOffset = node.quadBufferIndex * BYTES;

package/src/core/renderers/webgl/WebGlShaderProgram.ts

@@ -30,6 +30,35 @@ export class WebGlShaderProgram implements CoreShaderProgram {
   public isDestroyed = false;
   supportsIndexedTextures = false;
 
+  /**
+   * Shadow copies of this program's GL uniform state, used by
+   * {@link bindRenderOp} to skip redundant gl.uniform* calls.
+   *
+   * @remarks
+   * GL uniform values are state on the program object and persist across
+   * useProgram switches, and bindRenderOp is the only writer of these
+   * uniforms, so the shadows always mirror GL truth — even when ops using
+   * other programs are interleaved between two ops of this program.
+   *
+   * `lastBoundUniforms` tracks the shader node's uniform collection by
+   * identity: collections are created once, filled once, and shared by
+   * reference across shader nodes with the same value key (see
+   * WebGlShaderNode.update), so reference equality implies value equality.
+   * The failure direction is safe — a new collection holding identical
+   * values just causes a redundant upload, never a wrong skip.
+   *
+   * Sentinels: -1 never collides with real pixel ratios, resolutions,
+   * alphas, dimensions, or time values (all >= 0).
+   */
+  protected lastBoundUniforms: unknown = null;
+  protected lastPixelRatio = -1;
+  protected lastResolutionW = -1;
+  protected lastResolutionH = -1;
+  protected lastAlpha = -1;
+  protected lastDimensionsW = -1;
+  protected lastDimensionsH = -1;
+  protected lastTime = -1;
+
   /**
    * Cached Vertex Array Objects, keyed by the buffer collection they capture.
    *
@@ -198,44 +227,78 @@ export class WebGlShaderProgram implements CoreShaderProgram {
       return;
     }
 
-    // Bind render texture framebuffer dimensions as resolution
-    // if the parent has a render texture
+    // Resolve target pixel ratio / resolution, then compare-and-set against
+    // the program's shadow state. Each gl.uniform* call below crosses into
+    // the GPU-process command buffer, so skipping value-identical re-uploads
+    // is a real per-op CPU saving on embedded targets.
+    let pixelRatio: number;
+    let resolutionW: number;
+    let resolutionH: number;
     if (USE_RTT && parentHasRenderTexture === true && framebufferDimensions) {
-      const { w, h } = framebufferDimensions;
       // Force pixel ratio to 1.0 for render textures since they are always 1:1
       // the final render texture will be rendered to the screen with the correct pixel ratio
-      this.glw.uniform1f('u_pixelRatio', 1.0);
-
+      pixelRatio = 1.0;
       // Set resolution to the framebuffer dimensions
-      this.glw.uniform2f('u_resolution', w, h);
+      resolutionW = framebufferDimensions.w;
+      resolutionH = framebufferDimensions.h;
     } else {
-      this.glw.uniform1f('u_pixelRatio', renderOp.stage.pixelRatio);
+      pixelRatio = renderOp.stage.pixelRatio;
+      resolutionW = this.glw.canvas.width;
+      resolutionH = this.glw.canvas.height;
+    }
 
-      this.glw.uniform2f(
-        'u_resolution',
-        this.glw.canvas.width,
-        this.glw.canvas.height,
-      );
+    if (pixelRatio !== this.lastPixelRatio) {
+      this.glw.uniform1f('u_pixelRatio', pixelRatio);
+      this.lastPixelRatio = pixelRatio;
     }
 
-    if (this.useTimeValue === true) {
+    if (
+      resolutionW !== this.lastResolutionW ||
+      resolutionH !== this.lastResolutionH
+    ) {
+      this.glw.uniform2f('u_resolution', resolutionW, resolutionH);
+      this.lastResolutionW = resolutionW;
+      this.lastResolutionH = resolutionH;
+    }
+
+    if (this.useTimeValue === true && renderOp.time !== this.lastTime) {
       this.glw.uniform1f('u_time', renderOp.time);
+      this.lastTime = renderOp.time;
     }
 
-    if (this.useSystemAlpha === true) {
+    if (
+      this.useSystemAlpha === true &&
+      renderOp.worldAlpha !== this.lastAlpha
+    ) {
       this.glw.uniform1f('u_alpha', renderOp.worldAlpha);
+      this.lastAlpha = renderOp.worldAlpha;
     }
 
-    if (this.useSystemDimensions === true) {
+    if (
+      this.useSystemDimensions === true &&
+      (renderOp.w !== this.lastDimensionsW ||
+        renderOp.h !== this.lastDimensionsH)
+    ) {
       this.glw.uniform2f('u_dimensions', renderOp.w, renderOp.h);
+      this.lastDimensionsW = renderOp.w;
+      this.lastDimensionsH = renderOp.h;
     }
 
     const shader = renderOp.shader as WebGlShaderNode;
     if (shader.props !== undefined) {
       /**
        * loop over all precalculated uniform types
+       *
+       * Collections are immutable after being filled and shared by reference
+       * across shader nodes with equal value keys, so when the same object is
+       * already bound the GL program still holds exactly these values and the
+       * whole pass (loops + gl calls) can be skipped.
        */
       const uniforms = shader.uniforms;
+      if ((uniforms as unknown) === this.lastBoundUniforms) {
+        return;
+      }
+      this.lastBoundUniforms = uniforms;
 
       for (const key in uniforms.single) {
         const { method, value } = uniforms.single[key]!;