figureone 1.7.1 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figureone",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "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

@@ -42,6 +42,12 @@ declare class GLObject extends DrawingObject {
         loadColor: TypeColor;
         [key: string]: any;
     } | null;
+    maskTextures: Array<{
+        id: string;
+        src: string;
+        loadColor: TypeColor;
+        uniformName: string;
+    }>;
     attributes: {
         [attributeName: string]: {
             buffer: WebGLBuffer | null;
@@ -70,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;
@@ -85,8 +92,32 @@ declare class GLObject extends DrawingObject {
      * Buffer a texture for the shape to be painted with.
      */
     addTexture(location: string, mapFrom?: Rect, mapTo?: Rect, mapToBuffer?: string, points?: Array<number>, repeat?: boolean, onLoad?: null | (() => void), loadColor?: TypeColor): void;
+    /**
+     * Buffer a mask texture for the `textureMap` color mode. Each call appends a
+     * mask, bound to the next u_mask{i} sampler. Masks share the base texture's
+     * coordinates, so only a source and load color are needed. The default load
+     * color is fully transparent so that, until the mask loads, no region is
+     * recolored and the base texture shows through unchanged.
+     *
+     * An empty `location` registers a transparent placeholder, which keeps the
+     * u_mask{i} indexing aligned with the tint blocks when a caller supplies an
+     * invalid/missing mask in a positional list (the slot becomes a no-op).
+     */
+    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;

package/types/js/figure/FigurePrimitives/FigurePrimitiveTypes.d.ts

@@ -224,6 +224,30 @@ export type OBJ_Texture = {
     repeat?: boolean;
     onLoad?: () => void;
 };
+/**
+ * Mask texture used by the `gl` primitive to recolor regions of a base
+ * `texture`. A mask shares the base texture's coordinates, so it must be the
+ * same dimensions and aligned with the base image. Each of a mask's `r`, `g`,
+ * `b` and `a` channels selects a region recolored by an entry of the
+ * primitive's `tints` option.
+ *
+ * Supply a single mask with `mask`, or several with `masks` (an array). Mask `m`
+ * (0-based) uses `tints[4m]`, `tints[4m + 1]`, `tints[4m + 2]` and
+ * `tints[4m + 3]` for its r, g, b and a channels - so each mask adds four
+ * recolorable regions. A single mask costs one extra texture fetch and four
+ * mixes; each additional mask adds one fetch and four mixes.
+ *
+ * @property {string} [src] url of the mask image
+ * @property {TypeColor} [loadColor] color shown while the mask loads
+ * (`[0, 0, 0, 0]` - fully transparent, so nothing is recolored until the mask
+ * has loaded)
+ * @interface
+ * @group Shaders
+ */
+export type OBJ_TextureMask = {
+    src?: string;
+    loadColor?: TypeColor;
+};
 /**
  * Pulse options object
  *
@@ -443,6 +467,12 @@ export type TypeText = 'gl' | '2d';
  * {@link OBJ_FragmentShader} for names of attributes and uniforms used in the
  * shaders, and when they are used.
  *
+ * A texture can be recolored by region using one or more masks (see the mask
+ * examples below):
+ *
+ * ![](./apiassets/gl_mask.png)
+ * ![](./apiassets/gl_mask2.png)
+ *
  * @property {TypeGLPrimitive} [glPrimitive]
  * @property {TypeVertexShader} [vertexShader]
  * @property {TypeFragmentShader} [fragmentShader]
@@ -585,6 +615,46 @@ export type TypeText = 'gl' | '2d';
  *     },
  *   ],
  * });
+ *
+ * @example
+ * // Recolor regions of a texture with a mask. The mask image marks regions to
+ * // recolor in its red, green, blue and alpha channels, which map to tints 0,
+ * // 1, 2 and 3. Unmasked pixels keep the base texture's color.
+ * const p = figure.add({
+ *   make: 'gl',
+ *   vertices: [-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5],
+ *   numVertices: 6,
+ *   texture: {
+ *     src: './base.png',
+ *     coords: [0, 0, 1, 0, 0, 1, 1, 0, 1, 1, 0, 1],
+ *     loadColor: [0, 0, 0, 0],
+ *   },
+ *   mask: { src: './mask.png' },
+ *   tints: [[1, 0, 0, 1], [0, 0, 1, 1]],
+ * });
+ * // Change the first region's color at runtime
+ * p.custom.setTint(0, [0, 1, 0, 1]);
+ *
+ * @example
+ * // Recolor with two masks. Each mask adds four regions (its r, g, b, a
+ * // channels), so mask 0 uses tints 0-3 and mask 1 uses tints 4-7. Here mask 0
+ * // recolors three circles (tints 0, 1, 2) and mask 1 recolors a bar (tint 4).
+ * figure.add({
+ *   make: 'gl',
+ *   vertices: [-0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, 0.5, 0.5, -0.5, 0.5],
+ *   numVertices: 6,
+ *   texture: {
+ *     src: './base.png',
+ *     coords: [0, 0, 1, 0, 0, 1, 1, 0, 1, 1, 0, 1],
+ *     loadColor: [0, 0, 0, 0],
+ *   },
+ *   masks: [{ src: './mask.png' }, { src: './mask1.png' }],
+ *   tints: [
+ *     [1, 0, 0, 1], [0, 0.6, 0, 1], [0, 0, 1, 1], null, // mask 0: circles
+ *     [0.6, 0, 0.8, 1],                                 // mask 1: bar
+ *   ],
+ * });
+ *
  * @interface
  * @group Shaders
  */
@@ -595,6 +665,9 @@ export type OBJ_GenericGL = {
     attributes?: Array<OBJ_GLAttribute>;
     uniforms?: Array<OBJ_GLUniform>;
     texture?: OBJ_Texture;
+    mask?: OBJ_TextureMask;
+    masks?: Array<OBJ_TextureMask>;
+    tints?: Array<TypeColor | null>;
     dimension?: 2 | 3;
     light?: 'directional' | 'point' | null;
     vertices?: OBJ_GLVertexBuffer;

package/types/js/figure/webgl/shaders.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Number of recolorable regions a single mask texture provides in the
+ * `textureMap` color mode - one per channel (r, g, b, a). N masks therefore
+ * define `CHANNELS_PER_MASK * N` tints.
+ * @group Shaders
+ */
+export declare const CHANNELS_PER_MASK = 4;
 /**
  * Options used to compose vertex shader source code.
  *
@@ -53,14 +60,14 @@
  *    to fragment shader used when `light = 'point'`
  *
  * @property {2 | 3} [dimension] (`2`)
- * @property {'vertex' | 'uniform' | 'texture'} [color] (`uniform`)
+ * @property {'vertex' | 'uniform' | 'texture' | 'textureMap'} [color] (`uniform`)
  * @property {'point' | 'directional' | null} [light] (`null`)
  * @interface
  * @group Shaders
  */
 export type OBJ_VertexShader = {
     light?: 'point' | 'directional' | null;
-    color?: 'vertex' | 'uniform' | 'texture';
+    color?: 'vertex' | 'uniform' | 'texture' | 'textureMap';
     dimension?: 2 | 3;
 };
 /**
@@ -93,7 +100,16 @@ export type TypeVertexShader = string | {
  * - `vec4 u_color`: global color for all vertices used all times. When
  *   `color = 'texture'` or `color = 'vertex'`, only the alpha channel of
  *   `u_color` is used.
- * - `sampler2D u_texture`: texture used when `color = 'texture'`.
+ * - `sampler2D u_texture`: texture used when `color = 'texture'`,
+ *   `color = 'textureAlpha'` or `color = 'textureMap'`.
+ * - `sampler2D u_mask0`, `u_mask1`, ...: mask textures used when
+ *   `color = 'textureMap'` (one per mask, set by the `masks` count). Each mask's
+ *   `r`, `g`, `b` and `a` channels select four regions of `u_texture` to
+ *   recolor. Mask `m`'s four channels map to tints `u_tint{4m+0..3}`.
+ * - `vec4 u_tint0`, `u_tint1`, ...: region tint colors used when
+ *   `color = 'textureMap'` (four per mask). The `rgb` channels are the tint
+ *   color and the `a` channel is the tint strength (`0` leaves the base texture
+ *   unchanged).
  * - `vec3 u_directionalLight`: world space position of directional light
  *   source used when `light = 'directional'`
  * - `float u_ambientLight`: ambient light used when `light = 'directional'` or
@@ -113,14 +129,15 @@ export type TypeVertexShader = string | {
  *    from vertex shader used when `light = 'point'`
  *
  * @property {2 | 3} [dimension] (`2`)
- * @property {'vertex' | 'uniform' | 'texture'} [color] (`uniform`)
+ * @property {'vertex' | 'uniform' | 'texture' | 'textureMap'} [color] (`uniform`)
  * @property {'point' | 'directional' | null} [light] (`null`)
  * @interface
  * @group Shaders
  */
 export type OBJ_FragmentShader = {
     light?: 'point' | 'directional' | null;
-    color?: 'vertex' | 'uniform' | 'texture';
+    color?: 'vertex' | 'uniform' | 'texture' | 'textureMap';
+    masks?: number;
 };
 /**
  * A fragment shader can be defined with either:

package/types/js/figure/webgl/webgl.d.ts

@@ -12,11 +12,16 @@ declare class WebGLInstance {
     textures: {
         [name: string]: {
             glTexture: WebGLTexture;
-            index: number;
+            handle: number;
+            refCount: number;
             state: 'loading' | 'loaded';
             onLoad: Array<((b: boolean, n: number) => void) | string>;
         };
     };
+    boundUnits: Array<string | null>;
+    nextTextureHandle: number;
+    maxTextureUnits: number;
+    warnedUnitOverflow: boolean;
     atlases: {
         [atlasId: string]: Atlas;
     };
@@ -39,8 +44,12 @@ declare class WebGLInstance {
     addTexture(id: string, data: string | HTMLImageElement | HTMLCanvasElement, loadColor?: TypeColor, repeat?: boolean, onLoad?: null | string | ((b: boolean, n: number) => void), force?: boolean): number;
     getAtlas(options: OBJ_Atlas): Atlas;
     recreateAtlases(): void;
+    acquireTexture(id: string): boolean;
     deleteTexture(id: string): void;
+    freeTexture(id: string): void;
     contextLost(): void;
+    clearBoundUnits(id: string): void;
+    bindTextureToUnit(id: string, unit: number): boolean;
     cleanup(): void;
     setTextureData(id: string, image: Record<string, any> | TypeColor, // image data
     repeat?: boolean): boolean;