Skip to content

Commit 44b01db

Browse files
Mugen87Mugen87
authored
Docs: More JSDoc. (#30727)
1 parent 0c6ff67 commit 44b01db

33 files changed

+2994
-787
lines changed

‎examples/jsm/postprocessing/AfterimagePass.js‎

Lines changed: 90 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -10,103 +10,155 @@ import { Pass, FullScreenQuad } from './Pass.js';
1010
import { CopyShader } from '../shaders/CopyShader.js';
1111
import { AfterimageShader } from '../shaders/AfterimageShader.js';
1212

13+
/**
14+
* Pass for a basic after image effect.
15+
*
16+
* ```js
17+
* const afterimagePass = new AfterimagePass( 0.9 );
18+
* composer.addPass( afterimagePass );
19+
* ```
20+
*
21+
* @augments Pass
22+
*/
1323
class AfterimagePass extends Pass {
1424

25+
/**
26+
* Constructs a new after image pass.
27+
*
28+
* @param {number} [damp=0.96] - The damping intensity. A higher value means a stronger after image effect.
29+
*/
1530
constructor( damp = 0.96 ) {
1631

1732
super();
1833

19-
this.shader = AfterimageShader;
20-
21-
this.uniforms = UniformsUtils.clone( this.shader.uniforms );
34+
/**
35+
* The pass uniforms. Use this object if you want to update the
36+
* `damp` value at runtime.
37+
* ```js
38+
* pass.uniforms.damp.value = 0.9;
39+
* ```
40+
*
41+
* @type {Object}
42+
*/
43+
this.uniforms = UniformsUtils.clone( AfterimageShader.uniforms );
2244

2345
this.uniforms[ 'damp' ].value = damp;
2446

25-
this.textureComp = new WebGLRenderTarget( window.innerWidth, window.innerHeight, {
26-
magFilter: NearestFilter,
27-
type: HalfFloatType
28-
} );
29-
30-
this.textureOld = new WebGLRenderTarget( window.innerWidth, window.innerHeight, {
31-
magFilter: NearestFilter,
32-
type: HalfFloatType
33-
} );
34-
47+
/**
48+
* The composition material.
49+
*
50+
* @type {ShaderMaterial}
51+
*/
3552
this.compFsMaterial = new ShaderMaterial( {
3653

3754
uniforms: this.uniforms,
38-
vertexShader: this.shader.vertexShader,
39-
fragmentShader: this.shader.fragmentShader
55+
vertexShader: AfterimageShader.vertexShader,
56+
fragmentShader: AfterimageShader.fragmentShader
4057

4158
} );
4259

43-
this.compFsQuad = new FullScreenQuad( this.compFsMaterial );
44-
45-
const copyShader = CopyShader;
46-
60+
/**
61+
* The copy material.
62+
*
63+
* @type {ShaderMaterial}
64+
*/
4765
this.copyFsMaterial = new ShaderMaterial( {
48-
uniforms: UniformsUtils.clone( copyShader.uniforms ),
49-
vertexShader: copyShader.vertexShader,
50-
fragmentShader: copyShader.fragmentShader,
66+
uniforms: UniformsUtils.clone( CopyShader.uniforms ),
67+
vertexShader: CopyShader.vertexShader,
68+
fragmentShader: CopyShader.fragmentShader,
5169
blending: NoBlending,
5270
depthTest: false,
5371
depthWrite: false
5472
} );
5573

56-
this.copyFsQuad = new FullScreenQuad( this.copyFsMaterial );
74+
// internals
75+
76+
this._textureComp = new WebGLRenderTarget( window.innerWidth, window.innerHeight, {
77+
magFilter: NearestFilter,
78+
type: HalfFloatType
79+
} );
80+
81+
this._textureOld = new WebGLRenderTarget( window.innerWidth, window.innerHeight, {
82+
magFilter: NearestFilter,
83+
type: HalfFloatType
84+
} );
85+
86+
this._compFsQuad = new FullScreenQuad( this.compFsMaterial );
87+
this._copyFsQuad = new FullScreenQuad( this.copyFsMaterial );
5788

5889
}
5990

91+
/**
92+
* Performs the after image pass.
93+
*
94+
* @param {WebGLRenderer} renderer - The renderer.
95+
* @param {WebGLRenderTarget} writeBuffer - The write buffer. This buffer is intended as the rendering
96+
* destination for the pass.
97+
* @param {WebGLRenderTarget} readBuffer - The read buffer. The pass can access the result from the
98+
* previous pass from this buffer.
99+
* @param {number} deltaTime - The delta time in seconds.
100+
* @param {boolean} maskActive - Whether masking is active or not.
101+
*/
60102
render( renderer, writeBuffer, readBuffer/*, deltaTime, maskActive*/ ) {
61103

62-
this.uniforms[ 'tOld' ].value = this.textureOld.texture;
104+
this.uniforms[ 'tOld' ].value = this._textureOld.texture;
63105
this.uniforms[ 'tNew' ].value = readBuffer.texture;
64106

65-
renderer.setRenderTarget( this.textureComp );
66-
this.compFsQuad.render( renderer );
107+
renderer.setRenderTarget( this._textureComp );
108+
this._compFsQuad.render( renderer );
67109

68-
this.copyFsQuad.material.uniforms.tDiffuse.value = this.textureComp.texture;
110+
this._copyFsQuad.material.uniforms.tDiffuse.value = this._textureComp.texture;
69111

70112
if ( this.renderToScreen ) {
71113

72114
renderer.setRenderTarget( null );
73-
this.copyFsQuad.render( renderer );
115+
this._copyFsQuad.render( renderer );
74116

75117
} else {
76118

77119
renderer.setRenderTarget( writeBuffer );
78120

79121
if ( this.clear ) renderer.clear();
80122

81-
this.copyFsQuad.render( renderer );
123+
this._copyFsQuad.render( renderer );
82124

83125
}
84126

85127
// Swap buffers.
86-
const temp = this.textureOld;
87-
this.textureOld = this.textureComp;
88-
this.textureComp = temp;
128+
const temp = this._textureOld;
129+
this._textureOld = this._textureComp;
130+
this._textureComp = temp;
89131
// Now textureOld contains the latest image, ready for the next frame.
90132

91133
}
92134

135+
/**
136+
* Sets the size of the pass.
137+
*
138+
* @param {number} width - The width to set.
139+
* @param {number} height - The width to set.
140+
*/
93141
setSize( width, height ) {
94142

95-
this.textureComp.setSize( width, height );
96-
this.textureOld.setSize( width, height );
143+
this._textureComp.setSize( width, height );
144+
this._textureOld.setSize( width, height );
97145

98146
}
99147

148+
/**
149+
* Frees the GPU-related resources allocated by this instance. Call this
150+
* method whenever the pass is no longer used in your app.
151+
*/
100152
dispose() {
101153

102-
this.textureComp.dispose();
103-
this.textureOld.dispose();
154+
this._textureComp.dispose();
155+
this._textureOld.dispose();
104156

105157
this.compFsMaterial.dispose();
106158
this.copyFsMaterial.dispose();
107159

108-
this.compFsQuad.dispose();
109-
this.copyFsQuad.dispose();
160+
this._compFsQuad.dispose();
161+
this._copyFsQuad.dispose();
110162

111163
}
112164

‎examples/jsm/postprocessing/BloomPass.js‎

Lines changed: 89 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -9,25 +9,47 @@ import {
99
import { Pass, FullScreenQuad } from './Pass.js';
1010
import { ConvolutionShader } from '../shaders/ConvolutionShader.js';
1111

12+
/**
13+
* A pass for a basic Bloom effect.
14+
*
15+
* {@link UnrealBloomPass} produces a more advanced Bloom but is also
16+
* more expensive.
17+
*
18+
* ```js
19+
* const effectBloom = new BloomPass( 0.75 );
20+
* composer.addPass( effectBloom );
21+
* ```
22+
*
23+
* @augments Pass
24+
*/
1225
class BloomPass extends Pass {
1326

27+
/**
28+
* Constructs a new Bloom pass.
29+
*
30+
* @param {number} [strength=1] - The Bloom strength.
31+
* @param {number} [kernelSize=25] - The kernel size.
32+
* @param {number} [sigma=4] - The sigma.
33+
*/
1434
constructor( strength = 1, kernelSize = 25, sigma = 4 ) {
1535

1636
super();
1737

18-
// render targets
19-
20-
this.renderTargetX = new WebGLRenderTarget( 1, 1, { type: HalfFloatType } ); // will be resized later
21-
this.renderTargetX.texture.name = 'BloomPass.x';
22-
this.renderTargetY = new WebGLRenderTarget( 1, 1, { type: HalfFloatType } ); // will be resized later
23-
this.renderTargetY.texture.name = 'BloomPass.y';
24-
2538
// combine material
2639

40+
/**
41+
* The combine pass uniforms.
42+
*
43+
* @type {Object}
44+
*/
2745
this.combineUniforms = UniformsUtils.clone( CombineShader.uniforms );
28-
2946
this.combineUniforms[ 'strength' ].value = strength;
3047

48+
/**
49+
* The combine pass material.
50+
*
51+
* @type {ShaderMaterial}
52+
*/
3153
this.materialCombine = new ShaderMaterial( {
3254

3355
name: CombineShader.name,
@@ -43,11 +65,21 @@ class BloomPass extends Pass {
4365

4466
const convolutionShader = ConvolutionShader;
4567

68+
/**
69+
* The convolution pass uniforms.
70+
*
71+
* @type {Object}
72+
*/
4673
this.convolutionUniforms = UniformsUtils.clone( convolutionShader.uniforms );
4774

4875
this.convolutionUniforms[ 'uImageIncrement' ].value = BloomPass.blurX;
4976
this.convolutionUniforms[ 'cKernel' ].value = ConvolutionShader.buildKernel( sigma );
5077

78+
/**
79+
* The convolution pass material.
80+
*
81+
* @type {ShaderMaterial}
82+
*/
5183
this.materialConvolution = new ShaderMaterial( {
5284

5385
name: convolutionShader.name,
@@ -61,67 +93,101 @@ class BloomPass extends Pass {
6193

6294
} );
6395

96+
/**
97+
* Overwritten to disable the swap.
98+
*
99+
* @type {boolean}
100+
* @default false
101+
*/
64102
this.needsSwap = false;
65103

66-
this.fsQuad = new FullScreenQuad( null );
104+
// internals
105+
106+
this._renderTargetX = new WebGLRenderTarget( 1, 1, { type: HalfFloatType } ); // will be resized later
107+
this._renderTargetX.texture.name = 'BloomPass.x';
108+
this._renderTargetY = new WebGLRenderTarget( 1, 1, { type: HalfFloatType } ); // will be resized later
109+
this._renderTargetY.texture.name = 'BloomPass.y';
110+
111+
this._fsQuad = new FullScreenQuad( null );
67112

68113
}
69114

115+
/**
116+
* Performs the Bloom pass.
117+
*
118+
* @param {WebGLRenderer} renderer - The renderer.
119+
* @param {WebGLRenderTarget} writeBuffer - The write buffer. This buffer is intended as the rendering
120+
* destination for the pass.
121+
* @param {WebGLRenderTarget} readBuffer - The read buffer. The pass can access the result from the
122+
* previous pass from this buffer.
123+
* @param {number} deltaTime - The delta time in seconds.
124+
* @param {boolean} maskActive - Whether masking is active or not.
125+
*/
70126
render( renderer, writeBuffer, readBuffer, deltaTime, maskActive ) {
71127

72128
if ( maskActive ) renderer.state.buffers.stencil.setTest( false );
73129

74130
// Render quad with blurred scene into texture (convolution pass 1)
75131

76-
this.fsQuad.material = this.materialConvolution;
132+
this._fsQuad.material = this.materialConvolution;
77133

78134
this.convolutionUniforms[ 'tDiffuse' ].value = readBuffer.texture;
79135
this.convolutionUniforms[ 'uImageIncrement' ].value = BloomPass.blurX;
80136

81-
renderer.setRenderTarget( this.renderTargetX );
137+
renderer.setRenderTarget( this._renderTargetX );
82138
renderer.clear();
83-
this.fsQuad.render( renderer );
139+
this._fsQuad.render( renderer );
84140

85141

86142
// Render quad with blurred scene into texture (convolution pass 2)
87143

88-
this.convolutionUniforms[ 'tDiffuse' ].value = this.renderTargetX.texture;
144+
this.convolutionUniforms[ 'tDiffuse' ].value = this._renderTargetX.texture;
89145
this.convolutionUniforms[ 'uImageIncrement' ].value = BloomPass.blurY;
90146

91-
renderer.setRenderTarget( this.renderTargetY );
147+
renderer.setRenderTarget( this._renderTargetY );
92148
renderer.clear();
93-
this.fsQuad.render( renderer );
149+
this._fsQuad.render( renderer );
94150

95151
// Render original scene with superimposed blur to texture
96152

97-
this.fsQuad.material = this.materialCombine;
153+
this._fsQuad.material = this.materialCombine;
98154

99-
this.combineUniforms[ 'tDiffuse' ].value = this.renderTargetY.texture;
155+
this.combineUniforms[ 'tDiffuse' ].value = this._renderTargetY.texture;
100156

101157
if ( maskActive ) renderer.state.buffers.stencil.setTest( true );
102158

103159
renderer.setRenderTarget( readBuffer );
104160
if ( this.clear ) renderer.clear();
105-
this.fsQuad.render( renderer );
161+
this._fsQuad.render( renderer );
106162

107163
}
108164

165+
/**
166+
* Sets the size of the pass.
167+
*
168+
* @param {number} width - The width to set.
169+
* @param {number} height - The width to set.
170+
*/
109171
setSize( width, height ) {
110172

111-
this.renderTargetX.setSize( width, height );
112-
this.renderTargetY.setSize( width, height );
173+
this._renderTargetX.setSize( width, height );
174+
this._renderTargetY.setSize( width, height );
113175

114176
}
115177

178+
/**
179+
* Frees the GPU-related resources allocated by this instance. Call this
180+
* method whenever the pass is no longer used in your app.
181+
*/
116182
dispose() {
117183

118-
this.renderTargetX.dispose();
119-
this.renderTargetY.dispose();
184+
this._renderTargetX.dispose();
185+
this._renderTargetY.dispose();
120186

121187
this.materialCombine.dispose();
122188
this.materialConvolution.dispose();
123189

124-
this.fsQuad.dispose();
190+
this._fsQuad.dispose();
125191

126192
}
127193

0 commit comments

Comments
 (0)