[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

davepagurek · 2025-08-08T14:02:19Z

src/webgl/ShaderGenerator.js

+ *   myShader = baseColorShader().modify(() => {
+ *     getObjectInputs(inputs => {
+ *       // Create a sine wave along the x axis in object space
+ *       let t = uniformFloat(() => millis());


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

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

davepagurek · 2025-08-08T14:03:49Z

src/webgl/ShaderGenerator.js

+ * @method getColor
+ * @description
+ * Registers a callback to set the final color for each pixel in a filter shader. This hook can be used inside <a href="#/p5/baseFilterShader">baseFilterShader()</a>.modify() and similar shader modify calls to control the output color for each pixel. The callback receives the following arguments:
+ * - `inputs`: an object with properties like `texCoord`, `canvasSize`, `texelSize`, etc.


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.

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 · 2025-08-08T14:06:54Z

src/webgl/ShaderGenerator.js

+ *     getPixelInputs(inputs => {
+ *       // Animate opacity based on x position
+ *       let t = uniformFloat(() => millis());
+ *       inputs.opacity = 0.5 + 0.5 * sin(inputs.texCoord.x * 10.0 + t * 0.002);


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.

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 · 2025-08-08T14:23:36Z

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 · 2025-08-08T14:26:43Z

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 · 2025-08-08T14:29:33Z

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

davepagurek · 2025-08-08T19:56:32Z

src/webgl/ShaderGenerator.js

+/**
+ * @method shouldDiscard
+ * @description
+ * Registers a callback to decide whether to discard (skip drawing) a fragment (pixel) in the fragment shader. This hook can be used inside <a href="#/p5/baseStrokeShader">baseStrokeShader()</a>.modify() and similar shader modify calls to create effects like round points or custom masking. The callback receives a boolean:


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

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

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!

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

davepagurek reviewed Aug 8, 2025

View reviewed changes

Abhayaj247 force-pushed the update-strands-docs branch from 8dafa9a to 1146190 Compare August 8, 2025 15:10

Address maintainer feedback: Update ShaderGenerator docs and examples

36c4c2d

Abhayaj247 force-pushed the update-strands-docs branch 7 times, most recently 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

Address Maintainer feedbacks: Update ShaderGenerator docs and examples

29fbe52

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

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

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!

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

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