[p5.strands] Instancing API improvements

[aashu2006]

Increasing access

This makes GPU instancing easier to discover and use without requiring a deep understanding of the underlying rendering pipeline. The goal is to make performant rendering techniques more approachable for artists, educators, students, and beginners.

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
• p5.strands

Feature enhancement details

Summary

This issue tracks implementation work for improving the p5.strands instancing API as part of the Microgrant project.

Instancing is a powerful GPU technique for efficiently drawing large numbers of similar objects, but the current API can be difficult for newer users to discover and understand. This project builds on the existing rendering architecture to provide a more approachable and discoverable API surface.

Proposed Direction

let repeater = instances(100);
repeater.sphere(20);

// in a shader
let i = instanceIndex();

Planned Work

• Add instanceIndex() as an alias for instanceID()
• Implement instances(count) returning a drawable object
• Integrate instancing with existing primitive rendering paths
• Add tests for WebGL and WebGPU
• Add documentation and examples

Project Context

This issue serves as a tracking thread for ongoing work and related pull requests for the p5.strands instancing API.

References

• Design proposal: gist link
• Visual exploration: tldraw link

[aashu2006]

cc @ksen0 @davepagurek

[davepagurek]

Does instanceIndex() need to be a function? Possibly we could define a getter, similar to how other non-functions like width work in strands, that does the same thing.

[aashu2006]

I kept it as a function in this #8912 because instanceID() is currently a function and the goal here was to make instanceIndex() a minimal alias.

thinking about it more, instanceIndex does feel closer to built-in values like width or mouseX than to something that's actually performing work. Do you see it as eventually replacing instanceID() entirely as the preferred API, and if so would you lean towards making both of them values rather than functions?

[davepagurek]

I think we can keep instanceID() how it is but mark it as deprecated for now, moving towards instanceIndex as the slightly easier to use API.

[aashu2006]

Got it, I think having instanceIndex() as the preferred API while keeping instanceID() around for compatibility is a good path forward. Do you see instanceIndex eventually being a value, or do you think it should stay a function?

[davepagurek]

I think since it's effectively a constant within the shader, it feels conceptually closer to a value. That also means we don't have to worry about users accidentally forgetting the braces at the end too.

[aashu2006]

"forgetting the parentheses" point is especially convincing since it's something beginners are likely to run into. I'll take a look at how the other built-in strands values are exposed and see what would be involved in making instanceIndex a value instead.