InstancedMesh: Add support for async color definitions.

[CodyJasonBennett]

Fixed #21786

Description

Flags the current instanced material for update on render whenever instanceColor is (un)set. This tracks async effects without explicitly managing them in InstancedMesh.

Show Example:

The following renders a red cube whenever instanceColor is properly in sync with the mesh (~1s).

import * as THREE from 'three';

let renderer, scene, camera;

init();
animate();

function init() {

    renderer = new THREE.WebGLRenderer();
    renderer.setSize( window.innerWidth, window.innerHeight );
    renderer.setPixelRatio( window.devicePixelRatio );
    document.body.appendChild( renderer.domElement );

    scene = new THREE.Scene();
    
    camera = new THREE.PerspectiveCamera( 40, window.innerWidth / window.innerHeight );
    camera.position.z = 5;

    const geometry = new THREE.BoxGeometry();

    const material = new THREE.ShaderMaterial({
      vertexShader: /* glsl */ `

        varying vec3 vColor;

        void main() {

          #ifdef USE_INSTANCING_COLOR

            vColor = instanceColor;

          #endif

          gl_Position = projectionMatrix * modelViewMatrix * instanceMatrix * vec4( position, 1.0 );

        }

      `,
      fragmentShader: /* glsl */ `

        varying vec3 vColor;

        void main() {

          gl_FragColor = vec4( vColor, 1.0 );

        }

      `,
    });

    const mesh = new THREE.InstancedMesh( geometry, material, 1 );
    scene.add( mesh );

    setTimeout(() => {

      mesh.setColorAt( 0, new THREE.Color( 'red' ) );
      mesh.instanceColor.needsUpdate = true;

    }, 1000 );

}

function animate() {

  requestAnimationFrame( animate );
  renderer.render( scene, camera );

}

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

Filesize dev	Filesize PR	Diff
643.8 kB (159.6 kB)	644 kB (159.7 kB)	+170 B

🌳 Bundle size after tree-shaking

Minimal build including a renderer, camera, empty scene, and dependencies.

Filesize dev	Filesize PR	Diff
437 kB (105.8 kB)	437.2 kB (105.8 kB)	+170 B

[Mugen87]

We have to decide first if we want to support setting instanceColor asynchronously or if the data setup has to be done before the first render.

The problem is that every additional check in setProgram() increases the per-frame overhead for all scenes. So my personal preference is to not add these checks but update the docs instead.

[Mugen87]

On the other hand setting up the instanced mesh before the first render does not fix the use case described in #21786 (comment).

Um, this is indeed a tricky one. I guess I'm okay with accepting the changes to the renderer then.