feat: Bring back kernel.immutable and kernel.setImmutable() with defaults to false

  Along with tests and documentation on which versions are affected.  Sorry for the inconvenience!
feat: Add more advanced-typescript.ts
fix: Alter documentation mentioning v2
fix: Example of fluid.html, to use `immutable`

Author: robertleeplummerjr

README.md

@@ -70,9 +70,12 @@ const multiplyMatrix = gpu.createKernel(function(a: number[][], b: number[][]) {
 const c = multiplyMatrix(a, b) as number[][];
 ```
 
+[Click here](/examples) for more typescript examples.
+
 # Table of Contents
 
-NOTE: documentation is slightly out of date for the upcoming release of v2.  We will fix it!  In the mean time, if you'd like to assist (PLEASE) let us know.
+Notice documentation is off?  We do try our hardest, but if you find something,
+  [please bring it to our attention](https://github.com/gpujs/gpu.js/issues), or _[become a contributor](#contributors)_!
 
 * [Demos](#demos)
 * [Installation](#installation)
@@ -91,7 +94,7 @@ NOTE: documentation is slightly out of date for the upcoming release of v2.  We
 * [Loops](#loops)
 * [Pipelining](#pipelining)
   * [Cloning Textures](#cloning-textures-new-in-v2)
-  * [Cleanup pipeline texture memory](#cleanup-pipeline-texture-memory-new-in-v2)
+  * [Cleanup pipeline texture memory](#cleanup-pipeline-texture-memory-new-in-v24)
 * [Offscreen Canvas](#offscreen-canvas)
 * [Cleanup](#cleanup)
 * [Flattened typed array support](#flattened-typed-array-support)
@@ -235,7 +238,8 @@ Settings are an object used to create a `kernel` or `kernelMap`.  Example: `gpu.
   * VERY IMPORTANT! - Use this to add special native functions to your environment when you need specific functionality is needed.
 * `injectedNative` or `kernel.setInjectedNative(string)` **New in V2!**: string, defined as: `{ functionName: functionSource }`.  This is for injecting native code before translated kernel functions.
 * `subKernels` or `kernel.setSubKernels(array)`: array, generally inherited from `GPU` instance.
-* ~~`immutable` or `kernel.setImmutable(boolean)`: boolean, default = `false`~~ Deprecated
+* `immutable` or `kernel.setImmutable(boolean)`: boolean, default = `false`
+  * VERY IMPORTANT! - This was removed in v2.4.0 - v2.7.0, and brought back in v2.8.0 [by popular demand](https://github.com/gpujs/gpu.js/issues/572), please upgrade to get the feature
 * `strictIntegers` or `kernel.setStrictIntegers(boolean)`: boolean, default = `false` - allows undefined argumentTypes and function return values to use strict integer declarations.
 * `useLegacyEncoder` or `kernel.setUseLegacyEncoder(boolean)`: boolean, default `false` - more info [here](https://github.com/gpujs/gpu.js/wiki/Encoder-details).
 * `tactic` or `kernel.setTactic('speed' | 'balanced' | 'precision')` **New in V2!**: Set the kernel's tactic for compilation.  Allows for compilation to better fit how GPU.js is being used (internally uses `lowp` for 'speed', `mediump` for 'balanced', and `highp` for 'precision').  Default is lowest resolution supported for output.
@@ -845,13 +849,15 @@ const result2 = kernel2(result1);
 ```
 
 ### Cleanup pipeline texture memory **New in V2.4!**
-Handling minimal amounts of GPU memory is handled internally, but a good practice is to clean up memory you no longer need.
+When using `kernel.immutable = true` recycling GPU memory is handled internally, but a good practice is to clean up memory you no longer need it.
 Cleanup kernel outputs by using `texture.delete()` to keep GPU memory as small as possible.
 
 NOTE: Internally textures will only release from memory if there are no references to them.
-When using pipeline mode on a kernel K the output for each call will be a newly allocated texture T.
-If, after getting texture T as an output, T.delete() is called, the next call to K will reuse T as its output texture.
+When using pipeline mode on a kernel `K` the output for each call will be a newly allocated texture `T`.
+If, after getting texture `T` as an output, `T.delete()` is called, the next call to K will reuse `T` as its output texture.
 
+Alternatively, if you'd like to clear out a `texture` and yet keep it in memory, you may use `texture.clear()`, which
+will cause the `texture` to persist in memory, but its internal values to become all zeros.
 
 ## Offscreen Canvas
 GPU.js supports offscreen canvas where available.  Here is an example of how to use it with two files, `gpu-worker.js`, and `index.js`:
@@ -1114,6 +1120,8 @@ const result = kernelMap();
 console.log(result as number[][][]);
 ```
 
+[Click here](/examples) for more typescript examples.
+
 ## Destructured Assignments **New in V2!**
 Destructured Objects and Arrays work in GPU.js.
 * Object destructuring

dist/gpu-browser-core.js

@@ -4,8 +4,8 @@
  *
  * GPU Accelerated JavaScript
  *
- * @version 2.7.0
- * @date Tue Mar 10 2020 15:46:55 GMT-0400 (Eastern Daylight Time)
+ * @version 2.8.0
+ * @date Wed Mar 11 2020 07:33:36 GMT-0400 (Eastern Daylight Time)
  *
  * @license MIT
  * The MIT License
@@ -5095,7 +5095,7 @@ class GLKernel extends Kernel {
   }
 
   renderTexture() {
-    return this.texture.clone();
+    return this.immutable ? this.texture.clone() : this.texture;
   }
   readPackedPixelsToUint8Array() {
     if (this.precision !== 'unsigned') throw new Error('Requires this.precision to be "unsigned"');
@@ -5150,8 +5150,14 @@ class GLKernel extends Kernel {
     const result = {
       result: this.renderOutput(),
     };
-    for (let i = 0; i < this.subKernels.length; i++) {
-      result[this.subKernels[i].property] = this.mappedTextures[i].clone();
+    if (this.immutable) {
+      for (let i = 0; i < this.subKernels.length; i++) {
+        result[this.subKernels[i].property] = this.mappedTextures[i].clone();
+      }
+    } else {
+      for (let i = 0; i < this.subKernels.length; i++) {
+        result[this.subKernels[i].property] = this.mappedTextures[i];
+      }
     }
     return result;
   }
@@ -5259,6 +5265,7 @@ class GLKernel extends Kernel {
   }
 
   updateTextureArgumentRefs(kernelValue, arg) {
+    if (!this.immutable) return;
     if (this.texture.texture === arg.texture) {
       const { prevArg } = kernelValue;
       if (prevArg) {
@@ -6317,7 +6324,7 @@ class Kernel {
   }
 
   setImmutable(flag) {
-    utils.warnDeprecated('method', 'setImmutable');
+    this.immutable = flag;
     return this;
   }
 
@@ -10260,7 +10267,7 @@ class WebGLKernel extends GLKernel {
         gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
         this._setupOutputTexture();
         gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
-        return this.texture.clone();
+        return this.immutable ? this.texture.clone() : this.texture;
       }
       gl.bindRenderbuffer(gl.RENDERBUFFER, null);
       gl.bindFramebuffer(gl.FRAMEBUFFER, null);

dist/gpu-browser-core.min.js

@@ -4,8 +4,8 @@
  *
  * GPU Accelerated JavaScript
  *
- * @version 2.7.0
- * @date Tue Mar 10 2020 15:46:55 GMT-0400 (Eastern Daylight Time)
+ * @version 2.8.0
+ * @date Wed Mar 11 2020 07:33:35 GMT-0400 (Eastern Daylight Time)
  *
  * @license MIT
  * The MIT License
@@ -9548,7 +9548,7 @@ class GLKernel extends Kernel {
   }
 
   renderTexture() {
-    return this.texture.clone();
+    return this.immutable ? this.texture.clone() : this.texture;
   }
   readPackedPixelsToUint8Array() {
     if (this.precision !== 'unsigned') throw new Error('Requires this.precision to be "unsigned"');
@@ -9603,8 +9603,14 @@ class GLKernel extends Kernel {
     const result = {
       result: this.renderOutput(),
     };
-    for (let i = 0; i < this.subKernels.length; i++) {
-      result[this.subKernels[i].property] = this.mappedTextures[i].clone();
+    if (this.immutable) {
+      for (let i = 0; i < this.subKernels.length; i++) {
+        result[this.subKernels[i].property] = this.mappedTextures[i].clone();
+      }
+    } else {
+      for (let i = 0; i < this.subKernels.length; i++) {
+        result[this.subKernels[i].property] = this.mappedTextures[i];
+      }
     }
     return result;
   }
@@ -9712,6 +9718,7 @@ class GLKernel extends Kernel {
   }
 
   updateTextureArgumentRefs(kernelValue, arg) {
+    if (!this.immutable) return;
     if (this.texture.texture === arg.texture) {
       const { prevArg } = kernelValue;
       if (prevArg) {
@@ -10770,7 +10777,7 @@ class Kernel {
   }
 
   setImmutable(flag) {
-    utils.warnDeprecated('method', 'setImmutable');
+    this.immutable = flag;
     return this;
   }
 
@@ -14713,7 +14720,7 @@ class WebGLKernel extends GLKernel {
         gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
         this._setupOutputTexture();
         gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
-        return this.texture.clone();
+        return this.immutable ? this.texture.clone() : this.texture;
       }
       gl.bindRenderbuffer(gl.RENDERBUFFER, null);
       gl.bindFramebuffer(gl.FRAMEBUFFER, null);

dist/gpu-browser.js

@@ -0,0 +1,55 @@
+/**
+ * This is an arbitrary example (overly complex with types for overly simplified kernel) to show type inheritance
+ * throughout the kernel's usage.
+ *
+ * The whole idea here is that you can define custom:
+ * - `constants`
+ * - `this` context
+ * - mapped kernels
+ * - arguments
+ * - kernel output
+ */
+
+import { GPU, Texture, IKernelFunctionThis, IConstantsThis } from '../src';
+
+const gpu = new GPU();
+
+interface IConstants extends IConstantsThis {
+  rotation: number,
+}
+
+interface IThis extends IKernelFunctionThis {
+  constants: IConstants,
+}
+
+function kernelFunction(this: IThis, degrees: number, divisors: [number, number]): [number, number] {
+  const bounds = subKernel(this.constants.rotation * degrees);
+  return [bounds[0] / divisors[0], bounds[1] / divisors[1]];
+}
+
+function subKernel(value: number): [number, number] {
+  return [-value, value];
+}
+
+const kernelMap = gpu.createKernelMap<typeof kernelFunction>({
+  test: subKernel,
+}, kernelFunction)
+  .setConstants<IConstants>({
+    rotation: 45,
+  })
+  .setOutput([1])
+  .setPrecision('single')
+  .setPipeline(true)
+  .setImmutable(true);
+
+const { test, result } = kernelMap(360, [256, 512]);
+const testTexture = test as Texture;
+const resultTexture = result as Texture;
+
+console.log(testTexture.toArray() as [number, number][]);
+console.log(resultTexture.toArray() as [number, number][]);
+
+testTexture.delete();
+resultTexture.delete();
+
+kernelMap.destroy();

dist/gpu-browser.min.js

@@ -294,6 +294,7 @@
         output: [ this.particleCount*3 ],
         pipeline: true,
         tactic: 'speed',
+        immutable: true,
       });
 
       /*
@@ -312,6 +313,7 @@
         constants: { particleCount: this.particleCount, pitch: 3 },
         loopMaxIterations: this.particleCount,
         tactic: 'speed',
+        immutable: true,
       });
 
       this.setVelocity = gpu.createKernel(function(list, index, camDir, amount) {
@@ -326,6 +328,7 @@
         constants: { particleCount: this.particleCount, pitch: 3 },
         loopMaxIterations: this.particleCount,
         tactic: 'speed',
+        immutable: true,
       });
 
       /*
@@ -339,6 +342,7 @@
         pipeline: true,
         loopMaxIterations: this.particleCount,
         tactic: 'speed',
+        immutable: true,
       });
 
       this.rotateCamera = gpu.createKernel(function(rotLR, rotUD, camCenter, camDir, camUp, camNearWidth, camFarWidth, camDist) {
@@ -360,7 +364,8 @@
       }, {
         output: [ 3 ],
         tactic: 'speed',
-        pipeline: true
+        pipeline: true,
+        immutable: true,
       });
 
       this.updateCameraPosition = gpu.createKernel(function(camDir, camP, moveTFR, dt) {
@@ -373,7 +378,8 @@
       }, {
         output: [3],
         tactic: 'speed',
-        pipeline: true
+        pipeline: true,
+        immutable: true,
       });
 
       /*
@@ -784,6 +790,7 @@
         output: [3],
         pipeline: true,
         tactic: 'speed',
+        immutable: true,
       });
 
       this.crossv = gpu.createKernel(function(a, b) {
@@ -800,6 +807,7 @@
         output: [3],
         pipeline: true,
         tactic: 'speed',
+        immutable: true,
       });
     }
 

examples/advanced-typescript.ts

@@ -1,6 +1,6 @@
 {
   "name": "gpu.js",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "GPU Accelerated JavaScript",
   "engines": {
     "node": ">=8.0.0"

examples/fluid.html

@@ -789,7 +789,7 @@ class GLKernel extends Kernel {
   }
 
   renderTexture() {
-    return this.texture.clone();
+    return this.immutable ? this.texture.clone() : this.texture;
   }
   readPackedPixelsToUint8Array() {
     if (this.precision !== 'unsigned') throw new Error('Requires this.precision to be "unsigned"');
@@ -850,8 +850,14 @@ class GLKernel extends Kernel {
     const result = {
       result: this.renderOutput(),
     };
-    for (let i = 0; i < this.subKernels.length; i++) {
-      result[this.subKernels[i].property] = this.mappedTextures[i].clone();
+    if (this.immutable) {
+      for (let i = 0; i < this.subKernels.length; i++) {
+        result[this.subKernels[i].property] = this.mappedTextures[i].clone();
+      }
+    } else {
+      for (let i = 0; i < this.subKernels.length; i++) {
+        result[this.subKernels[i].property] = this.mappedTextures[i];
+      }
     }
     return result;
   }
@@ -964,6 +970,7 @@ class GLKernel extends Kernel {
    * @param {GLTexture} arg
    */
   updateTextureArgumentRefs(kernelValue, arg) {
+    if (!this.immutable) return;
     if (this.texture.texture === arg.texture) {
       const { prevArg } = kernelValue;
       if (prevArg) {