figureone 1.8.0 → 1.9.1

package/index.js

@@ -7174,6 +7174,11 @@ var GLObject = /*#__PURE__*/function (_DrawingObject) {
   // is precomputed so the draw loop allocates nothing). A mask with an empty
   // src is a transparent placeholder - an index-preserving no-op slot.
 
+  // The webgl texture id this object currently holds a base-texture reference to
+  // (acquired by initTexture, or adopted from a shared atlas via
+  // setBaseTextureRef). resetTextureBuffer releases exactly this id, so the
+  // release can never be unbalanced with the acquire. null = no reference held.
+
   function GLObject(webgl) {
     var _this;
     var vertexShader = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {
@@ -7203,6 +7208,7 @@ var GLObject = /*#__PURE__*/function (_DrawingObject) {
     _this.numVertices = 0;
     _this.uniforms = {};
     _this.texture = null;
+    _this.acquiredBaseTextureId = null;
     _this.maskTextures = [];
     // this.selectorProgramIndex = this.webgl.getProgram(selectorVertexShader, selectorFragShader);
     _this.initProgram();
@@ -7463,6 +7469,10 @@ var GLObject = /*#__PURE__*/function (_DrawingObject) {
       //   gl.STATIC_DRAW,
       // );
       webgl.addTexture(id, data || src, loadColor, repeat, this.executeOnLoad.bind(this), force);
+      // addTexture took/holds a reference to this id; record it so
+      // resetTextureBuffer releases exactly what was acquired. (For a forced
+      // update the id is unchanged, so this is idempotent.)
+      this.acquiredBaseTextureId = id;
       this.state = webgl.textures[texture.id].state;
 
       // Register the optional mask textures (textureMap color mode). Each loads
@@ -7527,6 +7537,30 @@ var GLObject = /*#__PURE__*/function (_DrawingObject) {
       // }
     }
 
+    /**
+     * Adopt a base-texture reference to an already-registered texture (e.g. a
+     * shared font atlas uploaded by the Atlas, whose id this object renders with
+     * but does not upload itself).
+     *
+     * Releases any previously-held base reference first (so a font/atlas change
+     * rebalances correctly) and is idempotent when the id is unchanged. If the
+     * texture isn't registered yet, no reference is taken and acquiredBaseTextureId
+     * is cleared, so the later resetTextureBuffer release stays balanced (it only
+     * releases a reference that was actually acquired).
+     */
+  }, {
+    key: "setBaseTextureRef",
+    value: function setBaseTextureRef(id) {
+      if (this.acquiredBaseTextureId === id) {
+        return;
+      }
+      var webgl = this.webgl;
+      if (this.acquiredBaseTextureId != null) {
+        webgl.deleteTexture(this.acquiredBaseTextureId);
+      }
+      this.acquiredBaseTextureId = webgl.acquireTexture(id) ? id : null;
+    }
+
     // A texture map is a texture coords point that lines up with the texture
     // vertex point. So, if the vertex shape is rectangular, centered at the
     // origin and wants to incorporate the entire texture, then the map would
@@ -7707,14 +7741,15 @@ var GLObject = /*#__PURE__*/function (_DrawingObject) {
         maskTextures = this.maskTextures,
         webgl = this.webgl,
         gl = this.gl;
-      if (texture) {
-        if (deleteTexture && webgl.textures[texture.id] != null) {
-          webgl.deleteTexture(texture.id);
-        }
-        if (texture.buffer != null) {
-          gl.deleteBuffer(texture.buffer);
-          texture.buffer = null;
-        }
+      if (deleteTexture && this.acquiredBaseTextureId != null) {
+        // Release exactly the base reference this object acquired, so a failed
+        // acquire (e.g. an atlas not registered yet) can never over-release.
+        webgl.deleteTexture(this.acquiredBaseTextureId);
+        this.acquiredBaseTextureId = null;
+      }
+      if (texture && texture.buffer != null) {
+        gl.deleteBuffer(texture.buffer);
+        texture.buffer = null;
       }
       if (deleteTexture) {
         maskTextures.forEach(function (maskTexture) {
@@ -7994,6 +8029,9 @@ var GLObject = /*#__PURE__*/function (_DrawingObject) {
       gl.uniform1f(locations.u_z, this.z);
       gl.uniform4f(locations.u_color, color[0], color[1], color[2], color[3]);
       var texture = this.texture;
+      // Set when a textured object's base texture can't be bound, so we skip the
+      // draw rather than sampling a stale/wrong texture (see below).
+      var skipDraw = false;
       if (texture != null && targetTexture === false) {
         // Tell the position attribute how to get data out of positionBuffer (ARRAY_BUFFER)
         var texSize = 2; // 2 components per iteration
@@ -8007,27 +8045,49 @@ var GLObject = /*#__PURE__*/function (_DrawingObject) {
         gl.enableVertexAttribArray(locations.a_texcoord);
         gl.bindBuffer(gl.ARRAY_BUFFER, texture.buffer);
         gl.vertexAttribPointer(locations.a_texcoord, texSize, texType, texNormalize, texStride, texOffset);
-        gl.uniform1i(locations.u_use_texture, 1);
-        var index = webglInstance.textures[texture.id].index;
-        gl.uniform1i(locations.u_texture, index);
-
-        // Bind the mask textures (textureMap color mode), each to its own texture
-        // unit and precomputed u_mask{i} sampler. They reuse the a_texcoord /
-        // v_texcoord bound above, so no extra attribute is needed. Uses an indexed
-        // loop with precomputed uniform names to avoid per-frame allocation.
-        var maskTextures = this.maskTextures;
-        for (var i = 0; i < maskTextures.length; i += 1) {
-          var maskTexture = maskTextures[i];
-          var maskLocation = locations[maskTexture.uniformName];
-          var maskRegistered = webglInstance.textures[maskTexture.id];
-          if (maskLocation != null && maskRegistered != null) {
-            gl.uniform1i(maskLocation, maskRegistered.index);
+        // Assign content texture units for this draw from the shared pool. Unit 0
+        // is reserved for the target/selector framebuffer texture, so content
+        // starts at unit 1: the base texture, then each mask texture in turn.
+        // bindTextureToUnit only issues a bindTexture when the unit isn't already
+        // pointing at that texture, so runs of draws sharing a texture (e.g. text
+        // sharing a font atlas) issue no bind calls.
+        var textureUnit = 1;
+        if (webglInstance.bindTextureToUnit(texture.id, textureUnit)) {
+          gl.uniform1i(locations.u_use_texture, 1);
+          gl.uniform1i(locations.u_texture, textureUnit);
+          textureUnit += 1;
+
+          // Bind the mask textures (textureMap color mode), each to its own
+          // texture unit and precomputed u_mask{i} sampler. They reuse the
+          // a_texcoord / v_texcoord bound above, so no extra attribute is needed.
+          // Only assign the sampler if the bind succeeds — otherwise the uniform
+          // would default to sampler 0 (the reserved target texture) and recolor
+          // with garbage. Uses an indexed loop with precomputed uniform names to
+          // avoid per-frame allocation.
+          var maskTextures = this.maskTextures;
+          for (var i = 0; i < maskTextures.length; i += 1) {
+            var maskTexture = maskTextures[i];
+            var maskLocation = locations[maskTexture.uniformName];
+            if (maskLocation != null && webglInstance.bindTextureToUnit(maskTexture.id, textureUnit)) {
+              gl.uniform1i(maskLocation, textureUnit);
+              textureUnit += 1;
+            }
           }
+        } else {
+          // The base texture isn't available (e.g. a shared texture was deleted by
+          // another element's cleanup while this one still references it). The
+          // composed texture shaders sample u_texture unconditionally, so there is
+          // no safe in-shader fallback — skip this object's draw this frame rather
+          // than sampling whatever stale texture occupies the unit.
+          gl.uniform1i(locations.u_use_texture, 0);
+          skipDraw = true;
         }
       } else {
         gl.uniform1i(locations.u_use_texture, 0);
       }
-      gl.drawArrays(this.glPrimitive, 0, numDrawVertices);
+      if (!skipDraw) {
+        gl.drawArrays(this.glPrimitive, 0, numDrawVertices);
+      }
       if (texture) {
         gl.disableVertexAttribArray(locations.a_texcoord);
       }
@@ -52888,11 +52948,20 @@ var FigureElementPrimitiveGLText = /*#__PURE__*/function (_FigureElementPrimiti)
         scene: scene,
         font: this.font
       });
+      var textureID = this.atlas.font.getTextureID();
       if (this.drawingObject.texture == null) {
-        this.drawingObject.addTexture(this.atlas.font.getTextureID());
+        this.drawingObject.addTexture(textureID);
       } else {
-        this.drawingObject.texture.id = this.atlas.font.getTextureID();
-      }
+        this.drawingObject.texture.id = textureID;
+      }
+      // Take a webgl reference to the shared atlas texture so it survives other
+      // elements' cleanup. The Atlas registers/uploads the texture; this element
+      // only adopts its id (GLObject.addTexture above doesn't touch webgl), so
+      // without this its resetTextureBuffer release would be unbalanced and the
+      // first element's cleanup would free the atlas for the others.
+      // setBaseTextureRef releases any previously-held id (createAtlas re-runs on
+      // font changes) and is idempotent when the id is unchanged.
+      this.drawingObject.setBaseTextureRef(textureID);
       // console.log(this.atlas)
       this.setText(this.text);
       this.atlasNotificationsID = this.atlas.notifications.add('updated', this.loaded.bind(this));
@@ -66580,13 +66649,31 @@ function composeFragShader() {
     // alpha controls how strongly that region is recolored (0 = leave the base
     // color unchanged). With one mask this is exactly four mixes and one extra
     // texture fetch; each additional mask adds one fetch and four mixes.
+    //
+    // Masks are uploaded with premultiplied alpha, so a region only carries full
+    // weight where the mask pixel is opaque. Author each mask pixel as one of:
+    //   keep base : [0, 0, 0, 0] (transparent)
+    //   region 0  : [1, 0, 0, 1] -> u_tint0   (r channel)
+    //   region 1  : [0, 1, 0, 1] -> u_tint1   (g channel)
+    //   region 2  : [0, 0, 1, 1] -> u_tint2   (b channel)
+    //   region 3  : [0, 0, 0, 1] -> u_tint3   (a channel, opaque black)
+    // With every painted region opaque, the alpha channel is 1 across all of them,
+    // so it can't act as an independent region on its own. The a-channel mix below
+    // gates on (1 - r - g - b) so region 3 is exactly the opaque-black pixels - the
+    // ones not already claimed by an r/g/b region. Regions 0-2 support partial
+    // weight by lowering their channel value (e.g. [0.5, 0, 0, 1]); region 3 is
+    // full-weight only, with slight antialiasing softness at its borders.
     src += '  vec4 base = texture2D(u_texture, v_texcoord);\n';
     src += '  vec3 col = base.rgb;\n';
     for (var _m = 0; _m < numMasks; _m += 1) {
       src += "  vec4 mask".concat(_m, " = texture2D(u_mask").concat(_m, ", v_texcoord);\n");
       for (var c = 0; c < CHANNELS_PER_MASK; c += 1) {
         var _t = _m * CHANNELS_PER_MASK + c;
-        src += "  col = mix(col, u_tint".concat(_t, ".rgb, mask").concat(_m, ".").concat(channels[c], " * u_tint").concat(_t, ".a);\n");
+        if (channels[c] === 'a') {
+          src += "  col = mix(col, u_tint".concat(_t, ".rgb, mask").concat(_m, ".a * (1.0 - clamp(mask").concat(_m, ".r + mask").concat(_m, ".g + mask").concat(_m, ".b, 0.0, 1.0)) * u_tint").concat(_t, ".a);\n");
+        } else {
+          src += "  col = mix(col, u_tint".concat(_t, ".rgb, mask").concat(_m, ".").concat(channels[c], " * u_tint").concat(_t, ".a);\n");
+        }
       }
     }
     src += '  gl_FragColor = vec4(col, base.a * u_color.a);\n';
@@ -67165,6 +67252,20 @@ var WebGLInstance = /*#__PURE__*/function () {
     value:
     // locations: Object;
 
+    // Content texture units are a small shared pool reused across draws. Unit 0 is
+    // reserved for the target/selector framebuffer texture, so content starts at
+    // unit 1. boundUnits[u] tracks which texture id is currently bound to GL unit
+    // u, so bindTextureToUnit can skip redundant binds (bind-on-change).
+
+    // Monotonic source for texture handles (never reused, so deleting a texture
+    // can never cause a later texture to collide with a live one).
+
+    // gl.MAX_TEXTURE_IMAGE_UNITS (the fragment-shader sampler limit), queried once
+    // for a diagnostic warning. Matches the per-object mask guard in
+    // FigurePrimitives.gl().
+
+    // Set once the unit-budget warning has fired, so it isn't logged every frame.
+
     /*
       Add, or update a texture. If the texture already exists, then do nothing.
        A texture is referenced with a unique id, and defined by either a url (string), Image or html canvas element.
@@ -67180,45 +67281,52 @@ var WebGLInstance = /*#__PURE__*/function () {
       var onLoad = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : null;
       var force = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : false;
       /*
-        If the texture already exits, then return its index. If the texture is
-        still loading, then add the onLoad callback to the list of callbacks to
-        be called once the texture loads.
+        A texture id can be shared by multiple owners (e.g. several GLText elements
+        using the same font atlas, plus the Atlas itself). Each addTexture call
+        that isn't a forced content update acquires one reference; deleteTexture
+        releases one, and the GL texture is freed only when the last owner releases
+        it. This lets one element's cleanup() drop its reference without pulling a
+        still-shared texture out from under the survivors.
+         If the texture already exists and is still loading, the onLoad callback is
+        added to the list to be called once the texture loads.
       */
       if (!force && this.textures[id] != null) {
-        if (this.textures[id].state === 'loaded') {
-          if (onLoad != null) {
-            this.textures[id].onLoad.push(onLoad);
-          }
+        // Another owner (or the same owner re-acquiring) references an existing
+        // texture: take a reference and (re)register the load callback.
+        var existingTexture = this.textures[id];
+        existingTexture.refCount += 1;
+        if (onLoad != null) {
+          existingTexture.onLoad.push(onLoad);
+        }
+        if (existingTexture.state === 'loaded') {
           this.onLoad(id);
-          return this.textures[id].index;
         }
-        // Otherwise loading
+        return existingTexture.handle;
+      }
+      var gl = this.gl;
+      if (this.textures[id] != null) {
+        // Forced content update of an existing texture: keep its identity AND
+        // reference count so other owners survive the update. setTextureData
+        // (below) frees and replaces the old glTexture, so the entry — including
+        // its glTexture pointer — is preserved here rather than recreated.
+        // Append (don't replace) onLoad so pending callbacks other owners
+        // registered while the texture was still loading aren't silently dropped.
+        this.textures[id].state = 'loading';
         if (onLoad != null) {
           this.textures[id].onLoad.push(onLoad);
         }
-        return this.textures[id].index;
-        // removed by dead control flow
-
-      }
-      var index = 0;
-      if (this.textures[id] != null) {
-        index = this.textures[id].index;
       } else {
-        index = Object.keys(this.textures).length + 1;
+        // Brand new texture: the first owner holds the only reference.
+        this.textures[id] = {
+          id: id,
+          state: 'loading',
+          onLoad: onLoad != null ? [onLoad] : [],
+          handle: this.nextTextureHandle,
+          refCount: 1
+        };
+        this.nextTextureHandle += 1;
       }
-      // If a texture already exists, then unload it
-      this.deleteTexture(id);
-      var gl = this.gl;
-      this.textures[id] = {
-        id: id,
-        state: 'loading',
-        onLoad: [],
-        index: index
-      };
       var texture = this.textures[id];
-      if (onLoad != null) {
-        texture.onLoad.push(onLoad);
-      }
       // If the data is a url string, then load the data into an image
       if (typeof data === 'string') {
         this.setTextureData(id, loadColor);
@@ -67237,7 +67345,7 @@ var WebGLInstance = /*#__PURE__*/function () {
         this.onLoad(id);
         texture.state = 'loaded';
       }
-      return this.textures[id].index;
+      return this.textures[id].handle;
     }
   }, {
     key: "getAtlas",
@@ -67273,6 +67381,27 @@ var WebGLInstance = /*#__PURE__*/function () {
         throw errors[0];
       }
     }
+
+    // Take an additional reference to an already-registered texture, without
+    // re-uploading it or touching its load callbacks. Used when an element adopts
+    // a texture another owner created and uploaded (e.g. a GLText element sharing
+    // a font atlas registered by the Atlas). Returns false if the texture isn't
+    // registered yet, in which case no reference was taken. Release with
+    // deleteTexture.
+  }, {
+    key: "acquireTexture",
+    value: function acquireTexture(id) {
+      var texture = this.textures[id];
+      if (texture == null) {
+        return false;
+      }
+      texture.refCount += 1;
+      return true;
+    }
+
+    // Release one reference to a texture. The GL texture is freed only once the
+    // last owner releases it, so one element's cleanup can't delete a texture
+    // another element still shares (see addTexture for the rationale).
   }, {
     key: "deleteTexture",
     value: function deleteTexture(id) {
@@ -67280,13 +67409,27 @@ var WebGLInstance = /*#__PURE__*/function () {
       if (texture == null) {
         return;
       }
-      var gl = this.gl;
+      texture.refCount -= 1;
+      if (texture.refCount <= 0) {
+        this.freeTexture(id);
+      }
+    }
 
-      // If texture exists, then delete it
+    // Unconditionally free a texture regardless of reference count. Used for
+    // teardown (cleanup), where every owner is going away at once.
+  }, {
+    key: "freeTexture",
+    value: function freeTexture(id) {
+      var texture = this.textures[id];
+      if (texture == null) {
+        return;
+      }
+      var gl = this.gl;
+      // gl.deleteTexture unbinds it from any unit it was bound to, so we just drop
+      // the stale cache entries.
       if (texture.glTexture != null) {
-        gl.activeTexture(gl.TEXTURE0 + texture.index);
-        gl.bindTexture(gl.TEXTURE_2D, null);
         gl.deleteTexture(texture.glTexture);
+        this.clearBoundUnits(id);
       }
       this.cancel(id);
       delete this.textures[id];
@@ -67298,6 +67441,53 @@ var WebGLInstance = /*#__PURE__*/function () {
       Object.keys(this.textures).forEach(function (id) {
         _this3.textures[id].glTexture = null;
       });
+      // The new context starts with nothing bound, so the bind cache is stale.
+      this.boundUnits = [];
+    }
+
+    // Drop any working-unit cache entries that point at this texture id, so a
+    // future draw re-binds rather than trusting a stale/deleted glTexture.
+  }, {
+    key: "clearBoundUnits",
+    value: function clearBoundUnits(id) {
+      for (var u = 0; u < this.boundUnits.length; u += 1) {
+        if (this.boundUnits[u] === id) {
+          this.boundUnits[u] = null;
+        }
+      }
+    }
+
+    /*
+      Bind a registered texture to a content texture unit for the current draw.
+       Content units are a small shared pool (unit 0 is reserved for the
+      target/selector framebuffer texture). bindTexture is only issued when the
+      unit is not already pointing at this texture, so runs of draws that share a
+      texture (e.g. text sharing a font atlas) issue zero bind calls.
+    */
+  }, {
+    key: "bindTextureToUnit",
+    value: function bindTextureToUnit(id, unit) {
+      var texture = this.textures[id];
+      if (texture == null || texture.glTexture == null) {
+        return false;
+      }
+      if (unit >= this.maxTextureUnits) {
+        // Out of unit budget: warn once (not every frame) and don't issue an
+        // out-of-range bind. The caller treats false as "not bound".
+        if (!this.warnedUnitOverflow) {
+          (0,_tools_tools__WEBPACK_IMPORTED_MODULE_2__.Console)("FigureOne WebGL warning: texture unit ".concat(unit, " exceeds this device's ") + "MAX_TEXTURE_IMAGE_UNITS (".concat(this.maxTextureUnits, "). Reduce the ") + 'number of simultaneous textures/masks.');
+          this.warnedUnitOverflow = true;
+        }
+        return false;
+      }
+      if (this.boundUnits[unit] === id) {
+        return true;
+      }
+      var gl = this.gl;
+      gl.activeTexture(gl.TEXTURE0 + unit);
+      gl.bindTexture(gl.TEXTURE_2D, texture.glTexture);
+      this.boundUnits[unit] = id;
+      return true;
     }
   }, {
     key: "cleanup",
@@ -67311,9 +67501,10 @@ var WebGLInstance = /*#__PURE__*/function () {
         }
       });
       this.programs = [];
-      // Delete all textures
+      // Free all textures outright, ignoring reference counts — every owner is
+      // going away in this teardown.
       Object.keys(this.textures).forEach(function (id) {
-        _this4.deleteTexture(id);
+        _this4.freeTexture(id);
       });
       this.textures = {};
       // Clean up atlases
@@ -67334,20 +67525,27 @@ var WebGLInstance = /*#__PURE__*/function () {
         return (value & value - 1) === 0;
       }
       var texture = this.textures[id];
-      var index = texture.index;
       var gl = this.gl;
+      // Upload happens on the first content unit as scratch. Any cache entry for
+      // this id refers to the old glTexture we're about to replace, so invalidate
+      // them all before binding the new one.
+      var uploadUnit = 1;
+      this.clearBoundUnits(id);
 
       // If texture exists, then delete it
       if (texture.glTexture != null) {
-        gl.activeTexture(gl.TEXTURE0 + index);
+        gl.activeTexture(gl.TEXTURE0 + uploadUnit);
         gl.bindTexture(gl.TEXTURE_2D, null);
         gl.deleteTexture(texture.glTexture);
       }
       // Create a texture
       var glTexture = gl.createTexture();
       texture.glTexture = glTexture;
-      gl.activeTexture(gl.TEXTURE0 + index);
+      gl.activeTexture(gl.TEXTURE0 + uploadUnit);
       gl.bindTexture(gl.TEXTURE_2D, glTexture);
+      // The new glTexture is now bound to the upload unit; record it so a draw
+      // that needs it on this unit can skip a redundant bind.
+      this.boundUnits[uploadUnit] = id;
       gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, 1);
 
       // If image is a color, then create s ingle pixel image of that color
@@ -67411,7 +67609,7 @@ var WebGLInstance = /*#__PURE__*/function () {
     value: function onLoad(id) {
       var _this5 = this;
       this.textures[id].onLoad.forEach(function (f) {
-        return _this5.fnMap.exec(f, true, _this5.textures[id].index);
+        return _this5.fnMap.exec(f, true, _this5.textures[id].handle);
       });
       this.textures[id].onLoad = [];
     }
@@ -67420,7 +67618,7 @@ var WebGLInstance = /*#__PURE__*/function () {
     value: function cancel(id) {
       var _this6 = this;
       this.textures[id].onLoad.forEach(function (f) {
-        return _this6.fnMap.exec(f, false, _this6.textures[id].index);
+        return _this6.fnMap.exec(f, false, _this6.textures[id].handle);
       });
       this.textures[id].onLoad = [];
     }
@@ -67485,6 +67683,11 @@ var WebGLInstance = /*#__PURE__*/function () {
     value: function init(gl) {
       this.gl = gl;
       this.textures = {};
+      this.boundUnits = [];
+      this.nextTextureHandle = 1;
+      this.warnedUnitOverflow = false;
+      var maxUnits = gl.getParameter ? gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS) : 0;
+      this.maxTextureUnits = maxUnits || 8;
       this.programs = [];
       this.targetTexture = null;
       this.lastUsedProgram = null;
@@ -82098,8 +82301,8 @@ var tools = {
  */
 
 var Fig = {
-  version: "1.8.0",
-  gitHash: "4b64a8de5",
+  version: "1.9.1",
+  gitHash: "0adca1678",
   tools: tools,
   Figure: _js_figure_Figure__WEBPACK_IMPORTED_MODULE_5__["default"],
   Recorder: _js_figure_Recorder_Recorder__WEBPACK_IMPORTED_MODULE_7__.Recorder,

package/llms-full.txt

@@ -115,6 +115,8 @@ Path to figure element(s) within a collection. Supports multiple formats:
 | loadColor | TypeColor | `[0, 0, 1, 0.5]` | Color while loading |
 | onLoad | () => void | | Callback after load |
 
+A `texture` on the `gl` primitive can be recolored by region with one or more masks — see OBJ_TextureMask under OBJ_GenericGL.
+
 ### OBJ_FigurePrimitive (base for all primitives)
 
 | Property | Type | Default | Description |
@@ -365,12 +367,47 @@ Extends OBJ_Generic (without drawType).
 | attributes | OBJ_GLAttribute[] | | Shader attributes |
 | uniforms | OBJ_GLUniform[] | | Shader uniforms |
 | texture | OBJ_Texture | | Texture |
+| mask | OBJ_TextureMask | | Single mask to recolor regions of `texture` |
+| masks | OBJ_TextureMask[] | | Multiple masks (each adds 4 recolorable regions) |
+| tints | (TypeColor \| null)[] | | Recolor per region; mask `m` uses `tints[4m]`…`tints[4m+3]` for its r,g,b,a channels (`null` = leave region unchanged) |
 | dimension | `2` \| `3` | `2` | Coordinate dimensions |
 | light | `'directional'` \| `'point'` \| null | null | Lighting |
 | vertices | number[] \| object | | Vertex data |
 | colors | number[] \| object | | Per-vertex colors |
 | normals | number[] \| object | | Normal vectors |
 
+A texture can be recolored by region using one or more masks. A mask shares the base texture's coordinates (same dimensions, aligned to the base image); each of its r, g, b, a channels marks a region. Mask `m` is recolored by `tints[4m]` (r), `tints[4m + 1]` (g), `tints[4m + 2]` (b), `tints[4m + 3]` (a); unmasked pixels keep the base texture's color. A single mask costs one extra texture fetch and four mixes; each additional mask adds one fetch and four mixes.
+
+### OBJ_TextureMask
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| src | string | | URL of the mask image |
+| loadColor | TypeColor | `[0, 0, 0, 0]` | Color shown while the mask loads (transparent = nothing recolored until loaded) |
+
+```js
+// Recolor three regions of a texture with one mask. The mask image's red,
+// green and blue channels mark the regions tinted by tints 0, 1 and 2.
+figure.add({
+  make: 'gl',
+  vertices: [-0.8, -0.8, 0.8, -0.8, -0.8, 0.8, 0.8, -0.8, 0.8, 0.8, -0.8, 0.8],
+  texture: { src: './image.png', coords: [0, 0, 1, 0, 0, 1, 1, 0, 1, 1, 0, 1] },
+  mask: { src: './mask.png' },
+  tints: [[1, 0, 0, 1], [0, 0.6, 0, 1], [0, 0, 1, 1]],
+});
+
+// Two masks: mask 0 uses tints 0-3, mask 1 uses tints 4-7.
+figure.add({
+  make: 'gl',
+  // ...vertices, texture...
+  masks: [{ src: './mask.png' }, { src: './mask1.png' }],
+  tints: [
+    [1, 0, 0, 1], [0, 0.6, 0, 1], [0, 0, 1, 1], null, // mask 0
+    [0.6, 0, 0.8, 1],                                 // mask 1
+  ],
+});
+```
+
 ### OBJ_Morph (`make: 'morph'`)
 
 Morphable shape with multiple point arrays that can be animated between.

package/llms.txt

@@ -97,6 +97,16 @@ figure.add({
   make: 'rectangle', width: 1.8, height: 1.2,
   texture: { src: 'image.jpg', mapTo: [-0.9, -0.6, 1.8, 1.2] },
 });
+
+// Recolor regions of a texture with masks (gl primitive). Each mask's r,g,b,a
+// channels mark regions; mask m is tinted by tints[4m]..tints[4m+3].
+figure.add({
+  make: 'gl',
+  vertices: [-0.8, -0.8, 0.8, -0.8, -0.8, 0.8, 0.8, -0.8, 0.8, 0.8, -0.8, 0.8],
+  texture: { src: 'image.png', coords: [0, 0, 1, 0, 0, 1, 1, 0, 1, 1, 0, 1] },
+  masks: [{ src: 'mask.png' }, { src: 'mask1.png' }],
+  tints: [[1, 0, 0, 1], [0, 0.6, 0, 1], [0, 0, 1, 1], null, [0.6, 0, 0.8, 1]],
+});
 ```
 
 ### Element Properties

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figureone",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Draw, animate and interact with shapes, text, plots and equations in Javascript. Create interactive slide shows, and interactive videos.",
   "main": "index.js",
   "types": "types/index.d.ts",

package/types/js/figure/DrawingObjects/GLObject/GLObject.d.ts

@@ -76,6 +76,7 @@ declare class GLObject extends DrawingObject {
     fragmentShader: TypeFragmentShader;
     selectorVertexShader: TypeVertexShader;
     selectorFragmentShader: TypeFragmentShader;
+    acquiredBaseTextureId: string | null;
     constructor(webgl: WebGLInstance, vertexShader?: TypeVertexShader, fragmentShader?: TypeFragmentShader, selectorVertexShader?: TypeVertexShader, selectorFragShader?: TypeFragmentShader);
     init(webgl: WebGLInstance): void;
     initProgram(): void;
@@ -105,6 +106,18 @@ declare class GLObject extends DrawingObject {
     addMaskTexture(location?: string, loadColor?: TypeColor): void;
     updateTexture(data: HTMLImageElement): void;
     initTexture(force?: boolean): void;
+    /**
+     * Adopt a base-texture reference to an already-registered texture (e.g. a
+     * shared font atlas uploaded by the Atlas, whose id this object renders with
+     * but does not upload itself).
+     *
+     * Releases any previously-held base reference first (so a font/atlas change
+     * rebalances correctly) and is idempotent when the id is unchanged. If the
+     * texture isn't registered yet, no reference is taken and acquiredBaseTextureId
+     * is cleared, so the later resetTextureBuffer release stays balanced (it only
+     * releases a reference that was actually acquired).
+     */
+    setBaseTextureRef(id: string): void;
     createTextureMap(xMinGL?: number, xMaxGL?: number, yMinGL?: number, yMaxGL?: number, xMinTex?: number, xMaxTex?: number, yMinTex?: number, yMaxTex?: number): void;
     addVertices(vertices: Array<number>, dimension?: 2 | 3, usage?: TypeGLBufferUsage): void;
     addVertices3(vertices: Array<number>, usage?: TypeGLBufferUsage): void;