[p5.strands] Add reference entries for each hook

[davepagurek]

Increasing access

In 2.0, we released p5.strands! Currently, the documentation is a little sparse, and you have to find either our one tutorial, or look at the examples on a base shader (e.g. baseMaterialShader.) The text of the referencedoesn't mention strands. If we can document p5.strands more like how we document regular p5 functions, more people can discover it, and learning how to use it will be more straightforward.

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• Build process
• Unit testing
• Internationalization
• Friendly errors
• Other (specify if possible)

Feature enhancement details

A p5.strands snippet might look something like this:

myShader = baseMaterialShader().modify(() => {
  let time = uniformFloat(() => millis());
  getWorldInputs((inputs) => {
    inputs.position.y +=
      20 * sin(time * 0.001 + inputs.position.x * 0.05);
    return inputs;
  });
});

The getWorldInputs function is a hook. These hooks are currently only described on the reference for the base shaders that use them (e.g. https://beta.p5js.org/reference/p5/basematerialshader/), and are currently described in GLSL, as that was the only way to modify shaders at the time those docs were written.

I'm proposing that we:

• Create a new reference page for each hook function (e.g. getObjectInputs, combineColors, etc)
  • Since these methods are dynamically created, the reference pages can be made by placing a doc comment block at the end of a file describing each method even though the method itself is not next to the comment block (similar to how properties of classes are documented.)
  • Put these in a new p5.strands section or subsection of the reference by using @module (for section) and @submodule (for subsection) in the doc comments. Open to ideas about exactly where in the reference it should go!
  • Describe without GLSL how to use the hook
  • Create (or copy from the base shader) an example or two for each hook reference (e.g. for hooks coming from multiple shaders, maybe show an example of each?)
  • Link back to all the base shader references that include it (e.g. getObjectInputs is on I think all of our base shaders)
• Update the base shader docs to link to all the individual hook docs rather than describing them all in a table
• Update the shader.modify() docs to mention p5.strands JS callbacks as well as the object-with-glsl option currently described

We don't have to do all of these in one go, I can make a subtasks for each if someone is interested in getting started on just a part of this 🙂

[Abhayaj247]

Hi @davepagurek ,I want to work on this, assign to me

[davepagurek]

Thanks @Abhayaj247!

[Abhayaj247]

Hi @davepagurek ! Before I update all hooks, I want to confirm the documentation style and file location.
I am creating the new reference documentation for p5.strands hooks in:
p5.js/src/webgl/p5.strands.js
Here’s what I’m planning for each hook (example: getWorldInputs) :

/**
 * @method getWorldInputs
 * @param {Object} inputs An object containing:
 *   - `position`: [x, y, z], the position of the vertex in world space
 *   - `normal`: [x, y, z], the normal vector in world space
 *   - `texCoord`: [u, v], the texture coordinates
 *   - `color`: [r, g, b, a], the vertex color
 * @return {Object} The modified inputs object
 * @example
 * <div modernizr='webgl'>
 * <code>
 * let myShader;
 * function setup() {
 *   createCanvas(200, 200, WEBGL);
 *   myShader = baseMaterialShader().modify({
 *     uniforms: {
 *       'float time': () => millis()
 *     },
 *     'getWorldInputs': (inputs) => {
 *       inputs.position[1] += 20 * Math.sin(time * 0.001 + inputs.position[0] * 0.05);
 *       return inputs;
 *     }
 *   });
 * }
 * function draw() {
 *   background(255);
 *   shader(myShader);
 *   lights();
 *   noStroke();
 *   fill('red');
 *   sphere(50);
 * }
 * </code>
 * </div>
 */

Could you please confirm if this is the correct style, level of detail, and file location for the new p5.strands documentation?
If so, I’ll proceed with the rest in this format. Thanks!

[davepagurek]

For location: we currently have the rest of the p5.strands implementation in src/webgl/ShaderGenerator.js, potentially we could add these doc comment blocks to the end of that file? Or @lukeplowden if you think that file is getting too busy, then splitting these out into a separate file like you describe works too.

The doc comment structure looks good in general! Some small modifications:

• If you add @for p5 then that tells the reference that this is a global function and not a class function
• getWorldInputs itself actually has no return value, and takes in a single function as a parameter. That function is what needs to take in an object containing those properties, and return a modified object. Maybe take a look at the callbacks in loading methods like loadImage for an example of how to do the type for that.
  • For the properties on an input, @lukeplowden and @perminder-17 what do you think would be the best way to describe those? [x, y, z] sorta looks like you'd access it like an array (e.g. position[0]) rather than like an object (position.x), but describing it like { x, y, z } might be syntactically confusing too. It's kind of like a p5.Vector, but also it isn't one. What do you think about describing it like "an object with x, y, and z properties"?
  • If we do the above, we may need to replace the u and v for the texture coordinate property with x and y, since those are the names you'd have to access its values with
• As a last thing, as part of the description, can we also list and link to the reference for the shaders that have that hook?

EDIT: one other thought. Currently we still have the @experimental label on other strands-related things, so we maybe should add that to these too for consistency.

[davepagurek]

Also if it helps, feel free to make a draft PR with just some of the changes if you want to get feedback before then doing all the rest.

[Abhayaj247]

Thank you for the detailed feedback @davepagurek !

I’ll create a draft PR with just a few of the updated doc comments (for example, getWorldInputs, combineColors, and getPointSize) so you can review the style, level of detail, and file location before I update the rest.

Also, is it required to use the full PR template (with checklist, screenshots, etc.) for a draft PR, or is a simpler description acceptable at this stage? I want to make sure I’m following the project’s preferred workflow.

Thanks again for your guidance - looking forward to your feedback on the draft PR!

[davepagurek]

Feel free to keep it simple for a draft 🙂 The rest can all be added later.