feat(core): default physicallyCorrectLights to true (#2148)

* feat(core): default `physicallyCorrectLights` to true * chore: streamline gl defaults * chore(docs): note new gl defaults * chore(tests): flip gl prop case, respect lighting preferences
pmndrs · Mar 29, 2022 · 3e96b79 · 3e96b79
1 parent acfdb6a
commit 3e96b79
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 3 deletions.
diff --git a/docs/API/canvas.mdx b/docs/API/canvas.mdx
@@ -51,6 +51,7 @@ and with the following properties:
 
 - outputEncoding = THREE.sRGBEncoding
 - toneMapping = THREE.ACESFilmicToneMapping
+- physicallyCorrectLights = true
 
 It will also create the following scene internals:
 

diff --git a/docs/tutorials/v8-migration-guide.mdx b/docs/tutorials/v8-migration-guide.mdx
@@ -55,7 +55,9 @@ export default function App() {
 }
 ```
 
-## New dpr default
+## New gl defaults
+
+### DPR
 
 The default DPR has changed from `1` to `[1, 2]`, which will clamp depending on the screen's native pixel ratio.
 
@@ -69,6 +71,18 @@ This was the most common setting in the wild, so it was brought in as a better d
 <Canvas />
 ```
 
+### physicallyCorrectLights
+
+`gl.physicallyCorrectLights` has been enabled to calculate lighting consistently with models and PBR workflows (see [#2127](https://github.com/pmndrs/react-three-fiber/issues/2127)).
+
+This multiplies lights' `intensity` by a factor of one instead of PI. For other properties like `decay` and `distance`, see [https://threejs.org/docs/#api/en/lights/PointLight](https://threejs.org/docs/#api/en/lights/PointLight).
+
+You can configure `physicallyCorrectLights` yourself via the `gl` prop:
+
+```jsx
+<Canvas gl={{ physicallyCorrectLights: true | false }} />
+```
+
 ## Improved WebXR handling
 
 ### Automatic WebXR switching

diff --git a/packages/fiber/src/core/index.tsx b/packages/fiber/src/core/index.tsx
@@ -177,8 +177,11 @@ function createRoot<TCanvas extends Element>(canvas: TCanvas): ReconcilerRoot<TC
       if ((THREE as any).ColorManagement) (THREE as any).ColorManagement.legacyMode = false
       const outputEncoding = linear ? THREE.LinearEncoding : THREE.sRGBEncoding
       const toneMapping = flat ? THREE.NoToneMapping : THREE.ACESFilmicToneMapping
+      const physicallyCorrectLights =
+        (glConfig as Partial<Properties<THREE.WebGLRenderer>>)?.physicallyCorrectLights ?? true
       if (gl.outputEncoding !== outputEncoding) gl.outputEncoding = outputEncoding
       if (gl.toneMapping !== toneMapping) gl.toneMapping = toneMapping
+      if (gl.physicallyCorrectLights !== physicallyCorrectLights) gl.physicallyCorrectLights = physicallyCorrectLights
 
       // Set gl props
       if (glConfig && !is.fun(glConfig) && !isRenderer(glConfig) && !is.equ(glConfig, gl, shallowLoose))

diff --git a/packages/fiber/tests/core/renderer.test.tsx b/packages/fiber/tests/core/renderer.test.tsx
@@ -609,12 +609,12 @@ describe('renderer', () => {
     let gl: THREE.WebGLRenderer = null!
     await act(async () => {
       gl = createRoot(canvas)
-        .configure({ gl: { physicallyCorrectLights: true } })
+        .configure({ gl: { physicallyCorrectLights: false } })
         .render(<group />)
         .getState().gl
     })
 
-    expect(gl.physicallyCorrectLights).toBe(true)
+    expect(gl.physicallyCorrectLights).toBe(false)
   })
 
   it('should set a renderer via gl callback', async () => {
@@ -652,4 +652,23 @@ describe('renderer', () => {
     expect(gl.outputEncoding).toBe(THREE.LinearEncoding)
     expect(gl.toneMapping).toBe(THREE.NoToneMapping)
   })
+
+  it('should respect lighting preferences via gl', async () => {
+    let gl: THREE.WebGLRenderer = null!
+    await act(async () => {
+      gl = createRoot(canvas)
+        .render(<group />)
+        .getState().gl
+    })
+
+    expect(gl.physicallyCorrectLights).toBe(true)
+
+    await act(async () => {
+      gl = createRoot(canvas)
+        .configure({ gl: { physicallyCorrectLights: false } })
+        .render(<group />)
+        .getState().gl
+    })
+    expect(gl.physicallyCorrectLights).toBe(false)
+  })
 })