Skip to content

Commit e0e43da

Browse files
mrdoobmrdoob
authored
Merge pull request #17156 from Mugen87/dev30
Docs: Added basic guide for post-processing.
2 parents 8e981a5 + 9509904 commit e0e43da

File tree

3 files changed

+226
-0
lines changed

3 files changed

+226
-0
lines changed

‎docs/list.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ var list = {
2424
"How to update things": "manual/en/introduction/How-to-update-things",
2525
"How to dispose of objects": "manual/en/introduction/How-to-dispose-of-objects",
2626
"How to create VR content": "manual/en/introduction/How-to-create-VR-content",
27+
"How to use post-processing": "manual/en/introduction/How-to-use-post-processing",
2728
"Matrix transformations": "manual/en/introduction/Matrix-transformations",
2829
"Animation system": "manual/en/introduction/Animation-system"
2930
},
@@ -461,6 +462,7 @@ var list = {
461462
"如何更新场景": "manual/zh/introduction/How-to-update-things",
462463
"如何废置对象": "manual/zh/introduction/How-to-dispose-of-objects",
463464
"如何创建VR内容": "manual/zh/introduction/How-to-create-VR-content",
465+
"How to use post-processing": "manual/zh/introduction/How-to-use-post-processing",
464466
"矩阵变换": "manual/zh/introduction/Matrix-transformations",
465467
"动画系统": "manual/zh/introduction/Animation-system"
466468
},

‎docs/manual/en/introduction/How-to-use-post-processing.html‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8">
5+
<base href="../../../" />
6+
<script src="list.js"></script>
7+
<script src="page.js"></script>
8+
<link type="text/css" rel="stylesheet" href="page.css" />
9+
</head>
10+
<body>
11+
<h1>How to use post-processing</h1>
12+
13+
<p>
14+
Many three.js applications render their 3D objects directly to the screen. Sometimes, however, you want to apply one or more graphical
15+
effects like Depth-Of-Field, Bloom, Film Grain or various types of Anti-aliasing. Post-processing is a widely used approach
16+
to implement such effects. First, the scene is rendered to a render target which represents a buffer in the video card's memory.
17+
In the next step one ore more post-processing passes apply filters and effects to the image buffer before it is eventually rendered to
18+
the screen.
19+
</p>
20+
<p>
21+
three.js provides a complete post-processing solution via [page:EffectComposer] to implement such a workflow.
22+
</p>
23+
24+
<h2>Workflow</h2>
25+
26+
<p>
27+
The first step in the process is to import all necessary files from the examples directory. The guide assumes your are using the official
28+
[link:https://www.npmjs.com/package/three npm package] of three.js. For our basic demo in this guide we need the following files.
29+
</p>
30+
31+
<code>
32+
import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
33+
import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass.js';
34+
import { GlitchPass } from 'three/examples/jsm/postprocessing/GlitchPass.js';
35+
</code>
36+
37+
<p>
38+
After all files are successfully imported, we can create our composer by passing in an instance of [page:WebGLRenderer].
39+
</p>
40+
41+
<code>
42+
var composer = new EffectComposer( renderer );
43+
</code>
44+
45+
<p>
46+
When using a composer, it's necessary to change the application's animation loop. Instead of calling the render method of
47+
[page:WebGLRenderer], we now use the respective counterpart of [page:EffectComposer].
48+
</p>
49+
50+
<code>
51+
function animate() {
52+
53+
requestAnimationFrame( animate );
54+
55+
composer.render();
56+
57+
}
58+
</code>
59+
60+
<p>
61+
Our composer is now ready so it's possible to configure the chain of post-processing passes. These passes are responsible for creating
62+
the final visual output of the application. They are processed in order of their addition/insertion. In our example, the instance of *RenderPass*
63+
is executed first and then the instance of *GlitchPass*. The last enabled pass in the chain is automatically rendered to the screen. The setup
64+
of the passes looks like so:
65+
</p>
66+
67+
<code>
68+
var renderPass = new RenderPass( scene, camera );
69+
composer.addPass( renderPass );
70+
71+
var glitchPass = new GlitchPass();
72+
composer.addPass( glitchPass );
73+
</code>
74+
75+
<p>
76+
*RenderPass* is normally placed at the beginning of the chain in order to provide the rendered scene as an input for the next post-processing step. In our case,
77+
*GlitchPass* is going to use these image data to apply a wild glitch effect. Check out this [link:https://threejs.org/examples/webgl_postprocessing_glitch live example]
78+
to see it in action.
79+
</p>
80+
81+
<h2>Built-in Passes</h2>
82+
83+
<p>
84+
You can use a wide range of pre-defined post-processing passes provided by the engine. They are located in the
85+
[link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm/postprocessing postprocessing] directory.
86+
</p>
87+
88+
<h2>Custom Passes</h2>
89+
90+
<p>
91+
Sometimes you want to write a custom post-processing shader and include it into the chain of post-processing passes. For this scenario,
92+
you can utilize *ShaderPass*. After importing the file and your custom shader, you can use the following code to setup the pass.
93+
</p>
94+
95+
<code>
96+
import { ShaderPass } from 'three/examples/jsm/postprocessing/ShaderPass.js';
97+
import { LuminosityShader } from 'three/examples/jsm/shaders/LuminosityShader.js';
98+
99+
// later in your init routine
100+
101+
var luminosityPass = new ShaderPass( LuminosityShader );
102+
composer.addPass( luminosityPass );
103+
</code>
104+
105+
<p>
106+
The repository provides a file called [link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/shaders/CopyShader.js CopyShader] which is a
107+
good starting code for your own custom shader. *CopyShader* just copies the image contents of the [page:EffectComposer]'s read buffer
108+
to its write buffer without applying any effects.
109+
</p>
110+
111+
</body>
112+
</html>

‎docs/manual/zh/introduction/How-to-use-post-processing.html‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8">
5+
<base href="../../../" />
6+
<script src="list.js"></script>
7+
<script src="page.js"></script>
8+
<link type="text/css" rel="stylesheet" href="page.css" />
9+
</head>
10+
<body>
11+
<h1>How to use post-processing</h1>
12+
13+
<p>
14+
Many three.js applications render their 3D objects directly to the screen. Sometimes, however, you want to apply one or more graphical
15+
effects like Depth-Of-Field, Bloom, Film Grain or various types of Anti-aliasing. Post-processing is a widely used approach
16+
to implement such effects. First, the scene is rendered to a render target which represents a buffer in the video card's memory.
17+
In the next step one ore more post-processing passes apply filters and effects to the image buffer before it is eventually rendered to
18+
the screen.
19+
</p>
20+
<p>
21+
three.js provides a complete post-processing solution via [page:EffectComposer] to implement such a workflow.
22+
</p>
23+
24+
<h2>Workflow</h2>
25+
26+
<p>
27+
The first step in the process is to import all necessary files from the examples directory. The guide assumes your are using the official
28+
[link:https://www.npmjs.com/package/three npm package] of three.js. For our basic demo in this guide we need the following files.
29+
</p>
30+
31+
<code>
32+
import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
33+
import { RenderPass } from 'three/examples/jsm/postprocessing/RenderPass.js';
34+
import { GlitchPass } from 'three/examples/jsm/postprocessing/GlitchPass.js';
35+
</code>
36+
37+
<p>
38+
After all files are successfully imported, we can create our composer by passing in an instance of [page:WebGLRenderer].
39+
</p>
40+
41+
<code>
42+
var composer = new EffectComposer( renderer );
43+
</code>
44+
45+
<p>
46+
When using a composer, it's necessary to change the application's animation loop. Instead of calling the render method of
47+
[page:WebGLRenderer], we now use the respective counterpart of [page:EffectComposer].
48+
</p>
49+
50+
<code>
51+
function animate() {
52+
53+
requestAnimationFrame( animate );
54+
55+
composer.render();
56+
57+
}
58+
</code>
59+
60+
<p>
61+
Our composer is now ready so it's possible to configure the chain of post-processing passes. These passes are responsible for creating
62+
the final visual output of the application. They are processed in order of their addition/insertion. In our example, the instance of *RenderPass*
63+
is executed first and then the instance of *GlitchPass*. The last enabled pass in the chain is automatically rendered to the screen. The setup
64+
of the passes looks like so:
65+
</p>
66+
67+
<code>
68+
var renderPass = new RenderPass( scene, camera );
69+
composer.addPass( renderPass );
70+
71+
var glitchPass = new GlitchPass();
72+
composer.addPass( glitchPass );
73+
</code>
74+
75+
<p>
76+
*RenderPass* is normally placed at the beginning of the chain in order to provide the rendered scene as an input for the next post-processing step. In our case,
77+
*GlitchPass* is going to use these image data to apply a wild glitch effect. Check out this [link:https://threejs.org/examples/webgl_postprocessing_glitch live example]
78+
to see it in action.
79+
</p>
80+
81+
<h2>Built-in Passes</h2>
82+
83+
<p>
84+
You can use a wide range of pre-defined post-processing passes provided by the engine. They are located in the
85+
[link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm/postprocessing postprocessing] directory.
86+
</p>
87+
88+
<h2>Custom Passes</h2>
89+
90+
<p>
91+
Sometimes you want to write a custom post-processing shader and include it into the chain of post-processing passes. For this scenario,
92+
you can utilize *ShaderPass*. After importing the file and your custom shader, you can use the following code to setup the pass.
93+
</p>
94+
95+
<code>
96+
import { ShaderPass } from 'three/examples/jsm/postprocessing/ShaderPass.js';
97+
import { LuminosityShader } from 'three/examples/jsm/shaders/LuminosityShader.js';
98+
99+
// later in your init routine
100+
101+
var luminosityPass = new ShaderPass( LuminosityShader );
102+
composer.addPass( luminosityPass );
103+
</code>
104+
105+
<p>
106+
The repository provides a file called [link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/shaders/CopyShader.js CopyShader] which is a
107+
good starting code for your own custom shader. *CopyShader* just copies the image contents of the [page:EffectComposer]'s read buffer
108+
to its write buffer without applying any effects.
109+
</p>
110+
111+
</body>
112+
</html>

0 commit comments

Comments
 (0)