src/core/EffectComposer.js

import {
	DepthStencilFormat,
	DepthTexture,
	LinearFilter,
	SRGBColorSpace,
	UnsignedByteType,
	UnsignedIntType,
	UnsignedInt248Type,
	Vector2,
	WebGLRenderTarget
} from "three";
 
import { Timer } from "./Timer.js";
import { ClearMaskPass } from "../passes/ClearMaskPass.js";
import { CopyPass } from "../passes/CopyPass.js";
import { MaskPass } from "../passes/MaskPass.js";
import { Pass } from "../passes/Pass.js";
 
/**
 * The EffectComposer may be used in place of a normal WebGLRenderer.
 *
 * The auto clear behaviour of the provided renderer will be disabled to prevent unnecessary clear operations.
 *
 * It is common practice to use a {@link RenderPass} as the first pass to automatically clear the buffers and render a
 * scene for further processing.
 *
 * @implements {Resizable}
 * @implements {Disposable}
 */
 
export class EffectComposer {
 
	/**
	 * Constructs a new effect composer.
	 *
	 * @param {WebGLRenderer} renderer - The renderer that should be used.
	 * @param {Object} [options] - The options.
	 * @param {Boolean} [options.depthBuffer=true] - Whether the main render targets should have a depth buffer.
	 * @param {Boolean} [options.stencilBuffer=false] - Whether the main render targets should have a stencil buffer.
	 * @param {Boolean} [options.alpha] - Deprecated. Buffers are always RGBA since three r137.
	 * @param {Number} [options.multisampling=0] - The number of samples used for multisample antialiasing. Requires WebGL 2.
	 * @param {Number} [options.frameBufferType] - The type of the internal frame buffers. It's recommended to use HalfFloatType if possible.
	 */
 
	constructor(renderer = null, {
		depthBuffer = true,
		stencilBuffer = false,
		multisampling = 0,
		frameBufferType
	} = {}) {
 
		/**
		 * The renderer.
		 *
		 * @type {WebGLRenderer}
		 * @private
		 */
 
		this.renderer = null;
 
		/**
		 * The input buffer.
		 *
		 * Two identical buffers are used to avoid reading from and writing to the same render target.
		 *
		 * @type {WebGLRenderTarget}
		 * @private
		 */
 
		this.inputBuffer = this.createBuffer(depthBuffer, stencilBuffer, frameBufferType, multisampling);
 
		/**
		 * The output buffer.
		 *
		 * @type {WebGLRenderTarget}
		 * @private
		 */
 
		this.outputBuffer = this.inputBuffer.clone();
 
		/**
		 * A copy pass used for copying masked scenes.
		 *
		 * @type {CopyPass}
		 * @private
		 */
 
		this.copyPass = new CopyPass();
 
		/**
		 * A depth texture.
		 *
		 * @type {DepthTexture}
		 * @private
		 */
 
		this.depthTexture = null;
 
		/**
		 * The passes.
		 *
		 * @type {Pass[]}
		 * @private
		 */
 
		this.passes = [];
 
		/**
		 * A timer.
		 *
		 * @type {Timer}
		 * @private
		 */
 
		this.timer = new Timer();
 
		/**
		 * Determines whether the last pass automatically renders to screen.
		 *
		 * @type {Boolean}
		 */
 
		this.autoRenderToScreen = true;
 
		this.setRenderer(renderer);
 
	}
 
	/**
	 * The current amount of samples used for multisample anti-aliasing.
	 *
	 * @type {Number}
	 */
 
	get multisampling() {
 
		// TODO Raise min three version to 138 and remove || 0.
		return this.inputBuffer.samples || 0;
 
	}
 
	/**
	 * Sets the amount of MSAA samples.
	 *
	 * Requires WebGL 2. Set to zero to disable multisampling.
	 *
	 * @type {Number}
	 */
 
	set multisampling(value) {
 
		const buffer = this.inputBuffer;
		const multisampling = this.multisampling;
 
		if(multisampling > 0 && value > 0) {
 
			this.inputBuffer.samples = value;
			this.outputBuffer.samples = value;
			this.inputBuffer.dispose();
			this.outputBuffer.dispose();
 
		} else if(multisampling !== value) {
 
			this.inputBuffer.dispose();
			this.outputBuffer.dispose();
 
			// Enable or disable MSAA.
			this.inputBuffer = this.createBuffer(
				buffer.depthBuffer,
				buffer.stencilBuffer,
				buffer.texture.type,
				value
			);
 
			this.inputBuffer.depthTexture = this.depthTexture;
			this.outputBuffer = this.inputBuffer.clone();
 
		}
 
	}
 
	/**
	 * Returns the internal timer.
	 *
	 * @return {Timer} The timer.
	 */
 
	getTimer() {
 
		return this.timer;
 
	}
 
	/**
	 * Returns the renderer.
	 *
	 * @return {WebGLRenderer} The renderer.
	 */
 
	getRenderer() {
 
		return this.renderer;
 
	}
 
	/**
	 * Sets the renderer.
	 *
	 * @param {WebGLRenderer} renderer - The renderer.
	 */
 
	setRenderer(renderer) {
 
		this.renderer = renderer;
 
		if(renderer !== null) {
 
			const size = renderer.getSize(new Vector2());
			const alpha = renderer.getContext().getContextAttributes().alpha;
			const frameBufferType = this.inputBuffer.texture.type;
 
			if(frameBufferType === UnsignedByteType && renderer.outputColorSpace === SRGBColorSpace) {
 
				this.inputBuffer.texture.colorSpace = SRGBColorSpace;
				this.outputBuffer.texture.colorSpace = SRGBColorSpace;
 
				this.inputBuffer.dispose();
				this.outputBuffer.dispose();
 
			}
 
			renderer.autoClear = false;
			this.setSize(size.width, size.height);
 
			for(const pass of this.passes) {
 
				pass.initialize(renderer, alpha, frameBufferType);
 
			}
 
		}
 
	}
 
	/**
	 * Replaces the current renderer with the given one.
	 *
	 * The auto clear mechanism of the provided renderer will be disabled. If the new render size differs from the
	 * previous one, all passes will be updated.
	 *
	 * By default, the DOM element of the current renderer will automatically be removed from its parent node and the DOM
	 * element of the new renderer will take its place.
	 *
	 * @deprecated Use setRenderer instead.
	 * @param {WebGLRenderer} renderer - The new renderer.
	 * @param {Boolean} updateDOM - Indicates whether the old canvas should be replaced by the new one in the DOM.
	 * @return {WebGLRenderer} The old renderer.
	 */
 
	replaceRenderer(renderer, updateDOM = true) {
 
		const oldRenderer = this.renderer;
		const parent = oldRenderer.domElement.parentNode;
 
		this.setRenderer(renderer);
 
		if(updateDOM && parent !== null) {
 
			parent.removeChild(oldRenderer.domElement);
			parent.appendChild(renderer.domElement);
 
		}
 
		return oldRenderer;
 
	}
 
	/**
	 * Creates a depth texture attachment that will be provided to all passes.
	 *
	 * Note: When a shader reads from a depth texture and writes to a render target that uses the same depth texture
	 * attachment, the depth information will be lost. This happens even if `depthWrite` is disabled.
	 *
	 * @private
	 * @return {DepthTexture} The depth texture.
	 */
 
	createDepthTexture() {
 
		const depthTexture = this.depthTexture = new DepthTexture();
 
		// Hack: Make sure the input buffer uses the depth texture.
		this.inputBuffer.depthTexture = depthTexture;
		this.inputBuffer.dispose();
 
		if(this.inputBuffer.stencilBuffer) {
 
			depthTexture.format = DepthStencilFormat;
			depthTexture.type = UnsignedInt248Type;
 
		} else {
 
			depthTexture.type = UnsignedIntType;
 
		}
 
		return depthTexture;
 
	}
 
	/**
	 * Deletes the current depth texture.
	 *
	 * @private
	 */
 
	deleteDepthTexture() {
 
		if(this.depthTexture !== null) {
 
			this.depthTexture.dispose();
			this.depthTexture = null;
 
			// Update the input buffer.
			this.inputBuffer.depthTexture = null;
			this.inputBuffer.dispose();
 
			for(const pass of this.passes) {
 
				pass.setDepthTexture(null);
 
			}
 
		}
 
	}
 
	/**
	 * Creates a new render target.
	 *
	 * @deprecated Create buffers manually via WebGLRenderTarget instead.
	 * @param {Boolean} depthBuffer - Whether the render target should have a depth buffer.
	 * @param {Boolean} stencilBuffer - Whether the render target should have a stencil buffer.
	 * @param {Number} type - The frame buffer type.
	 * @param {Number} multisampling - The number of samples to use for antialiasing.
	 * @return {WebGLRenderTarget} A new render target that equals the renderer's canvas.
	 */
 
	createBuffer(depthBuffer, stencilBuffer, type, multisampling) {
 
		const renderer = this.renderer;
		const size = (renderer === null) ? new Vector2() : renderer.getDrawingBufferSize(new Vector2());
 
		const options = {
			minFilter: LinearFilter,
			magFilter: LinearFilter,
			stencilBuffer,
			depthBuffer,
			type
		};
 
		const renderTarget = new WebGLRenderTarget(size.width, size.height, options);
 
		if(multisampling > 0) {
 
			renderTarget.ignoreDepthForMultisampleCopy = false;
			renderTarget.samples = multisampling;
 
		}
 
		if(type === UnsignedByteType && renderer !== null && renderer.outputColorSpace === SRGBColorSpace) {
 
			renderTarget.texture.colorSpace = SRGBColorSpace;
 
		}
 
		renderTarget.texture.name = "EffectComposer.Buffer";
		renderTarget.texture.generateMipmaps = false;
 
		return renderTarget;
 
	}
 
	/**
	 * Can be used to change the main scene for all registered passes and effects.
	 *
	 * @param {Scene} scene - The scene.
	 */
 
	setMainScene(scene) {
 
		for(const pass of this.passes) {
 
			pass.mainScene = scene;
 
		}
 
	}
 
	/**
	 * Can be used to change the main camera for all registered passes and effects.
	 *
	 * @param {Camera} camera - The camera.
	 */
 
	setMainCamera(camera) {
 
		for(const pass of this.passes) {
 
			pass.mainCamera = camera;
 
		}
 
	}
 
	/**
	 * Adds a pass, optionally at a specific index.
	 *
	 * @param {Pass} pass - A new pass.
	 * @param {Number} [index] - An index at which the pass should be inserted.
	 */
 
	addPass(pass, index) {
 
		const passes = this.passes;
		const renderer = this.renderer;
 
		const drawingBufferSize = renderer.getDrawingBufferSize(new Vector2());
		const alpha = renderer.getContext().getContextAttributes().alpha;
		const frameBufferType = this.inputBuffer.texture.type;
 
		pass.setRenderer(renderer);
		pass.setSize(drawingBufferSize.width, drawingBufferSize.height);
		pass.initialize(renderer, alpha, frameBufferType);
 
		if(this.autoRenderToScreen) {
 
			if(passes.length > 0) {
 
				passes[passes.length - 1].renderToScreen = false;
 
			}
 
			if(pass.renderToScreen) {
 
				this.autoRenderToScreen = false;
 
			}
 
		}
 
		if(index !== undefined) {
 
			passes.splice(index, 0, pass);
 
		} else {
 
			passes.push(pass);
 
		}
 
		if(this.autoRenderToScreen) {
 
			passes[passes.length - 1].renderToScreen = true;
 
		}
 
		if(pass.needsDepthTexture || this.depthTexture !== null) {
 
			if(this.depthTexture === null) {
 
				const depthTexture = this.createDepthTexture();
 
				for(pass of passes) {
 
					pass.setDepthTexture(depthTexture);
 
				}
 
			} else {
 
				pass.setDepthTexture(this.depthTexture);
 
			}
 
		}
 
	}
 
	/**
	 * Removes a pass.
	 *
	 * @param {Pass} pass - The pass.
	 */
 
	removePass(pass) {
 
		const passes = this.passes;
		const index = passes.indexOf(pass);
		const exists = (index !== -1);
		const removed = exists && (passes.splice(index, 1).length > 0);
 
		if(removed) {
 
			if(this.depthTexture !== null) {
 
				// Check if the depth texture is still required.
				const reducer = (a, b) => (a || b.needsDepthTexture);
				const depthTextureRequired = passes.reduce(reducer, false);
 
				if(!depthTextureRequired) {
 
					if(pass.getDepthTexture() === this.depthTexture) {
 
						pass.setDepthTexture(null);
 
					}
 
					this.deleteDepthTexture();
 
				}
 
			}
 
			if(this.autoRenderToScreen) {
 
				// Check if the removed pass was the last one.
				if(index === passes.length) {
 
					pass.renderToScreen = false;
 
					if(passes.length > 0) {
 
						passes[passes.length - 1].renderToScreen = true;
 
					}
 
				}
 
			}
 
		}
 
	}
 
	/**
	 * Removes all passes.
	 */
 
	removeAllPasses() {
 
		const passes = this.passes;
 
		this.deleteDepthTexture();
 
		if(passes.length > 0) {
 
			if(this.autoRenderToScreen) {
 
				passes[passes.length - 1].renderToScreen = false;
 
			}
 
			this.passes = [];
 
		}
 
	}
 
	/**
	 * Renders all enabled passes in the order in which they were added.
	 *
	 * @param {Number} [deltaTime] - The time since the last frame in seconds.
	 */
 
	render(deltaTime) {
 
		const renderer = this.renderer;
		const copyPass = this.copyPass;
 
		let inputBuffer = this.inputBuffer;
		let outputBuffer = this.outputBuffer;
 
		let stencilTest = false;
		let context, stencil, buffer;
 
		if(deltaTime === undefined) {
 
			this.timer.update();
			deltaTime = this.timer.getDelta();
 
		}
 
		for(const pass of this.passes) {
 
			if(pass.enabled) {
 
				pass.render(renderer, inputBuffer, outputBuffer, deltaTime, stencilTest);
 
				if(pass.needsSwap) {
 
					if(stencilTest) {
 
						copyPass.renderToScreen = pass.renderToScreen;
						context = renderer.getContext();
						stencil = renderer.state.buffers.stencil;
 
						// Preserve the unaffected pixels.
						stencil.setFunc(context.NOTEQUAL, 1, 0xffffffff);
						copyPass.render(renderer, inputBuffer, outputBuffer, deltaTime, stencilTest);
						stencil.setFunc(context.EQUAL, 1, 0xffffffff);
 
					}
 
					buffer = inputBuffer;
					inputBuffer = outputBuffer;
					outputBuffer = buffer;
 
				}
 
				if(pass instanceof MaskPass) {
 
					stencilTest = true;
 
				} else if(pass instanceof ClearMaskPass) {
 
					stencilTest = false;
 
				}
 
			}
 
		}
 
	}
 
	/**
	 * Sets the size of the buffers, passes and the renderer.
	 *
	 * @param {Number} width - The width.
	 * @param {Number} height - The height.
	 * @param {Boolean} [updateStyle] - Determines whether the style of the canvas should be updated.
	 */
 
	setSize(width, height, updateStyle) {
 
		const renderer = this.renderer;
		const currentSize = renderer.getSize(new Vector2());
 
		if(width === undefined || height === undefined) {
 
			width = currentSize.width;
			height = currentSize.height;
 
		}
 
		if(currentSize.width !== width || currentSize.height !== height) {
 
			// Update the logical render size.
			renderer.setSize(width, height, updateStyle);
 
		}
 
		// The drawing buffer size takes the device pixel ratio into account.
		const drawingBufferSize = renderer.getDrawingBufferSize(new Vector2());
		this.inputBuffer.setSize(drawingBufferSize.width, drawingBufferSize.height);
		this.outputBuffer.setSize(drawingBufferSize.width, drawingBufferSize.height);
 
		for(const pass of this.passes) {
 
			pass.setSize(drawingBufferSize.width, drawingBufferSize.height);
 
		}
 
	}
 
	/**
	 * Resets this composer by deleting all passes and creating new buffers.
	 */
 
	reset() {
 
		this.dispose();
		this.autoRenderToScreen = true;
 
	}
 
	/**
	 * Disposes this composer and all passes.
	 */
 
	dispose() {
 
		for(const pass of this.passes) {
 
			pass.dispose();
 
		}
 
		this.passes = [];
 
		if(this.inputBuffer !== null) {
 
			this.inputBuffer.dispose();
 
		}
 
		if(this.outputBuffer !== null) {
 
			this.outputBuffer.dispose();
 
		}
 
		this.deleteDepthTexture();
		this.copyPass.dispose();
		this.timer.dispose();
 
		Pass.fullscreenGeometry.dispose();
 
	}
 
}