From a3aeaa29a0662f85393ce350508523e9b72acad1 Mon Sep 17 00:00:00 2001 From: Abhayaj247 Date: Tue, 24 Jun 2025 20:06:28 +0530 Subject: [PATCH 1/6] docs: Add initial draft of Strands documentation --- src/webgl/p5.strands.js | 152 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 src/webgl/p5.strands.js diff --git a/src/webgl/p5.strands.js b/src/webgl/p5.strands.js new file mode 100644 index 0000000000..f5d56011f2 --- /dev/null +++ b/src/webgl/p5.strands.js @@ -0,0 +1,152 @@ +/** + * @typedef {Object} Vertex + * @property {{x: number, y: number, z: number}} position - The position of the vertex in world space. + * @property {{x: number, y: number, z: number}} normal - The normal vector at the vertex in world space. + * @property {{x: number, y: number}} texCoord - The texture coordinates (x, y) for the vertex. + * @property {{r: number, g: number, b: number, a: number}} color - The color at the vertex. + */ + +/** + * @function getWorldInputs + * @experimental + * @description + * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied. + * + * This hook is available in: + * - {@link p5.baseMaterialShader} + * - {@link p5.baseNormalShader} + * - {@link p5.baseColorShader} + * - {@link p5.baseStrokeShader} + * + * @param {function(Vertex): Vertex} callback + * A callback function which receives and returns a Vertex struct. + * + * @see {@link p5.baseMaterialShader} + * @see {@link p5.Shader#modify} + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseMaterialShader().modify(() => { + * getWorldInputs(inputs => { + * // Move the vertex up and down in a wave + * inputs.position.y += 20 * sin( + * millis() * 0.001 + inputs.position.x * 0.05 + * ); + * return inputs; + * }); + * }); + * } + * function draw() { + * background(255); + * shader(myShader); + * lights(); + * noStroke(); + * fill('red'); + * sphere(50); + * } + * + *
+ */ + +/** + * @function combineColors + * @experimental + * @description + * Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to control the final color output of a material. The callback receives a ColorComponents struct and should return an object with a `color` property ({ r, g, b }) and an `opacity` property (number). + * + * This hook is available in: + * - {@link p5.baseMaterialShader} + * - {@link p5.baseNormalShader} + * - {@link p5.baseColorShader} + * - {@link p5.baseStrokeShader} + * + * @param {function(ColorComponents): { color: {r: number, g: number, b: number}, opacity: number }} callback + * A callback function which receives a ColorComponents struct and returns the final color and opacity. + * + * @see {@link p5.baseMaterialShader} + * @see {@link p5.Shader#modify} + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseMaterialShader().modify(() => { + * combineColors(components => { + * // Custom color combination: add a red tint + * let color = { + * r: components.baseColor.r * components.diffuse.r + + * components.ambientColor.r * components.ambient.r + + * components.specularColor.r * components.specular.r + + * components.emissive.r + 0.2, + * g: components.baseColor.g * components.diffuse.g + + * components.ambientColor.g * components.ambient.g + + * components.specularColor.g * components.specular.g + + * components.emissive.g, + * b: components.baseColor.b * components.diffuse.b + + * components.ambientColor.b * components.ambient.b + + * components.specularColor.b * components.specular.b + + * components.emissive.b + * }; + * return { color, opacity: components.opacity }; + * }); + * }); + * } + * function draw() { + * background(255); + * shader(myShader); + * lights(); + * noStroke(); + * fill('red'); + * sphere(50); + * } + * + *
+ */ + +/** + * @function getPointSize + * @experimental + * @description + * Registers a callback to modify the size of points when rendering with a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() or similar, when drawing points (e.g., with the point() function in WEBGL mode). The callback receives the current point size (number) and should return the new size (number). + * + * This hook is available in: + * - {@link p5.baseMaterialShader} + * - {@link p5.baseNormalShader} + * - {@link p5.baseColorShader} + * - {@link p5.baseStrokeShader} + * + * @param {function(size: number): number} callback + * A callback function which receives and returns the point size. + * + * @see {@link p5.baseMaterialShader} + * @see {@link p5.Shader#modify} + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseMaterialShader().modify(() => { + * getPointSize(size => { + * // Make points pulse in size over time + * return size * (1.0 + 0.5 * sin(millis() * 0.002)); + * }); + * }); + * } + * function draw() { + * background(255); + * shader(myShader); + * strokeWeight(20); + * stroke('blue'); + * point(0, 0); + * } + * + *
+ */ \ No newline at end of file From 8e199d84aa16ccbb24b301d2c6aefe2ac950a49d Mon Sep 17 00:00:00 2001 From: Abhayaj247 Date: Thu, 26 Jun 2025 19:32:59 +0530 Subject: [PATCH 2/6] docs: move p5.strands JSDoc to end of shaderGenerator.js and remove separate file --- src/webgl/ShaderGenerator.js | 156 +++++++++++++++++++++++++++++++++++ src/webgl/p5.strands.js | 152 ---------------------------------- 2 files changed, 156 insertions(+), 152 deletions(-) delete mode 100644 src/webgl/p5.strands.js diff --git a/src/webgl/ShaderGenerator.js b/src/webgl/ShaderGenerator.js index d029ed44ef..fc9a6250c9 100644 --- a/src/webgl/ShaderGenerator.js +++ b/src/webgl/ShaderGenerator.js @@ -1638,3 +1638,159 @@ export default shadergenerator; if (typeof p5 !== 'undefined') { p5.registerAddon(shadergenerator) } + + + +/* ------------------------------------------------------------- */ +/** + * @typedef {Object} Vertex + * @property {{x: number, y: number, z: number}} position - The position of the vertex in world space. + * @property {{x: number, y: number, z: number}} normal - The normal vector at the vertex in world space. + * @property {{x: number, y: number}} texCoord - The texture coordinates (x, y) for the vertex. + * @property {{r: number, g: number, b: number, a: number}} color - The color at the vertex. + */ + +/** + * @function getWorldInputs + * @experimental + * @description + * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied. + * + * This hook is available in: + * - {@link p5.baseMaterialShader} + * - {@link p5.baseNormalShader} + * - {@link p5.baseColorShader} + * - {@link p5.baseStrokeShader} + * + * @param {function(Vertex): Vertex} callback + * A callback function which receives and returns a Vertex struct. + * + * @see {@link p5.baseMaterialShader} + * @see {@link p5.Shader#modify} + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseMaterialShader().modify(() => { + * getWorldInputs(inputs => { + * // Move the vertex up and down in a wave + * inputs.position.y += 20 * sin( + * millis() * 0.001 + inputs.position.x * 0.05 + * ); + * return inputs; + * }); + * }); + * } + * function draw() { + * background(255); + * shader(myShader); + * lights(); + * noStroke(); + * fill('red'); + * sphere(50); + * } + * + *
+ */ + +/** + * @function combineColors + * @experimental + * @description + * Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to control the final color output of a material. The callback receives a ColorComponents struct and should return an object with a `color` property ({ r, g, b }) and an `opacity` property (number). + * + * This hook is available in: + * - {@link p5.baseMaterialShader} + * - {@link p5.baseNormalShader} + * - {@link p5.baseColorShader} + * - {@link p5.baseStrokeShader} + * + * @param {function(ColorComponents): { color: {r: number, g: number, b: number}, opacity: number }} callback + * A callback function which receives a ColorComponents struct and returns the final color and opacity. + * + * @see {@link p5.baseMaterialShader} + * @see {@link p5.Shader#modify} + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseMaterialShader().modify(() => { + * combineColors(components => { + * // Custom color combination: add a red tint + * let color = { + * r: components.baseColor.r * components.diffuse.r + + * components.ambientColor.r * components.ambient.r + + * components.specularColor.r * components.specular.r + + * components.emissive.r + 0.2, + * g: components.baseColor.g * components.diffuse.g + + * components.ambientColor.g * components.ambient.g + + * components.specularColor.g * components.specular.g + + * components.emissive.g, + * b: components.baseColor.b * components.diffuse.b + + * components.ambientColor.b * components.ambient.b + + * components.specularColor.b * components.specular.b + + * components.emissive.b + * }; + * return { color, opacity: components.opacity }; + * }); + * }); + * } + * function draw() { + * background(255); + * shader(myShader); + * lights(); + * noStroke(); + * fill('red'); + * sphere(50); + * } + * + *
+ */ + +/** + * @function getPointSize + * @experimental + * @description + * Registers a callback to modify the size of points when rendering with a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() or similar, when drawing points (e.g., with the point() function in WEBGL mode). The callback receives the current point size (number) and should return the new size (number). + * + * This hook is available in: + * - {@link p5.baseMaterialShader} + * - {@link p5.baseNormalShader} + * - {@link p5.baseColorShader} + * - {@link p5.baseStrokeShader} + * + * @param {function(size: number): number} callback + * A callback function which receives and returns the point size. + * + * @see {@link p5.baseMaterialShader} + * @see {@link p5.Shader#modify} + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseMaterialShader().modify(() => { + * getPointSize(size => { + * // Make points pulse in size over time + * return size * (1.0 + 0.5 * sin(millis() * 0.002)); + * }); + * }); + * } + * function draw() { + * background(255); + * shader(myShader); + * strokeWeight(20); + * stroke('blue'); + * point(0, 0); + * } + * + *
+ */ diff --git a/src/webgl/p5.strands.js b/src/webgl/p5.strands.js deleted file mode 100644 index f5d56011f2..0000000000 --- a/src/webgl/p5.strands.js +++ /dev/null @@ -1,152 +0,0 @@ -/** - * @typedef {Object} Vertex - * @property {{x: number, y: number, z: number}} position - The position of the vertex in world space. - * @property {{x: number, y: number, z: number}} normal - The normal vector at the vertex in world space. - * @property {{x: number, y: number}} texCoord - The texture coordinates (x, y) for the vertex. - * @property {{r: number, g: number, b: number, a: number}} color - The color at the vertex. - */ - -/** - * @function getWorldInputs - * @experimental - * @description - * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied. - * - * This hook is available in: - * - {@link p5.baseMaterialShader} - * - {@link p5.baseNormalShader} - * - {@link p5.baseColorShader} - * - {@link p5.baseStrokeShader} - * - * @param {function(Vertex): Vertex} callback - * A callback function which receives and returns a Vertex struct. - * - * @see {@link p5.baseMaterialShader} - * @see {@link p5.Shader#modify} - * - * @example - *
- * - * let myShader; - * function setup() { - * createCanvas(200, 200, WEBGL); - * myShader = baseMaterialShader().modify(() => { - * getWorldInputs(inputs => { - * // Move the vertex up and down in a wave - * inputs.position.y += 20 * sin( - * millis() * 0.001 + inputs.position.x * 0.05 - * ); - * return inputs; - * }); - * }); - * } - * function draw() { - * background(255); - * shader(myShader); - * lights(); - * noStroke(); - * fill('red'); - * sphere(50); - * } - * - *
- */ - -/** - * @function combineColors - * @experimental - * @description - * Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to control the final color output of a material. The callback receives a ColorComponents struct and should return an object with a `color` property ({ r, g, b }) and an `opacity` property (number). - * - * This hook is available in: - * - {@link p5.baseMaterialShader} - * - {@link p5.baseNormalShader} - * - {@link p5.baseColorShader} - * - {@link p5.baseStrokeShader} - * - * @param {function(ColorComponents): { color: {r: number, g: number, b: number}, opacity: number }} callback - * A callback function which receives a ColorComponents struct and returns the final color and opacity. - * - * @see {@link p5.baseMaterialShader} - * @see {@link p5.Shader#modify} - * - * @example - *
- * - * let myShader; - * function setup() { - * createCanvas(200, 200, WEBGL); - * myShader = baseMaterialShader().modify(() => { - * combineColors(components => { - * // Custom color combination: add a red tint - * let color = { - * r: components.baseColor.r * components.diffuse.r + - * components.ambientColor.r * components.ambient.r + - * components.specularColor.r * components.specular.r + - * components.emissive.r + 0.2, - * g: components.baseColor.g * components.diffuse.g + - * components.ambientColor.g * components.ambient.g + - * components.specularColor.g * components.specular.g + - * components.emissive.g, - * b: components.baseColor.b * components.diffuse.b + - * components.ambientColor.b * components.ambient.b + - * components.specularColor.b * components.specular.b + - * components.emissive.b - * }; - * return { color, opacity: components.opacity }; - * }); - * }); - * } - * function draw() { - * background(255); - * shader(myShader); - * lights(); - * noStroke(); - * fill('red'); - * sphere(50); - * } - * - *
- */ - -/** - * @function getPointSize - * @experimental - * @description - * Registers a callback to modify the size of points when rendering with a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() or similar, when drawing points (e.g., with the point() function in WEBGL mode). The callback receives the current point size (number) and should return the new size (number). - * - * This hook is available in: - * - {@link p5.baseMaterialShader} - * - {@link p5.baseNormalShader} - * - {@link p5.baseColorShader} - * - {@link p5.baseStrokeShader} - * - * @param {function(size: number): number} callback - * A callback function which receives and returns the point size. - * - * @see {@link p5.baseMaterialShader} - * @see {@link p5.Shader#modify} - * - * @example - *
- * - * let myShader; - * function setup() { - * createCanvas(200, 200, WEBGL); - * myShader = baseMaterialShader().modify(() => { - * getPointSize(size => { - * // Make points pulse in size over time - * return size * (1.0 + 0.5 * sin(millis() * 0.002)); - * }); - * }); - * } - * function draw() { - * background(255); - * shader(myShader); - * strokeWeight(20); - * stroke('blue'); - * point(0, 0); - * } - * - *
- */ \ No newline at end of file From c9d07c1c954d234cc99009429ca8a6cde9e774b2 Mon Sep 17 00:00:00 2001 From: Abhayaj247 Date: Sun, 29 Jun 2025 14:00:48 +0530 Subject: [PATCH 3/6] docs: fix JSDoc syntax for p5.js compatibility --- src/webgl/ShaderGenerator.js | 86 ++++++++++++++---------------------- 1 file changed, 34 insertions(+), 52 deletions(-) diff --git a/src/webgl/ShaderGenerator.js b/src/webgl/ShaderGenerator.js index fc9a6250c9..afb492e757 100644 --- a/src/webgl/ShaderGenerator.js +++ b/src/webgl/ShaderGenerator.js @@ -1642,31 +1642,20 @@ if (typeof p5 !== 'undefined') { /* ------------------------------------------------------------- */ -/** - * @typedef {Object} Vertex - * @property {{x: number, y: number, z: number}} position - The position of the vertex in world space. - * @property {{x: number, y: number, z: number}} normal - The normal vector at the vertex in world space. - * @property {{x: number, y: number}} texCoord - The texture coordinates (x, y) for the vertex. - * @property {{r: number, g: number, b: number, a: number}} color - The color at the vertex. - */ - /** * @function getWorldInputs * @experimental * @description - * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied. + * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside baseMaterialShader().modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied. * * This hook is available in: - * - {@link p5.baseMaterialShader} - * - {@link p5.baseNormalShader} - * - {@link p5.baseColorShader} - * - {@link p5.baseStrokeShader} + * - baseMaterialShader() + * - baseNormalShader() + * - baseColorShader() + * - baseStrokeShader() * - * @param {function(Vertex): Vertex} callback - * A callback function which receives and returns a Vertex struct. - * - * @see {@link p5.baseMaterialShader} - * @see {@link p5.Shader#modify} + * @param {function} callback + * A callback function which receives a vertex object containing position (vec3), normal (vec3), texCoord (vec2), and color (vec4) properties. The function should return the modified vertex object. * * @example *
@@ -1700,19 +1689,16 @@ if (typeof p5 !== 'undefined') { * @function combineColors * @experimental * @description - * Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() and similar shader modify calls to control the final color output of a material. The callback receives a ColorComponents struct and should return an object with a `color` property ({ r, g, b }) and an `opacity` property (number). + * Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside baseMaterialShader().modify() and similar shader modify calls to control the final color output of a material. The callback receives color components (baseColor, diffuse, ambientColor, ambient, specularColor, specular, emissive, opacity) and returns a vec4 for the final color. * * This hook is available in: - * - {@link p5.baseMaterialShader} - * - {@link p5.baseNormalShader} - * - {@link p5.baseColorShader} - * - {@link p5.baseStrokeShader} - * - * @param {function(ColorComponents): { color: {r: number, g: number, b: number}, opacity: number }} callback - * A callback function which receives a ColorComponents struct and returns the final color and opacity. + * - baseMaterialShader() + * - baseNormalShader() + * - baseColorShader() + * - baseStrokeShader() * - * @see {@link p5.baseMaterialShader} - * @see {@link p5.Shader#modify} + * @param {function} callback + * A callback function which receives color components (baseColor, diffuse, ambientColor, ambient, specularColor, specular, emissive, opacity) and returns a vec4 for the final color. * * @example *
@@ -1723,21 +1709,20 @@ if (typeof p5 !== 'undefined') { * myShader = baseMaterialShader().modify(() => { * combineColors(components => { * // Custom color combination: add a red tint - * let color = { - * r: components.baseColor.r * components.diffuse.r + - * components.ambientColor.r * components.ambient.r + - * components.specularColor.r * components.specular.r + - * components.emissive.r + 0.2, - * g: components.baseColor.g * components.diffuse.g + - * components.ambientColor.g * components.ambient.g + - * components.specularColor.g * components.specular.g + - * components.emissive.g, - * b: components.baseColor.b * components.diffuse.b + - * components.ambientColor.b * components.ambient.b + - * components.specularColor.b * components.specular.b + - * components.emissive.b - * }; - * return { color, opacity: components.opacity }; + * let r = components.baseColor.r * components.diffuse.r + + * components.ambientColor.r * components.ambient.r + + * components.specularColor.r * components.specular.r + + * components.emissive.r + 0.2; + * let g = components.baseColor.g * components.diffuse.g + + * components.ambientColor.g * components.ambient.g + + * components.specularColor.g * components.specular.g + + * components.emissive.g; + * let b = components.baseColor.b * components.diffuse.b + + * components.ambientColor.b * components.ambient.b + + * components.specularColor.b * components.specular.b + + * components.emissive.b; + * let a = components.opacity; + * return vec4(r, g, b, a); * }); * }); * } @@ -1757,20 +1742,17 @@ if (typeof p5 !== 'undefined') { * @function getPointSize * @experimental * @description - * Registers a callback to modify the size of points when rendering with a shader. This hook can be used inside {@link p5.baseMaterialShader}.modify() or similar, when drawing points (e.g., with the point() function in WEBGL mode). The callback receives the current point size (number) and should return the new size (number). + * Registers a callback to modify the size of points when rendering with a shader. This hook can be used inside baseMaterialShader().modify() or similar, when drawing points (e.g., with the point() function in WEBGL mode). The callback receives the current point size (number) and should return the new size (number). * * This hook is available in: - * - {@link p5.baseMaterialShader} - * - {@link p5.baseNormalShader} - * - {@link p5.baseColorShader} - * - {@link p5.baseStrokeShader} + * - baseMaterialShader() + * - baseNormalShader() + * - baseColorShader() + * - baseStrokeShader() * - * @param {function(size: number): number} callback + * @param {function} callback * A callback function which receives and returns the point size. * - * @see {@link p5.baseMaterialShader} - * @see {@link p5.Shader#modify} - * * @example *
* From 06cf6197042b0ea31f0579e5ecddfd6592982a09 Mon Sep 17 00:00:00 2001 From: Abhayaj247 Date: Wed, 9 Jul 2025 20:06:27 +0530 Subject: [PATCH 4/6] docs: clarify combineColors and getPointSize documentation per maintainer feedback --- src/webgl/ShaderGenerator.js | 55 +++++++++++++++++++++++++----------- 1 file changed, 38 insertions(+), 17 deletions(-) diff --git a/src/webgl/ShaderGenerator.js b/src/webgl/ShaderGenerator.js index afb492e757..ff000d5ce2 100644 --- a/src/webgl/ShaderGenerator.js +++ b/src/webgl/ShaderGenerator.js @@ -1689,7 +1689,18 @@ if (typeof p5 !== 'undefined') { * @function combineColors * @experimental * @description - * Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside baseMaterialShader().modify() and similar shader modify calls to control the final color output of a material. The callback receives color components (baseColor, diffuse, ambientColor, ambient, specularColor, specular, emissive, opacity) and returns a vec4 for the final color. + * Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside baseMaterialShader().modify() and similar shader modify calls to control the final color output of a material. The callback receives an object with the following properties: + * + * - `baseColor`: a vector with three components representing the base color (red, green, blue) + * - `diffuse`: a single number representing the diffuse reflection + * - `ambientColor`: a vector with three components representing the ambient color + * - `ambient`: a single number representing the ambient reflection + * - `specularColor`: a vector with three components representing the specular color + * - `specular`: a single number representing the specular reflection + * - `emissive`: a vector with three components representing the emissive color + * - `opacity`: a single number representing the opacity + * + * The callback should return a vector with four components (red, green, blue, alpha) for the final color. * * This hook is available in: * - baseMaterialShader() @@ -1698,7 +1709,7 @@ if (typeof p5 !== 'undefined') { * - baseStrokeShader() * * @param {function} callback - * A callback function which receives color components (baseColor, diffuse, ambientColor, ambient, specularColor, specular, emissive, opacity) and returns a vec4 for the final color. + * A callback function which receives the object described above and returns a vector with four components for the final color. * * @example *
@@ -1709,20 +1720,19 @@ if (typeof p5 !== 'undefined') { * myShader = baseMaterialShader().modify(() => { * combineColors(components => { * // Custom color combination: add a red tint - * let r = components.baseColor.r * components.diffuse.r + - * components.ambientColor.r * components.ambient.r + - * components.specularColor.r * components.specular.r + - * components.emissive.r + 0.2; - * let g = components.baseColor.g * components.diffuse.g + - * components.ambientColor.g * components.ambient.g + - * components.specularColor.g * components.specular.g + - * components.emissive.g; - * let b = components.baseColor.b * components.diffuse.b + - * components.ambientColor.b * components.ambient.b + - * components.specularColor.b * components.specular.b + - * components.emissive.b; - * let a = components.opacity; - * return vec4(r, g, b, a); + * let r = components.baseColor[0] * components.diffuse + + * components.ambientColor[0] * components.ambient + + * components.specularColor[0] * components.specular + + * components.emissive[0] + 0.2; + * let g = components.baseColor[1] * components.diffuse + + * components.ambientColor[1] * components.ambient + + * components.specularColor[1] * components.specular + + * components.emissive[1]; + * let b = components.baseColor[2] * components.diffuse + + * components.ambientColor[2] * components.ambient + + * components.specularColor[2] * components.specular + + * components.emissive[2]; + * return [r, g, b, components.opacity]; * }); * }); * } @@ -1742,13 +1752,24 @@ if (typeof p5 !== 'undefined') { * @function getPointSize * @experimental * @description - * Registers a callback to modify the size of points when rendering with a shader. This hook can be used inside baseMaterialShader().modify() or similar, when drawing points (e.g., with the point() function in WEBGL mode). The callback receives the current point size (number) and should return the new size (number). + * Registers a callback to modify the size of points when rendering with a shader. + * + * This hook can be used inside the following shader modify functions: + * - baseMaterialShader().modify() + * - baseNormalShader().modify() + * - baseColorShader().modify() + * - baseStrokeShader().modify() + * - baseFilterShader().modify() + * + * Use this hook when drawing points (for example, with the point() function in WEBGL mode). + * The callback receives the current point size (number) and should return the new size (number). * * This hook is available in: * - baseMaterialShader() * - baseNormalShader() * - baseColorShader() * - baseStrokeShader() + * - baseFilterShader() * * @param {function} callback * A callback function which receives and returns the point size. From 1d01ca8f085677adc172263b81ef1e4528577ac0 Mon Sep 17 00:00:00 2001 From: Abhayaj247 Date: Thu, 10 Jul 2025 12:07:28 +0530 Subject: [PATCH 5/6] docs: remove getPointSize documentation as it is not present in public shaders --- src/webgl/ShaderGenerator.js | 52 +----------------------------------- 1 file changed, 1 insertion(+), 51 deletions(-) diff --git a/src/webgl/ShaderGenerator.js b/src/webgl/ShaderGenerator.js index ff000d5ce2..5fa695d4a9 100644 --- a/src/webgl/ShaderGenerator.js +++ b/src/webgl/ShaderGenerator.js @@ -1746,54 +1746,4 @@ if (typeof p5 !== 'undefined') { * } * *
- */ - -/** - * @function getPointSize - * @experimental - * @description - * Registers a callback to modify the size of points when rendering with a shader. - * - * This hook can be used inside the following shader modify functions: - * - baseMaterialShader().modify() - * - baseNormalShader().modify() - * - baseColorShader().modify() - * - baseStrokeShader().modify() - * - baseFilterShader().modify() - * - * Use this hook when drawing points (for example, with the point() function in WEBGL mode). - * The callback receives the current point size (number) and should return the new size (number). - * - * This hook is available in: - * - baseMaterialShader() - * - baseNormalShader() - * - baseColorShader() - * - baseStrokeShader() - * - baseFilterShader() - * - * @param {function} callback - * A callback function which receives and returns the point size. - * - * @example - *
- * - * let myShader; - * function setup() { - * createCanvas(200, 200, WEBGL); - * myShader = baseMaterialShader().modify(() => { - * getPointSize(size => { - * // Make points pulse in size over time - * return size * (1.0 + 0.5 * sin(millis() * 0.002)); - * }); - * }); - * } - * function draw() { - * background(255); - * shader(myShader); - * strokeWeight(20); - * stroke('blue'); - * point(0, 0); - * } - * - *
- */ + */ \ No newline at end of file From e73b52431c1ba48d05d406e7f33d5c3aa2032f73 Mon Sep 17 00:00:00 2001 From: Abhayaj247 Date: Fri, 11 Jul 2025 14:02:41 +0530 Subject: [PATCH 6/6] Add documentation for remaining public shader hooks in ShaderGenerator.js --- src/webgl/ShaderGenerator.js | 339 ++++++++++++++++++++++++++++++++++- 1 file changed, 333 insertions(+), 6 deletions(-) diff --git a/src/webgl/ShaderGenerator.js b/src/webgl/ShaderGenerator.js index 5fa695d4a9..999152e56b 100644 --- a/src/webgl/ShaderGenerator.js +++ b/src/webgl/ShaderGenerator.js @@ -1644,9 +1644,8 @@ if (typeof p5 !== 'undefined') { /* ------------------------------------------------------------- */ /** * @function getWorldInputs - * @experimental * @description - * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside baseMaterialShader().modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied. + * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside baseColorShader().modify() and similar shader modify calls to customize vertex positions, normals, texture coordinates, and colors before rendering. "World space" refers to the coordinate system of the 3D scene, before any camera or projection transformations are applied. * * This hook is available in: * - baseMaterialShader() @@ -1687,7 +1686,6 @@ if (typeof p5 !== 'undefined') { /** * @function combineColors - * @experimental * @description * Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside baseMaterialShader().modify() and similar shader modify calls to control the final color output of a material. The callback receives an object with the following properties: * @@ -1704,9 +1702,6 @@ if (typeof p5 !== 'undefined') { * * This hook is available in: * - baseMaterialShader() - * - baseNormalShader() - * - baseColorShader() - * - baseStrokeShader() * * @param {function} callback * A callback function which receives the object described above and returns a vector with four components for the final color. @@ -1746,4 +1741,336 @@ if (typeof p5 !== 'undefined') { * } * *
+ */ + +/** + * @function beforeVertex + * @description + * Registers a callback to run custom code at the very start of the vertex shader. This hook can be used inside baseColorShader().modify() and similar shader modify calls to set up variables or perform calculations that affect every vertex before processing begins. The callback receives no arguments. + * + * This hook is available in: + * - baseColorShader() + * - baseMaterialShader() + * - baseNormalShader() + * - baseStrokeShader() + * + * @param {function} callback + * A callback function which is called before each vertex is processed. + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseColorShader().modify(() => { + * beforeVertex(() => { + * // Set up a variable for later use + * let wave = sin(millis() * 0.001); + * }); + * }); + * } + * + *
+ */ + +/** + * @function getObjectInputs + * @description + * Registers a callback to modify the properties of each vertex before any transformations are applied in the vertex shader. This hook can be used inside baseColorShader().modify() and similar shader modify calls to move, color, or otherwise modify the raw model data. The callback receives an object with the following properties: + * - `position`: `[x, y, z]` — the original position of the vertex + * - `normal`: `[x, y, z]` — the direction the surface is facing + * - `texCoord`: `[u, v]` — the texture coordinates + * - `color`: `[r, g, b, a]` — the color of the vertex + * + * Return the modified object to update the vertex. + * + * This hook is available in: + * - baseColorShader() + * - baseMaterialShader() + * - baseNormalShader() + * - baseStrokeShader() + * + * @param {function} callback + * A callback function which receives the vertex object and should return it after making any changes. + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseColorShader().modify(() => { + * getObjectInputs(inputs => { + * // Raise all vertices by 10 units + * inputs.position[1] += 10; + * return inputs; + * }); + * }); + * } + * + *
+ */ + +/** + * @function getCameraInputs + * @description + * Registers a callback to adjust vertex properties after the model has been transformed by the camera, but before projection, in the vertex shader. This hook can be used inside baseColorShader().modify() and similar shader modify calls to create effects that depend on the camera's view. The callback receives an object with the following properties: + * - `position`: `[x, y, z]` — the position after camera transformation + * - `normal`: `[x, y, z]` — the normal after camera transformation + * - `texCoord`: `[u, v]` — the texture coordinates + * - `color`: `[r, g, b, a]` — the color of the vertex + * + * Return the modified object to update the vertex. + * + * This hook is available in: + * - baseColorShader() + * - baseMaterialShader() + * - baseNormalShader() + * - baseStrokeShader() + * + * @param {function} callback + * A callback function which receives the vertex object and should return it after making any changes. + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseColorShader().modify(() => { + * getCameraInputs(inputs => { + * // Tint all vertices blue + * inputs.color[2] = 1.0; + * return inputs; + * }); + * }); + * } + * + *
+ */ + +/** + * @function afterVertex + * @description + * Registers a callback to run custom code at the very end of the vertex shader. This hook can be used inside baseColorShader().modify() and similar shader modify calls to perform cleanup or final calculations after all vertex processing is done. The callback receives no arguments. + * + * This hook is available in: + * - baseColorShader() + * - baseMaterialShader() + * - baseNormalShader() + * - baseStrokeShader() + * + * @param {function} callback + * A callback function which is called after each vertex is processed. + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseColorShader().modify(() => { + * afterVertex(() => { + * // Example: store the y position for use in the fragment shader + * myVarying = position.y; + * }); + * }); + * } + * + *
+ */ + +/** + * @function beforeFragment + * @description + * Registers a callback to run custom code at the very start of the fragment shader. This hook can be used inside baseColorShader().modify() and similar shader modify calls to set up variables or perform calculations that affect every pixel before color calculations begin. The callback receives no arguments. + * + * This hook is available in: + * - baseColorShader() + * - baseMaterialShader() + * - baseNormalShader() + * - baseStrokeShader() + * + * @param {function} callback + * A callback function which is called before each fragment is processed. + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseColorShader().modify(() => { + * beforeFragment(() => { + * // Set up a variable for later use + * let brightness = 0.5; + * }); + * }); + * } + * + *
+ */ + +/** + * @function getPixelInputs + * @description + * Registers a callback to modify the properties of each fragment (pixel) before the final color is calculated in the fragment shader. This hook can be used inside baseMaterialShader().modify() and similar shader modify calls to change opacity or other per-pixel properties. The callback receives an object with the following properties: + * - `opacity`: a number between 0 and 1 for the pixel's transparency + * (Other properties may be available depending on the shader.) + * + * Return the modified object to update the fragment. + * + * This hook is available in: + * - baseMaterialShader() + * - baseStrokeShader() + * + * @param {function} callback + * A callback function which receives the fragment inputs object and should return it after making any changes. + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseMaterialShader().modify(() => { + * getPixelInputs(inputs => { + * // Make the fragment half as opaque + * inputs.opacity *= 0.5; + * return inputs; + * }); + * }); + * } + * + *
+ */ + +/** + * @function shouldDiscard + * @description + * Registers a callback to decide whether to discard (skip drawing) a fragment (pixel) in the fragment shader. This hook can be used inside baseStrokeShader().modify() and similar shader modify calls to create effects like round points or custom masking. The callback receives a boolean: + * - `willDiscard`: true if the fragment would be discarded by default + * + * Return true to discard the fragment, or false to keep it. + * + * This hook is available in: + * - baseStrokeShader() + * + * @param {function} callback + * A callback function which receives a boolean and should return a boolean. + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseStrokeShader().modify(() => { + * shouldDiscard(willDiscard => { + * // Never discard any fragments + * return false; + * }); + * }); + * } + * + *
+ */ + +/** + * @function getFinalColor + * @description + * Registers a callback to change the final color of each pixel after all lighting and mixing is done in the fragment shader. This hook can be used inside baseColorShader().modify() and similar shader modify calls to adjust the color before it appears on the screen. The callback receives a color array: + * - `[r, g, b, a]`: the current color (red, green, blue, alpha) + * + * Return a new color array to change the output color. + * + * This hook is available in: + * - baseColorShader() + * - baseMaterialShader() + * - baseNormalShader() + * - baseStrokeShader() + * + * @param {function} callback + * A callback function which receives the color array and should return a color array. + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseColorShader().modify(() => { + * getFinalColor(color => { + * // Make the output color fully opaque + * color[3] = 1.0; + * return color; + * }); + * }); + * } + * + *
+ */ + +/** + * @function afterFragment + * @description + * Registers a callback to run custom code at the very end of the fragment shader. This hook can be used inside baseColorShader().modify() and similar shader modify calls to perform cleanup or final per-pixel effects after all color calculations are done. The callback receives no arguments. + * + * This hook is available in: + * - baseColorShader() + * - baseMaterialShader() + * - baseNormalShader() + * - baseStrokeShader() + * + * @param {function} callback + * A callback function which is called after each fragment is processed. + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseColorShader().modify(() => { + * afterFragment(() => { + * // Example: darken the final color of each pixel + * finalColor.rgb *= 0.8; + * }); + * }); + * } + * + *
+ */ + +/** + * @function getColor + * @description + * Registers a callback to set the final color for each pixel in a filter shader. This hook can be used inside baseFilterShader().modify() and similar shader modify calls to control the output color for each pixel. The callback receives the following arguments: + * - `inputs`: an object with properties like `texCoord`, `canvasSize`, `texelSize`, etc. + * - `canvasContent`: a sampler2D texture with the sketch's contents before the filter is applied + * + * Return a color array `[r, g, b, a]` for the pixel. + * + * This hook is available in: + * - baseFilterShader() + * + * @param {function} callback + * A callback function which receives the inputs object and canvasContent, and should return a color array. + * + * @example + *
+ * + * let myShader; + * function setup() { + * createCanvas(200, 200, WEBGL); + * myShader = baseFilterShader().modify(() => { + * getColor((inputs, canvasContent) => { + * // Return the original color + * return getTexture(canvasContent, inputs.texCoord); + * }); + * }); + * } + * + *
*/ \ No newline at end of file