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

src/webgl/ShaderGenerator.js

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-08-08T17:49:59Z

Hi @davepagurek

Quick check on shouldDiscard: I changed the example to the string-based form to avoid the earlier runtime error.


myShader = baseStrokeShader().modify({
  'bool shouldDiscard': '(bool outside) { return outside; }'
});

It renders correctly (3D → Stroke) with no console errors. Is this usage/signature what you’d like to show, or would you prefer a version that produces a more visible effect (e.g., always keep: return false;, or always discard: return true;)? Happy to adjust.

📸 shouldDiscard
Attached Screenshot/Video below:

Abhayaj247 · 2025-08-08T17:59:37Z

Thanks for the detailed review! @davepagurek , I’ve addressed each point:

1. Uniform scope: Moved the uniformFloat(() => millis()) declarations inside modify() but outside the callbacks (both getPixelInputs and getObjectInputs).
1. getFinalColor docs: Updated to say “a four component vector representing red, green, blue, and alpha” for consistency.
1. getFinalColor example: Removed color.a = 1 and switched to a clearer change: color.b += 0.2.
1. getColor example: Left as-is (thanks!).
1. getObjectInputs amplitude: Reduced from 20 to 0.5 to match the -1..1 object-space range.
1. getObjectInputs uniform scope: Moved the uniform declaration up into modify() (same pattern as IDEs #1).
1. getColor docs (properties): Expanded into a nested bullet list with clear descriptions (texCoord, canvasSize, texelSize, color, and what they represent).
1. getPixelInputs field + docs: Replaced inputs.opacity (not a field) with inputs.color.a animation. Also updated docs to list properties for both Material and Stroke shaders, so users see exactly what’s available.

Key example updates:


// getPixelInputs
myShader = baseMaterialShader().modify(() => {
  let t = uniformFloat(() => millis());
  getPixelInputs(inputs => {
    if (inputs.color && inputs.texCoord) {
      inputs.color.a = 0.5 + 0.5 * sin(inputs.texCoord.x * 10.0 + t * 0.002);
    }
    return inputs;
  });
});

// getObjectInputs
myShader = baseColorShader().modify(() => {
  let t = uniformFloat(() => millis());
  getObjectInputs(inputs => {
    inputs.position.y += 0.5 * sin(inputs.position.x * 0.1 + t * 0.002);
    return inputs;
  });
});

// getFinalColor
getFinalColor(color => {
  color.b += 0.2;
  return color;
});

I've made all the requested changes. If you have a moment, could you please review and let me know if any further adjustments are needed?

Thank you for your time!

Abhayaj247 · 2025-08-08T18:11:31Z

@davepagurek I’ve now gone through all hooks and their examples in the local reference build. Everything appears and renders correctly. When you have a moment, could you please review on your end as well and let me know if you spot anything else?

Thank you!

davepagurek · 2025-08-08T19:50:09Z

src/webgl/ShaderGenerator.js

+ *   - `texCoord`: a vector with two components representing the texture coordinates (u, v)
+ *   - `canvasSize`: a vector with two components representing the canvas size in pixels (width, height)
+ *   - `texelSize`: a vector with two components representing the size of a single texel in texture space
+ *   - `color`: a vector with four components representing the current pixel color (red, green, blue, alpha)


This isn't one of the input properties, we can take this line out.

Removed the color property from the getColor parameters list since it’s not an actual input property.

davepagurek · 2025-08-08T19:52:34Z

src/webgl/ShaderGenerator.js

+ *     let t = uniformFloat(() => millis());
+ *     getPixelInputs(inputs => {
+ *       // Animate alpha (transparency) based on x position
+ *       if (inputs.color && inputs.texCoord) {


These properties will always exist, we don't need an if statement here.

Removed the if check for inputs.color and inputs.texCoord as these properties are always present.

davepagurek · 2025-08-08T19:54:25Z

src/webgl/ShaderGenerator.js

+ *   lights();
+ *   noStroke();
+ *   fill('purple');
+ *   sphere(50);


I noticed that this example has some weird artifacts when animating. I'm pretty sure this is just because of the fact that drawing semitransparent stuff in 3D is currently difficult and is order-dependent. But, if we switch sphere(50) to circle(0, 0, 100), it looks great in 2D. Maybe let's do that to avoid the issues?

Screen.Recording.2025-08-08.at.3.51.34.PM.mov

Updated the example to use circle(0, 0, 100) instead of sphere(50) to avoid 3D transparency artifacts.

davepagurek · 2025-08-08T19:55:40Z

src/webgl/ShaderGenerator.js

+ *     getWorldInputs(inputs => {
+ *       // Move the vertex up and down in a wave in world space
+ *       // In world space, moving the object (e.g., with translate()) will affect these coordinates
+ *       inputs.position.y += 0.5 * sin(t * 0.001 + inputs.position.x * 0.05);


I think maybe the wrong one got updated -- a scale of 20 makes sense here because in world space, the sphere is 50 units tall. The update to change the scale to 0.5 was for object space where the sphere is 2 units tall.

Suggested change

* inputs.position.y += 0.5 * sin(t * 0.001 + inputs.position.x * 0.05);

* inputs.position.y += 20 * sin(t * 0.001 + inputs.position.x * 0.05);

Changed the wave displacement scale from 0.5 to 20 for the world-space example, matching the object’s actual size.

src/webgl/ShaderGenerator.js

davepagurek · 2025-08-08T19:59:07Z

src/webgl/ShaderGenerator.js

+/**
+ * @method getWorldInputs
+ * @description
+ * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside <a href="#/p5/baseColorShader">baseColorShader()</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.


getWorldInputs doesn't yet have a description of the parameters to inputs. It has the same inputs as getObjectInputs and getCameraInputs, can we copy and paste the properties bullet list from one of those here?

Added a parameters bullet list for getWorldInputs, matching the format and content from getObjectInputs/getCameraInputs.

Abhayaj247 · 2025-08-09T10:12:55Z

Thanks for the detailed review! @davepagurek , I’ve addressed each point:

getColor docs: Removed the color property from the parameter list since it’s not an actual input property.
getPixelInputs example: Removed the unnecessary if checks for inputs.color and inputs.texCoord, as these are always present.
Shape example: Updated sphere(50) to circle(0, 0, 100) to avoid 3D transparency artifacts in the example.
getWorldInputs wave example: Changed the displacement scale from 0.5 to 20 to better match the object’s actual size in world space.
shouldDiscard method: Added the @private JSDoc tag as suggested.
getWorldInputs docs: Added a parameters bullet list (position, normal, texCoord, color) to match the style of getObjectInputs/getCameraInputs.

All requested changes have been made. Please let me know if you spot anything else that needs adjusting.

Thank you for your guidance!

perminder-17

Hi @Abhayaj247 thanks for your work on this, it mostly looks good to me, just a few minor suggestions on the examples and docs. Really thanks for your hard work and patience. :)

perminder-17 · 2025-08-18T15:10:59Z

src/webgl/ShaderGenerator.js

+/**
+ * @method getWorldInputs
+ * @description
+ * Registers a callback to modify the world-space properties of each vertex in a shader. This hook can be used inside <a href="#/p5/baseColorShader">baseColorShader()</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.


Probably you could attach a link here for modify where you write:

similar shader .modify() calls to customize.....

It should look something like this.

Thanks for pointing this out! I’ve added a link to .modify() so it’s consistent with other references.

perminder-17 · 2025-08-18T15:13:22Z

src/webgl/ShaderGenerator.js

+ * - <a href="#/p5/baseColorShader">baseColorShader()</a>
+ * - <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>
+ *
+ * @param {function} callback


Suggested change

* @param {function} callback

* @param {Function} callback

Probably you could use Function wherever you used it in lowercase

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

perminder-17 · 2025-08-18T15:36:46Z

src/webgl/ShaderGenerator.js

+ *   shader(myShader);
+ *   lights();
+ *   noStroke();
+ *   fill('red');


When you use fill('red'), the red tint dominates and your custom color mix can’t show clearly. Probably you could remove fill() or use fill(255) (white) so your shader’s color shows as intended. Thanks :)

Makes sense - I’ve replaced fill('red') with fill('white') so the shader’s colors show clearly.

perminder-17 · 2025-08-18T15:41:10Z

src/webgl/ShaderGenerator.js

+/**
+ * @method combineColors
+ * @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:


similar shader modify calls to

similarly here as well, use .modify() with link

Done ✅ I’ve updated this section to use .modify() with a link for clarity.

perminder-17 · 2025-08-18T15:50:17Z

src/webgl/ShaderGenerator.js

+ *   - `normal`: a vector with three components representing the surface normal
+ *   - `texCoord`: a vector with two components representing the texture coordinates (u, v)
+ *   - `ambientLight`: a vector with three components representing the ambient light color
+ *   - `ambientMaterial`: a vector with three components representing the material's ambient color
+ *   - `specularMaterial`: a vector with three components representing the material's specular color
+ *   - `emissiveMaterial`: a vector with three components representing the material's emissive color
+ *   - `color`: a vector with four components representing the base color (red, green, blue, alpha)
+ *   - `shininess`: a number controlling specular highlights
+ *   - `metalness`: a number controlling the metalness factor


In these, wherever you write "a vector with three components" would it be nice when you write "a three-component vector" and also, after every sentence you should give a period .. What you think?

Great suggestion! I’ve rephrased those to “a three-component vector” and added periods at the end of each line.

perminder-17 · 2025-08-18T15:51:02Z

src/webgl/ShaderGenerator.js

+ *   - `color`: a vector with four components representing the stroke color (red, green, blue, alpha)
+ *   - `tangent`: a vector with two components representing the stroke tangent
+ *   - `center`: a vector with two components representing the cap/join center
+ *   - `position`: a vector with two components representing the current fragment position
+ *   - `strokeWeight`: a number representing the stroke weight in pixels


Here also, rephrasing it and adding a period ..

Applied the same rephrasing and punctuation improvements here as well 👍.

perminder-17 · 2025-08-18T15:55:12Z

src/webgl/ShaderGenerator.js

+ *   myShader = baseColorShader().modify(() => {
+ *     getFinalColor(color => {
+ *       // Add a blue tint to the output color
+ *       color.b += 0.2;


The blue effect is very minimal from the shader when I saw the sketch, could you use 0.4 instead of 0.2?

Thanks - I’ve increased the blue tint to 0.4 so the effect is more noticeable.

perminder-17 · 2025-08-18T16:05:12Z

src/webgl/ShaderGenerator.js

+ *     let t = uniformFloat(() => millis());
+ *     getObjectInputs(inputs => {
+ *       // Create a sine wave along the x axis in object space
+ *       inputs.position.y += 20 * sin(t * 0.001 + inputs.position.x * 0.05);


A very minor suggestion, 20 is too high, the sphere goes off the canvas for long time. Use 2 or 3 instead, so the wave stays visible and the sphere stays in view.

Good point 🙂 I’ve reduced the sine wave amplitude to 3 so the sphere stays visible within the canvas.

perminder-17 · 2025-08-18T16:10:01Z

src/webgl/ShaderGenerator.js

+ *   shader(myShader);
+ *   noStroke();
+ *   fill('blue');
+ *   sphere(100);


Since the canvas is 200×200, sphere(100) has a 200-pixel diameter and reaches the edges. Can we switch to sphere(50) so it stays comfortably within the canvas?

Makes sense - I’ve updated sphere(100) to sphere(50) so it fits comfortably within the canvas.

…, wording, and shader examples for clarity and consistency

Abhayaj247 · 2025-08-19T07:52:18Z

Hi @perminder-17 ,

Thanks a lot for the detailed review 🙌 I’ve gone through your comments and made the suggested changes :

1. Added links for .modify() references where mentioned.
2. Updated @param {function} to @param {Function} consistently.
3. Removed fill('red') and replaced with fill('white') so the shader colors show correctly.
4. Rephrased “a vector with three components” → “a three-component vector” and added periods at the end of each line for consistency.
5. Applied the same rephrasing and punctuation improvements in stroke-related docs.
6. Increased the blue tint value from 0.2 → 0.4 for better visibility.
7. Reduced sine wave amplitude from 20 → 3 to keep the sphere in view.
8. Changed sphere(100) → sphere(50) so it fits comfortably in the 200×200 canvas.

All requested changes have been made. Please let me know if you spot anything else that needs adjusting.

Thank you for your guidance!

davepagurek · 2025-08-19T23:01:59Z

src/webgl/ShaderGenerator.js

+ *   background(200);
+ *   shader(myShader);
+ *   noStroke();
+ *   fill('blue');


Currently the inputs.color.b = 1 has no effect if you comment it out because the input color's blue channel is already maxed out from the fill('blue') here. Can we use fill('red') so that we get a visible color change?

Good point 👍 I’ve changed fill('blue') to fill('red') so the effect of modifying the blue channel is clearly visible.

davepagurek · 2025-08-19T23:04:42Z

src/webgl/ShaderGenerator.js

+ *   shader(myShader);
+ *   noStroke();
+ *   fill('orange');
+ *   sphere(100);


@perminder-17 mentioned it on another example, but on here too sphere(100) fills the canvas entirely, I think sphere(50) leaves some room for it to go up and down:

Screen.Recording.2025-08-19.at.7.02.27.PM.mov

Thanks for catching that! I’ve updated sphere(100) to sphere(50) so it fits better within the canvas.

davepagurek · 2025-08-19T23:06:25Z

src/webgl/ShaderGenerator.js

+ *     let t = uniformFloat(() => millis());
+ *     getObjectInputs(inputs => {
+ *       // Create a sine wave along the x axis in object space
+ *       inputs.position.y += 3 * sin(t * 0.001 + inputs.position.x * 0.05);


The 3 here is also so large it goes off canvas (object space, for a sphere, goes between -1 and 1). Similarly, the small scale on inputs.position.x causes it to not have a very visible impact. Multipliers of 1 look decent here, meaning we can just take both multipliers out:

Suggested change

* inputs.position.y += 3 * sin(t * 0.001 + inputs.position.x * 0.05);

* inputs.position.y += sin(t * 0.001 + inputs.position.x);

Makes sense - I’ve simplified the sine wave expression by removing the multipliers as suggested. It now uses:

inputs.position.y += sin(t * 0.001 + inputs.position.x);

davepagurek

This is really close to being there! I took a look at the docs in the p5 website locally, and noticed the three small things I commented above. After that we're good to merge!

…size, and simplifying sine wave example

Abhayaj247 · 2025-08-20T05:58:47Z

Hi @davepagurek ,

Thanks a lot for the detailed review 🙌 I’ve gone through your comments and made the suggested changes :

- Changed fill('blue') to fill('red') so the blue channel modification is clearly visible.
- Updated sphere(100) to sphere(50) to ensure it fits comfortably within the canvas.
- Simplified the sine wave example by removing the multipliers as suggested, using:
inputs.position.y += sin(t * 0.001 + inputs.position.x);

All requested changes have been made. Please let me know if you’d like any further refinements. 🚀

Thank you for your guidance!

Abhayaj247 · 2025-08-20T06:14:15Z

Hi @davepagurek , I’ve addressed the feedback you shared. Once this looks good, could you please let me know if there are any additional steps required before merging?For example, do I need to open a separate pull request following a specific PR format, or will this one be merged directly?

Also, if you feel any further adjustments are needed, please let me know and I’ll be happy to update. Thanks 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

src/webgl/ShaderGenerator.js Show resolved Hide resolved

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

Abhayaj247 force-pushed the update-strands-docs branch from 3b3437c to 36c4c2d Compare August 8, 2025 16:51

Fix shouldDiscard example

6e1311d

Abhayaj247 force-pushed the update-strands-docs branch from f4872c4 to 6e1311d Compare August 8, 2025 17:14

Abhayaj247 added 2 commits August 8, 2025 22:47

Fix getPixelInputs description and getFinalColor example

58d8e5d

Fix getPixelInputs description and getColor description

483edcb

davepagurek reviewed Aug 8, 2025

View reviewed changes

src/webgl/ShaderGenerator.js Outdated Show resolved Hide resolved

davepagurek reviewed Aug 8, 2025

View reviewed changes

Address Maintainer feedbacks: Update ShaderGenerator docs and examples

29fbe52

perminder-17 reviewed Aug 18, 2025

View reviewed changes

Abhayaj247 added 2 commits August 19, 2025 13:00

Address maintainer feedback by refining references, param annotations…

be56924

…, wording, and shader examples for clarity and consistency

updated .modify() links

17992d7

Abhayaj247 requested review from perminder-17 and davepagurek August 19, 2025 08:09

davepagurek reviewed Aug 19, 2025

View reviewed changes

Address maintainer feedback by updating fill color, adjusting sphere …

ff81847

…size, and simplifying sine wave example

Abhayaj247 requested a review from davepagurek August 20, 2025 06:05

	* inputs.position.y += 0.5 * sin(t * 0.001 + inputs.position.x * 0.05);
	* inputs.position.y += 20 * sin(t * 0.001 + inputs.position.x * 0.05);

	* inputs.position.y += 3 * sin(t * 0.001 + inputs.position.x * 0.05);
	* inputs.position.y += sin(t * 0.001 + inputs.position.x);

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!

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 Aug 8, 2025

Uh oh!

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

Uh oh!

Uh oh!

Abhayaj247 commented Aug 8, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Abhayaj247 Aug 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

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 Aug 8, 2025 •

edited

Loading

Abhayaj247 Aug 9, 2025 •

edited

Loading

Abhayaj247 commented Aug 9, 2025 •

edited

Loading