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

[Abhayaj247]

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]

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.

[Abhayaj247]

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]

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.

[Abhayaj247]

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]

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.

[Abhayaj247]

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

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!

[Abhayaj247]

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

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]

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.

[Abhayaj247]

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]

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]

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

[Abhayaj247]

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

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.

[Abhayaj247]

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

[davepagurek]

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

[Abhayaj247]

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.

[Abhayaj247]

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

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

[Abhayaj247]

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]

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]

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:

• baseColorShader()
• baseFilterShader()
• baseMaterialShader()
• baseNormalShader()
• baseStrokeShader()

[Abhayaj247]

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.

[davepagurek]

Same as before, let's move this declaration up out of getObjectInputs but still inside of modify

[Abhayaj247]

Done! I've moved the uniformFloat declaration outside of the getObjectInputs callback but still inside the modify function, just like with getPixelInputs.

[davepagurek]

Can we list the properties with descriptions (maybe as a bullet list one level deeper)? These are the docs people look to for reference, so rather than saying etc, we should be explaining all the properties in detail.

[Abhayaj247]

Excellent suggestion! I've updated the getColor documentation to list all the callback properties with detailed descriptions as a bullet list. This provides much better reference material for users.

[davepagurek]

Taking a look at the error in the console, I don't think opacity exists in the material shader's inputs:

Nor the stroke shader:

So we'll need to update this callback to use a property that does exist. Also, we should probably update the docs to have bullet lists of properties for both the material and stroke shaders, since they have different properties.

[Abhayaj247]

Thanks for flagging that! You’re right - opacity isn’t part of the material or stroke shader Inputs.

I’ve updated the getPixelInputs example to use valid fields. It now animates the alpha channel of inputs.color based on texCoord.x, and moves the uniform outside the callback:

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;
  });
});

I also expanded the docs to list the available properties for callbacks (e.g., texCoord, color, etc.) so it’s clear which fields are valid for each shader. Let me know if you’d like me to add any additional fields or clarify further.

[Abhayaj247]

Looking at the combineColors function, I see this error in the console:

I think the problem for this one is that we're combining some scalar values (like baseColor.r) with some vector values (components.ambient):

let r = components.baseColor.r * components.diffuse +
              components.ambientColor.r * components.ambient +
              components.specularColor.r * components.specular +
              components.emissive.r + 0.2;

I think to make this work, we need to consistently use one or the other. So that could mean also doing components.diffuse.r, components.specular.r, etc. Or alternatively, doing the whole combination as a vector operation, e.g.:

return [
        components.baseColor * components.diffuse +
          components.ambientColor * components.ambient +
          components.specularColor * components.specular +
          components.emissive +
          [0.2, 0, 0], // Your extra tint
        components.opacity
      ];

(We may also want to make the tint not be in the red channel since the fill in that example is already red, making the tint harder to notice.)

I haven't looked at the other ones that don't show up just yet but that's my process for figuring out the issue: opening the console and seeing what the error is and then going from there.

Also for what it's worth, the ones that you mentioned appeared but not as 3D do show up in the 3D -> Material section for me, is that what you were referring to? Or do you just mean that it's drawing 2D content?

Thank you for the detailed feedback @davepagurek !

• For combineColors, I see the issue with mixing scalars and vectors. I’ll update the example to use vector operations throughout, as you suggested, and will pick a more visible tint color.
• I’ll also review the other hooks that aren’t appearing by checking for errors in the browser console and fixing any similar issues.
• Regarding that appeared not as 3D the hooks getFinalColor and getColor: they do appear under the 3D → Material section in the reference, but the examples themselves are rendering as 2D shapes (like a flat circle or heart), not as 3D objects. Is this the intended behavior, or should these examples be updated to use 3D primitives for consistency with the section?

I’ll make these updates and follow up with any further questions or fixes. Thanks again for your guidance!

[davepagurek]

I think it's OK that it's not 3D, nesting Material in 3D is a bit of a misnomer since WebGL !== 3D but we don't have to address that here 🙂

[Abhayaj247]

I think it's OK that it's not 3D, nesting Material in 3D is a bit of a misnomer since WebGL !== 3D but we don't have to address that here 🙂

Thank you for clarifying! That makes sense - I’ll leave those examples as they are for now.

[Abhayaj247]

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]

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).
• 2. getFinalColor docs: Updated to say “a four component vector representing red, green, blue, and alpha” for consistency.
• 3. getFinalColor example: Removed color.a = 1 and switched to a clearer change: color.b += 0.2.
• 4. getColor example: Left as-is (thanks!).
• 5. getObjectInputs amplitude: Reduced from 20 to 0.5 to match the -1..1 object-space range.
• 6. getObjectInputs uniform scope: Moved the uniform declaration up into modify() (same pattern as IDEs #1).
• 7. getColor docs (properties): Expanded into a nested bullet list with clear descriptions (texCoord, canvasSize, texelSize, color, and what they represent).
• 8. 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]

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

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

[Abhayaj247]

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

[davepagurek]

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

[Abhayaj247]

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

[davepagurek]

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

[Abhayaj247]

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

[davepagurek]

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

[Abhayaj247]

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

[davepagurek]

I think we talked about marking this one as @private, can we do that?

[Abhayaj247]

Added the @private JSDoc tag to the shouldDiscard method as discussed.

[davepagurek]

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?

[Abhayaj247]

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

[Abhayaj247]

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

1. getColor docs: Removed the color property from the parameter list since it’s not an actual input property.
2. getPixelInputs example: Removed the unnecessary if checks for inputs.color and inputs.texCoord, as these are always present.
3. Shape example: Updated sphere(50) to circle(0, 0, 100) to avoid 3D transparency artifacts in the example.
4. getWorldInputs wave example: Changed the displacement scale from 0.5 to 20 to better match the object’s actual size in world space.
5. shouldDiscard method: Added the @private JSDoc tag as suggested.
6. 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!