ColorManagement: Add ColorManagement.define( { ... } )

[donmccurdy]

Related issue: #29259 (comment)

Adds support for loading color space definitions from three/addons/..., and for user-supplied color space definitions. As the web platform adds support for wide gamut and “HDR” color spaces, this change is intended to allow more experimentation and flexible color workflows. Transfer functions are predefined at this time, and cannot be added dynamically.

Example:

import { ColorManagement } from 'three';
import { 
  DisplayP3ColorSpace,
  DisplayP3ColorSpaceImpl,
  LinearDisplayP3ColorSpace,
  LinearDisplayP3ColorSpaceImpl
} from 'three/addons/math/ColorSpaces.js';

// register Display P3
ColorManagement.define( {
  [ DisplayP3ColorSpace ]: DisplayP3ColorSpaceImpl,
  [ LinearDisplayP3ColorSpace ]: LinearDisplayP3ColorSpaceImpl
} );

// use Display P3
ColorManagement.workingColorSpace = LinearDisplayP3ColorSpace;
renderer.outputColorSpace = DisplayP3ColorSpace;
color.setRGB( r, g, b, DisplayP3ColorSpace );
...

Notable changes:

• SRGBColorSpace and LinearSRGBColorspace (working color space) are included by default
• DisplayP3ColorSpace and LinearDisplayP3ColorSpace are moved to three/addons
• LinearRec2020ColorSpace and LinearRec2100DisplayColorSpace are added to three/addons
• Restrictions on ColorManagement.workingColorSpace are removed; support for anything other than LinearSRGBColorSpace should be considered 'experimental'
• ColorManagement is refactored to allow use of external color space definitions

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	687.46 170.22	686.84 170.1	-615 B -121 B
WebGPU	840.72 225.48	840.76 225.5	+45 B +19 B
WebGPU Nodes	840.22 225.36	840.27 225.38	+45 B +22 B

🌳 Bundle size after tree-shaking

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

	Before	After	Diff
WebGL	463.24 111.86	462.72 111.74	-517 B -124 B
WebGPU	534.85 144.34	535.01 144.4	+155 B +63 B
WebGPU Nodes	491.2 134.09	491.35 134.19	+155 B +103 B

[sunag]

With the exception of SRGB, wide gamut can we perform color space conversions just using matrix multiplication?
The implementation looks amazing.

[donmccurdy]

Thanks @sunag! Yes, we can convert from any supported RGB color space "A" to "B" with the same structure:

<decode transfer function A>
<matrix multiplication>
<encode transfer function B>

If either A or B is a ”linear” space, its transfer function is a no-op, and that step can be skipped. So conversion between two linear spaces would just be a matrix multiplication.

For now the only transfer functions we need to care about today are the “sRGB” transfer functions, (our LinearToSRGB and SRGBToLinear functions), shared by sRGB and Display P3 color spaces. Perhaps we'll need a few more transfer functions someday, but probably not soon.

[donmccurdy]

@WestLangley @Mugen87 with r169 out now, I'd love to merge this early in the month for r170 if possible – do you see any concerns? I don't feel strongly that Display P3 needs to be moved to three/addons, I think that's the only "breaking change" here, but it was nice to use as a test case for future color spaces in three/addons.

/cc @gkjohnson FYI