playcanvas / playcanvas/engine

Decide where StandardMaterial ambientSH lives once light probes exist (last value outside the material uniform buffer)

Open
#9,407 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area: graphics enhancement
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 in ShaderProcessorOptions.getUniformBindGroup first; otherwise the shader keeps reading the SH as a mesh uniform.
  • LitMaterial has its own ambientSH parameter that stays on the parameter path.
  • In-place edits of the Float32Array are live today because the scope holds the reference; a buffer member would compare the 27 floats in update() to keep that.

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.