Skip to content

[WIP] Docs: Add initial draft of Strands documentation (feedback wanted) #7940

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Sep 5, 2025
Merged

[WIP] Docs: Add initial draft of Strands documentation (feedback wanted) #7940

Changes from 1 commit
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
a3aeaa2
docs: Add initial draft of Strands documentation
Abhayaj247 Jun 24, 2025
8e199d8
docs: move p5.strands JSDoc to end of shaderGenerator.js and remove s…
Abhayaj247 Jun 26, 2025
c9d07c1
docs: fix JSDoc syntax for p5.js compatibility
Abhayaj247 Jun 29, 2025
06cf619
docs: clarify combineColors and getPointSize documentation per mainta…
Abhayaj247 Jul 9, 2025
1d01ca8
docs: remove getPointSize documentation as it is not present in publi…
Abhayaj247 Jul 10, 2025
e73b524
Add documentation for remaining public shader hooks in ShaderGenerato…
Abhayaj247 Jul 11, 2025
6b54ecd
Address maintainer feedback: update shader hook docs and examples for…
Abhayaj247 Jul 17, 2025
1146190
Update ShaderGenerator docs and examples
Abhayaj247 Aug 7, 2025
36c4c2d
Address maintainer feedback: Update ShaderGenerator docs and examples
Abhayaj247 Aug 8, 2025
6e1311d
Fix shouldDiscard example
Abhayaj247 Aug 8, 2025
58d8e5d
Fix getPixelInputs description and getFinalColor example
Abhayaj247 Aug 8, 2025
483edcb
Fix getPixelInputs description and getColor description
Abhayaj247 Aug 8, 2025
29fbe52
Address Maintainer feedbacks: Update ShaderGenerator docs and examples
Abhayaj247 Aug 9, 2025
be56924
Address maintainer feedback by refining references, param annotations…
Abhayaj247 Aug 19, 2025
17992d7
updated .modify() links
Abhayaj247 Aug 19, 2025
ff81847
Address maintainer feedback by updating fill color, adjusting sphere …
Abhayaj247 Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 34 additions & 52 deletions src/webgl/ShaderGenerator.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>.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}
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
*
* @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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* @param {function} callback
* @param {Function} callback

Probably you could use Function wherever you used it in lowercase

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’ve updated @param {function} to @param {Function} throughout for consistency.

* 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
* <div modernizr='webgl'>
Expand Down Expand Up @@ -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 <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>.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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we describe the input as being an object with the properties baseColor, diffuse, ambientColor, etc? I think it would be important to describe the size of each item (e.g. position/normal are vec3s, texture coordinates are vec2s, color is a vec4) -- although maybe rather than using terms like vec3 we could describe it as "a vector with three components" to avoid referencing the vec3 type, since there aren't user-facing docs for that yet. A bullet list might work if that's too much info to put in one sentence.

One other note is that when we refer to a name of a property/variable/etc in code, such as when listing properties here, we should put the names in backticks so they render as code (baseColor instead of baseColor.)

Copy link
Author

@Abhayaj247 Abhayaj247 Jul 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

/**
 * @function combineColors
 * @experimental
 * @description
 * Registers a callback to customize how color components are combined in the fragment shader. This hook can be used inside <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>.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:
 * - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
 * - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
 * - <a href="#/p5/baseColorShader">baseColorShader()</a>
 * - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
 * - <a href="#/p5/baseFilterShader">baseFilterShader()</a>
 *
 * @param {function} callback
 *        A callback function which receives the object described above and returns a vector with four components for the final color.
 *
 * @example
 * <div modernizr='webgl'>
 * <code>
 * let myShader;
 * function setup() {
 *   createCanvas(200, 200, WEBGL);
 *   myShader = baseMaterialShader().modify(() => {
 *     combineColors(components => {
 *       // Custom color combination: add a red tint
 *       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];
 *     });
 *   });
 * }
 * function draw() {
 *   background(255);
 *   shader(myShader);
 *   lights();
 *   noStroke();
 *   fill('red');
 *   sphere(50);
 * }
 * </code>
 * </div>
 */

@davepagurek Thank you for your feedback! I’ve updated the documentation for combineColors to describe the input as an object with each property listed in a bullet list, using backticks for property names and describing the size of each in plain language. The example now uses array notation for vector properties. Please let me know if you’d like any further adjustments.

*
* 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.
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
*
* @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
* <div modernizr='webgl'>
Expand All @@ -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);
* });
* });
* }
Expand All @@ -1757,20 +1742,17 @@ if (typeof p5 !== 'undefined') {
* @function getPointSize
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a heads up -- currently the only public base shaders are:

The point shader, while it has some hooks, is currently still private, as we may end up using the stroke shader to render points in the future.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

/**
 * @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:
 * - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>.modify()
 * - <a href="#/p5/baseNormalShader">baseNormalShader()</a>.modify()
 * - <a href="#/p5/baseColorShader">baseColorShader()</a>.modify()
 * - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>.modify()
 * - <a href="#/p5/baseFilterShader">baseFilterShader()</a>.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:
 * - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
 * - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
 * - <a href="#/p5/baseColorShader">baseColorShader()</a>
 * - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
 * - <a href="#/p5/baseFilterShader">baseFilterShader()</a>
 *
 * @param {function} callback
 *        A callback function which receives and returns the point size.
 *
 * @example
 * <div modernizr='webgl'>
 * <code>
 * 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);
 * }
 * </code>
 * </div>
 */

@davepagurek Thank you for the clarification regarding public base shaders. I’ve updated the documentation for getPointSize to reference only the public shaders and removed any mention of private or internal shaders. Please let me know if you have any further suggestions or preferences.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think getPointSize itself is only present in the base point shader, so I think we don't need this one.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think getPointSize itself is only present in the base point shader, so I think we don't need this one.

@davepagurek Thank you for clarifying! I have removed the documentation for getPointSize since it is only present in the base point shader and not part of the public shaders.
Please let me know if there’s anything else I should update.

* @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 <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>.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}
* - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>
* - <a href="#/p5/baseNormalShader">baseNormalShader()</a>
* - <a href="#/p5/baseColorShader">baseColorShader()</a>
* - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
*
* @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
* <div modernizr='webgl'>
* <code>
Expand Down