WebGPURenderer performance trace analysis

[mrdoob]

Description

This week I learnt I can ask Claude to analyze chrome devtools performance traces.

I tried it with a 2 second trace of this example and these are the findings:

▗ ▗   ▖ ▖  Claude Code v2.1.29
           Opus 4.5 · Claude Max
  ▘▘ ▝▝    ~/Work/git/three.js

❯ Can you investigate Trace-20260201T095112.json.gz and see what's taking   
  the most CPU time? The code for this in the /src folder (WebGPURenderer). 
   Lets see if we can find any possible performance improvmeents.           

⏺ Bash(gunzip -c Trace-20260201T095112.json.gz | head -c 50000)
  ⎿  {"metadata": {
       "source": "DevTools",
       "startTime": "2026-02-01T00:51:12.270Z",
     … +874 lines (ctrl+o to expand)

⏺ Bash(gunzip -c Trace-20260201T095112.json.gz | jq -r '.traceEvents[] |
      select(.cat == "devtools.timeline" and .name == "FunctionCall") | "\(.dur
      // 0) \(.args.data.f…)
  ⎿  311556 update
     854
     120 MutationObserver.observe.childList

⏺ Let me get more detailed profiling data from the trace.

⏺ Bash(gunzip -c Trace-20260201T095112.json.gz | jq -r '.traceEvents[] |
      select(.name == "Profile" or .name == "ProfileChunk")' 2>/dev/null | head
      -c 100000)
  ⎿  {
       "args": {
         "data": {
     … +6502 lines (ctrl+o to expand)

⏺ Bash(gunzip -c Trace-20260201T095112.json.gz | jq -c '.traceEvents[] |
      select(.name == "ProfileChunk") | .args.data.cpuProfile.nodes[]? |
      select(.callFrame.url != nu…)
  ⎿  (No content)

⏺ Bash(gunzip -c Trace-20260201T095112.json.gz | jq '.traceEvents[] |
      select(.name == "ProfileChunk") | .args.data.cpuProfile.nodes' 2>/dev/null
       | jq -s 'add | .[] | s…)
  ⎿  (No content)

⏺ Bash(gunzip -c Trace-20260201T095112.json.gz | jq '[.traceEvents[] |
      select(.name == "ProfileChunk") | .args.data.cpuProfile.nodes // empty] |
      add | map(select(.call…)
  ⎿  (No content)

⏺ Read 1 file (ctrl+o to expand)

⏺ Bash(gunzip -c Trace-20260201T095112.json.gz | python3 -c "
      import json…)
  ⎿ Top functions by self time (microseconds):
    =======================================================================
    =========
    … +46 lines (ctrl+o to expand)


⏺ Excellent! Now let me map these hot functions to the source code in /src.

⏺ Searched for 7 patterns, read 2 files (ctrl+o to expand)

⏺ Let me also check the ChainMap and RenderList which are high on the list.

⏺ Searched for 1 pattern, read 1 file (ctrl+o to expand)

⏺ Let me check the Renderer's _renderObjectDirect method and getCacheKey which
  are also high on CPU time.

⏺ Searched for 1 pattern, read 1 file (ctrl+o to expand)

⏺ Based on my analysis of the trace file, here's a summary of the top CPU 
  consumers in the WebGPURenderer:

  Performance Analysis Results
  ┌────────────────┬────────────────────────┬───────────────────────┐
  │ Self Time (µs) │        Function        │       Location        │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 37,647         │ get (ChainMap)         │ ChainMap.js           │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 34,074         │ setPipelineAndBindings │ WebGPUBackend.js:1505 │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 22,994         │ _renderObjectDirect    │ Renderer.js:3301      │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 19,725         │ get (DataMap)          │ DataMap/other         │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 17,913         │ setVertexBuffer        │ WebGPU native         │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 13,202         │ updateMatrixWorld      │ Object3D.js           │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 11,141         │ sort                   │ RenderList.js:362     │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 10,693         │ draw                   │ WebGPUBackend.js:1486 │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 9,943          │ setBindGroup           │ WebGPU native         │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 9,033          │ needsRenderUpdate      │ WebGPUBackend.js:1799 │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 8,469          │ _projectObject         │ Renderer.js           │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 7,421          │ getCacheKey            │ RenderObject.js       │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 7,092          │ intersectsSphere       │ Frustum.js            │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 3,187          │ painterSortStable      │ RenderList.js:12      │
  ├────────────────┼────────────────────────┼───────────────────────┤
  │ 1,993          │ cyrb53                 │ hash function         │
  └────────────────┴────────────────────────┴───────────────────────┘
  Key Hotspots & Potential Improvements

  1. ChainMap get lookups (37.6ms) — Highest cost

  The ChainMap iterates through multiple nested WeakMaps per lookup. For scenes
  with many objects, this compounds.

  Potential improvement: Consider caching the result or using a simpler
  single-key lookup when possible (e.g., combining keys into a single object
  reference).

  2. needsRenderUpdate (9ms) — Expensive comparison

  At WebGPUBackend.js:1799-1828, there's a massive comparison of ~25 material
  properties every frame:
  if ( data.material !== material || data.materialVersion !== material.version
  ||
       data.transparent !== material.transparent || data.blending !== ... // 25+
   comparisons

  Potential improvement: Use a single version number or hash on the material
  rather than comparing every property individually.

  3. painterSortStable (3.2ms) — Called per comparison

  The sort comparator at RenderList.js:12-31 has 4 levels of nested if-else
  checks. With many objects, this adds up.

  Potential improvement: Pre-compute a single sort key (e.g., (groupOrder << 24)
   | (renderOrder << 16) | z_encoded) to allow a single numeric comparison.

  4. setCacheKey / getRenderCacheKey (7.4ms)

  Cache key generation involves string concatenation which is expensive.

  5. WebGPU Native Calls (28ms total)

  setVertexBuffer, setBindGroup, setIndexBuffer are already optimized by
  tracking current state to avoid redundant calls. This is working correctly.

  Would you like me to implement any of these optimizations? The most impactful
  would likely be:
  1. Simplifying needsRenderUpdate with a version/hash approach
  2. Optimizing the sort comparator with pre-computed keys

✻ Cooked for 2m 12s

/fyi @sunag @Mugen87

Solution

Reduce CPU usage.

Alternatives

Not reduce CPU usage.

Additional context

No response

[Mugen87]

Yeah, these are known points to me since during my work on performance improvements over the last weeks I've seen these every time in the analysis. The by far biggest (WebGL related) CPU issues are actually not listed which is the UBO binding and update overhead (see #30560). Also it's best to disable the static checkbox in the example to make sure the render objects go through the entire checks. My comments to the points:

1. The ChainMap overhead seems high and it might makes sense to look for alternatives. That said, if we build some sort of ID or key from the chain map objects, we end up with string concatenation or hash computation which is expensive as well (this is also mentioned by Claude in your trace). Besides, when using weak maps, we don't have to think about disposal/ removal from entries. If we build up a Map or Object with string keys, we must make sure it does not "fill up" over time creating memory leaks. This was a major argument for using weak maps in the first place (even in WebGLRenderer).

2. The comparisons in NodeMaterialObserver are required if we want to retain the flexibility of WebGLRenderer where we also perform many comparison when the version does not change. The suggestion to just use a version number has its own drawbacks (it would require a manual needsUpdate or a complex monitoring of all material properties and value access which has its own overhead) and the hash computation would introduce computation overhead as well and prevent "early-outs" which are possible when comparing properties directly. Below is a comparable section to NodeMaterialObserver in WebGLRenderer.

three.js/src/renderers/WebGLRenderer.js

Lines 2269 to 2426 in 6026174

	const fog = scene.fog;
	const environment = ( material.isMeshStandardMaterial || material.isMeshLambertMaterial || material.isMeshPhongMaterial ) ? scene.environment : null;
	const colorSpace = ( _currentRenderTarget === null ) ? _this.outputColorSpace : ( _currentRenderTarget.isXRRenderTarget === true ? _currentRenderTarget.texture.colorSpace : LinearSRGBColorSpace );
	const usePMREM = material.isMeshStandardMaterial || ( material.isMeshLambertMaterial && ! material.envMap ) || ( material.isMeshPhongMaterial && ! material.envMap );
	const envMap = environments.get( material.envMap || environment, usePMREM );
	const vertexAlphas = material.vertexColors === true && !! geometry.attributes.color && geometry.attributes.color.itemSize === 4;
	const vertexTangents = !! geometry.attributes.tangent && ( !! material.normalMap || material.anisotropy > 0 );
	const morphTargets = !! geometry.morphAttributes.position;
	const morphNormals = !! geometry.morphAttributes.normal;
	const morphColors = !! geometry.morphAttributes.color;
	let toneMapping = NoToneMapping;
	if ( material.toneMapped ) {
	if ( _currentRenderTarget === null || _currentRenderTarget.isXRRenderTarget === true ) {
	toneMapping = _this.toneMapping;
	}
	}
	const morphAttribute = geometry.morphAttributes.position || geometry.morphAttributes.normal || geometry.morphAttributes.color;
	const morphTargetsCount = ( morphAttribute !== undefined ) ? morphAttribute.length : 0;
	const materialProperties = properties.get( material );
	const lights = currentRenderState.state.lights;
	if ( _clippingEnabled === true ) {
	if ( _localClippingEnabled === true || camera !== _currentCamera ) {
	const useCache =
	camera === _currentCamera &&
	material.id === _currentMaterialId;
	// we might want to call this function with some ClippingGroup
	// object instead of the material, once it becomes feasible
	// (#8465, #8379)
	clipping.setState( material, camera, useCache );
	}
	}
	//
	let needsProgramChange = false;
	if ( material.version === materialProperties.__version ) {
	if ( materialProperties.needsLights && ( materialProperties.lightsStateVersion !== lights.state.version ) ) {
	needsProgramChange = true;
	} else if ( materialProperties.outputColorSpace !== colorSpace ) {
	needsProgramChange = true;
	} else if ( object.isBatchedMesh && materialProperties.batching === false ) {
	needsProgramChange = true;
	} else if ( ! object.isBatchedMesh && materialProperties.batching === true ) {
	needsProgramChange = true;
	} else if ( object.isBatchedMesh && materialProperties.batchingColor === true && object.colorTexture === null ) {
	needsProgramChange = true;
	} else if ( object.isBatchedMesh && materialProperties.batchingColor === false && object.colorTexture !== null ) {
	needsProgramChange = true;
	} else if ( object.isInstancedMesh && materialProperties.instancing === false ) {
	needsProgramChange = true;
	} else if ( ! object.isInstancedMesh && materialProperties.instancing === true ) {
	needsProgramChange = true;
	} else if ( object.isSkinnedMesh && materialProperties.skinning === false ) {
	needsProgramChange = true;
	} else if ( ! object.isSkinnedMesh && materialProperties.skinning === true ) {
	needsProgramChange = true;
	} else if ( object.isInstancedMesh && materialProperties.instancingColor === true && object.instanceColor === null ) {
	needsProgramChange = true;
	} else if ( object.isInstancedMesh && materialProperties.instancingColor === false && object.instanceColor !== null ) {
	needsProgramChange = true;
	} else if ( object.isInstancedMesh && materialProperties.instancingMorph === true && object.morphTexture === null ) {
	needsProgramChange = true;
	} else if ( object.isInstancedMesh && materialProperties.instancingMorph === false && object.morphTexture !== null ) {
	needsProgramChange = true;
	} else if ( materialProperties.envMap !== envMap ) {
	needsProgramChange = true;
	} else if ( material.fog === true && materialProperties.fog !== fog ) {
	needsProgramChange = true;
	} else if ( materialProperties.numClippingPlanes !== undefined &&
	( materialProperties.numClippingPlanes !== clipping.numPlanes ||
	materialProperties.numIntersection !== clipping.numIntersection ) ) {
	needsProgramChange = true;
	} else if ( materialProperties.vertexAlphas !== vertexAlphas ) {
	needsProgramChange = true;
	} else if ( materialProperties.vertexTangents !== vertexTangents ) {
	needsProgramChange = true;
	} else if ( materialProperties.morphTargets !== morphTargets ) {
	needsProgramChange = true;
	} else if ( materialProperties.morphNormals !== morphNormals ) {
	needsProgramChange = true;
	} else if ( materialProperties.morphColors !== morphColors ) {
	needsProgramChange = true;
	} else if ( materialProperties.toneMapping !== toneMapping ) {
	needsProgramChange = true;
	} else if ( materialProperties.morphTargetsCount !== morphTargetsCount ) {
	needsProgramChange = true;
	}
	} else {
	needsProgramChange = true;
	materialProperties.__version = material.version;
	}

I still think we can potentially safe some checks if render objects share geometries and materials. We just have to honor node data (attributes data can be defined via nodes as well) in this process otherwise we end up with wrong cache hits.

3. Although the overhead is quite minor we could maybe squeeze out a bit of performance of the sort functions. WebGLRenderer would also benefit from that. The question is: Is the computation of a key per sort item actually faster than a bunch of comparisons. This is something we should give a try.

4 and 5 can be ignored for now I would say.

[sunag]

We can use set/get on material properties, considering that the user doesn't use this for mathematical calculations like in Vector*, few interactions per frame. After defining a property, we internally set _propertiesVersion, for example. With this and a few other adjustments, we can remove the NodeMaterialObserver. We will certainly see a significant reduction in comparisons per frame.

set map( value ) {

	this._map = value;
	this._propertiesVersion ++;

}

[mrdoob]

Yes, this is something I always considered doing.