Renderer: Rename shadowMap.color to shadowMap.colored.

[Mugen87]

Related issue: #32596 (comment)

Description

The PR renames shadowMap.color so it's more clear the property is a boolean.

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	355.34 84.47	355.34 84.47	+0 B +0 B
WebGPU	618.69 171.84	618.7 171.85	+14 B +9 B
WebGPU Nodes	617.29 171.6	617.3 171.6	+14 B +8 B

🌳 Bundle size after tree-shaking

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

	Before	After	Diff
WebGL	487.5 119.33	487.5 119.33	+0 B +0 B
WebGPU	690.95 187.49	690.96 187.5	+14 B +9 B
WebGPU Nodes	640.79 174.72	640.8 174.73	+14 B +8 B

[sunag]

Wouldn't the term 'colored' be better? To be honest, I think the term 'Enabled' as a suffix is redundant; it's fine for defining the block using only '.enabled', but I don't think it should go beyond that. If we imagine this throughout the API, we'll see that the 'Enabled' suffix could easily be removed and replaced with something much more like 'renderer.depth', 'material.transparent', and so on.

[Mugen87]

I think colored is a good compromise. The name is compact and prevents that developers get the assumption the property's value is an instance of THREE.Color.

[WestLangley]

Sorry, but this is still not clear to me.

Where is the "custom color" set?

What does this property enable, precisely? When is it required?

If you can explain that in a few words, then perhaps we can come up with a better definition.

[sunag]

material.castShadowNode allows to customize the colors and opacity of the cast shadow per material with a vec4.

three.js/src/renderers/common/Renderer.js

Lines 3056 to 3060 in 288d8a3

	if ( this.shadowMap.colored !== true ) {
	warnOnce( 'Renderer: `shadowMap.colored` needs to be set to `true` when using `material.castShadowNode`.' );
	}

[WestLangley]

So renderer.shadowMap.colored = true is only required if material.castShadowNode is defined?

[sunag]

For now, yes. But your question made me rethink a few things.

This hasn't been implemented in the PBR yet; it should be eventually. The concept of colored shadows should be replaced by light transmission.

I think we could consider a more suitable name in this sense, if we consider that there is no colored shadow in the physically-based sense, but rather the transmission of light and the tint due to its color interference.

Should this be called shadowMap.transmitted?

[WestLangley]

Shadows are the absence of light in three.js, as they are in the real world.

On a related note, light.shadow.intensity = 0.5 is a hack that, in effect, allows light to transmit through the object, brightening (and potentially tinting) the shadow. This property works without setting renderer.shadowMap.colored = true.

[sunag]

Yes, it's no different from what is stated here.

The term transmitted should imply that the shadow should somehow consider the transmission of light in non-opaque materials.

[trusktr]

If not using material.cashShadowNode, should renderer.shadowMap.transmitted (previously .colored) be always set to false?

EDIT: Ah, I think it is that transmitted true on its own without castShadowNode will be used when built-in transmission is added later, right?

[sunag]

@trusktr Yes for both, that's the intention.