@needle-tools/engine/src/engine-components/postprocessing/Effects/ColorAdjustments.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import { NoToneMapping } from "three";

import { MODULES } from "../../../engine/engine_modules.js";
import { serializable } from "../../../engine/engine_serialization.js";
import { type EffectProviderResult, PostProcessingEffect } from "../PostProcessingEffect.js";
import { VolumeParameter } from "../VolumeParameter.js";
import { registerCustomEffectType } from "../VolumeProfile.js";
import { ToneMappingEffect } from "./Tonemapping.js";

/**
 * [ColorAdjustments](https://engine.needle.tools/docs/api/ColorAdjustments) allows you to modify the overall color properties of the rendered scene, including post-exposure, contrast, hue shift, and saturation.  
 * These adjustments can be used to enhance the visual aesthetics of the scene or to achieve specific artistic effects.
 * @summary Color Adjustments Post-Processing Effect
 * @category Effects
 * @group Components
 */
export class ColorAdjustments extends PostProcessingEffect {

    get typeName() {
        return "ColorAdjustments";
    }

    /**
     * Whether values for contrast, hueshift or saturation are remapped to a different range.
     */
    remap = true;

    @serializable(VolumeParameter)
    readonly postExposure: VolumeParameter = new VolumeParameter(1);

    /**
     * Range -1 to 1, where 0 is the default value, -1 is the lowest contrast and 1 is the highest contrast.
     * @default 0
     */
    @serializable(VolumeParameter)
    readonly contrast: VolumeParameter = new VolumeParameter(0);

    @serializable(VolumeParameter)
    readonly hueShift: VolumeParameter = new VolumeParameter(0);

    @serializable(VolumeParameter)
    readonly saturation: VolumeParameter = new VolumeParameter(0);

    init() {
        this.postExposure!.valueProcessor = v => {
            if(!this.remap) return v;
            v = Math.pow(2.0, v);
            return v;
        }
        this.contrast.valueProcessor = (v: number) => {
            if(!this.remap) return v;
            let divisor = 1;
            if (v > 0) divisor = 200;
            else if (v < 0) divisor = 100;
            // if (v > 0) divisor *= Math.PI;
            const val = v / divisor;
            return val;
        };
        this.contrast.defaultValue = 0;

        this.hueShift.valueProcessor = (v: number) => {
            if(!this.remap) return v;
            return Math.PI * v / 180;
        }
        this.hueShift.defaultValue = 0;

        this.saturation.valueProcessor = (v: number) => {
            if(!this.remap) return v;
            if (v < 0) return (v / 100);
            const sat = (v / (100 * Math.PI));
            return sat;
        }
        this.saturation.defaultValue = 0;
    }

    onCreateEffect(): EffectProviderResult {
        const effects: EffectProviderResult = [];

        // TODO: do we still need this?
        // if (this.context.renderer.toneMapping !== NoToneMapping && this.postExposure.overrideState)
        //     this.context.renderer.toneMapping = NoToneMapping;
        // Find the ToneMapping effect because we need it to apply post exposure.
        // We don't auto-create one — that would be a surprising side effect on the user's stack,
        // and the user should add a ToneMappingEffect explicitly if they want PostExposure.
        const tonemappingEffect = this.postprocessingContext?.components.find(
            (c): c is ToneMappingEffect => c instanceof ToneMappingEffect
        );
        let warnedMissingTonemap = false;
        this.postExposure!.onValueChanged = (v) => {
            if (!this.postExposure.overrideState) return;
            if (!tonemappingEffect) {
                if (!warnedMissingTonemap) {
                    warnedMissingTonemap = true;
                    console.warn("[PostProcessing] ColorAdjustments.PostExposure has no effect: add a ToneMappingEffect to your postprocessing stack.");
                }
                return;
            }
            tonemappingEffect.exposure.value = v;
        };

        const brightnesscontrast = new MODULES.POSTPROCESSING.MODULE.BrightnessContrastEffect();
        this.contrast!.onValueChanged = v => brightnesscontrast.contrast = v;

        const hueSaturationEffect = new MODULES.POSTPROCESSING.MODULE.HueSaturationEffect();
        this.hueShift!.onValueChanged = v => hueSaturationEffect.hue = v;
        this.saturation!.onValueChanged = v => hueSaturationEffect.saturation = v;


        effects.push(brightnesscontrast);
        effects.push(hueSaturationEffect);
        return effects;
    }
}
registerCustomEffectType("ColorAdjustments", ColorAdjustments);