processing / processing/p5.js

Make p5.strands matrix uniform helpers (uniformMat2x2/3x3/4x4) production-ready: tests, docs, p5.Matrix support

Open
#8,992 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Area:WebGL Enhancement
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.js auto-registers uniformMat2x2,
    uniformMat3x3, and uniformMat4x4 from 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/ or test/ — 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 in p5.strands.js
  • setUniform accepting a p5.Matrix directly (there is currently
    no isMatrix unwrapping alongside isVector/isColor, so only
    flat column-major arrays work)

Open questions for maintainers:

  1. Naming: the registration only produces uniformMat3x3-style names (no
    uniformMat3 alias, 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.
  2. Should the p5.Matrix acceptance in setUniform be part of this
    issue or split out?

I'd like to fix this myself if approved.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.