Make p5.strands matrix uniform helpers (uniformMat2x2/3x3/4x4) production-ready: tests, docs, p5.Matrix support
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 24k
- Forks
- 3.8k
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 25
Description
Increasing access
Matrix uniforms are a basic building block for shader work (transforms,
instancing, lighting), but the strands helpers for them are currently
discoverable only by reading the source, and parts of the path fail
silently. Silent failures are hardest on exactly the learners p5.js
serves — a sketch that renders nothing with a clean console gives a
beginner no thread to pull. Documenting and testing these helpers turns
an undocumented internal into a supported, learnable feature, and removes
the need for workarounds like the three-vec3 hack in Renderer3D.js.
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
Other-p5.strands,WEBGPU.
Context: in #8953 (comment: [https://github.com/processing/p5.js/issues/8953#issuecomment-5000277736]) I traced the current
state of strands matrix uniforms on main (8886f4c6e), and @perminder-17
confirmed the uniforms half is a good separate piece and asked for a
scoped issue. The operator/arithmetic side (m * v etc. in
binaryOpNode) is explicitly out of scope here — @perminder-17 is
working on that under #8953.
What exists today (verified empirically):
- The DataType loop in
strands_api.jsauto-registersuniformMat2x2,
uniformMat3x3, anduniformMat4x4from the mat entries in
ir_types.js. - WebGL:
uniformMat3x3('uM', [...9 floats])generates a valid
uniform mat3x3 uM;declaration (strands shaders are
#version 300 es), compiles, links, and renders. - WebGPU: the same call generates a correct
mat3x3<f32>member in the
hook uniforms struct with proper bindings. - However: zero references in
docs/ortest/— the helpers are
generated-only, never exercised, never documented.
Proposed scope:
- Unit tests for mat2/mat3/mat4 uniform declaration + upload on the
WebGL backend (test/unit/webgl/), including the mat2 upload path
added in #8978 - Equivalent unit tests on the WebGPU backend (
test/unit/webgpu/),
verifying upload end-to-end (codegen is confirmed correct; the
upload/buffer-layout path is currently untested) - Visual regression test(s) exercising a matrix uniform in a
.modify()sketch on both backends - Reference documentation for the three helpers, following the
existing documentation pattern inp5.strands.js -
setUniformaccepting ap5.Matrixdirectly (there is currently
noisMatrixunwrapping alongsideisVector/isColor, so only
flat column-major arrays work)
Open questions for maintainers:
- Naming: the registration only produces
uniformMat3x3-style names (no
uniformMat3alias, since the alias branch covers only vec and
sampler types). Should shorter aliases be added, or is the explicit
NxN form preferred? Happy to follow whichever. - Should the
p5.Matrixacceptance insetUniformbe part of this
issue or split out?
I'd like to fix this myself if approved.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with strands_api.js and ir_types.js to trace registration of uniformMat2x2, uniformMat3x3, and uniformMat4x4, then inspect the existing tests under test/unit/webgl/ and test/unit/webgpu/. Follow the documentation pattern in p5.strands.js. Done means both backends have upload coverage, matrix-uniform visual coverage exists, the helpers are documented, and the p5.Matrix and naming questions are resolved.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- computer-graphics, documentation, testing
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100