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

Abhayaj247 · 2025-06-18T20:28:01Z

This draft PR adds new JSDoc reference entries for a few p5.strands hooks, following the feedback in #7919.

The new doc comments use JavaScript-only examples and describe the callback signature as discussed.
I’ve included examples for :
getWorldInputs
combineColors
getPointSize
The doc comments are currently placed in a new file :

src/webgl/p5.strands.js

(Open to moving them if you prefer a different location.)

Could you please review the style, level of detail, and file location?

Once confirmed, I’ll update the rest of the hooks in the same format.

Thanks for your guidance!

welcome · 2025-06-18T20:28:04Z

🎉 Thanks for opening this pull request! Please check out our contributing guidelines if you haven't already. And be sure to add yourself to the list of contributors on the readme page!

lukeplowden

I would be inclined to give a little bit more context for each of the hook functions. For now this is the only presence of p5.strands in the documentation. I would mention where these functions can be used, and explain what world space is, for example. Let me know if you need help with that as it's a newer feature

lukeplowden · 2025-06-18T23:04:29Z

src/webgl/p5.strands.js

+ *   myShader = baseMaterialShader().modify(() => {
+ *     getWorldInputs((inputs) => {
+ *       // Move the vertex up and down in a wave
+ *       inputs.position.y += 20 * Math.sin(millis() * 0.001 + inputs.position.x * 0.05);


In this case, you have to use sin() not Math.sin!

Updated the example to use sin() instead of Math.sin() as suggested.

// Before: inputs.position.y += 20 * Math.sin(millis() * 0.001 + inputs.position.x * 0.05); // After: inputs.position.y += 20 * sin(millis() * 0.001 + inputs.position.x * 0.05);

lukeplowden · 2025-06-19T23:09:32Z

src/webgl/p5.strands.js

+ * @function getWorldInputs
+ * @experimental
+ * @description
+ * Registers a callback to modify world-space vertex inputs for each vertex.


Maybe 'vertex inputs for each vertex' is a bit redundant here. I would remove the 'for each vertex' part or reword slightly

Reworded the description to remove redundancy and improve clarity.

// Before: * Registers a callback to modify world-space vertex inputs for each vertex. // After: * Registers a callback to modify the world-space properties of each vertex in a shader.

lukeplowden · 2025-06-19T23:13:23Z

src/webgl/p5.strands.js

+ * - {@link p5.baseStrokeShader}
+ *
+ * @param {function(inputs: { position: {x: number, y: number, z: number}, normal: {x: number, y: number, z: number}, texCoord: {x: number, y: number}, color: {r: number, g: number, b: number, a: number} }): object} callback
+ *        A function that receives the current inputs and returns the modified inputs.


Maybe something like "a callback function which receives and returns a Vertex struct."

Updated the callback parameter description to reference a Vertex struct and added a @typedef for clarity.

/** * @typedef {Object} Vertex * @property {{x: number, y: number, z: number}} position - The position of the vertex in world space. * @property {{x: number, y: number, z: number}} normal - The normal vector at the vertex in world space. * @property {{x: number, y: number}} texCoord - The texture coordinates (x, y) for the vertex. * @property {{r: number, g: number, b: number, a: number}} color - The color at the vertex. */ /** * @param {function(Vertex): Vertex} callback * A callback function which receives and returns a Vertex struct. */

lukeplowden · 2025-06-19T23:17:36Z

src/webgl/p5.strands.js

+ * The callback receives the current point size (number) and should return the new size (number).
+ *
+ * This hook is available in:
+ * - {@link p5.pointShader}


Do we have a point shader?

Removed the reference to p5.pointShader and only listed the correct shaders for each hook.

// Before: * This hook is available in: * - {@link p5.pointShader} // After: * This hook is available in: * - {@link p5.baseMaterialShader} * - {@link p5.baseNormalShader} * - {@link p5.baseColorShader} * - {@link p5.baseStrokeShader}

Abhayaj247 · 2025-06-20T08:03:19Z

Thank you for the review and detailed feedback @lukeplowden .

I have made the following updates to address all the points :

Added more context and explanations for each hook, including where these functions can be used (e.g., inside baseMaterialShader().modify()) and an explanation of what “world space” means.
Updated all code examples to use sin() instead of Math.sin().
Reworded the phrase “vertex inputs for each vertex” for clarity and to avoid redundancy.
Callback parameters are now described as receiving and returning a Vertex struct, and I have added a @typedef for Vertex at the top of the file.
Removed the reference to p5.pointShader and only listed the correct shaders for each hook.

Please let me know if there’s anything else I should update. Thank you!

Abhayaj247 · 2025-06-20T08:12:06Z

Hi @lukeplowden ,

I have addressed all the feedback and updated the documentation accordingly. If everything looks good and the changes are correct, please let me know so I can proceed with documenting the remaining hooks in the same style.

Or, if any further changes are needed, please let me know and I will update accordingly.

Thank you!

Abhayaj247 · 2025-06-20T15:46:35Z

Also, just to note, @lukeplowden : my previous commit was mistakenly deleted. All the updates mentioned above are now included in my current commit. Thank you for your understanding!

Abhayaj247 · 2025-06-23T06:22:25Z

Hi @lukeplowden , just following up on this PR.

I’ve made all the updates you suggested (details in my previous comment). Please let me know if there’s anything else I should update, or if this is good to go. Thank you!

perminder-17

Hi @Abhayaj247 thankyou for taking this task. I haven’t reviewed it in detail yet, but have you created a separate file for the documentation? Do you think we could generate the reference pages by adding a doc-comment block at the end of the file that describes each method?

perminder-17

I also noticed that you added the reference documentation to the main branch, but p5.Strands is implemented in the dev-2.0 branch.

Could you please retarget your PR to the dev-2.0 branch and re-base your work on top of it?

Steps:

In the PR, click Edit ➜ change the base from main to dev-2.0 ➜ Save (Already I did)

Locally:

git fetch origin
git checkout strands-docs-draft
git rebase origin/dev-2.0
git push --force-with-lease

This will make the PR show only your intended changes against dev-2.0, with conflicts resolved. Thanks!

Abhayaj247 · 2025-06-23T07:24:13Z

Hi @Abhayaj247 thankyou for taking this task. I haven’t reviewed it in detail yet, but have you created a separate file for the documentation? Do you think we could generate the reference pages by adding a doc-comment block at the end of the file that describes each method?

Hi @perminder-17 , thank you for your response!

I haven’t created a separate file for the documentation - instead, I’ve added detailed doc-comment blocks directly above each method within the p5.strands.js file. This approach is consistent with how documentation is handled elsewhere in the codebase and should allow the reference pages to be generated automatically.

If you’d prefer, I can also add a summary doc-comment block at the end of the file that describes each method, or create a separate documentation file as needed. Please let me know your preference, and I’ll be happy to make the adjustments!

Thank you!

Abhayaj247 · 2025-06-23T07:48:08Z

I also noticed that you added the reference documentation to the main branch, but p5.Strands is implemented in the dev-2.0 branch.

Could you please retarget your PR to the dev-2.0 branch and re-base your work on top of it?

Steps:

In the PR, click Edit ➜ change the base from main to dev-2.0 ➜ Save (Already I did)

Locally:
git fetch origin
git checkout strands-docs-draft
git rebase origin/dev-2.0
git push --force-with-lease
This will make the PR show only your intended changes against dev-2.0, with conflicts resolved. Thanks!

Hi @perminder-17,
I’m following the steps to rebase my branch onto dev-2.0 as suggested :


git fetch origin
git checkout strands-docs-draft
git rebase origin/dev-2.0
git push --force-with-lease

However, While rebasing onto dev-2.0 locally, I’m encountering repeated merge conflicts in files like README.md and .all-contributorsrc. Should I need resolve each conflict manually, or is it acceptable to skip these commits if they’re not relevant to my changes? Please advise on the preferred approach. Thank you!

Here’s an example of the error I’m seeing:

For

For  .all-contributorsrc :

CONFLICT (content): Merge conflict in .all-contributorsrc
error: could not apply 8b7f6f252... docs: update .all-contributorsrc [skip ci]
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".
hint: You can instead skip this commit: run "git rebase --skip".
hint: To abort and get back to the state before "git rebase", run "git rebase --abort".
Could not apply 8b7f6f252... docs: update .all-contributorsrc [skip ci]

For  README.md :

CONFLICT (content): Merge conflict in README.md
error: could not apply ef7104d6e... docs: update README.md [skip ci]
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".       
hint: You can instead skip this commit: run "git rebase --skip".
hint: To abort and get back to the state before "git rebase", run "git rebase --abort".
Could not apply ef7104d6e... docs: update README.md [skip ci]

Abhayaj247 · 2025-06-24T06:26:16Z

Hi @perminder-17,

Just following up on my previous question regarding the repeated merge conflicts while rebasing onto dev-2.0 (specifically in files like README.md and .all-contributorsrc).

Should I resolve each conflict manually, or is it acceptable to skip these commits if they’re not relevant to my changes?

Would appreciate your advice on the preferred approach. Thank you!

perminder-17 · 2025-06-24T14:01:00Z

Just following up on my previous question regarding the repeated merge conflicts while rebasing onto dev-2.0 (specifically in files like README.md and .all-contributorsrc).

Would it be okay for you to open a new PR targeting dev-2.0 branch if you're facing issues? The idea is not to solve the merge conflicts manually, but the easiest way for now would be to close this one and open a new PR copying the changes from this PR and pasting it to the dev-2.0 ones?

Abhayaj247 · 2025-06-24T14:12:34Z

Just following up on my previous question regarding the repeated merge conflicts while rebasing onto dev-2.0 (specifically in files like README.md and .all-contributorsrc).

Would it be okay for you to open a new PR targeting dev-2.0 branch if you're facing issues? The idea is not to solve the merge conflicts manually, but the easiest way for now would be to close this one and open a new PR copying the changes from this PR and pasting it to the dev-2.0 ones?

Thank you for the suggestion @perminder-17 !
I’ll go ahead and open a new PR targeting dev-2.0 by copying my changes over, and will close the current one.
Appreciate your help!

perminder-17 · 2025-06-24T14:14:23Z

Thanks for your patience and really sorry for the delay in reviewing.

Abhayaj247 · 2025-06-24T14:16:57Z

Thanks for your patience and really sorry for the delay in reviewing.

No problem at all, and thanks for taking the time to review!

Abhayaj247 · 2025-06-24T15:03:44Z

Closing this PR in favor of #7940, which ports these changes to the dev-2.0 branch as suggested by the maintainers. The new PR avoids the previous merge conflicts and follows the recommended workflow.

Thank you to everyone who reviewed and provided feedback here!

Abhayaj247 mentioned this pull request Jun 18, 2025

[p5.strands] Add reference entries for each hook #7919

Open

17 tasks

lukeplowden reviewed Jun 19, 2025

View reviewed changes

Abhayaj247 closed this Jun 20, 2025

Abhayaj247 force-pushed the strands-docs-draft branch from 6f732bc to ae09118 Compare June 20, 2025 14:17

Abhayaj247 reopened this Jun 20, 2025

Abhayaj247 closed this Jun 20, 2025

Abhayaj247 force-pushed the strands-docs-draft branch from 9947d92 to ae09118 Compare June 20, 2025 14:30

Abhayaj247 reopened this Jun 20, 2025

Abhayaj247 closed this Jun 20, 2025

Abhayaj247 force-pushed the strands-docs-draft branch from cc727b0 to ae09118 Compare June 20, 2025 15:40

Update p5.strands hooks documentation based on reviewer feedback

ab5319f

Abhayaj247 reopened this Jun 20, 2025

perminder-17 self-requested a review June 22, 2025 18:04

perminder-17 reviewed Jun 23, 2025

View reviewed changes

perminder-17 requested changes Jun 23, 2025

View reviewed changes

perminder-17 changed the base branch from main to dev-2.0 June 23, 2025 07:22

perminder-17 changed the base branch from dev-2.0 to main June 24, 2025 14:01

Abhayaj247 mentioned this pull request Jun 24, 2025

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

Open

Abhayaj247 closed this Jun 24, 2025

Abhayaj247 deleted the strands-docs-draft branch June 24, 2025 15:08

Uh oh!

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

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

Uh oh!

Conversation

Abhayaj247 commented Jun 18, 2025

Uh oh!

welcome bot commented Jun 18, 2025

Uh oh!

lukeplowden left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

Abhayaj247 commented Jun 20, 2025

Uh oh!

Abhayaj247 commented Jun 20, 2025

Uh oh!

Abhayaj247 commented Jun 23, 2025

Uh oh!

perminder-17 left a comment

Choose a reason for hiding this comment

Uh oh!

perminder-17 left a comment • 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!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

perminder-17 commented Jun 24, 2025

Uh oh!

Abhayaj247 commented Jun 24, 2025

Uh oh!

perminder-17 commented Jun 24, 2025

Uh oh!

Abhayaj247 commented Jun 24, 2025

Uh oh!

Abhayaj247 commented Jun 24, 2025

Uh oh!

Uh oh!

Abhayaj247 commented Jun 20, 2025 •

edited

Loading

perminder-17 left a comment •

edited

Loading

Abhayaj247 commented Jun 23, 2025 •

edited

Loading

Abhayaj247 commented Jun 23, 2025 •

edited

Loading

Abhayaj247 commented Jun 24, 2025 •

edited

Loading