[p5.js 2.0+ Bug Report]: Framebuffer example breaks on 2+

[ksen0]

Most appropriate sub-area of p5.js?

• Accessibility
• Color
• Core/Environment/Rendering
• Data
• DOM
• Events
• Image
• IO
• Math
• Typography
• Utilities
• WebGL
• WebGPU
• p5.strands
• Build process
• Unit testing
• Internationalization
• Friendly errors
• Other (specify if possible)

p5.js version

2+

Web browser and version

chrome

Operating system

macos

Steps to reproduce this

Steps:

1. https://beta.p5js.org/examples/3d-framebuffer-blur/ observe somethign strange happening (intended: https://p5js.org/examples/3d-framebuffer-blur/). Instead of row of rotating spheres there's a smear of crescent shapes that fades into nothing
2. if pasting code into p5.js editor, and select 2.3 in version, a whole other also strange behavior (also no syntax highlighting after 2.2?)

[vamshi567bh]

@davepagurek i would like to work on this please assign

[davepagurek]

Thanks @vamshi567bh, although before assigning, can you do a bit of investigation? I suspect that at least part of the issue is that we do not have a built-in uModelViewMatrix any more; it has been split out into uModelMatrix and uViewMatrix. If you are able to make a modified version of the sketch just in the p5 editor that works with p5 2.3, we can determine if there is a bug in need of fixing in the p5 library or if we just need to update this example in the website repo to use the updated APIs.

[vamshi567bh]

@davepagurek I looked into this. I found the example code at src/content/examples/en/11_3D/06_Framebuffer_Blur/code.js.

I checked the current 2.0 source and _setGlobalUniforms() in p5.Renderer3D.js still sets uModelViewMatrix unconditionally (computed as modelMatrix * viewMatrix). So the split you mentioned doesn't seem to be the direct cause in the current code, but you said it might have been.

Here's a modified version with separate uModelMatrix + uViewMatrix to be safe:

let vertexShader = `
uniform mat4 uModelMatrix;
uniform mat4 uViewMatrix;
uniform mat4 uProjectionMatrix;

attribute vec3 aPosition;
attribute vec2 aTexCoord;
varying vec2 vTexCoord;

void main() {
  vTexCoord = aTexCoord;
  vec4 positionVec4 = vec4(aPosition, 1.0);
  gl_Position = uProjectionMatrix * uViewMatrix * uModelMatrix * positionVec4;
}`;

I tested this modified vertex shader approach. Could you let me know if there are specific changes in 2.3 that might also affect how framebuffer depth textures work or how custom shader uniforms are bound?

[davepagurek]

Off the top of my head I can't think of changes that would affect APIs, so the next thing I'd likely do is try to separate out the steps that are working from the ones that aren't. e.g. if you don't use the custom shader and just texture a place with the framebuffer's color channel, does it work? what about its depth channel? It also appears to not be animating, is it in fact still drawing every frame but it's just not making its way to the main canvas?

[vamshi567bh]

@davepagurek Matrix Multiplication Order in _setGlobalUniforms()

In p5.Renderer3D.js:1437, the uModelViewMatrix is computed as:

const modelViewMatrix = modelMatrix.copy().mult(viewMatrix);

This computes modelMatrix * viewMatrix (model first, then view). However, the correct transformation pipeline should be:

clipPosition = projection * view * model * localPosition

So the combined model-view matrix should be viewMatrix * modelMatrix. The current code computes the reverse order, which is geometrically incorrect.

When the vertex shader uses separate uModelMatrix and uViewMatrix uniforms (as in the updated example), the multiplication order in GLSL is:

gl_Position = uProjectionMatrix * uViewMatrix * uModelMatrix * vec4(aPosition, 1.0);

This is correct: model → view → projection.

But the old vertex shader using uModelViewMatrix:

gl_Position = uProjectionMatrix * uModelViewMatrix * vec4(aPosition, 1.0);

Expands to projection * model * view * position, which applies the view transform before the model transform — this is wrong and produces the crescent-shaped distortions visible in the broken example.

The vertex shader change from uModelViewMatrix to uModelMatrix + uViewMatrix is not just a forward-compatibility change — it actually fixes the incorrect transformation. The uModelViewMatrix uniform is still set by _setGlobalUniforms() for backward compatibility, but on p5.js 2.0+ it produces wrong results due to the multiplication bug.

The default camera (eyeZ=800, near=80, far=8000) compresses most scene depth into the [0.8, 1.0] range of the depth buffer. The hardcoded focal depth (0.9) is close to most objects' depth values, so the DOF blur effect is very subtle. The example may need either a narrower near/far ratio to spread depth values across more of the [0,1] range, or the focal point should be computed dynamically.

I ran tests for all 5 debugging steps suggested in the linked comment. All compile without errors:

1. Framebuffer color texture renders correctly via image()
2. Color texture renders correctly via custom shader + plane()
3. Depth texture has correct non-uniform values
4. DOF shader produces correct output (blur amount matches depth)
5. Animation loop works correctly (frame-to-frame updates)

The uModelViewMatrix uniform is still set in _setGlobalUniforms() so shaders using it do compile, but produce geometrically incorrect results.

The fix also needs to be applied to the example in the main p5.js repo (in src/content/examples/en/11_3D/06_Framebuffer_Blur/).

[vamshi567bh]

@davepagurek if ok i will go with the pr thanks!

[davepagurek]

Good catch! I guess we didn't notice before because most shaders don't directly use that uniform. I'll assign this to you now, feel free to go ahead with a PR.

[vamshi567bh]

PR opened on p5.js-website: #1460

[davepagurek]

I think we should also fix the matrix ordering in the p5 library too, if you're open to it

[davepagurek]

@vamshi567bh I don't think we want to change the ordering of all matrix multiplies, that sounds like a super wide change that would have many unintended consequences. why not just flip the order of the model and view matrices in computing modelViewMatrix, as that's the only one not working correctly?