playcanvas / playcanvas/engine
Decide where StandardMaterial ambientSH lives once light probes exist (last value outside the material uniform buffer)
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 16.8k
- Forks
- 2k
- Avg merge
- 4h 32m
- Merged PRs (30d)
- 222
Description
StandardMaterial#ambientSH is the one material value deliberately left out of the material uniform buffer after #6157 and the PRs that closed it. Every other value of a standard material lives in the buffer; the spherical harmonics still go through the scope as ambientSH[0], which on WebGPU means 144 bytes written into the per-draw mesh uniform buffer for every draw of a material that uses them.
It was left as is on purpose: per-material SH is rarely used, and light probe support (see #2484 for reflection probes) will likely change the requirements. The data may come from textures, be selected per mesh instance, or move to the scene or view level rather than the material. When probes are designed, decide where the SH data lives and move it out of the per-draw path at the same time. The options considered:
- a presence-gated array member of the material uniform buffer (9 vec3, 144 bytes, only on materials with an SH array; presence already selects the shader's ambient source),
- the view uniform buffer, if SH becomes a scene or camera level term,
- a texture, if probe data is sampled.
Details for whoever does it:
- The shader processor matches a parsed uniform by its plain name, while a uniform buffer format keys an array member as
name[0], so an array member of the material buffer needs a small lookup fix inShaderProcessorOptions.getUniformBindGroupfirst; otherwise the shader keeps reading the SH as a mesh uniform. LitMaterialhas its ownambientSHparameter that stays on the parameter path.- In-place edits of the
Float32Arrayare live today because the scope holds the reference; a buffer member would compare the 27 floats inupdate()to keep that.
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 ShaderProcessorOptions.getUniformBindGroup and inspect how parsed uniform names differ from uniform-buffer array members. Read the ambientSH handling in LitMaterial and its update() path, along with the decisions in #6157 and #2484. Done means choosing the appropriate storage level for SH data, removing it from the per-draw mesh path, and preserving live in-place Float32Array edits.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- computer-graphics, performance
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100