From 4593312068e242755dfaf892ba950111324c3809 Mon Sep 17 00:00:00 2001 From: limzykenneth Date: Mon, 7 Sep 2026 09:24:22 +0800 Subject: [PATCH 01/10] Add maximum allowed gif dimension --- src/image/loading_displaying.js | 41 +++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/src/image/loading_displaying.js b/src/image/loading_displaying.js index 3d23cc4c0b..4cb2eb4f67 100644 --- a/src/image/loading_displaying.js +++ b/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 + * 100,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 p5.Image 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) => { From 7de9fc053a7402fb9714b496ed7abe43500d1355 Mon Sep 17 00:00:00 2001 From: limzykenneth Date: Mon, 7 Sep 2026 09:26:56 +0800 Subject: [PATCH 02/10] Fix documentation indicating incorrect default value of MAX_GIF_PIXELS --- src/image/loading_displaying.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/image/loading_displaying.js b/src/image/loading_displaying.js index 4cb2eb4f67..dd4ebaca00 100644 --- a/src/image/loading_displaying.js +++ b/src/image/loading_displaying.js @@ -16,7 +16,7 @@ function loadingDisplaying(p5, fn){ * * 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 - * 100,000,000. This means an image's width multiplied by its height must not + * 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 From 349458200b5bfc060f842da41716d2cd8b95042d Mon Sep 17 00:00:00 2001 From: Roy Macdonald Date: Wed, 22 Jul 2026 20:31:35 -0400 Subject: [PATCH 03/10] Fixed typo in quaternion multiplication --- src/webgl/p5.Quat.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/webgl/p5.Quat.js b/src/webgl/p5.Quat.js index d10f509b94..02eb53d0f7 100644 --- a/src/webgl/p5.Quat.js +++ b/src/webgl/p5.Quat.js @@ -41,7 +41,7 @@ class Quat { 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 From 76a7c7fe4abc78027e8d699ae0ddfa9bf18f2cb9 Mon Sep 17 00:00:00 2001 From: Roy Macdonald Date: Thu, 23 Jul 2026 17:31:54 -0400 Subject: [PATCH 04/10] Corrected function name in inline doc --- src/webgl/p5.Quat.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/webgl/p5.Quat.js b/src/webgl/p5.Quat.js index 02eb53d0f7..d9204aec32 100644 --- a/src/webgl/p5.Quat.js +++ b/src/webgl/p5.Quat.js @@ -34,7 +34,7 @@ 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 */ From 143162c97c58936c247a7ed5dcb10437c17ea2b8 Mon Sep 17 00:00:00 2001 From: kit <1304340+ksen0@users.noreply.github.com> Date: Fri, 28 Aug 2026 15:57:14 +0200 Subject: [PATCH 05/10] Create documentation for decorators in p5.js Added guide on using decorators in p5.js --- contributor_docs/decorators.md | 102 +++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 contributor_docs/decorators.md diff --git a/contributor_docs/decorators.md b/contributor_docs/decorators.md new file mode 100644 index 0000000000..1ca05d8400 --- /dev/null +++ b/contributor_docs/decorators.md @@ -0,0 +1,102 @@ +# 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. The purpose is avoiding 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 its original arguments + return target.apply(this, args); + } + const wasInternalCall = this._isUserCall; + this._isUserCall = true; + try { + if ( + !wasInternalCall && + !p5.disableFriendlyErrors && + !p5.disableParameterValidator + ) { + validate(name, args); + } + return target.apply(this, args); + } finally { + this._isUserCall = wasInternalCall; + } + }; + } + } + ); +``` + +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 out `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. + +### Step 2: Register decorator + +Second, use `pattern` to register the decorator on various targets. You can use path comparison (as in the FES example above), or text: + +```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 [partially implement the TC39 proposal](https://github.com/processing/p5.js/issues/8334). 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! From 3ec2dccea3ab139e3c35e74533846348aecaf667 Mon Sep 17 00:00:00 2001 From: kit <1304340+ksen0@users.noreply.github.com> Date: Fri, 28 Aug 2026 16:01:06 +0200 Subject: [PATCH 06/10] Update decorators documentation with visibility tags Added instructions for using @private and @internal tags in docstrings. --- contributor_docs/decorators.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/contributor_docs/decorators.md b/contributor_docs/decorators.md index 1ca05d8400..6f62f237e5 100644 --- a/contributor_docs/decorators.md +++ b/contributor_docs/decorators.md @@ -86,6 +86,8 @@ export function _exampleDecorator(target, ...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 path comparison (as in the FES example above), or text: From 2a782dfb5e1fb07e932628d0fc2fe27bf8e3b9d5 Mon Sep 17 00:00:00 2001 From: kit <1304340+ksen0@users.noreply.github.com> Date: Mon, 31 Aug 2026 17:40:26 +0200 Subject: [PATCH 07/10] Update contributor_docs/decorators.md Co-authored-by: Kenneth Lim --- contributor_docs/decorators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributor_docs/decorators.md b/contributor_docs/decorators.md index 6f62f237e5..61af55f34d 100644 --- a/contributor_docs/decorators.md +++ b/contributor_docs/decorators.md @@ -71,7 +71,7 @@ Next, we will show step by step how to add a decorator. These steps are adapted ### Step 1: Define behavior -First, create a new function, which will be out `decorator`: +First, create a new function, which will be our `decorator`: ```js /** From 6f73054acd9225f1b0dc8ff8789ebb690f43bb20 Mon Sep 17 00:00:00 2001 From: kit <1304340+ksen0@users.noreply.github.com> Date: Mon, 31 Aug 2026 17:40:36 +0200 Subject: [PATCH 08/10] Update contributor_docs/decorators.md Co-authored-by: Kenneth Lim --- contributor_docs/decorators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributor_docs/decorators.md b/contributor_docs/decorators.md index 61af55f34d..0224994723 100644 --- a/contributor_docs/decorators.md +++ b/contributor_docs/decorators.md @@ -90,7 +90,7 @@ Please include the **@private** and **@internal** tags in docstrings, to make su ### Step 2: Register decorator -Second, use `pattern` to register the decorator on various targets. You can use path comparison (as in the FES example above), or text: +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); From c1306969ca7efb8a0b4e77a28f05560940396dfe Mon Sep 17 00:00:00 2001 From: kit <1304340+ksen0@users.noreply.github.com> Date: Wed, 2 Sep 2026 21:14:28 +0200 Subject: [PATCH 09/10] Improved clarity based on feedback --- contributor_docs/decorators.md | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/contributor_docs/decorators.md b/contributor_docs/decorators.md index 0224994723..cef06e4628 100644 --- a/contributor_docs/decorators.md +++ b/contributor_docs/decorators.md @@ -6,7 +6,9 @@ The p5.js Decorators API is mainly aimed at addon authors (see also: guide for [ ## 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. The purpose is avoiding duplicate code, because: +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 @@ -42,23 +44,13 @@ Consider the example the Friendly Error System (FES) parameter validation ([code if (p5.disableFriendlyErrors) { // When this is called, the decorators' work is done; - // the original function is called with its original arguments - return target.apply(this, args); - } - const wasInternalCall = this._isUserCall; - this._isUserCall = true; - try { - if ( - !wasInternalCall && - !p5.disableFriendlyErrors && - !p5.disableParameterValidator - ) { - validate(name, args); - } + // the original function is called with the given arguments return target.apply(this, args); - } finally { - this._isUserCall = wasInternalCall; } + + // Additional logic could happen here; afterwards, + // the original function is also called with the givem arguments + return target.apply(this, args); }; } } @@ -101,4 +93,4 @@ Notice that `_exampleDecorator` is passed as a function. The Decorator API will ## Contributing -In p5.js, decorators are supported since [version 2.3.0](https://github.com/processing/p5.js/releases/tag/v2.3.0), and [partially implement the TC39 proposal](https://github.com/processing/p5.js/issues/8334). 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! +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! From 1abff3406e9781e4d54ceab9f62077596f1d4dba Mon Sep 17 00:00:00 2001 From: Roberto Date: Mon, 31 Aug 2026 12:08:47 -0600 Subject: [PATCH 10/10] Fix false 'Expected at most 2 arguments' FES error for variadic min()/max() The runtime implementation of min() and max() is variadic, but their documented overloads only declared (n0, n1), so the parameter validator rejected calls like min(1, 2, 3, 4). Add a {...Number} rest parameter to the two-number overload of both functions (same pattern as createVector) and update parameterData.json accordingly. Calls with fewer than two number arguments still fail validation with the same friendly error as before, and the single-array overload is unchanged. --- docs/parameterData.json | 6 ++++-- src/math/calculation.js | 2 ++ test/unit/core/param_errors.js | 29 +++++++++++++++++++++++++++++ 3 files changed, 35 insertions(+), 2 deletions(-) diff --git a/docs/parameterData.json b/docs/parameterData.json index bee74cb5d6..345e300bc4 100644 --- a/docs/parameterData.json +++ b/docs/parameterData.json @@ -2167,7 +2167,8 @@ "overloads": [ [ "Number", - "Number" + "Number", + "...Number[]" ], [ "Number[]" @@ -2345,7 +2346,8 @@ "overloads": [ [ "Number", - "Number" + "Number", + "...Number[]" ], [ "Number[]" diff --git a/src/math/calculation.js b/src/math/calculation.js index aaa3e61158..0cdb94c02e 100644 --- a/src/math/calculation.js +++ b/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. */ /** diff --git a/test/unit/core/param_errors.js b/test/unit/core/param_errors.js index ca64f3c360..9beb870533 100644 --- a/test/unit/core/param_errors.js +++ b/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', []);