From 3e96b7911f8753bf496966e7df6bd851a3e16417 Mon Sep 17 00:00:00 2001
From: Cody Bennett <hi@codyb.co>
Date: Tue, 29 Mar 2022 14:13:19 -0500
Subject: [PATCH] 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
---
 docs/API/canvas.mdx                         |  1 +
 docs/tutorials/v8-migration-guide.mdx       | 16 +++++++++++++-
 packages/fiber/src/core/index.tsx           |  3 +++
 packages/fiber/tests/core/renderer.test.tsx | 23 +++++++++++++++++++--
 4 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/docs/API/canvas.mdx b/docs/API/canvas.mdx
index 5c4b2b0829..c2f88768b5 100644
--- 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
index ad2c50a9f4..87949a90fd 100644
--- 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
index 398fbc95ec..dccfd8d42a 100644
--- 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
index 1e6bf2d655..a438bda42f 100644
--- 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)
+  })
 })