From 26760307ec002ec24d11ea0e3b443760a21787b0 Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Wed, 26 Feb 2025 16:55:47 +0100 Subject: [PATCH] Docs: More JSDoc. (#30615) * Docs: More JSDoc. * JSDoc: Improve page title. --- src/geometries/BoxGeometry.js | 38 +++++++++++++++++++ src/geometries/CapsuleGeometry.js | 34 +++++++++++++++++ src/geometries/CircleGeometry.js | 40 ++++++++++++++++++++ src/geometries/ConeGeometry.js | 38 +++++++++++++++++++ src/geometries/CylinderGeometry.js | 39 +++++++++++++++++++ src/geometries/DodecahedronGeometry.js | 32 ++++++++++++++++ src/geometries/EdgesGeometry.js | 28 ++++++++++++++ src/geometries/ExtrudeGeometry.js | 52 ++++++++++++++++++++++++++ src/geometries/IcosahedronGeometry.js | 32 ++++++++++++++++ src/geometries/LatheGeometry.js | 40 ++++++++++++++++++++ src/geometries/OctahedronGeometry.js | 32 ++++++++++++++++ src/geometries/PlaneGeometry.js | 34 +++++++++++++++++ src/geometries/PolyhedronGeometry.js | 29 ++++++++++++++ src/geometries/RingGeometry.js | 36 ++++++++++++++++++ src/geometries/ShapeGeometry.js | 37 ++++++++++++++++++ src/geometries/SphereGeometry.js | 37 ++++++++++++++++++ src/geometries/TetrahedronGeometry.js | 32 ++++++++++++++++ src/geometries/TorusGeometry.js | 35 +++++++++++++++++ src/geometries/TorusKnotGeometry.js | 38 +++++++++++++++++++ src/geometries/TubeGeometry.js | 49 ++++++++++++++++++++++++ src/geometries/WireframeGeometry.js | 32 ++++++++++++++++ utils/docs/jsdoc.config.json | 1 + utils/docs/template/tmpl/layout.tmpl | 2 +- 23 files changed, 766 insertions(+), 1 deletion(-) diff --git a/src/geometries/BoxGeometry.js b/src/geometries/BoxGeometry.js index 486a3cd9d67539..2a5c5b11cc570b 100644 --- a/src/geometries/BoxGeometry.js +++ b/src/geometries/BoxGeometry.js @@ -2,14 +2,45 @@ import { BufferGeometry } from '../core/BufferGeometry.js'; import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { Vector3 } from '../math/Vector3.js'; +/** + * A geometry class for a rectangular cuboid with a given width, height, and depth. + * On creation, the cuboid is centred on the origin, with each edge parallel to one + * of the axes. + * + * ```js + * const geometry = new THREE.BoxGeometry( 1, 1, 1 ); + * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } ); + * const cube = new THREE.Mesh( geometry, material ); + * scene.add( cube ); + * ``` + * + * @augments BufferGeometry + */ class BoxGeometry extends BufferGeometry { + /** + * Constructs a new box geometry. + * + * @param {number} [width=1] - The width. That is, the length of the edges parallel to the X axis. + * @param {number} [height=1] - The height. That is, the length of the edges parallel to the Y axis. + * @param {number} [depth=1] - The depth. That is, the length of the edges parallel to the Z axis. + * @param {number} [widthSegments=1] - Number of segmented rectangular faces along the width of the sides. + * @param {number} [heightSegments=1] - Number of segmented rectangular faces along the height of the sides. + * @param {number} [depthSegments=1] - Number of segmented rectangular faces along the depth of the sides. + */ constructor( width = 1, height = 1, depth = 1, widthSegments = 1, heightSegments = 1, depthSegments = 1 ) { super(); this.type = 'BoxGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { width: width, height: height, @@ -169,6 +200,13 @@ class BoxGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {BoxGeometry} A new instance. + */ static fromJSON( data ) { return new BoxGeometry( data.width, data.height, data.depth, data.widthSegments, data.heightSegments, data.depthSegments ); diff --git a/src/geometries/CapsuleGeometry.js b/src/geometries/CapsuleGeometry.js index 15172e85a76d23..47187f3f5e3540 100644 --- a/src/geometries/CapsuleGeometry.js +++ b/src/geometries/CapsuleGeometry.js @@ -1,8 +1,28 @@ import { Path } from '../extras/core/Path.js'; import { LatheGeometry } from './LatheGeometry.js'; +/** + * A geometry class for a capsule with given radii and height. It is constructed using a lathe. + * + * ```js + * const geometry = new THREE.CapsuleGeometry( 1, 1, 4, 8 ); + * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } ); + * const capsule = new THREE.Mesh( geometry, material ); + * scene.add( capsule ); + * ``` + * + * @augments LatheGeometry + */ class CapsuleGeometry extends LatheGeometry { + /** + * Constructs a new capsule geometry. + * + * @param {number} [radius=1] - Radius of the capsule. + * @param {number} [length=1] - Length of the middle section. + * @param {number} [capSegments=4] - Number of curve segments used to build the caps. + * @param {number} [radialSegments=8] - Number of segmented faces around the circumference of the capsule. + */ constructor( radius = 1, length = 1, capSegments = 4, radialSegments = 8 ) { const path = new Path(); @@ -13,6 +33,13 @@ class CapsuleGeometry extends LatheGeometry { this.type = 'CapsuleGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radius: radius, length: length, @@ -22,6 +49,13 @@ class CapsuleGeometry extends LatheGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {CapsuleGeometry} A new instance. + */ static fromJSON( data ) { return new CapsuleGeometry( data.radius, data.length, data.capSegments, data.radialSegments ); diff --git a/src/geometries/CircleGeometry.js b/src/geometries/CircleGeometry.js index 63e912126e69f9..c1666c43623ac2 100644 --- a/src/geometries/CircleGeometry.js +++ b/src/geometries/CircleGeometry.js @@ -3,14 +3,47 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { Vector3 } from '../math/Vector3.js'; import { Vector2 } from '../math/Vector2.js'; +/** + * A simple shape of Euclidean geometry. It is constructed from a + * number of triangular segments that are oriented around a central point and + * extend as far out as a given radius. It is built counter-clockwise from a + * start angle and a given central angle. It can also be used to create + * regular polygons, where the number of segments determines the number of + * sides. + * + * ```js + * const geometry = new THREE.CircleGeometry( 5, 32 ); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const circle = new THREE.Mesh( geometry, material ); + * scene.add( circle ) + * ``` + * + * @augments BufferGeometry + */ class CircleGeometry extends BufferGeometry { + /** + * Constructs a new circle geometry. + * + * @param {number} [radius=1] - Radius of the circle. + * @param {number} [segments=32] - Number of segments (triangles), minimum = `3`. + * @param {number} [thetaStart=0] - Start angle for first segment in radians. + * @param {number} [thetaLength=Math.PI*2] - The central angle, often called theta, + * of the circular sector in radians. The default value results in a complete circle. + */ constructor( radius = 1, segments = 32, thetaStart = 0, thetaLength = Math.PI * 2 ) { super(); this.type = 'CircleGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radius: radius, segments: segments, @@ -89,6 +122,13 @@ class CircleGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {CircleGeometry} A new instance. + */ static fromJSON( data ) { return new CircleGeometry( data.radius, data.segments, data.thetaStart, data.thetaLength ); diff --git a/src/geometries/ConeGeometry.js b/src/geometries/ConeGeometry.js index 912b388f6ef8b2..dcf3c55562d035 100644 --- a/src/geometries/ConeGeometry.js +++ b/src/geometries/ConeGeometry.js @@ -1,13 +1,44 @@ import { CylinderGeometry } from './CylinderGeometry.js'; +/** + * A geometry class for representing a cone. + * + * ```js + * const geometry = new THREE.ConeGeometry( 5, 20, 32 ); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const cone = new THREE.Mesh(geometry, material ); + * scene.add( cone ); + * ``` + * + * @augments CylinderGeometry + */ class ConeGeometry extends CylinderGeometry { + /** + * Constructs a new cone geometry. + * + * @param {number} [radius=1] - Radius of the cone base. + * @param {number} [height=1] - Height of the cone. + * @param {number} [radialSegments=32] - Number of segmented faces around the circumference of the cone. + * @param {number} [heightSegments=1] - Number of rows of faces along the height of the cone. + * @param {boolean} [openEnded=false] - Whether the base of the cone is open or capped. + * @param {boolean} [thetaStart=0] - Start angle for first segment, in radians. + * @param {boolean} [thetaLength=Math.PI*2] - The central angle, often called theta, of the circular sector, in radians. + * The default value results in a complete cone. + */ constructor( radius = 1, height = 1, radialSegments = 32, heightSegments = 1, openEnded = false, thetaStart = 0, thetaLength = Math.PI * 2 ) { super( 0, radius, height, radialSegments, heightSegments, openEnded, thetaStart, thetaLength ); this.type = 'ConeGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radius: radius, height: height, @@ -20,6 +51,13 @@ class ConeGeometry extends CylinderGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {ConeGeometry} A new instance. + */ static fromJSON( data ) { return new ConeGeometry( data.radius, data.height, data.radialSegments, data.heightSegments, data.openEnded, data.thetaStart, data.thetaLength ); diff --git a/src/geometries/CylinderGeometry.js b/src/geometries/CylinderGeometry.js index c112e0171441f8..ff006f9084a46e 100644 --- a/src/geometries/CylinderGeometry.js +++ b/src/geometries/CylinderGeometry.js @@ -3,14 +3,46 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { Vector3 } from '../math/Vector3.js'; import { Vector2 } from '../math/Vector2.js'; +/** + * A geometry class for representing a cylinder. + * + * ```js + * const geometry = new THREE.CylinderGeometry( 5, 5, 20, 32 ); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const cylinder = new THREE.Mesh( geometry, material ); + * scene.add( cylinder ); + * ``` + * + * @augments BufferGeometry + */ class CylinderGeometry extends BufferGeometry { + /** + * Constructs a new cylinder geometry. + * + * @param {number} [radiusTop=1] - Radius of the cylinder at the top. + * @param {number} [radiusBottom=1] - Radius of the cylinder at the bottom. + * @param {number} [height=1] - Height of the cylinder. + * @param {number} [radialSegments=32] - Number of segmented faces around the circumference of the cylinder. + * @param {number} [heightSegments=1] - Number of rows of faces along the height of the cylinder. + * @param {boolean} [openEnded=false] - Whether the base of the cylinder is open or capped. + * @param {boolean} [thetaStart=0] - Start angle for first segment, in radians. + * @param {boolean} [thetaLength=Math.PI*2] - The central angle, often called theta, of the circular sector, in radians. + * The default value results in a complete cylinder. + */ constructor( radiusTop = 1, radiusBottom = 1, height = 1, radialSegments = 32, heightSegments = 1, openEnded = false, thetaStart = 0, thetaLength = Math.PI * 2 ) { super(); this.type = 'CylinderGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radiusTop: radiusTop, radiusBottom: radiusBottom, @@ -281,6 +313,13 @@ class CylinderGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {CylinderGeometry} A new instance. + */ static fromJSON( data ) { return new CylinderGeometry( data.radiusTop, data.radiusBottom, data.height, data.radialSegments, data.heightSegments, data.openEnded, data.thetaStart, data.thetaLength ); diff --git a/src/geometries/DodecahedronGeometry.js b/src/geometries/DodecahedronGeometry.js index 3434df937d9494..2ddd1f5075777d 100644 --- a/src/geometries/DodecahedronGeometry.js +++ b/src/geometries/DodecahedronGeometry.js @@ -1,7 +1,25 @@ import { PolyhedronGeometry } from './PolyhedronGeometry.js'; +/** + * A geometry class for representing a dodecahedron. + * + * ```js + * const geometry = new THREE.DodecahedronGeometry(); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const dodecahedron = new THREE.Mesh( geometry, material ); + * scene.add( dodecahedron ); + * ``` + * + * @augments PolyhedronGeometry + */ class DodecahedronGeometry extends PolyhedronGeometry { + /** + * Constructs a new dodecahedron geometry. + * + * @param {number} [radius=1] - Radius of the dodecahedron. + * @param {number} [detail=0] - Setting this to a value greater than `0` adds vertices making it no longer a dodecahedron. + */ constructor( radius = 1, detail = 0 ) { const t = ( 1 + Math.sqrt( 5 ) ) / 2; @@ -47,6 +65,13 @@ class DodecahedronGeometry extends PolyhedronGeometry { this.type = 'DodecahedronGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radius: radius, detail: detail @@ -54,6 +79,13 @@ class DodecahedronGeometry extends PolyhedronGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {DodecahedronGeometry} A new instance. + */ static fromJSON( data ) { return new DodecahedronGeometry( data.radius, data.detail ); diff --git a/src/geometries/EdgesGeometry.js b/src/geometries/EdgesGeometry.js index 4dc79c0cb2fdec..4ab931a9317bd0 100644 --- a/src/geometries/EdgesGeometry.js +++ b/src/geometries/EdgesGeometry.js @@ -9,14 +9,42 @@ const _v1 = /*@__PURE__*/ new Vector3(); const _normal = /*@__PURE__*/ new Vector3(); const _triangle = /*@__PURE__*/ new Triangle(); +/** + * Can be used as a helper object to view the edges of a geometry. + * + * ```js + * const geometry = new THREE.BoxGeometry(); + * const edges = new THREE.EdgesGeometry( geometry ); + * const line = new THREE.LineSegments( edges ); + * scene.add( line ); + * ``` + * + * Note: It is not yet possible to serialize/deserialize instances of this class. + * + * @augments BufferGeometry + */ class EdgesGeometry extends BufferGeometry { + /** + * Constructs a new edges geometry. + * + * @param {?BufferGeometry} [geometry=null] - The geometry. + * @param {number} [thresholdAngle=1] - An edge is only rendered if the angle (in degrees) + * between the face normals of the adjoining faces exceeds this value. + */ constructor( geometry = null, thresholdAngle = 1 ) { super(); this.type = 'EdgesGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { geometry: geometry, thresholdAngle: thresholdAngle diff --git a/src/geometries/ExtrudeGeometry.js b/src/geometries/ExtrudeGeometry.js index a27b67da818c2f..275d752cb5557b 100644 --- a/src/geometries/ExtrudeGeometry.js +++ b/src/geometries/ExtrudeGeometry.js @@ -28,14 +28,58 @@ import { Vector3 } from '../math/Vector3.js'; import { Shape } from '../extras/core/Shape.js'; import { ShapeUtils } from '../extras/ShapeUtils.js'; +/** + * Creates extruded geometry from a path shape. + * + * ```js + * const length = 12, width = 8; + * + * const shape = new THREE.Shape(); + * shape.moveTo( 0,0 ); + * shape.lineTo( 0, width ); + * shape.lineTo( length, width ); + * shape.lineTo( length, 0 ); + * shape.lineTo( 0, 0 ); + * + * const geometry = new THREE.ExtrudeGeometry( shape ); + * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } ); + * const mesh = new THREE.Mesh( geometry, material ) ; + * scene.add( mesh ); + * ``` + * + * @augments BufferGeometry + */ class ExtrudeGeometry extends BufferGeometry { + /** + * Constructs a new extrude geometry. + * + * @param {Shape|Array} [shapes] - A shape or an array of shapes. + * @param {Object} [options={}] - The extrude settings. + * @param {number} [options.curveSegments=12] - Number of points on the curves. + * @param {number} [options.steps=1] - Number of points used for subdividing segments along the depth of the extruded spline. + * @param {number} [options.depth=1] - Depth to extrude the shape. + * @param {boolean} [options.bevelEnabled=true] - Whether to beveling to the shape or not. + * @param {number} [options.bevelThickness=0.2] - How deep into the original shape the bevel goes. + * @param {number} [options.bevelSize=bevelThickness-0.1] - Distance from the shape outline that the bevel extends. + * @param {number} [options.bevelOffset=0] - Distance from the shape outline that the bevel starts. + * @param {number} [options.bevelSegments=3] - Number of bevel layers. + * @param {Curve} [options.extrudePath=3] - A 3D spline path along which the shape should be extruded. Bevels not supported for path extrusion. + * @param {Object} [options.UVGenerator] - An object that provides UV generator functions for custom UV generation. + */ constructor( shapes = new Shape( [ new Vector2( 0.5, 0.5 ), new Vector2( - 0.5, 0.5 ), new Vector2( - 0.5, - 0.5 ), new Vector2( 0.5, - 0.5 ) ] ), options = {} ) { super(); this.type = 'ExtrudeGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { shapes: shapes, options: options @@ -698,6 +742,14 @@ class ExtrudeGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @param {Array} shapes - An array of shapes. + * @return {ExtrudeGeometry} A new instance. + */ static fromJSON( data, shapes ) { const geometryShapes = []; diff --git a/src/geometries/IcosahedronGeometry.js b/src/geometries/IcosahedronGeometry.js index 5ffd4a02ba16d4..b78b009be49d52 100644 --- a/src/geometries/IcosahedronGeometry.js +++ b/src/geometries/IcosahedronGeometry.js @@ -1,7 +1,25 @@ import { PolyhedronGeometry } from './PolyhedronGeometry.js'; +/** + * A geometry class for representing an icosahedron. + * + * ```js + * const geometry = new THREE.IcosahedronGeometry(); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const icosahedron = new THREE.Mesh( geometry, material ); + * scene.add( icosahedron ); + * ``` + * + * @augments PolyhedronGeometry + */ class IcosahedronGeometry extends PolyhedronGeometry { + /** + * Constructs a new icosahedron geometry. + * + * @param {number} [radius=1] - Radius of the icosahedron. + * @param {number} [detail=0] - Setting this to a value greater than `0` adds vertices making it no longer a icosahedron. + */ constructor( radius = 1, detail = 0 ) { const t = ( 1 + Math.sqrt( 5 ) ) / 2; @@ -23,6 +41,13 @@ class IcosahedronGeometry extends PolyhedronGeometry { this.type = 'IcosahedronGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radius: radius, detail: detail @@ -30,6 +55,13 @@ class IcosahedronGeometry extends PolyhedronGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {IcosahedronGeometry} A new instance. + */ static fromJSON( data ) { return new IcosahedronGeometry( data.radius, data.detail ); diff --git a/src/geometries/LatheGeometry.js b/src/geometries/LatheGeometry.js index 914d96730d9f89..1e1a3680b3a723 100644 --- a/src/geometries/LatheGeometry.js +++ b/src/geometries/LatheGeometry.js @@ -4,14 +4,47 @@ import { Vector3 } from '../math/Vector3.js'; import { Vector2 } from '../math/Vector2.js'; import { clamp } from '../math/MathUtils.js'; +/** + * Creates meshes with axial symmetry like vases. The lathe rotates around the Y axis. + * + * ```js + * const points = []; + * for ( let i = 0; i < 10; i ++ ) { + * points.push( new THREE.Vector2( Math.sin( i * 0.2 ) * 10 + 5, ( i - 5 ) * 2 ) ); + * } + * const geometry = new THREE.LatheGeometry( points ); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const lathe = new THREE.Mesh( geometry, material ); + * scene.add( lathe ); + * ``` + * + * @augments BufferGeometry + */ class LatheGeometry extends BufferGeometry { + /** + * Constructs a new lathe geometry. + * + * @param {Array} [points] - An array of points in 2D space. The x-coordinate of each point + * must be greater than zero. + * @param {number} [segments=12] - The number of circumference segments to generate. + * @param {number} [phiStart=0] - The starting angle in radians. + * @param {number} [phiLength=Math.PI*2] - The radian (0 to 2PI) range of the lathed section 2PI is a + * closed lathe, less than 2PI is a portion. + */ constructor( points = [ new Vector2( 0, - 0.5 ), new Vector2( 0.5, 0 ), new Vector2( 0, 0.5 ) ], segments = 12, phiStart = 0, phiLength = Math.PI * 2 ) { super(); this.type = 'LatheGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { points: points, segments: segments, @@ -177,6 +210,13 @@ class LatheGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {LatheGeometry} A new instance. + */ static fromJSON( data ) { return new LatheGeometry( data.points, data.segments, data.phiStart, data.phiLength ); diff --git a/src/geometries/OctahedronGeometry.js b/src/geometries/OctahedronGeometry.js index d91bb1a18830d7..3b1af08c786ad9 100644 --- a/src/geometries/OctahedronGeometry.js +++ b/src/geometries/OctahedronGeometry.js @@ -1,7 +1,25 @@ import { PolyhedronGeometry } from './PolyhedronGeometry.js'; +/** + * A geometry class for representing an octahedron. + * + * ```js + * const geometry = new THREE.OctahedronGeometry(); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const octahedron = new THREE.Mesh( geometry, material ); + * scene.add( octahedron ); + * ``` + * + * @augments PolyhedronGeometry + */ class OctahedronGeometry extends PolyhedronGeometry { + /** + * Constructs a new octahedron geometry. + * + * @param {number} [radius=1] - Radius of the octahedron. + * @param {number} [detail=0] - Setting this to a value greater than `0` adds vertices making it no longer a octahedron. + */ constructor( radius = 1, detail = 0 ) { const vertices = [ @@ -19,6 +37,13 @@ class OctahedronGeometry extends PolyhedronGeometry { this.type = 'OctahedronGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radius: radius, detail: detail @@ -26,6 +51,13 @@ class OctahedronGeometry extends PolyhedronGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {OctahedronGeometry} A new instance. + */ static fromJSON( data ) { return new OctahedronGeometry( data.radius, data.detail ); diff --git a/src/geometries/PlaneGeometry.js b/src/geometries/PlaneGeometry.js index 53f98f7a37a255..e88b00a069ff11 100644 --- a/src/geometries/PlaneGeometry.js +++ b/src/geometries/PlaneGeometry.js @@ -1,14 +1,41 @@ import { BufferGeometry } from '../core/BufferGeometry.js'; import { Float32BufferAttribute } from '../core/BufferAttribute.js'; +/** + * A geometry class for representing a plane. + * + * ```js + * const geometry = new THREE.PlaneGeometry( 1, 1 ); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00, side: THREE.DoubleSide } ); + * const plane = new THREE.Mesh( geometry, material ); + * scene.add( plane ); + * ``` + * + * @augments BufferGeometry + */ class PlaneGeometry extends BufferGeometry { + /** + * Constructs a new plane geometry. + * + * @param {number} [width=1] - The width along the X axis. + * @param {number} [height=1] - The height along the Y axis + * @param {number} [widthSegments=1] - The number of segments along the X axis. + * @param {number} [heightSegments=1] - The number of segments along the Y axis. + */ constructor( width = 1, height = 1, widthSegments = 1, heightSegments = 1 ) { super(); this.type = 'PlaneGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { width: width, height: height, @@ -87,6 +114,13 @@ class PlaneGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {PlaneGeometry} A new instance. + */ static fromJSON( data ) { return new PlaneGeometry( data.width, data.height, data.widthSegments, data.heightSegments ); diff --git a/src/geometries/PolyhedronGeometry.js b/src/geometries/PolyhedronGeometry.js index 114cfeece111b6..cf3a1828dc584a 100644 --- a/src/geometries/PolyhedronGeometry.js +++ b/src/geometries/PolyhedronGeometry.js @@ -3,14 +3,36 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { Vector3 } from '../math/Vector3.js'; import { Vector2 } from '../math/Vector2.js'; +/** + * A polyhedron is a solid in three dimensions with flat faces. This class + * will take an array of vertices, project them onto a sphere, and then + * divide them up to the desired level of detail. + * + * @augments BufferGeometry + */ class PolyhedronGeometry extends BufferGeometry { + /** + * Constructs a new polyhedron geometry. + * + * @param {Array} [vertices] - A flat array of vertices describing the base shape. + * @param {Array} [indices] - A flat array of indices describing the base shape. + * @param {number} [radius=1] - The radius of the shape. + * @param {number} [detail=0] - How many levels to subdivide the geometry. The more detail, the smoother the shape. + */ constructor( vertices = [], indices = [], radius = 1, detail = 0 ) { super(); this.type = 'PolyhedronGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { vertices: vertices, indices: indices, @@ -308,6 +330,13 @@ class PolyhedronGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {PolyhedronGeometry} A new instance. + */ static fromJSON( data ) { return new PolyhedronGeometry( data.vertices, data.indices, data.radius, data.details ); diff --git a/src/geometries/RingGeometry.js b/src/geometries/RingGeometry.js index 9a8cbbc5871162..79d34ef11c4da7 100644 --- a/src/geometries/RingGeometry.js +++ b/src/geometries/RingGeometry.js @@ -3,14 +3,43 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { Vector2 } from '../math/Vector2.js'; import { Vector3 } from '../math/Vector3.js'; +/** + * A class for generating a two-dimensional ring geometry. + * + * ```js + * const geometry = new THREE.RingGeometry( 1, 5, 32 ); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00, side: THREE.DoubleSide } ); + * const mesh = new THREE.Mesh( geometry, material ); + * scene.add( mesh ); + * ``` + * + * @augments BufferGeometry + */ class RingGeometry extends BufferGeometry { + /** + * Constructs a new ring geometry. + * + * @param {number} [innerRadius=0.5] - The inner radius of the ring. + * @param {number} [outerRadius=1] - The outer radius of the ring. + * @param {number} [thetaSegments=32] - Number of segments. A higher number means the ring will be more round. Minimum is `3`. + * @param {number} [phiSegments=1] - Number of segments per ring segment. Minimum is `1`. + * @param {number} [thetaStart=0] - Starting angle in radians. + * @param {number} [thetaLength=Math.PI*2] - Central angle in radians. + */ constructor( innerRadius = 0.5, outerRadius = 1, thetaSegments = 32, phiSegments = 1, thetaStart = 0, thetaLength = Math.PI * 2 ) { super(); this.type = 'RingGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { innerRadius: innerRadius, outerRadius: outerRadius, @@ -116,6 +145,13 @@ class RingGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {RingGeometry} A new instance. + */ static fromJSON( data ) { return new RingGeometry( data.innerRadius, data.outerRadius, data.thetaSegments, data.phiSegments, data.thetaStart, data.thetaLength ); diff --git a/src/geometries/ShapeGeometry.js b/src/geometries/ShapeGeometry.js index 5b97d771af1448..1f7593d50c14a6 100644 --- a/src/geometries/ShapeGeometry.js +++ b/src/geometries/ShapeGeometry.js @@ -4,14 +4,43 @@ import { Shape } from '../extras/core/Shape.js'; import { ShapeUtils } from '../extras/ShapeUtils.js'; import { Vector2 } from '../math/Vector2.js'; +/** + * Creates an one-sided polygonal geometry from one or more path shapes. + * + * ```js + * const arcShape = new THREE.Shape() + * .moveTo( 5, 1 ) + * .absarc( 1, 1, 4, 0, Math.PI * 2, false ); + * + * const geometry = new THREE.ShapeGeometry( arcShape ); + * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00, side: THREE.DoubleSide } ); + * const mesh = new THREE.Mesh( geometry, material ) ; + * scene.add( mesh ); + * ``` + * + * @augments BufferGeometry + */ class ShapeGeometry extends BufferGeometry { + /** + * Constructs a new shape geometry. + * + * @param {Shape|Array} [shapes] - A shape or an array of shapes. + * @param {number} [curveSegments=12] - Number of segments per shape. + */ constructor( shapes = new Shape( [ new Vector2( 0, 0.5 ), new Vector2( - 0.5, - 0.5 ), new Vector2( 0.5, - 0.5 ) ] ), curveSegments = 12 ) { super(); this.type = 'ShapeGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { shapes: shapes, curveSegments: curveSegments @@ -150,6 +179,14 @@ class ShapeGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @param {Array} shapes - An array of shapes. + * @return {ShapeGeometry} A new instance. + */ static fromJSON( data, shapes ) { const geometryShapes = []; diff --git a/src/geometries/SphereGeometry.js b/src/geometries/SphereGeometry.js index 56cd3805b4dc7a..2ef5e8f7845ba7 100644 --- a/src/geometries/SphereGeometry.js +++ b/src/geometries/SphereGeometry.js @@ -2,14 +2,44 @@ import { BufferGeometry } from '../core/BufferGeometry.js'; import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { Vector3 } from '../math/Vector3.js'; +/** + * A class for generating a sphere geometry. + * + * ```js + * const geometry = new THREE.SphereGeometry( 15, 32, 16 ); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const sphere = new THREE.Mesh( geometry, material ); + * scene.add( sphere ); + * ``` + * + * @augments BufferGeometry + */ class SphereGeometry extends BufferGeometry { + /** + * Constructs a new sphere geometry. + * + * @param {number} [radius=1] - The sphere radius. + * @param {number} [widthSegments=32] - The number of horizontal segments. Minimum value is `3`. + * @param {number} [heightSegments=16] - The number of vertical segments. Minimum value is `2`. + * @param {number} [phiStart=0] - The horizontal starting angle in radians. + * @param {number} [phiLength=Math.PI*2] - The horizontal sweep angle size. + * @param {number} [thetaStart=0] - The vertical starting angle in radians. + * @param {number} [thetaLength=Math.PI] - The vertical sweep angle size. + */ constructor( radius = 1, widthSegments = 32, heightSegments = 16, phiStart = 0, phiLength = Math.PI * 2, thetaStart = 0, thetaLength = Math.PI ) { super(); this.type = 'SphereGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radius: radius, widthSegments: widthSegments, @@ -126,6 +156,13 @@ class SphereGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {SphereGeometry} A new instance. + */ static fromJSON( data ) { return new SphereGeometry( data.radius, data.widthSegments, data.heightSegments, data.phiStart, data.phiLength, data.thetaStart, data.thetaLength ); diff --git a/src/geometries/TetrahedronGeometry.js b/src/geometries/TetrahedronGeometry.js index 77c62107f2e8f4..99738cef8aebfc 100644 --- a/src/geometries/TetrahedronGeometry.js +++ b/src/geometries/TetrahedronGeometry.js @@ -1,7 +1,25 @@ import { PolyhedronGeometry } from './PolyhedronGeometry.js'; +/** + * A geometry class for representing an tetrahedron. + * + * ```js + * const geometry = new THREE.TetrahedronGeometry(); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const tetrahedron = new THREE.Mesh( geometry, material ); + * scene.add( tetrahedron ); + * ``` + * + * @augments PolyhedronGeometry + */ class TetrahedronGeometry extends PolyhedronGeometry { + /** + * Constructs a new tetrahedron geometry. + * + * @param {number} [radius=1] - Radius of the tetrahedron. + * @param {number} [detail=0] - Setting this to a value greater than `0` adds vertices making it no longer a tetrahedron. + */ constructor( radius = 1, detail = 0 ) { const vertices = [ @@ -16,6 +34,13 @@ class TetrahedronGeometry extends PolyhedronGeometry { this.type = 'TetrahedronGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radius: radius, detail: detail @@ -23,6 +48,13 @@ class TetrahedronGeometry extends PolyhedronGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {TetrahedronGeometry} A new instance. + */ static fromJSON( data ) { return new TetrahedronGeometry( data.radius, data.detail ); diff --git a/src/geometries/TorusGeometry.js b/src/geometries/TorusGeometry.js index 9061e6d0315008..3dae9f4ce13ade 100644 --- a/src/geometries/TorusGeometry.js +++ b/src/geometries/TorusGeometry.js @@ -2,14 +2,42 @@ import { BufferGeometry } from '../core/BufferGeometry.js'; import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { Vector3 } from '../math/Vector3.js'; +/** + * A geometry class for representing an torus. + * + * ```js + * const geometry = new THREE.TorusGeometry( 10, 3, 16, 100 ); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const torus = new THREE.Mesh( geometry, material ); + * scene.add( torus ); + * ``` + * + * @augments BufferGeometry + */ class TorusGeometry extends BufferGeometry { + /** + * Constructs a new torus geometry. + * + * @param {number} [radius=1] - Radius of the torus, from the center of the torus to the center of the tube. + * @param {number} [tube=0.4] - Radius of the tube. Must be smaller than `radius`. + * @param {number} [radialSegments=12] - The number of radial segments. + * @param {number} [tubularSegments=48] - The number of tubular segments. + * @param {number} [arc=Math.PI*2] - Central angle in radians. + */ constructor( radius = 1, tube = 0.4, radialSegments = 12, tubularSegments = 48, arc = Math.PI * 2 ) { super(); this.type = 'TorusGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radius: radius, tube: tube, @@ -109,6 +137,13 @@ class TorusGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {TorusGeometry} A new instance. + */ static fromJSON( data ) { return new TorusGeometry( data.radius, data.tube, data.radialSegments, data.tubularSegments, data.arc ); diff --git a/src/geometries/TorusKnotGeometry.js b/src/geometries/TorusKnotGeometry.js index a8b82da0a8f0fc..6c7963ba18b40d 100644 --- a/src/geometries/TorusKnotGeometry.js +++ b/src/geometries/TorusKnotGeometry.js @@ -2,14 +2,45 @@ import { BufferGeometry } from '../core/BufferGeometry.js'; import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { Vector3 } from '../math/Vector3.js'; +/** + * Creates a torus knot, the particular shape of which is defined by a pair + * of coprime integers, p and q. If p and q are not coprime, the result will + * be a torus link. + * + * ```js + * const geometry = new THREE.TorusKnotGeometry( 10, 3, 100, 16 ); + * const material = new THREE.MeshBasicMaterial( { color: 0xffff00 } ); + * const torusKnot = new THREE.Mesh( geometry, material ); + * scene.add( torusKnot ); + * ``` + * + * @augments BufferGeometry + */ class TorusKnotGeometry extends BufferGeometry { + /** + * Constructs a new torus knot geometry. + * + * @param {number} [radius=1] - Radius of the torus knot. + * @param {number} [tube=0.4] - Radius of the tube. + * @param {number} [tubularSegments=64] - The number of tubular segments. + * @param {number} [radialSegments=8] - The number of radial segments. + * @param {number} [p=2] - This value determines, how many times the geometry winds around its axis of rotational symmetry. + * @param {number} [q=3] - This value determines, how many times the geometry winds around a circle in the interior of the torus. + */ constructor( radius = 1, tube = 0.4, tubularSegments = 64, radialSegments = 8, p = 2, q = 3 ) { super(); this.type = 'TorusKnotGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { radius: radius, tube: tube, @@ -156,6 +187,13 @@ class TorusKnotGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {TorusKnotGeometry} A new instance. + */ static fromJSON( data ) { return new TorusKnotGeometry( data.radius, data.tube, data.tubularSegments, data.radialSegments, data.p, data.q ); diff --git a/src/geometries/TubeGeometry.js b/src/geometries/TubeGeometry.js index 95247a0ce51197..4c021d8e71ace8 100644 --- a/src/geometries/TubeGeometry.js +++ b/src/geometries/TubeGeometry.js @@ -4,14 +4,56 @@ import * as Curves from '../extras/curves/Curves.js'; import { Vector2 } from '../math/Vector2.js'; import { Vector3 } from '../math/Vector3.js'; +/** + * Creates a tube that extrudes along a 3D curve. + * + * ```js + * class CustomSinCurve extends THREE.Curve { + * + * getPoint( t, optionalTarget = new THREE.Vector3() ) { + * + * const tx = t * 3 - 1.5; + * const ty = Math.sin( 2 * Math.PI * t ); + * const tz = 0; + * + * return optionalTarget.set( tx, ty, tz ); + * } + * + * } + * + * const path = new CustomSinCurve( 10 ); + * const geometry = new THREE.TubeGeometry( path, 20, 2, 8, false ); + * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } ); + * const mesh = new THREE.Mesh( geometry, material ); + * scene.add( mesh ); + * ``` + * + * @augments BufferGeometry + */ class TubeGeometry extends BufferGeometry { + /** + * Constructs a new tube geometry. + * + * @param {Curve} [path=QuadraticBezierCurve3] - A 3D curve defining the path of the tube. + * @param {number} [tubularSegments=64] - The number of segments that make up the tube. + * @param {number} [radius=1] -The radius of the tube. + * @param {number} [radialSegments=8] - The number of segments that make up the cross-section. + * @param {boolean} [closed=false] - Whether the tube is closed or not. + */ constructor( path = new Curves[ 'QuadraticBezierCurve3' ]( new Vector3( - 1, - 1, 0 ), new Vector3( - 1, 1, 0 ), new Vector3( 1, 1, 0 ) ), tubularSegments = 64, radius = 1, radialSegments = 8, closed = false ) { super(); this.type = 'TubeGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { path: path, tubularSegments: tubularSegments, @@ -183,6 +225,13 @@ class TubeGeometry extends BufferGeometry { } + /** + * Factory method for creating an instance of this class from the given + * JSON object. + * + * @param {Object} data - A JSON object representing the serialized geometry. + * @return {TubeGeometry} A new instance. + */ static fromJSON( data ) { // This only works for built-in curves (e.g. CatmullRomCurve3). diff --git a/src/geometries/WireframeGeometry.js b/src/geometries/WireframeGeometry.js index 353018bfe64952..734b453ec999b1 100644 --- a/src/geometries/WireframeGeometry.js +++ b/src/geometries/WireframeGeometry.js @@ -2,14 +2,46 @@ import { BufferGeometry } from '../core/BufferGeometry.js'; import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { Vector3 } from '../math/Vector3.js'; +/** + * Can be used as a helper object to visualize a geometry as a wireframe. + * + * ```js + * const geometry = new THREE.SphereGeometry(); + * + * const wireframe = new THREE.WireframeGeometry( geometry ); + * + * const line = new THREE.LineSegments( wireframe ); + * line.material.depthWrite = false; + * line.material.opacity = 0.25; + * line.material.transparent = true; + * + * scene.add( line ); + * ``` + * + * Note: It is not yet possible to serialize/deserialize instances of this class. + * + * @augments BufferGeometry + */ class WireframeGeometry extends BufferGeometry { + /** + * Constructs a new wireframe geometry. + * + * @param {?BufferGeometry} [geometry=null] - The geometry. + */ constructor( geometry = null ) { super(); this.type = 'WireframeGeometry'; + /** + * Holds the constructor parameters that have been + * used to generate the geometry. Any modification + * after instantiation does not change the geometry. + * + * @type {Object} + */ this.parameters = { geometry: geometry }; diff --git a/utils/docs/jsdoc.config.json b/utils/docs/jsdoc.config.json index 81c1413f5a935d..0898c11c6b484c 100644 --- a/utils/docs/jsdoc.config.json +++ b/utils/docs/jsdoc.config.json @@ -18,6 +18,7 @@ "src/core/Object3D.js", "src/core/EventDispatcher.js", "src/extras", + "src/geometries", "src/helpers", "src/lights", "src/loaders/nodes", diff --git a/utils/docs/template/tmpl/layout.tmpl b/utils/docs/template/tmpl/layout.tmpl index 407ce2d2a33460..393a6a51e229e2 100644 --- a/utils/docs/template/tmpl/layout.tmpl +++ b/utils/docs/template/tmpl/layout.tmpl @@ -2,7 +2,7 @@ - three.js docs + <?js= title || 'Home' ?> - three.js docs