Merge pull request #723 from pmndrs/cdl

CDL implementation for tone mapping

Author: vanruesc

manual/assets/js/src/demos/tone-mapping.ts

@@ -11,6 +11,7 @@ import {
 } from "three";
 
 import {
+	CDLPreset,
 	ClearPass,
 	EffectPass,
 	GeometryPass,
@@ -21,6 +22,7 @@ import {
 } from "postprocessing";
 
 import { GLTF, GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { BindingApi } from "@tweakpane/core";
 import { Pane } from "tweakpane";
 import { SpatialControls } from "spatial-controls";
 import * as Utils from "../utils/index.js";
@@ -120,13 +122,25 @@ window.addEventListener("load", () => void load().then((assets) => {
 
 	// Settings
 
+	const params = {
+		preset: CDLPreset.DEFAULT
+	};
+
+	let binding: BindingApi | undefined;
+
 	const container = document.getElementById("viewport")!;
 	const pane = new Pane({ container: container.querySelector<HTMLElement>(".tp")! });
 	const fpsGraph = Utils.createFPSGraph(pane);
 	const folder = pane.addFolder({ title: "Settings" });
 	folder.addBinding(light, "intensity", { label: "lightIntensity", min: 0, max: 100, step: 0.1 });
 	folder.addBinding(renderer, "toneMappingExposure", { min: 0, max: 4, step: 0.01 });
-	folder.addBinding(effect, "toneMapping", { options: Utils.enumToRecord(ToneMapping) });
+
+	folder.addBinding(effect, "toneMapping", { options: Utils.enumToRecord(ToneMapping) })
+		.on("change", (e) => void (binding!.hidden = (e.value !== ToneMapping.AGX)));
+
+	binding = folder.addBinding(params, "preset", { label: "CDL preset", options: Utils.enumToRecord(CDLPreset) })
+		.on("change", (e) => effect.cdl.applyPreset(e.value));
+
 	Utils.addBlendModeBindings(folder, effect.blendMode);
 
 	// Resize Handler

manual/content/demos/color-grading/tone-mapping.en.md

@@ -25,6 +25,15 @@ const toneMappingEffect = new ToneMappingEffect({
 > [!TIP]
 > Tone mapping should generally be applied late in a render pipeline, but before anti-aliasing and the final color space conversion.
 
+## Primary Color Grading
+
+The `ToneMappingEffect` uses the American Society of Cinematographers Color Decision List (ASC CDL) format to configure primary
+color grading information. This format defines the math for Slope, Offset, Power and Saturation and provides a way to influence the look of the tone-mapped image.
+
+> [!INFO]
+> Only `ToneMapping.AGX` currently supports CDL parameters.
+
 ## External Resources
 
 * [Tone Mapping Techniques](https://64.github.io/tonemapping)
+* [ASC CDL](https://en.wikipedia.org/wiki/ASC_CDL)

src/effects/ToneMappingEffect.ts

@@ -1,18 +1,11 @@
+import { ShaderChunk } from "three";
+import { CDLPreset } from "../enums/CDLPreset.js";
 import { ToneMapping } from "../enums/ToneMapping.js";
+import { ColorDecisionList } from "../utils/ColorDecisionList.js";
 import { Effect } from "./Effect.js";
 
 import fragmentShader from "./shaders/tone-mapping.frag";
 
-const toneMappingOperators = new Map<ToneMapping, string>([
-	[ToneMapping.LINEAR, "LinearToneMapping(texel)"],
-	[ToneMapping.REINHARD, "ReinhardToneMapping(texel)"],
-	[ToneMapping.CINEON, "CineonToneMapping(texel)"],
-	[ToneMapping.ACES_FILMIC, "ACESFilmicToneMapping(texel)"],
-	[ToneMapping.AGX, "AgXToneMapping(texel)"],
-	[ToneMapping.NEUTRAL, "NeutralToneMapping(texel)"],
-	[ToneMapping.CUSTOM, "CustomToneMapping(texel)"]
-]);
-
 /**
  * ToneMappingEffect options.
  *
@@ -29,6 +22,14 @@ export interface ToneMappingEffectOptions {
 
 	toneMapping?: ToneMapping;
 
+	/**
+	 * A CDL Preset. Only applies to {@link ToneMapping.AGX}.
+	 *
+	 * @defaultValue null
+	 */
+
+	cdlPreset?: CDLPreset | null;
+
 }
 
 /**
@@ -39,18 +40,40 @@ export interface ToneMappingEffectOptions {
 
 export class ToneMappingEffect extends Effect implements ToneMappingEffectOptions {
 
+	/**
+	 * ASC CDL settings for primary color grading.
+	 */
+
+	readonly cdl: ColorDecisionList;
+
 	/**
 	 * Constructs a new tone mapping effect.
 	 *
 	 * @param options - The options.
 	 */
 
-	constructor({ toneMapping = ToneMapping.AGX }: ToneMappingEffectOptions = {}) {
+	constructor({ toneMapping = ToneMapping.AGX, cdlPreset = null }: ToneMappingEffectOptions = {}) {
 
 		super("ToneMappingEffect");
 
-		this.fragmentShader = fragmentShader;
+		this.fragmentShader = fragmentShader.replace(
+			// Resolve the #include early to ensure that applyCDL gets prefixed.
+			// This is only necessary because the shader chunk uses a function from the effect shader.
+			"#include <tonemapping_pars_fragment>",
+			ShaderChunk.tonemapping_pars_fragment.replace(
+				/(color = AgXOutsetMatrix \* color;)/,
+				"color = applyCDL(color);\n$1"
+			)
+		);
+
+		this.cdl = new ColorDecisionList();
+		this.cdl.addEventListener("toggle", () => this.onCDLToggle());
+
+		this.input.uniforms.set("cdl", this.cdl.uniform);
+		this.input.defines.set("USE_CDL", true);
+
 		this.toneMapping = toneMapping;
+		this.cdl.applyPreset(cdlPreset);
 
 	}
 
@@ -65,22 +88,31 @@ export class ToneMappingEffect extends Effect implements ToneMappingEffectOption
 		if(this.toneMapping !== value) {
 
 			const defines = this.input.defines;
-			defines.clear();
 			defines.set("TONE_MAPPING", value);
+			this.setChanged();
 
-			const operator = toneMappingOperators.get(value);
+		}
 
-			if(operator === undefined) {
+	}
 
-				throw new Error(`Invalid tone mapping: ${value}`);
+	/**
+	 * Performs tasks when the CDL is enabled or disabled.
+	 */
 
-			}
+	private onCDLToggle(): void {
 
-			defines.set("toneMapping(texel)", operator);
-			this.setChanged();
+		if(this.cdl.enabled) {
+
+			this.input.defines.set("USE_CDL", true);
+
+		} else {
+
+			this.input.defines.delete("USE_CDL");
 
 		}
 
+		this.setChanged();
+
 	}
 
 }

src/effects/shaders/tone-mapping.frag

@@ -1,7 +1,80 @@
+#ifdef USE_CDL
+
+	struct ColorDecisionList {
+		vec3 slope;
+		vec3 offset;
+		vec3 power;
+		float saturation;
+	};
+
+	uniform ColorDecisionList cdl;
+
+	/**
+	 * Applies ASC CDL v1.2 color grade to input color in an unspecified log or linear space.
+	 *
+	 * @see https://blender.stackexchange.com/a/55239/43930
+	 * @see https://docs.acescentral.com/specifications/acescc/
+	 * @param color - A color in a log space (such as LogC, ACEScc, or AgX Log).
+	 * @return - The transformed color (same color space).
+	 */
+
+	vec3 applyCDL(in vec3 color) {
+
+		// ASC CDL v1.2 explicitly requires Rec. 709 luminance coefficients.
+		float l = dot(color, vec3(0.2126, 0.7152, 0.0722));
+		vec3 v = max(color * cdl.slope + cdl.offset, 0.0);
+		vec3 pv = pow(v, cdl.power);
+
+		if(v.r > 0.0) { v.r = pv.r; }
+		if(v.g > 0.0) { v.g = pv.g; }
+		if(v.b > 0.0) { v.b = pv.b; }
+
+		return (v - l) * cdl.saturation + l;
+
+	}
+
+#else
+
+	#define applyCDL(color) color
+
+#endif
+
 #include <tonemapping_pars_fragment>
 
 vec4 mainImage(const in vec4 inputColor, const in vec2 uv, const in GData gData) {
 
-	return vec4(toneMapping(inputColor.rgb), inputColor.a);
+	vec3 result;
+
+	#if TONE_MAPPING == 0
+
+		result = LinearToneMapping(inputColor.rgb);
+
+	#elif TONE_MAPPING == 1
+
+		result = ReinhardToneMapping(inputColor.rgb);
+
+	#elif TONE_MAPPING == 2
+
+		result = CineonToneMapping(inputColor.rgb);
+
+	#elif TONE_MAPPING == 3
+
+		result = ACESFilmicToneMapping(inputColor.rgb);
+
+	#elif TONE_MAPPING == 4
+
+		result = AgXToneMapping(inputColor.rgb);
+
+	#elif TONE_MAPPING == 5
+
+		result = NeutralToneMapping(inputColor.rgb);
+
+	#elif TONE_MAPPING == 6
+
+		result = CustomToneMapping(inputColor.rgb);
+
+	#endif
+
+	return vec4(result, inputColor.a);
 
 }

src/enums/CDLPreset.ts

@@ -0,0 +1,35 @@
+/**
+ * An enumeration of CDL presets for different looks.
+ *
+ * @category Enums
+ */
+
+export enum CDLPreset {
+
+	/**
+	 * The baseline look.
+	 *
+	 * Good for testing, but not well suited for production use due to flat colors.
+	 */
+
+	DEFAULT,
+
+	/**
+	 * A warmer look with more vivid colors.
+	 */
+
+	GOLDEN,
+
+	/**
+	 * Punchy colors with more saturation and higher contrast.
+	 */
+
+	PUNCHY,
+
+	/**
+	 * Adjusted for production use to have a similar feeling of contrast as ACES over a wide range of scenes.
+	 */
+
+	NEEDLE
+
+}

src/enums/ToneMapping.ts

@@ -11,37 +11,37 @@ export enum ToneMapping {
 	 * No tone mapping, only exposure. Colors will be clamped to the output range.
 	 */
 
-	LINEAR,
+	LINEAR = 0,
 
 	/**
 	 * Basic Reinhard tone mapping.
 	 *
 	 * @see https://www.cs.utah.edu/docs/techreports/2002/pdf/UUCS-02-001.pdf
 	 */
 
-	REINHARD,
+	REINHARD = 1,
 
 	/**
 	 * Optimized filmic operator by Jim Hejl and Richard Burgess-Dawson.
 	 *
 	 * @see http://filmicworlds.com/blog/filmic-tonemapping-operators
 	 */
 
-	CINEON,
+	CINEON = 2,
 
 	/**
 	 * ACES filmic tone mapping with a scale of 1.0/0.6.
 	 */
 
-	ACES_FILMIC,
+	ACES_FILMIC = 3,
 
 	/**
 	 * Filmic tone mapping based on Blender's implementation using rec 2020 primaries.
 	 *
 	 * @see https://github.com/EaryChow/AgX
 	 */
 
-	AGX,
+	AGX = 4,
 
 	/**
 	 * Neutral tone mapping by Khronos.
@@ -50,7 +50,7 @@ export enum ToneMapping {
 	 * @see https://modelviewer.dev/examples/tone-mapping
 	 */
 
-	NEUTRAL,
+	NEUTRAL = 5,
 
 	/**
 	 * Custom tone mapping.
@@ -60,6 +60,6 @@ export enum ToneMapping {
 	 * @see https://threejs.org/docs/?q=shader#api/en/renderers/shaders/ShaderChunk
 	 */
 
-	CUSTOM
+	CUSTOM = 6
 
 }

src/enums/index.ts

@@ -1,4 +1,5 @@
 export * from "./ColorChannel.js";
+export * from "./CDLPreset.js";
 export * from "./DepthCopyMode.js";
 export * from "./DepthTestStrategy.js";
 export * from "./EffectShaderSection.js";