figureone 1.7.1 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figureone",
-  "version": "1.7.1",
+  "version": "1.8.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;
@@ -85,6 +91,18 @@ 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;
     createTextureMap(xMinGL?: number, xMaxGL?: number, yMinGL?: number, yMaxGL?: number, xMinTex?: number, xMaxTex?: number, yMinTex?: number, yMaxTex?: number): 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: