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

Abhayaj247 · 2025-06-24T14:56:37Z

Note: This PR replaces #7920 to resolve merge conflicts that occurred while rebasing onto the dev-2.0 branch.

This PR introduces new JSDoc reference entries for several p5.strands hooks, as discussed in #7919 and based on recent feedback.

Key updates:

Added detailed documentation and JavaScript-only usage examples for the following hooks:
- getWorldInputs
- combineColors
- getPointSize
Described callback signatures for each hook.
Placed the new doc comments in src/webgl/p5.strands.js for clarity and modularity.

Request for feedback:

Please review the documentation style, level of detail, and the chosen file location.
If another location is preferred for these comments, I’m happy to move them.

Once I receive feedback and confirmation on the format and placement, I’ll proceed to document the remaining hooks in the same style.

Thank you for your time and guidance!

Abhayaj247 · 2025-06-24T15:01:08Z

Hi @perminder-17 Could you please review this new PR? It replaces the previous one #7920 due to merge conflicts and now targets dev-2.0.

Thank you!

perminder-17

Hi @Abhayaj247, thank you for your work! I noticed you added a new p5.strands.js file under src/webgl just for documentation, but it isn’t referenced anywhere else in the repo. Could you instead place your docs to the end of shaderGenerator.js? That way we avoid adding an unused file and keep things cleaner.

…eparate file

Abhayaj247 · 2025-06-26T14:05:48Z

Hi @Abhayaj247, thank you for your work! I noticed you added a new p5.strands.js file under src/webgl just for documentation, but it isn’t referenced anywhere else in the repo. Could you instead place your docs to the end of shaderGenerator.js? That way we avoid adding an unused file and keep things cleaner.

Hi @perminder-17,

I’ve moved the p5.strands JSDoc documentation to the end of shaderGenerator.js as requested, starting from line 1644. The separate file has been removed.

Could you please confirm if the style, detail, and placement look good? Once you approve, I’ll proceed to document the remaining hooks in the same format.

Please let me know if you’d like any further adjustments. Thank you!

davepagurek · 2025-06-28T16:59:11Z

src/webgl/ShaderGenerator.js

+ * 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}


I think although this is valid JSDoc, we don't yet support it in p5's jsdoc-to-reference pipeline. Currently we use <a href="...">, e.g.:

p5.js/src/type/p5.Font.js

Line 1207 in 0da0430

* <a href="#/p5/setup">setup()</a> before using the result.

Hi @davepagurek ,
I've updated all references to use the <a href="..."> syntax that p5.js supports, following the pattern from p5.Font.js. All links now use the format <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>.

davepagurek · 2025-06-28T17:02:10Z

src/webgl/ShaderGenerator.js

+
+/* ------------------------------------------------------------- */
+/**
+ * @typedef {Object} Vertex


I'm also not sure that typedef docs will show up in the reference, even though this does simplify the writing of the function parameter. If you test your branch on the p5.js-website repo, what does this look like? If it doesn't render, we may need to either document this object inline, or update the website to be able to support this syntax.

@davepagurek Thank you for the guidance on the @typedef issue. I've removed it and documented the vertex object properties inline in the parameter description to ensure clarity and compatibility with the documentation pipeline.

davepagurek · 2025-06-28T17:02:50Z

src/webgl/ShaderGenerator.js

+ * @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}


Similar to above, we probably don't support @see yet, but feel free to use regular links in a paragraph explaining why you might want to check out these related references!

@davepagurek , I've removed all @see tags since they're not supported in the current documentation pipeline. The documentation now relies on clear descriptions and contextual examples to guide users to related references.

davepagurek · 2025-06-28T17:05:49Z

src/webgl/ShaderGenerator.js

+ *   myShader = baseMaterialShader().modify(() => {
+ *     combineColors(components => {
+ *       // Custom color combination: add a red tint
+ *       let color = {


Although you can access .r, .g, .b, and .a properties, the return value would need to be either [r, g, b, a] as an array, or more explicitly, vec4(r, g, b, a) -- we don't yet support an object notation for this. (Also it will need to be just the one object, and not an object with separate color and opacity properties, for it to compile correctly I think.)

This also makes me wonder what the best way to document the inputs object is, since it's not exactly any normal type. @lukeplowden do you have any thoughts on this? We could call it a vec4 and then explain in the description of the function what this means, or even not give it a type at all, and just have an explanation in the description.

Although you can access .r, .g, .b, and .a properties, the return value would need to be either [r, g, b, a] as an array, or more explicitly, vec4(r, g, b, a) -- we don't yet support an object notation for this. (Also it will need to be just the one object, and not an object with separate color and opacity properties, for it to compile correctly I think.)

@davepagurek , I've corrected the combineColors example to return vec4(r, g, b, a) instead of object notation. The example now properly demonstrates the correct return format that will compile successfully.

This also makes me wonder what the best way to document the inputs object is, since it's not exactly any normal type. @lukeplowden do you have any thoughts on this? We could call it a vec4 and then explain in the description of the function what this means, or even not give it a type at all, and just have an explanation in the description.

Excellent point about the input object documentation. I've updated the parameter descriptions to clearly specify the available properties without using complex type annotations. For getWorldInputs, I've documented the vertex object properties inline, and for combineColors, I've listed all available color component properties in the description.

Abhayaj247 · 2025-06-29T09:09:18Z

Thank you for the comprehensive feedback @davepagurek . I've addressed all the documentation compatibility issues:

Updated all links to use the supported <a href="..."> syntax

Removed @typedef and documented properties inline

Removed unsupported @see tags

Corrected the combineColors return format to use vec4(r, g, b, a)

Improved parameter documentation with clear property descriptions

The documentation should now be fully compatible with the current p5.js documentation pipeline.

If there are any other modifications or improvements you’d like to see, please let me know—I'm happy to make further adjustments as needed.

davepagurek · 2025-07-04T22:00:51Z

src/webgl/ShaderGenerator.js

@@ -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.


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.)

/** * @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.

davepagurek · 2025-07-04T22:02:58Z

src/webgl/ShaderGenerator.js

+ * 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.
+ *
+ * This hook is available in:
+ * - <a href="#/p5/baseMaterialShader">baseMaterialShader()</a>


Looks great!

@davepagurek Thank you! I appreciate your guidance throughout this process. If there’s anything else you’d like me to adjust or clarify, please let me know.

davepagurek · 2025-07-04T22:03:49Z

src/webgl/ShaderGenerator.js

+ */
+
+/**
+ * @function getPointSize


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

baseColorShader()

baseFilterShader()

baseMaterialShader()

baseNormalShader()

baseStrokeShader()

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.

/** * @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.

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

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.

…iner feedback

Abhayaj247 · 2025-07-09T14:43:09Z

@davepagurek Thank you for your thoughtful feedback and guidance throughout this process. I have addressed all the points you raised:

The documentation for combineColors now describes 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 uses array notation for vector properties.
The documentation for getPointSize has been updated to reference only the public base shaders, with a clear and readable format.
All other formatting and clarity suggestions have been incorporated as well.

Please see the updated code blocks above for reference.

If you have any further suggestions or would like additional adjustments, I’m happy to make them!

davepagurek · 2025-07-09T17:07:17Z

Thanks @Abhayaj247, the docs are looking good! I think maybe we're ready to give the other hooks the same treatment now.

…c shaders

Abhayaj247 · 2025-07-10T06:41:45Z

Thanks @Abhayaj247, the docs are looking good! I think maybe we're ready to give the other hooks the same treatment now.

@davepagurek Thank you so much for your guidance and support throughout this process! I’m glad the documentation updates meet your expectations. I’ll proceed to document the remaining hooks in the same style.
Please let me know if you have any specific preferences or additional feedback as I work on those.

Abhayaj247 · 2025-07-10T14:29:40Z

Hi @davepagurek ,

As I continue updating the shader documentation, I’ve reviewed the codebase and found these hooks as the remaining ones that appear to be public or user-facing:

beforeVertex
afterVertex
beforeFragment
afterFragment
getFinalColor
shouldDiscard
getLocalNormal
getWorldNormal
getUV
getVertexColor

Additionally, I noticed hooks like getLinePosition, getLineCenter, and getStrokeWeight in the codebase, but they aren’t referenced in the main documentation. My understanding is that these are likely internal, but please let me know if you’d like them included as well.

Could you please confirm that this list covers all the hooks intended for user documentation? Once confirmed, I’ll proceed to document them in the new style.

Thank you for your guidance!

davepagurek · 2025-07-10T19:48:50Z

Hi @Abhayaj247! I think some of those, e.g. getUV, are from 1.x using an earlier beta of the hooks API, and are no longer present in the 2.0 branch. The ones to document are the ones in the tables on these pages on the beta.p5js.org 2.0 reference:

Abhayaj247 · 2025-07-11T06:16:08Z

Hi @davepagurek Thank you for clarifying! I’ll reference the tables on the official 2.0 beta documentation pages and ensure that only those hooks are documented. I’ll update the docs accordingly and let you know once it’s ready for review.

…r.js

Abhayaj247 · 2025-07-11T08:36:06Z

Hi @davepagurek

I’ve now added documentation for the remaining hooks listed in the tables for the following shaders in the 2.0 reference :

The newly documented hooks are :

beforeVertex
getObjectInputs
getCameraInputs
afterVertex
beforeFragment
getPixelInputs
shouldDiscard
getFinalColor
afterFragment
getColor

The hooks getWorldInputs and combineColors were already documented in previous updates.

Please let me know if there are any further adjustments or if you’d like me to include any additional hooks.

Thank you again for your guidance!

docs: Add initial draft of Strands documentation

a3aeaa2

Abhayaj247 mentioned this pull request Jun 24, 2025

[WIP] Docs: Add reference entries for p5.strands hooks (feedback wanted) #7920

Closed

perminder-17 self-requested a review June 24, 2025 15:13

perminder-17 requested changes Jun 26, 2025

View reviewed changes

docs: move p5.strands JSDoc to end of shaderGenerator.js and remove s…

8e199d8

…eparate file

Abhayaj247 requested a review from perminder-17 June 26, 2025 14:07

davepagurek reviewed Jun 28, 2025

View reviewed changes

docs: fix JSDoc syntax for p5.js compatibility

c9d07c1

Abhayaj247 requested a review from davepagurek June 29, 2025 09:14

davepagurek reviewed Jul 4, 2025

View reviewed changes

docs: clarify combineColors and getPointSize documentation per mainta…

06cf619

…iner feedback

Abhayaj247 requested a review from davepagurek July 9, 2025 14:45

docs: remove getPointSize documentation as it is not present in publi…

1d01ca8

…c shaders

Abhayaj247 force-pushed the update-strands-docs branch 2 times, most recently from 4e5489f to 1d01ca8 Compare July 11, 2025 08:31

Add documentation for remaining public shader hooks in ShaderGenerato…

e73b524

…r.js

Uh oh!

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

Abhayaj247 commented Jun 24, 2025

Uh oh!

Abhayaj247 commented Jun 24, 2025

Uh oh!

perminder-17 left a comment

Choose a reason for hiding this comment

Uh oh!

Abhayaj247 commented Jun 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Abhayaj247 Jun 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Abhayaj247 Jun 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Abhayaj247 commented Jun 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Abhayaj247 Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Abhayaj247 commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davepagurek commented Jul 9, 2025

Uh oh!

Abhayaj247 commented Jul 10, 2025

Uh oh!

Abhayaj247 commented Jul 10, 2025

Uh oh!

davepagurek commented Jul 10, 2025

Uh oh!

Abhayaj247 commented Jul 11, 2025

Uh oh!

Abhayaj247 commented Jul 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Abhayaj247 Jun 29, 2025 •

edited

Loading

Abhayaj247 Jun 29, 2025 •

edited

Loading

Abhayaj247 commented Jun 29, 2025 •

edited

Loading

Abhayaj247 Jul 9, 2025 •

edited

Loading

Abhayaj247 commented Jul 9, 2025 •

edited

Loading

Abhayaj247 commented Jul 11, 2025 •

edited

Loading