WebGLRenderer: Support "Linear Display P3" working color space and "Display P3" unlit rendering by donmccurdy · Pull Request #26644 · mrdoob/three.js

donmccurdy · 2023-08-25T01:27:05Z

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:

Assign ColorManagement.workingColorSpace = LinearDisplayP3ColorSpace
Assign renderer.outputColorSpace = DisplayP3ColorSpace
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.~~

Roadmap for supporting wide-gamut color workflows #26479

github-actions · 2023-08-25T01:29:38Z

📦 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

examples/webgl_test_wide_gamut.html

src/renderers/webgl/WebGLBackground.js

src/renderers/webgl/WebGLPrograms.js

src/renderers/webgl/WebGLProgram.js

src/renderers/webgl/WebGLTextures.js

src/renderers/webgl/WebGLUtils.js

src/math/ColorManagement.js

donmccurdy · 2023-08-30T01:19:55Z

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

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.
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.
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.
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.
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 · 2023-08-31T19:21:55Z

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.

src/renderers/webgl/WebGLBackground.js

mrdoob · 2023-09-07T10:17:22Z

src/renderers/WebGLRenderer.js

+		this.resetColorManagement = function () {
+
+			_gl.drawingBufferColorSpace = this._outputColorSpace === DisplayP3ColorSpace ? 'display-p3' : 'srgb';
+			_gl.unpackColorSpace = ColorManagement.workingColorSpace === LinearDisplayP3ColorSpace ? 'display-p3' : 'srgb';
+
+		};
+


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

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

Co-authored-by: Levi Pesin <35454228+LeviPesin@users.noreply.github.com>

donmccurdy · 2023-09-30T04:21:27Z

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

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

### Changelog Now compatible with three.js r157+ ### Docs None ### Description Closes #391 The `LinearTosRGB` function was renamed in r157 mrdoob/three.js#26644 and the old function was removed in r167 mrdoob/three.js#28901

…doob#31142)

github-advanced-security bot found potential problems Aug 25, 2023

View reviewed changes

donmccurdy commented Aug 25, 2023

View reviewed changes

src/math/ColorManagement.js Outdated Show resolved Hide resolved

donmccurdy mentioned this pull request Aug 25, 2023

Roadmap for supporting wide-gamut color workflows #26479

Open

10 tasks

LeviPesin reviewed Sep 4, 2023

View reviewed changes

src/renderers/webgl/WebGLBackground.js Outdated Show resolved Hide resolved

LeviPesin reviewed Sep 4, 2023

View reviewed changes

src/renderers/webgl/WebGLBackground.js Outdated Show resolved Hide resolved

donmccurdy mentioned this pull request Sep 7, 2023

USDZLoader: Load metallic, roughness, emissive, occlusion textures and fix color spaces #26710

Merged

mrdoob reviewed Sep 7, 2023

View reviewed changes

mrdoob added this to the r157 milestone Sep 7, 2023

donmccurdy added 19 commits September 7, 2023 10:24

WIP: Display P3 render example

80689ad

WIP: P3 implementation

47e0977

Clean up

caabb88

TransferFunction -> Transfer

a0c0c43

Clean up

d0736da

Clean up

d687708

Clean up

6339846

Move capabilities check out of WebGL.js

8db039b

Fix regressions

b990e5d

Clean up, fix typo

253e141

Clean up

5091edb

Listen for display gamut changes.

7fcb67a

Clean up

c9c7a9e

Fix regression in OutputPass.

6aaa778

Add 'LinearTosRGB' for backward-compatibility.

499149d

Add 'LinearToLinear' for backward-compatibility.

1fcc38b

Clean up

8b2fb84

Align labels

9b42148

Move detection of display-p3 capabilility to WebGL.js

98d5556

donmccurdy and others added 2 commits September 7, 2023 10:24

Apply suggestions from code review

bb5b1f3

Co-authored-by: Levi Pesin <35454228+LeviPesin@users.noreply.github.com>

Remove renderer.resetColorManangement()

b313f11

donmccurdy force-pushed the feat/webglrenderer-displayp3-v2 branch from 05e3aa0 to b313f11 Compare September 7, 2023 14:24

mrdoob merged commit 24ccd56 into mrdoob:dev Sep 7, 2023

donmccurdy deleted the feat/webglrenderer-displayp3-v2 branch September 7, 2023 16:54

This was referenced Sep 13, 2023

r157 three-types/three-ts-types#601

Closed

WebGLRenderer: Support "Linear Display P3" working color space and "Display P3" unlit rendering three-types/three-ts-types#608

Merged

elalish mentioned this pull request Oct 3, 2023

r157 google/model-viewer#4489

Merged

jtbandes mentioned this pull request Mar 27, 2025

Upgrade three.js dependency foxglove/three-text#398

Merged

Mugen87 added a commit to Mugen87/three.js that referenced this pull request May 21, 2025

WebGPURenderer: Apply color management changes from mrdoob#26644.

1814896

Mugen87 mentioned this pull request May 21, 2025

WebGPURenderer: Apply color management changes from #26644. #31142

Merged

Mugen87 added a commit that referenced this pull request May 21, 2025

WebGPURenderer: Apply color management changes from #26644. (#31142)

d1e71ae

RuthySheffi pushed a commit to RuthySheffi/three.js that referenced this pull request Jun 5, 2025

WebGPURenderer: Apply color management changes from mrdoob#26644. (mr…

f804796

…doob#31142)

RuthySheffi pushed a commit to RuthySheffi/three.js that referenced this pull request Jun 5, 2025

WebGPURenderer: Apply color management changes from mrdoob#26644. (mr…

e5db08d

…doob#31142)

Uh oh!

Conversation

donmccurdy commented Aug 25, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Aug 25, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Bundle size

🌳 Bundle size after tree-shaking

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

donmccurdy commented Aug 30, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

donmccurdy commented Aug 31, 2023

Uh oh!

Uh oh!

Uh oh!

mrdoob Sep 7, 2023

Choose a reason for hiding this comment

Uh oh!

donmccurdy Sep 7, 2023

Choose a reason for hiding this comment

Uh oh!

donmccurdy commented Sep 30, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

donmccurdy commented Aug 25, 2023 •

edited

Loading

github-actions bot commented Aug 25, 2023 •

edited

Loading

donmccurdy commented Aug 30, 2023 •

edited

Loading