Skip to content

Commit aea3452

Browse files
Mugen87Mugen87
authored
Docs: More JSDoc. (#30629)
1 parent eaf72e6 commit aea3452

15 files changed

+754
-35
lines changed

‎src/textures/CanvasTexture.js

+29
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,40 @@
11
import { Texture } from './Texture.js';
22

3+
/**
4+
* Creates a texture from a canvas element.
5+
*
6+
* This is almost the same as the base texture class, except that it sets {@link Texture#needsUpdate}
7+
* to `true` immediately since a canvas can direclty be used for rendering.
8+
*
9+
* @augments Texture
10+
*/
311
class CanvasTexture extends Texture {
412

13+
/**
14+
* Constructs a new texture.
15+
*
16+
* @param {HTMLCanvasElement} canvas - The HTML canvas element.
17+
* @param {number} [mapping=Texture.DEFAULT_MAPPING] - The texture mapping.
18+
* @param {number} [wrapS=ClampToEdgeWrapping] - The wrapS value.
19+
* @param {number} [wrapT=ClampToEdgeWrapping] - The wrapT value.
20+
* @param {number} [magFilter=LinearFilter] - The mag filter value.
21+
* @param {number} [minFilter=LinearMipmapLinearFilter] - The min filter value.
22+
* @param {number} [format=RGBAFormat] - The texture format.
23+
* @param {number} [type=UnsignedByteType] - The texture type.
24+
* @param {number} [anisotropy=Texture.DEFAULT_ANISOTROPY] - The anisotropy value.
25+
* @param {string} [colorSpace=NoColorSpace] - The color space value.
26+
*/
527
constructor( canvas, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy ) {
628

729
super( canvas, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy );
830

31+
/**
32+
* This flag can be used for type testing.
33+
*
34+
* @type {boolean}
35+
* @readonly
36+
* @default true
37+
*/
938
this.isCanvasTexture = true;
1039

1140
this.needsUpdate = true;

‎src/textures/CompressedArrayTexture.js

+57
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,83 @@
11
import { ClampToEdgeWrapping } from '../constants.js';
22
import { CompressedTexture } from './CompressedTexture.js';
33

4+
/**
5+
* Creates a texture 2D array based on data in compressed form.
6+
*
7+
* These texture are usually loaded with {@link CompressedTextureLoader}.
8+
*
9+
* @augments CompressedTexture
10+
*/
411
class CompressedArrayTexture extends CompressedTexture {
512

13+
/**
14+
* Constructs a new compressed array texture.
15+
*
16+
* @param {Array<Object>} mipmaps - This array holds for all mipmaps (including the bases mip)
17+
* the data and dimensions.
18+
* @param {number} width - The width of the texture.
19+
* @param {number} height - The height of the texture.
20+
* @param {number} depth - The depth of the texture.
21+
* @param {number} [format=RGBAFormat] - The min filter value.
22+
* @param {number} [type=UnsignedByteType] - The min filter value.
23+
*/
624
constructor( mipmaps, width, height, depth, format, type ) {
725

826
super( mipmaps, width, height, format, type );
927

28+
/**
29+
* This flag can be used for type testing.
30+
*
31+
* @type {boolean}
32+
* @readonly
33+
* @default true
34+
*/
1035
this.isCompressedArrayTexture = true;
36+
37+
/**
38+
* The image property of a compressed texture just defines its dimensions.
39+
*
40+
* @name CompressedArrayTexture#image
41+
* @type {{width:number,height:number,depth:number}}
42+
*/
1143
this.image.depth = depth;
44+
45+
/**
46+
* This defines how the texture is wrapped in the depth and corresponds to
47+
* *W* in UVW mapping.
48+
*
49+
* @type {(RepeatWrapping|ClampToEdgeWrapping|MirroredRepeatWrapping)}
50+
* @default ClampToEdgeWrapping
51+
*/
1252
this.wrapR = ClampToEdgeWrapping;
1353

54+
/**
55+
* A set of all layers which need to be updated in the texture.
56+
*
57+
* @type {Set<number>}
58+
*/
1459
this.layerUpdates = new Set();
1560

1661
}
1762

63+
/**
64+
* Describes that a specific layer of the texture needs to be updated.
65+
* Normally when {@link Texture#needsUpdate} is set to `true`, the
66+
* entire compressed texture array is sent to the GPU. Marking specific
67+
* layers will only transmit subsets of all mipmaps associated with a
68+
* specific depth in the array which is often much more performant.
69+
*
70+
* @param {number} layerIndex - The layer index that should be updated.
71+
*/
1872
addLayerUpdate( layerIndex ) {
1973

2074
this.layerUpdates.add( layerIndex );
2175

2276
}
2377

78+
/**
79+
* Resets the layer updates registry.
80+
*/
2481
clearLayerUpdates() {
2582

2683
this.layerUpdates.clear();

‎src/textures/CompressedCubeTexture.js

+29
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,42 @@
11
import { CubeReflectionMapping } from '../constants.js';
22
import { CompressedTexture } from './CompressedTexture.js';
33

4+
/**
5+
* Creates a cube texture based on data in compressed form.
6+
*
7+
* These texture are usually loaded with {@link CompressedTextureLoader}.
8+
*
9+
* @augments CompressedTexture
10+
*/
411
class CompressedCubeTexture extends CompressedTexture {
512

13+
/**
14+
* Constructs a new compressed texture.
15+
*
16+
* @param {Array<CompressedTexture>} images - An array of compressed textures.
17+
* @param {number} [format=RGBAFormat] - The texture format.
18+
* @param {number} [type=UnsignedByteType] - The texture type.
19+
*/
620
constructor( images, format, type ) {
721

822
super( undefined, images[ 0 ].width, images[ 0 ].height, format, type, CubeReflectionMapping );
923

24+
/**
25+
* This flag can be used for type testing.
26+
*
27+
* @type {boolean}
28+
* @readonly
29+
* @default true
30+
*/
1031
this.isCompressedCubeTexture = true;
32+
33+
/**
34+
* This flag can be used for type testing.
35+
*
36+
* @type {boolean}
37+
* @readonly
38+
* @default true
39+
*/
1140
this.isCubeTexture = true;
1241

1342
this.image = images;

‎src/textures/CompressedTexture.js

+64-6
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,82 @@
11
import { Texture } from './Texture.js';
22

3+
/**
4+
* Creates a texture based on data in compressed form.
5+
*
6+
* These texture are usually loaded with {@link CompressedTextureLoader}.
7+
*
8+
* @augments Texture
9+
*/
310
class CompressedTexture extends Texture {
411

12+
/**
13+
* Constructs a new compressed texture.
14+
*
15+
* @param {Array<Object>} mipmaps - This array holds for all mipmaps (including the bases mip)
16+
* the data and dimensions.
17+
* @param {number} width - The width of the texture.
18+
* @param {number} height - The height of the texture.
19+
* @param {number} [format=RGBAFormat] - The texture format.
20+
* @param {number} [type=UnsignedByteType] - The texture type.
21+
* @param {number} [mapping=Texture.DEFAULT_MAPPING] - The texture mapping.
22+
* @param {number} [wrapS=ClampToEdgeWrapping] - The wrapS value.
23+
* @param {number} [wrapT=ClampToEdgeWrapping] - The wrapT value.
24+
* @param {number} [magFilter=LinearFilter] - The mag filter value.
25+
* @param {number} [minFilter=LinearMipmapLinearFilter] - The min filter value.
26+
* @param {number} [anisotropy=Texture.DEFAULT_ANISOTROPY] - The anisotropy value.
27+
* @param {string} [colorSpace=NoColorSpace] - The color space.
28+
*/
529
constructor( mipmaps, width, height, format, type, mapping, wrapS, wrapT, magFilter, minFilter, anisotropy, colorSpace ) {
630

731
super( null, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy, colorSpace );
832

33+
/**
34+
* This flag can be used for type testing.
35+
*
36+
* @type {boolean}
37+
* @readonly
38+
* @default true
39+
*/
940
this.isCompressedTexture = true;
1041

42+
/**
43+
* The image property of a compressed texture just defines its dimensions.
44+
*
45+
* @type {{width:number,height:number}}
46+
*/
1147
this.image = { width: width, height: height };
12-
this.mipmaps = mipmaps;
1348

14-
// no flipping for cube textures
15-
// (also flipping doesn't work for compressed textures )
49+
/**
50+
* This array holds for all mipmaps (including the bases mip) the data and dimensions.
51+
*
52+
* @type {Array<Object>}
53+
*/
54+
this.mipmaps = mipmaps;
1655

56+
/**
57+
* If set to `true`, the texture is flipped along the vertical axis when
58+
* uploaded to the GPU.
59+
*
60+
* Overwritten and set to `false` by default since it is not possible to
61+
* flip compressed textures.
62+
*
63+
* @type {boolean}
64+
* @default false
65+
* @readonly
66+
*/
1767
this.flipY = false;
1868

19-
// can't generate mipmaps for compressed textures
20-
// mips must be embedded in DDS files
21-
69+
/**
70+
* Whether to generate mipmaps (if possible) for a texture.
71+
*
72+
* Overwritten and set to `false` by default since it is not
73+
* possible to generate mipmaps for compressed data. Mipmaps
74+
* must be embedded in the compressed texture file.
75+
*
76+
* @type {boolean}
77+
* @default false
78+
* @readonly
79+
*/
2280
this.generateMipmaps = false;
2381

2482
}

‎src/textures/CubeTexture.js

+52-4
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,69 @@
11
import { Texture } from './Texture.js';
22
import { CubeReflectionMapping } from '../constants.js';
33

4+
/**
5+
* Creates a cube texture made up of six images.
6+
*
7+
* ```js
8+
* const loader = new THREE.CubeTextureLoader();
9+
* loader.setPath( 'textures/cube/pisa/' );
10+
*
11+
* const textureCube = loader.load( [
12+
* 'px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png'
13+
* ] );
14+
*
15+
* const material = new THREE.MeshBasicMaterial( { color: 0xffffff, envMap: textureCube } );
16+
* ```
17+
*
18+
* @augments Texture
19+
*/
420
class CubeTexture extends Texture {
521

6-
constructor( images, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy, colorSpace ) {
7-
8-
images = images !== undefined ? images : [];
9-
mapping = mapping !== undefined ? mapping : CubeReflectionMapping;
22+
/**
23+
* Constructs a new cube texture.
24+
*
25+
* @param {Array<Image>} [images=[]] - An array holding a image for each side of a cube.
26+
* @param {number} [mapping=CubeReflectionMapping] - The texture mapping.
27+
* @param {number} [wrapS=ClampToEdgeWrapping] - The wrapS value.
28+
* @param {number} [wrapT=ClampToEdgeWrapping] - The wrapT value.
29+
* @param {number} [magFilter=LinearFilter] - The mag filter value.
30+
* @param {number} [minFilter=LinearMipmapLinearFilter] - The min filter value.
31+
* @param {number} [format=RGBAFormat] - The texture format.
32+
* @param {number} [type=UnsignedByteType] - The texture type.
33+
* @param {number} [anisotropy=Texture.DEFAULT_ANISOTROPY] - The anisotropy value.
34+
* @param {string} [colorSpace=NoColorSpace] - The color space value.
35+
*/
36+
constructor( images = [], mapping = CubeReflectionMapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy, colorSpace ) {
1037

1138
super( images, mapping, wrapS, wrapT, magFilter, minFilter, format, type, anisotropy, colorSpace );
1239

40+
/**
41+
* This flag can be used for type testing.
42+
*
43+
* @type {boolean}
44+
* @readonly
45+
* @default true
46+
*/
1347
this.isCubeTexture = true;
1448

49+
/**
50+
* If set to `true`, the texture is flipped along the vertical axis when
51+
* uploaded to the GPU.
52+
*
53+
* Overwritten and set to `false` by default.
54+
*
55+
* @type {boolean}
56+
* @default false
57+
*/
1558
this.flipY = false;
1659

1760
}
1861

62+
/**
63+
* Alias for {@link CubeTexture#image}.
64+
*
65+
* @type {Array<Image>}
66+
*/
1967
get images() {
2068

2169
return this.image;

0 commit comments

Comments
 (0)