Skip to content

pmndrs/postprocessing

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
August 30, 2022 00:59
October 17, 2022 13:12
December 29, 2022 00:32
src
February 20, 2023 23:08
October 17, 2022 02:03
February 20, 2023 23:24
October 18, 2019 17:06
February 3, 2022 15:51
December 29, 2022 14:36
October 28, 2022 00:25
February 24, 2023 21:14
February 24, 2023 21:13
May 22, 2022 14:12

Post Processing

CI Version

A post processing library that provides the means to implement image filter effects for three.js.

Demo · Sandbox · Documentation · Wiki

Installation

This library requires the peer dependency three.

npm install three postprocessing

Usage

Post processing introduces the concept of passes and effects to extend the common rendering workflow with fullscreen image manipulation tools. The following WebGL attributes should be used for an optimal post processing workflow:

import { WebGLRenderer } from "three";

const renderer = new WebGLRenderer({
	powerPreference: "high-performance",
	antialias: false,
	stencil: false,
	depth: false
});

The EffectComposer manages and runs passes. It is common practice to use a RenderPass as the first pass to automatically clear the buffers and render a scene for further processing. Fullscreen image effects are rendered via the EffectPass. Please refer to the usage example of three.js for more information on how to setup the renderer, scene and camera.

import { BloomEffect, EffectComposer, EffectPass, RenderPass } from "postprocessing";

const composer = new EffectComposer(renderer);
composer.addPass(new RenderPass(scene, camera));
composer.addPass(new EffectPass(camera, new BloomEffect()));

requestAnimationFrame(function render() {

	requestAnimationFrame(render);
	composer.render();

});

Output Encoding

New applications should follow a linear workflow for color management and postprocessing supports this automatically. Simply set WebGLRenderer.outputEncoding to sRGBEncoding and postprocessing will follow suit.

Postprocessing uses UnsignedByteType sRGB frame buffers to store intermediate results. This is a trade-off between hardware support, efficiency and quality since linear results normally require at least 12 bits per color channel to prevent color degradation and banding. With low precision sRGB buffers, colors will be clamped to [0.0, 1.0] and information loss will shift to the darker spectrum which leads to noticable banding in dark scenes. Linear, high precision HalfFloatType buffers don't have these issues and are the preferred option for HDR-like workflows on desktop devices. You can enable high precision frame buffers as follows:

import { HalfFloatType } from "three";

const composer = new EffectComposer(renderer, {
	frameBufferType: HalfFloatType
});

Performance

This library provides an EffectPass which automatically organizes and merges any given combination of effects. This minimizes the amount of render operations and makes it possible to combine many effects without the performance penalties of traditional pass chaining. Additionally, every effect can choose its own blend function.

All fullscreen render operations also use a single triangle that fills the screen. Compared to using a quad, this approach harmonizes with modern GPU rasterization patterns and eliminates unnecessary fragment calculations along the screen diagonal. This is especially beneficial for GPGPU passes and effects that use complex fragment shaders.

Performance Test

Included Effects

The total demo download size is about 60 MB.

Custom Effects

If you want to learn how to create custom effects or passes, please check the Wiki.

Contributing

Please refer to the contribution guidelines for details.

License

This library is licensed under the Zlib license.

The original code that this library is based on, was written by mrdoob and the three.js contributors and is licensed under the MIT license.