feat(webgpu): add read() to p5.StorageBuffer with tests

[aashu2006]

Resolves #8722

Changes:

I’ve added an async .read() method to p5.StorageBuffer so we can read data back from GPU buffers into JavaScript.

• It uses a staging buffer + mapAsync to copy data from GPU -> CPU
• For number buffers, it returns a Float32Array
• For struct buffers, it returns plain JS objects based on the schema
• I also added a private _unpackStructArray() helper to rebuild struct data from the packed buffer
• This follows the same pattern already used in readFramebufferPixels

Tests

I've added unit tests for:

1. reading float buffers
2. reading struct buffers
3. reading after .update()
4. reading after GPU compute verifiying actual GPU -> CPU flow
5. struct buffers with vector fields

Some Notes

• Struct data is returned as plain objects for e.g. arrays for vector fields, not p5.Vector or p5.Color
• .read() introduces a GPU - CPU sync point, so frequent use maybe can impact the performance

PR Checklist

• npm run lint passes
• Inline reference is included / updated
• Unit tests are included / updated

[aashu2006]

@davepagurek Hey, I’ve added the .read() implementation and tests for this, have a quick look at it whenever you have time 🙂

[p5-bot]

Continuous Release

CDN link

• https://raw.esm.sh/pr/p5@869a00a/lib/p5.min.js

Published Packages

• https://pkg.pr.new/p5@869a00a

Commit hash: 1aeeaef

Previous deployments

d650e1c

• https://raw.esm.sh/pr/p5@d0c77e1/lib/p5.min.js
• https://pkg.pr.new/p5@d0c77e1

---

This is an automated message.

[davepagurek]

Do you think we can move this to the renderer next to _packStructArray for consistency, and defer to the renderer from this class?

[aashu2006]

Yes, that makes sense. I will move _unpackStructArray next to _packStructArray in the renderer and call it from here for consistency.

[davepagurek]

ahh good catch. I guess we don't currently capture in the schema if these values came from arrays, vectors, or colors. I think we might want to record that so we can deserialize into the same format it came in as. Do you think something like that is feasible?

[aashu2006]

yeah that’s a good point, right now we’re just returning plain data, but preserving the original types like vectors or colors would be useful.

I think it’s doable by extending the schema to store the original input type, but it might add some complexity. I can look into that as a follow-up issue if that sounds good.

[davepagurek]

I think it might be worth exploring upfront, just because it changes the API a bit -- e.g. if we were to release just this then change the structure of return values, it could break users' code. (I don't think we're going to do a release in between PRs, but that's generally how I think about API changes -- we generally want to avoid, if we can, merging code with an API that we think we'll change.)

[aashu2006]

If we think the return format might change, it’s better to settle that before merging. Would you prefer that we preserve original types like vectors or colors in this PR, or keep the current plain data approach and commit to that API for now?

[davepagurek]

Let's see what preserving the original types involves. If it requires a lot of changes let me know and we can talk about whether it might be better to omit it, but if we can make it work, it feels like that'd be the preferable user experience.

[aashu2006]

Got it, I’ll explore preserving the original types and see how much it impacts the current schema logic. I’ll try to keep it minimal and share an update.

[davepagurek]

this is looking good, and thanks for the detailed tests!

[aashu2006]

@davepagurek I've pushed the changes moved _unpackStructArray to the renderer and updated usage. Happy to make any other tweaks if needed!

[aashu2006]

@davepagurek Just wanted to follow up on the return format question, happy to proceed either way, just wanted to check what direction you'd prefer here

[aashu2006]

@davepagurek I've now pushed an update to preserve the original types. For colors, I’m now scaling back using colorMaxes to match how _getRGBA normalizes values, so it works correctly with different colorMode settings. Let me know what you think!