add getTexture docs and examples for p5.strands

[nbogie]

Resolves #8438

Changes:

• Add docs for getTexture in /src/strands/p5.strands.js including two examples. I tried to pick examples that don't need understanding of (m)any other shader functions.
• Linked to the new getTexture reference page from buildFilterShader.

PR Checklist

• npm run lint passes - No, but my added code passes.
• [Inline reference] is included / updated
• npx documentation lint src/strands/p5.strands.js passes: only one warning new from my code: unknown @beta tag.

[nbogie]

I've shared this draft PR to get early feedback before converting the examples to the flat API

To-do:

• I think I need to re-write the examples using the "flat" API, following Experiment: flatter strands API #8314
• I need to fix the types.
• possibly, add one more example outside of a filter shader. This could follow later.
• add some description before each example (and possibly more comments)
• Find out if any interpolation is used when sampling from a lower-res texture, and if we have any control over that.

Questions:

• Should the examples use buildFilterShader() instead of modify()?
• How much should the function description clarify that it is for use in strands? (I can imagine this might be added as boilerplate for all functions in strands module)
• Is it necessary to bring my examples in line to be consistent with the others that pass an inline arrow function to modify() ? (I think that's significantly harder syntax for learners to read and debug, though more concise.)
• What should the param and return types be? I see no other functions referring to these vec2, vec4, sampler2D types.

current types

 * @param {typeof sampler2D} texture
 * @param {typeof vec2} coords
 * @returns {typeof vec4}

but these are all getting converted to any and void in type-gen.

[davepagurek]

Should the examples use buildFilterShader() instead of modify()?

I think so! After merging the flat strands API I believe that should be used now in all the reference examples, if I caught all of them,

How much should the function description clarify that it is for use in strands? (I can imagine this might be added as boilerplate for all functions in strands module)

For a function like this that only works in strands, I think a boilerplate sentence or two would be great, and then we can paste that into other reference items that are strands-only.

Is it necessary to bring my examples in line to be consistent with the others that pass an inline arrow function to modify() ? (I think that's significantly harder syntax for learners to read and debug, though more concise.)

I think I've also converted a bunch of those now that the flat strands PR has been merged too. but yeah, the idea will be to try to not use inline functions.

What should the param and return types be? I see no other functions referring to these vec2, vec4, sampler2D types.

This is a good question. They're kind of both p5.StrandsNode parameters (we don't really have subtypes for each data type currently), but that isn't a useful thing to show users in the reference because they don't know yet that that's what they're using when writing strands. Possibly for now the best thing could be to just not give a type, and to use the description to explain what should be passed in.

[davepagurek]

Find out if any interpolation is used when sampling from a lower-res texture, and if we have any control over that.

By default it'll use linear interpolation. Currently for a framebuffer you can do createFramebuffer({ textureFiltering: NEAREST}) to avoid that, and there is an internal renderer.getTexture(someImage).setInterpolation(NEAREST, NEAREST) that we probably shouldn't document before turning that into a better API.

[nbogie]

• Rewrote the examples.
  • example 1 (flat API)
  • example 2 (flat API)
• Tried to keep example line lengths short so they don't get wrapped.
• Removed the formal param and return types. Tried to give examples and articulate where values should be "compatible" with vec2 / vec4... 🤷‍♂️
• Added description at the start of each example
• Added Dave's info about interpolation and how to prevent it
• Added a sentence saying it was only available when using strands.
• Added @beta tag

[davepagurek]

Well written and the examples look good! Just one question about the parameter/return types when they don't have a real type just yet.

[davepagurek]

What does * show up as in the parameter data after running npm run docs, and on when built into the website? I believe generally we can just omit the {} section when we don't have an associated type.

[nbogie]

Oops, I'll omit it, thanks!

I don't know why i latched on to the rare usage (from random(arr), which gets its type patched)

update: checking...

with types omitted:

getTexture(texture: any, coords: any): void;

with {*} for params and return:

  getTexture(texture: any, coords: any): any;

so just that difference in return type.

both show no type info on the website.

[davepagurek]

ok that's good to know! We can use {*} for the return type then, and start to document when it makes sense to use that

[nbogie]

I found it now documented in the JSDocs for @param: https://jsdoc.app/tags-param#:~:text=Hello%20%27%20%2B%20somebody)%3B%0A%7D-,Allows%20any%20type,-/**%0A%20*%20%40param%20%7B (and elsewhere for object properties, though not for @return, I think just through oversight)

Weirdly, in the closure compiler docs around JSDoc it sounds like * should map to unknown in TS, and ? should may to any. I guess if it works and we're consistent...

[davepagurek]

sounds good, we can add back in whatever works here to get an any return type for this method.