Skip to content

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

Description

@harshiltewari2004

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 Add mat2 uniform support to WebGL setUniform, fixing silent no-op (#8… #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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions