+
- THREE.REVISION
+THREE.REVISION
- THREE.MOUSE.LEFT
- THREE.MOUSE.MIDDLE
- THREE.MOUSE.RIGHT
-
+
+THREE.SRGBColorSpace
+THREE.LinearSRGBColorSpace
+
+
+ + [page:SRGBColorSpace] (“sRGB”) refers to the color space defined by the Rec. 709 primaries, D65 + white point, and nonlinear sRGB transfer functions. sRGB is the default color space in + CSS, and is often found in color palettes and color pickers. Colors expressed in + hexadecimal or CSS notation are typically in the sRGB color space. +
+ ++ [page:LinearSRGBColorSpace] (“Linear-sRGB”) refers to the sRGB color space (above) with + linear transfer functions. Linear-sRGB is the working color space in three.js, used + throughout most of the rendering process. RGB components found in three.js materials + and shaders are in the Linear-sRGB color space. + D
+ ++ For further background and usage, see Color management. +
+ +
+THREE.MOUSE.LEFT
+THREE.MOUSE.MIDDLE
+THREE.MOUSE.RIGHT
+
- THREE.MOUSE.LEFT
- THREE.MOUSE.MIDDLE
- THREE.MOUSE.RIGHT
-
+
+THREE.SRGBColorSpace
+THREE.LinearSRGBColorSpace
+
+
+ + [page:SRGBColorSpace] (“sRGB”) refers to the color space defined by the Rec. 709 primaries, D65 + white point, and nonlinear sRGB transfer functions. sRGB is the default color space in + CSS, and is often found in color palettes and color pickers. Colors expressed in + hexadecimal or CSS notation are typically in the sRGB color space. +
+ ++ [page:LinearSRGBColorSpace] (“Linear-sRGB”) refers to the sRGB color space (above) with + linear transfer functions. Linear-sRGB is the working color space in three.js, used + throughout most of the rendering process. RGB components found in three.js materials + and shaders are in the Linear-sRGB color space. + D
+ ++ For further background and usage, see Color management. +
+ +
+ THREE.MOUSE.LEFT
+ THREE.MOUSE.MIDDLE
+ THREE.MOUSE.RIGHT
+
- THREE.MOUSE.LEFT
- THREE.MOUSE.MIDDLE
- THREE.MOUSE.RIGHT
-
+
+THREE.SRGBColorSpace
+THREE.LinearSRGBColorSpace
+
+
+ + [page:SRGBColorSpace] (“sRGB”) refers to the color space defined by the Rec. 709 primaries, D65 + white point, and nonlinear sRGB transfer functions. sRGB is the default color space in + CSS, and is often found in color palettes and color pickers. Colors expressed in + hexadecimal or CSS notation are typically in the sRGB color space. +
+ ++ [page:LinearSRGBColorSpace] (“Linear-sRGB”) refers to the sRGB color space (above) with + linear transfer functions. Linear-sRGB is the working color space in three.js, used + throughout most of the rendering process. RGB components found in three.js materials + and shaders are in the Linear-sRGB color space. + D
+ ++ For further background and usage, see Color management. +
+ +
+ THREE.MOUSE.LEFT
+ THREE.MOUSE.MIDDLE
+ THREE.MOUSE.RIGHT
+
+ Every color space is a collection of several design decisions, chosen together to support a + large range of colors while satisfying technical constraints related to precision and display + technologies. When creating a 3D asset, or assembling 3D assets together into a scene, it is + important to know what these properties are, and how the properties of one color space relate + to other color spaces in the scene. +
+ +
+ + Consider two very common color spaces: [page:SRGBColorSpace] ("sRGB") and + [page:LinearSRGBColorSpace] ("Linear-sRGB"). Both use the same primaries and white point, + and therefore have the same color gamut. Both use the RGB color model. They differ only in + the transfer functions — Linear-sRGB is linear with respect to physical light intensity. + sRGB uses the nonlinear sRGB transfer functions, and more closely resembles the way that + the human eye perceives light and the responsiveness of common display devices. +
+ ++ That difference is important. Lighting calculations and other rendering operations must + generally occur in a linear color space. However, a linear colors are less efficient to + store in an image or framebuffer, and do not look correct when viewed by a human observer. + As a result, input textures and the final rendered image will generally use the nonlinear + sRGB color space. +
+ +++ ++ ℹ️ NOTICE: While some modern displays support wider gamuts like Display-P3, + the web platform's graphics APIs largely rely on sRGB. Applications using three.js + today will typically use only the sRGB and Linear-sRGB color spaces. +
+
+ Linear workflows — required for modern rendering methods — generally involve more than + one color space, each assigned to a particular role. Linear and nonlinear color spaces are + appropriate for different roles, explained below. +
+ ++ Colors supplied to three.js — from color pickers, textures, 3D models, and other sources — + each have an associated color space. Those not already in the Linear-sRGB working color + space must be converted, and textures be given the correct texture.encoding assignment. + Certain conversions (for hexadecimal and CSS colors in sRGB) can be made automatically if + the legacy color management mode is disabled before initializing colors: +
+ +
+THREE.ColorManagement.legacyMode = false;
+
+
+ ++ ++ ⚠️ WARNING: [page:Scene.fog], [page:Scene.background], and [page:WebGLRenderer.setClearColor] + are exceptions to the rule. These properties are unaffected by [page:WebGLRenderer.outputEncoding] + and so must store RGB components in the renderer's output color space. +
+
++ ++ ⚠️ WARNING: Many formats for 3D models do not correctly or consistently + define color space information. While three.js attempts to handle most cases, problems + are common with older file formats. For best results, use glTF 2.0 ([page:GLTFLoader]) + and test 3D models in online viewers early to confirm the asset itself is correct. +
+
+ Rendering, interpolation, and many other operations must be performed in an open domain + linear working color space, in which RGB components are proportional to physical + illumination. In three.js, the working color space is Linear-sRGB. +
+ ++ Output to a display device, image, or video may involve conversion from the open domain + Linear-sRGB working color space to another color space. This conversion may be performed in + the main render pass ([page:WebGLRenderer.outputEncoding]), or during post-processing. +
+ +
+renderer.outputEncoding = THREE.sRGBEncoding; // optional with post-processing
+
+
+ ++ ++ ⚠️ WARNING: Render targets may use either sRGB or Linear-sRGB. sRGB makes + better use of limited precision. In the closed domain, 8 bits often suffice for sRGB + whereas ≥12 bits (half float) may be required for Linear-sRGB. If later pipeline + stages require Linear-sRGB input, the additional conversions may have a small + performance cost. +
+
+ Methods reading or modifying [page:Color] instances assume data is already in the + three.js working color space, Linear-sRGB. RGB and HSL components are direct + representations of data stored by the Color instance, and are never converted + implicitly. Color data may be explicitly converted with .convertLinearToSRGB() + or .convertSRGBToLinear(). +
+ +
+ // RGB components (no change).
+ color.r = color.g = color.b = 0.5;
+ console.log( color.r ); // → 0.5
+
+ // Manual conversion.
+ color.r = 0.5;
+ color.convertSRGBToLinear();
+ console.log( color.r ); // → 0.214041140
+
+
+ + With ColorManagement.legacyMode = false set (recommended), certain conversions + are made automatically. Because hexadecimal and CSS colors are generally sRGB, [page:Color] + methods will automatically convert these inputs from sRGB to Linear-sRGB in setters, or + convert from Linear-sRGB to sRGB when returning hexadecimal or CSS output from getters. +
+ +
+ // Hexadecimal conversion.
+ color.setHex( 0x808080 );
+ console.log( color.r ); // → 0.214041140
+ console.log( color.getHex() ); // → 0x808080
+
+ // CSS conversion.
+ color.setStyle( 'rgb( 0.5, 0.5, 0.5 )' );
+ console.log( color.r ); // → 0.214041140
+
+ // Override conversion with 'colorSpace' argument.
+ color.setHex( 0x808080, LinearSRGBColorSpace );
+ console.log( color.r ); // → 0.5
+ console.log( color.getHex( LinearSRGBColorSpace ) ); // → 0x808080
+ console.log( color.getHex( SRGBColorSpace ) ); // → 0xBCBCBC
+
+
+ + When an individual color or texture is misconfigured, it will appear darker or lighter than + expected. When the renderer's output color space is misconfigured, the entire scene may appear + darker (e.g. missing conversion to sRGB) or lighter (e.g. a double conversion to sRGB with + post-processing). In each case the problem may not be uniform, and simply increasing/decreasing + lighting does not solve it. +
+ ++ A more subtle issue appears when both the input color spaces and the output color + spaces are incorrect — the overall brightness levels may be fine, but colors may change + unexpectedly under different lighting, or shading may appear more blown-out and less soft + than intended. These two wrongs do not make a right, and it's important that the working + color space be linear ("scene referred") and the output color space be nonlinear + ("display referred"). +
+ +