WebGLRenderer: Support "Linear Display P3" working color space and "Display P3" unlit rendering

[donmccurdy]

tl;dr — Adds support for wide gamut color spaces in unlit rendering workflows such as 2D games, photogrammetry, and image processing applications.

---

Extends THREE.ColorManagement and THREE.WebGLRenderer with support — only in "unlit" scenes, currently — for the wide-gamut Display P3 color space. To use this feature, the following steps are required:

1. Assign ColorManagement.workingColorSpace = LinearDisplayP3ColorSpace
2. Assign renderer.outputColorSpace = DisplayP3ColorSpace
3. Assign texture.colorSpace = DisplayP3ColorSpace AND ensure each texture's ICC Profile (or other color space metadata) is correctly embedded

To see the difference in this example, you'll need use Chrome or Safari, and a display and operating system that support the Display P3 wide gamut color space. Most newer macOS devices will do fine, but your external monitor may not. The change covers only unlit rendering now, e.g. MeshBasicMaterial. More changes will be required to adjust the lit rendering pipeline for a wider gamut, and @WestLangley and I are still discussing those requirements.

---

The images attached are borrowed from https://webkit.org/blog-files/color-gamut/comparison.html. We will want to verify the licenses and attribution before merging this PR, or create our own examples.

---

Related

• Roadmap for supporting wide-gamut color workflows #26479

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

Filesize dev	Filesize PR	Diff
645.6 kB (160.2 kB)	647.6 kB (160.8 kB)	+2.07 kB

🌳 Bundle size after tree-shaking

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

Filesize dev	Filesize PR	Diff
438.9 kB (106.3 kB)	440.9 kB (106.9 kB)	+2.01 kB

[donmccurdy]

To summarize a few things happening in this PR and its demo —

1. When the browser supports Display P3 (In 2023: Chrome and Safari), and the developer knows their scene contains wide gamut content, we assign ColorManagement.workingColorSpace = LinearDisplayP3ColorSpace to enable wide gamut rendering.
2. When the display supports Display P3 (In 2023: Most macOS, iOS, and Pixel devices) we assign renderer.outputColorSpace = DisplayP3ColorSpace to enable wide gamut output. This may change during a session, if displays are (dis)connected or windows are moved to another display.
3. When a texture's .colorSpace property indicates that it uses primaries differing from those of the working color space (e.g. sRGB textures in a Linear Display P3 working color space) the renderer enables gl.UNPACK_COLORSPACE_CONVERSION_WEBGL to gamut map the texture to the working color space. This operation requires that the texture's ICC profile be correct; setting texture.colorSpace alone is not enough. WebGL cannot do this for compressed textures or data textures — they must already use the working primaries.
4. When a texture's .colorSpace property indicates that it uses a supported transfer function (both sRGB and Display P3 use the "sRGB" transfer function) the renderer chooses an internal format such that WebGL will automatically apply the sRGB EOTF when sampling from the texture.
5. After rendering, pixels are encoded to the output color space.

As a result of (3) and (4), color images are typically uploaded to WebGL in either sRGB or Display P3 (whichever is the non-linear analog to the linear working color space). When the GPU samples the textures, it decodes each sample by applying the sRGB EOTF, to obtain a sample in the working color space (Linear sRGB or Linear Display P3).

[donmccurdy]

I've simplified the demo, using just a three.js logo. Copyright assigned to the three.js authors, Creative Commons Attribution 3.0. This is ready to merge experimentally, when we are ready. We can then continue working on changes required for lit rendering.

[mrdoob]

Do we need this new method?
Could we inline the calls in set outputColorSpace( colorSpace )?

[donmccurdy]

No need for it – or we don't need a public method, at least. I've inlined the calls in the setter. ✅

[donmccurdy]

FYI, this demo has just broken in Safari on macOS Sonoma:

https://bugs.webkit.org/show_bug.cgi?id=262429