Skip to content

Commit 8552d3a

Browse files
Mugen87Mugen87
authoredMar 4, 2025··
Docs: More JSDoc. (#30646)
·
r175
1 parent e52f524 commit 8552d3a

27 files changed

+1084
-188
lines changed
 

Diff for: ‎examples/jsm/effects/AnaglyphEffect.js

+30
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,21 @@ import {
99
} from 'three';
1010
import { FullScreenQuad } from '../postprocessing/Pass.js';
1111

12+
/**
13+
* A class that creates an anaglyph effect.
14+
*
15+
* Note that this class can only be used with {@link WebGLRenderer}.
16+
* When using {@link WebGPURenderer}, use {@link AnaglyphPassNode}.
17+
*/
1218
class AnaglyphEffect {
1319

20+
/**
21+
* Constructs a new anaglyph effect.
22+
*
23+
* @param {WebGLRenderer} renderer - The renderer.
24+
* @param {number} width - The width of the effect in physical pixels.
25+
* @param {number} height - The height of the effect in physical pixels.
26+
*/
1427
constructor( renderer, width = 512, height = 512 ) {
1528

1629
// Dubois matrices from https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.7.6968&rep=rep1&type=pdf#page=4
@@ -94,6 +107,12 @@ class AnaglyphEffect {
94107

95108
const _quad = new FullScreenQuad( _material );
96109

110+
/**
111+
* Resizes the effect.
112+
*
113+
* @param {number} width - The width of the effect in logical pixels.
114+
* @param {number} height - The height of the effect in logical pixels.
115+
*/
97116
this.setSize = function ( width, height ) {
98117

99118
renderer.setSize( width, height );
@@ -105,6 +124,13 @@ class AnaglyphEffect {
105124

106125
};
107126

127+
/**
128+
* When using this effect, this method should be called instead of the
129+
* default {@link WebGLRenderer#render}.
130+
*
131+
* @param {Object3D} scene - The scene to render.
132+
* @param {Camera} camera - The camera.
133+
*/
108134
this.render = function ( scene, camera ) {
109135

110136
const currentRenderTarget = renderer.getRenderTarget();
@@ -130,6 +156,10 @@ class AnaglyphEffect {
130156

131157
};
132158

159+
/**
160+
* Frees internal resources. This method should be called
161+
* when the effect is no longer required.
162+
*/
133163
this.dispose = function () {
134164

135165
_renderTargetL.dispose();

Diff for: ‎examples/jsm/effects/AsciiEffect.js

+46-9
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,17 @@
11
/**
2-
* Ascii generation is based on https://github.com/hassadee/jsascii/blob/master/jsascii.js
2+
* A class that creates a ASCII effect.
33
*
4-
* 16 April 2012 - @blurspline
4+
* The ASCII generation is based on [jsascii]{@link https://github.com/hassadee/jsascii/blob/master/jsascii.js}.
55
*/
6-
76
class AsciiEffect {
87

8+
/**
9+
* Constructs a new ASCII effect.
10+
*
11+
* @param {WebGLRenderer} renderer - The renderer.
12+
* @param {string} [charSet=' .:-=+*#%@'] - The char set.
13+
* @param {AsciiEffect~Options} [options] - The configuration parameter.
14+
*/
915
constructor( renderer, charSet = ' .:-=+*#%@', options = {} ) {
1016

1117
// ' .,:;=|iI+hHOE#`$';
@@ -14,12 +20,12 @@ class AsciiEffect {
1420

1521
// Some ASCII settings
1622

17-
const fResolution = options[ 'resolution' ] || 0.15; // Higher for more details
23+
const fResolution = options[ 'resolution' ] || 0.15;
1824
const iScale = options[ 'scale' ] || 1;
19-
const bColor = options[ 'color' ] || false; // nice but slows down rendering!
20-
const bAlpha = options[ 'alpha' ] || false; // Transparency
21-
const bBlock = options[ 'block' ] || false; // blocked characters. like good O dos
22-
const bInvert = options[ 'invert' ] || false; // black is white, white is black
25+
const bColor = options[ 'color' ] || false;
26+
const bAlpha = options[ 'alpha' ] || false;
27+
const bBlock = options[ 'block' ] || false;
28+
const bInvert = options[ 'invert' ] || false;
2329
const strResolution = options[ 'strResolution' ] || 'low';
2430

2531
let width, height;
@@ -33,6 +39,12 @@ class AsciiEffect {
3339
let iWidth, iHeight;
3440
let oImg;
3541

42+
/**
43+
* Resizes the effect.
44+
*
45+
* @param {number} w - The width of the effect in logical pixels.
46+
* @param {number} h - The height of the effect in logical pixels.
47+
*/
3648
this.setSize = function ( w, h ) {
3749

3850
width = w;
@@ -44,14 +56,26 @@ class AsciiEffect {
4456

4557
};
4658

47-
59+
/**
60+
* When using this effect, this method should be called instead of the
61+
* default {@link WebGLRenderer#render}.
62+
*
63+
* @param {Object3D} scene - The scene to render.
64+
* @param {Camera} camera - The camera.
65+
*/
4866
this.render = function ( scene, camera ) {
4967

5068
renderer.render( scene, camera );
5169
asciifyImage( oAscii );
5270

5371
};
5472

73+
/**
74+
* The DOM element of the effect. This element must be used instead of the
75+
* default {@link WebGLRenderer#domElement}.
76+
*
77+
* @type {HTMLDivElement}
78+
*/
5579
this.domElement = domElement;
5680

5781

@@ -260,4 +284,17 @@ class AsciiEffect {
260284

261285
}
262286

287+
/**
288+
* This type represents configuration settings of `AsciiEffect`.
289+
*
290+
* @typedef {Object} AsciiEffect~Options
291+
* @property {number} [resolution=0.15] - A higher value leads to more details.
292+
* @property {number} [scale=1] - The scale of the effect.
293+
* @property {boolean} [color=false] - Whether colors should be enabled or not. Better quality but slows down rendering.
294+
* @property {boolean} [alpha=false] - Whether transparency should be enabled or not.
295+
* @property {boolean} [block=false] - Whether blocked characters should be enabled or not.
296+
* @property {boolean} [invert=false] - Whether colors should be inverted or not.
297+
* @property {('low'|'medium'|'high')} [strResolution='low'] - The string resolution.
298+
**/
299+
263300
export { AsciiEffect };

Diff for: ‎examples/jsm/effects/OutlineEffect.js

+59-111
Original file line numberDiff line numberDiff line change
@@ -7,63 +7,29 @@ import {
77
} from 'three';
88

99
/**
10-
* Reference: https://en.wikipedia.org/wiki/Cel_shading
10+
* An outline effect for toon shaders.
1111
*
12-
* API
13-
*
14-
* 1. Traditional
12+
* Note that this class can only be used with {@link WebGLRenderer}.
13+
* When using {@link WebGPURenderer}, use {@link ToonOutlinePassNode}.
1514
*
15+
* ```js
1616
* const effect = new OutlineEffect( renderer );
1717
*
1818
* function render() {
1919
*
2020
* effect.render( scene, camera );
2121
*
2222
* }
23-
*
24-
* 2. VR compatible
25-
*
26-
* const effect = new OutlineEffect( renderer );
27-
* let renderingOutline = false;
28-
*
29-
* scene.onAfterRender = function () {
30-
*
31-
* if ( renderingOutline ) return;
32-
*
33-
* renderingOutline = true;
34-
*
35-
* effect.renderOutline( scene, camera );
36-
*
37-
* renderingOutline = false;
38-
*
39-
* };
40-
*
41-
* function render() {
42-
*
43-
* renderer.render( scene, camera );
44-
*
45-
* }
46-
*
47-
* // How to set default outline parameters
48-
* new OutlineEffect( renderer, {
49-
* defaultThickness: 0.01,
50-
* defaultColor: [ 0, 0, 0 ],
51-
* defaultAlpha: 0.8,
52-
* defaultKeepAlive: true // keeps outline material in cache even if material is removed from scene
53-
* } );
54-
*
55-
* // How to set outline parameters for each material
56-
* material.userData.outlineParameters = {
57-
* thickness: 0.01,
58-
* color: [ 0, 0, 0 ],
59-
* alpha: 0.8,
60-
* visible: true,
61-
* keepAlive: true
62-
* };
23+
* ```
6324
*/
64-
6525
class OutlineEffect {
6626

27+
/**
28+
* Constructs a new outline effect.
29+
*
30+
* @param {WebGLRenderer} renderer - The renderer.
31+
* @param {OutlineEffect~Options} [parameters] - The configuration parameter.
32+
*/
6733
constructor( renderer, parameters = {} ) {
6834

6935
this.enabled = true;
@@ -413,6 +379,13 @@ class OutlineEffect {
413379

414380
}
415381

382+
/**
383+
* When using this effect, this method should be called instead of the
384+
* default {@link WebGLRenderer#render}.
385+
*
386+
* @param {Object3D} scene - The scene to render.
387+
* @param {Camera} camera - The camera.
388+
*/
416389
this.render = function ( scene, camera ) {
417390

418391
if ( this.enabled === false ) {
@@ -433,6 +406,30 @@ class OutlineEffect {
433406

434407
};
435408

409+
/**
410+
* This method can be used to render outlines in VR.
411+
*
412+
* ```js
413+
* const effect = new OutlineEffect( renderer );
414+
* let renderingOutline = false;
415+
*
416+
* scene.onAfterRender = function () {
417+
*
418+
* if ( renderingOutline ) return;
419+
*
420+
* renderingOutline = true;
421+
* effect.renderOutline( scene, camera );
422+
* renderingOutline = false;
423+
* };
424+
*
425+
* function render() {
426+
* renderer.render( scene, camera );
427+
* }
428+
* ```
429+
*
430+
* @param {Object3D} scene - The scene to render.
431+
* @param {Camera} camera - The camera.
432+
*/
436433
this.renderOutline = function ( scene, camera ) {
437434

438435
const currentAutoClear = renderer.autoClear;
@@ -460,80 +457,31 @@ class OutlineEffect {
460457

461458
};
462459

463-
/*
464-
* See #9918
465-
*
466-
* The following property copies and wrapper methods enable
467-
* OutlineEffect to be called from other *Effect, like
468-
*
469-
* effect = new StereoEffect( new OutlineEffect( renderer ) );
470-
*
471-
* function render () {
460+
/**
461+
* Resizes the effect.
472462
*
473-
* effect.render( scene, camera );
474-
*
475-
* }
463+
* @param {number} width - The width of the effect in logical pixels.
464+
* @param {number} height - The height of the effect in logical pixels.
476465
*/
477-
this.autoClear = renderer.autoClear;
478-
this.domElement = renderer.domElement;
479-
this.shadowMap = renderer.shadowMap;
480-
481-
this.clear = function ( color, depth, stencil ) {
482-
483-
renderer.clear( color, depth, stencil );
466+
this.setSize = function ( width, height ) {
484467

485-
};
486-
487-
this.getPixelRatio = function () {
488-
489-
return renderer.getPixelRatio();
490-
491-
};
492-
493-
this.setPixelRatio = function ( value ) {
494-
495-
renderer.setPixelRatio( value );
496-
497-
};
498-
499-
this.getSize = function ( target ) {
500-
501-
return renderer.getSize( target );
502-
503-
};
504-
505-
this.setSize = function ( width, height, updateStyle ) {
506-
507-
renderer.setSize( width, height, updateStyle );
508-
509-
};
510-
511-
this.setViewport = function ( x, y, width, height ) {
512-
513-
renderer.setViewport( x, y, width, height );
514-
515-
};
516-
517-
this.setScissor = function ( x, y, width, height ) {
518-
519-
renderer.setScissor( x, y, width, height );
520-
521-
};
522-
523-
this.setScissorTest = function ( boolean ) {
524-
525-
renderer.setScissorTest( boolean );
526-
527-
};
528-
529-
this.setRenderTarget = function ( renderTarget ) {
530-
531-
renderer.setRenderTarget( renderTarget );
468+
renderer.setSize( width, height );
532469

533470
};
534471

535472
}
536473

537474
}
538475

476+
/**
477+
* This type represents configuration settings of `OutlineEffect`.
478+
*
479+
* @typedef {Object} OutlineEffect~Options
480+
* @property {number} [defaultThickness=0.003] - The outline thickness.
481+
* @property {Array<number>} [defaultColor=[0,0,0]] - The outline color.
482+
* @property {number} [defaultAlpha=1] - The outline alpha value.
483+
* @property {boolean} [defaultKeepAlive=false] - Whether to keep alive cached internal materials or not.
484+
**/
485+
486+
539487
export { OutlineEffect };

0 commit comments

Comments
 (0)
Please sign in to comment.