2.3.3 Patch

contributor_docs/decorators.md

@@ -0,0 +1,96 @@
+# Decorators in p5.js and addons
+
+In programming, a [decorator](https://en.wikipedia.org/wiki/Decorator_pattern) helps to reduce duplicated code. In p5.js, decorators are applied using `p5.registerDecoration(pattern, decorator)`. This guide is for p5.js code contributors who would like to learn when to use a decorator, and how.
+
+The p5.js Decorators API is mainly aimed at addon authors (see also: guide for [creating addon libraries](https://p5js.org/contribute/creating_libraries/)), but is also used throughout the p5.js library code. In this guide, we use examples from p5.js.
+
+## When and Why to Use a Decorator
+
+Decorators are a design pattern for having **one place** where repeated logic is maintained (in our example, the [vector parameter validation](https://github.com/processing/p5.js/blob/522b89ecc85e6ba4442ba40c69d96c6a5d00c839/src/math/patch-vector.js#L85)), but it is still applied in multiple files. Decorators allow changing the behavior of existing functions without knowing how they are implemented, and without having to modify their source code.
+
+One common motivation is to avoid duplicate code, because:
+
+1. Duplicate code makes maintenance harder: when the validation logic has to be updated, the contributor has to remember all the different places where the update needs to be applied
+2. Duplicate code makes bugs or regressions more likely: when updates or fixes are not applied in all necessary places
+
+The p5.js library already uses decorators in:
+
+* The Friendly Error System parameter validation ([code](https://github.com/processing/p5.js/blob/522b89ecc85e6ba4442ba40c69d96c6a5d00c839/src/friendly_errors/param_validator.js#L656))
+* Flagging experimental functions ([code](https://github.com/processing/p5.js/blob/522b89ecc85e6ba4442ba40c69d96c6a5d00c839/src/core/experimental.js#L17))
+* Vector binary functions (like multiply and divide) parameter validation ([code](https://github.com/processing/p5.js/blob/522b89ecc85e6ba4442ba40c69d96c6a5d00c839/src/math/patch-vector.js#L85))
+
+All these uses are good examples of when a decorator is useful. Two of these examples are parameter validation: checking that parameters are well-formatted usually takes a few lines, and these lines have to be repeated in every function that has similar requirements. For example, for adding, subtracting, dividing, and multiplying vectors, the validation process is very similar.
+
+## How to Use a Decorator
+
+The main usage is `p5.registerDecoration(pattern, decorator)`, where `pattern` specifies **where** to run the code, and `decorator` specifies **what** code to run.
+
+Consider the example the Friendly Error System (FES) parameter validation ([code](https://github.com/processing/p5.js/blob/522b89ecc85e6ba4442ba40c69d96c6a5d00c839/src/friendly_errors/param_validator.js#L656)). The comments below were added for this guide.
+
+```js
+  p5.registerDecorator(
+
+    // This is the pattern. Any function where the path starts with
+    // `p5.prototype`, pattern will be true.
+    ({ path }) => {
+      return path.startsWith('p5.prototype');
+    },
+
+    // This is the decorator code. It always expects a `target` first
+    // and this is what the function being called is. 
+    function (target, { kind, name }) {
+      if (kind === 'method') {
+        return function (...args) {
+          if (p5.disableFriendlyErrors) {
+
+            // When this is called, the decorators' work is done;
+            // the original function is called with the given arguments
+            return target.apply(this, args);
+          }
+
+          // Additional logic could happen here; afterwards,
+          // the original function is also called with the givem arguments
+          return target.apply(this, args);
+        };
+      }
+    }
+  );
+```
+
+In the above example, notice that `return target.apply(this, args);` is always called. But the decorator decides - based on global settings and parameter validation logic - whether to also print some errors. That means FES errors can be printed, but this is managed entirely in this one decorator - never on individual functions being decorated and validated.
+
+Next, we will show step by step how to add a decorator. These steps are adapted from `Vector` parameter validation, so if you'd prefer a practical example, check [this code](https://github.com/processing/p5.js/blob/522b89ecc85e6ba4442ba40c69d96c6a5d00c839/src/math/patch-vector.js#L85) that defines and applies the decorators in `vectorValidation`. Then, the whole set of decorators is also added to p5 [here](https://github.com/processing/p5.js/blob/522b89ecc85e6ba4442ba40c69d96c6a5d00c839/src/math/index.js#L16) with `p5.registerAddon(vectorValidation);`. Notice how this code changes the behavior of `add`, `sub`, and other binary operations on `Vector`, but without ever modifying the files where those methods are created.
+
+### Step 1: Define behavior
+
+First, create a new function, which will be our `decorator`:
+
+```js
+/**
+ * @private
+ * @internal
+ */
+export function _exampleDecorator(target, ...args) {
+  console.log(`Hi! The function ${target.name || 'anonymous'} has been called with ${args.length} arguments`);
+  return target.call(this, args);
+}
+```
+
+When this decorator is applied to any function, it will print the message, and then execute the function as usual.
+
+Please include the **@private** and **@internal** tags in docstrings, to make sure these functions to not appear in the public reference; in general, they are not intended to be part of the public API.
+
+### Step 2: Register decorator
+
+Second, use `pattern` to register the decorator on various targets. You can use a function that returns `true` if the decorator should apply or vice versa, or a string that matches the `p5` member path exactly:
+
+```js
+p5.registerDecorator('p5.prototype.createVector', _exampleDecorator);
+p5.registerDecorator('p5.Vector.prototype.mult', _exampleDecorator);
+```
+
+Notice that `_exampleDecorator` is passed as a function. The Decorator API will then call the `decorator` function with the target and arguments when the `pattern` is matched.
+
+## Contributing
+
+In p5.js, decorators are supported since [version 2.3.0](https://github.com/processing/p5.js/releases/tag/v2.3.0), and follow [the TC39 proposal](https://github.com/tc39/proposal-decorators) as closely as possible. Unlike the TC39 proposal, the implementation in p5.js needs to be applied at runtime and after all addons are registered but before the p5 instance is created. Contribution to help maintain decorator usage in p5.js, its implementation, and documentation (especially documentation for addon authors) is welcome!

docs/parameterData.json

@@ -2167,7 +2167,8 @@
       "overloads": [
         [
           "Number",
-          "Number"
+          "Number",
+          "...Number[]"
         ],
         [
           "Number[]"
@@ -2345,7 +2346,8 @@
       "overloads": [
         [
           "Number",
-          "Number"
+          "Number",
+          "...Number[]"
         ],
         [
           "Number[]"

src/image/loading_displaying.js

@@ -11,6 +11,40 @@ import * as omggif from 'omggif';
 import { GIFEncoder, quantize, nearestColorIndex } from 'gifenc';
 
 function loadingDisplaying(p5, fn){
+  /**
+   * The largest possible number of pixels a gif frame can contain.
+   *
+   * This static property defines how large, in terms of dimension, a gif image
+   * is allowed to be loaded into a p5 sketch. The default value is
+   * 16,000,000. This means an image's width multiplied by its height must not
+   * exceed 100,000,000. For example, an image with width 10,000 and height
+   * 10,000 is just enough, as well as an image with width 5000 and height
+   * 20,000. An image with width 20,000 and height 20,000 is not allowed and
+   * will cause an error when it is loaded.
+   *
+   * To avoid this error, you should try to reduce the image dimension of the
+   * gif. If that is not possible or not desirable, you can set
+   * `MAX_GIF_PIXELS` to a higher value instead.
+   *
+   * @static
+   * @property {Boolean} MAX_GIF_PIXELS
+   *
+   * @example
+   * // META: norender
+   * // Increase the maximum pixel counts to 200,000,000
+   * p5.MAX_GIF_PIXELS = 200_000_000;
+   *
+   * let img;
+   * async function setup() {
+   *   createCanvas(100, 100);
+   *
+   *   background(200);
+   *
+   *   img = await loadImage('./a-large-animated.gif');
+   * }
+   */
+  p5.MAX_GIF_PIXELS = 4000 * 4000; // 4 Channel per pixels for total of 64MB
+
   /**
    * Loads an image to create a <a href="#/p5.Image">p5.Image</a> object.
    *
@@ -623,6 +657,13 @@ function loadingDisplaying(p5, fn){
     pImg.height = pImg.canvas.height = gifReader.height;
     const frames = [];
     const numFrames = gifReader.numFrames();
+
+    if (pImg.width * pImg.height > p5.MAX_GIF_PIXELS) {
+      // GIF is too big, refuse to proceed
+      p5.FES.log`The GIF is over the maximum allowed dimension. Try to shrink the image or set p5.MAX_GIF_PIXELS to a higher value.`();
+      throw new Error("The GIF is over the maximum allowed dimension.");
+    }
+
     let framePixels = new Uint8ClampedArray(pImg.width * pImg.height * 4);
 
     const loadGIFFrameIntoImage = (frameNum, gifReader) => {

src/math/calculation.js

@@ -970,6 +970,7 @@ function calculation(p5, fn){
    * @method max
    * @param  {Number} n0 first number to compare.
    * @param  {Number} n1 second number to compare.
+   * @param  {...Number} rest additional numbers to compare.
    * @return {Number}             maximum number.
    */
   /**
@@ -1089,6 +1090,7 @@ function calculation(p5, fn){
    * @method min
    * @param  {Number} n0 first number to compare.
    * @param  {Number} n1 second number to compare.
+   * @param  {...Number} rest additional numbers to compare.
    * @return {Number}             minimum number.
    */
   /**

src/webgl/p5.Quat.js

@@ -34,14 +34,14 @@ class Quat {
 
   /**
    * Multiplies a quaternion with other quaternion.
-   * @method mult
+   * @method multiply
    * @param  {p5.Quat} [quat] quaternion to multiply with the quaternion calling the method.
    * @chainable
    */
   multiply(quat) {
 
     return new Quat(
-      this.w * quat.w - this.vec.x * quat.vec.x - this.vec.y * quat.vec.y - this.vec.z - quat.vec.z,
+      this.w * quat.w - this.vec.x * quat.vec.x - this.vec.y * quat.vec.y - this.vec.z * quat.vec.z,
       this.w * quat.vec.x + this.vec.x * quat.w + this.vec.y * quat.vec.z - this.vec.z * quat.vec.y,
       this.w * quat.vec.y - this.vec.x * quat.vec.z + this.vec.y * quat.w + this.vec.z * quat.vec.x,
       this.w * quat.vec.z + this.vec.x * quat.vec.y - this.vec.y * quat.vec.x + this.vec.z * quat.w

test/unit/core/param_errors.js

@@ -257,6 +257,35 @@ suite('Validate Params', function () {
     });
   });
 
+  suite('validateParams: variadic min/max', function () {
+    ['min', 'max'].forEach(fn => {
+      test(`${fn}(): works with two numbers`, function () {
+        const result = mockP5Prototype._validate(`p5.${fn}`, [1, 2]);
+        assert.isTrue(result.success);
+      });
+      test(`${fn}(): works with more than two numbers`, function () {
+        const result = mockP5Prototype._validate(`p5.${fn}`, [1, 2, 3, 4]);
+        assert.isTrue(result.success);
+      });
+      test(`${fn}(): works with a single array of numbers`, function () {
+        const result = mockP5Prototype._validate(`p5.${fn}`, [[1, 2, 3, 4]]);
+        assert.isTrue(result.success);
+      });
+      test(`${fn}(): fails with no args`, function () {
+        const result = mockP5Prototype._validate(`p5.${fn}`, []);
+        assert.isFalse(result.success);
+      });
+      test(`${fn}(): fails with a single number`, function () {
+        const result = mockP5Prototype._validate(`p5.${fn}`, [5]);
+        assert.isFalse(result.success);
+      });
+      test(`${fn}(): fails with a non-number among the rest`, function () {
+        const result = mockP5Prototype._validate(`p5.${fn}`, [1, 2, '3', 4]);
+        assert.isFalse(result.success);
+      });
+    });
+  });
+
   suite('validateParams: rest arguments', function () {
     test('createVector(): works with no args', function() {
       const result = mockP5Prototype._validate('p5.createVector', []);