add getTexture docs and examples for p5.strands

[nbogie]

Resolves #8438

Changes:

Add docs for getTexture in /src/strands/p5.strands.js including some examples. I tried to pick examples that don't need understanding of (m)any other shader functions.

Screenshots of the change:

Top section docs and first example:

Second example:

End section of docs (params, return value)

PR Checklist

• npm run lint passes - No, but my added code passes.
• [Inline reference] is included / updated

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