Merge pull request #17777 from WestLangley/dev_chainable_path

Path: support chaining in Path and Shape methods

docs/api/en/extras/core/Path.html

@@ -60,7 +60,7 @@
 		<h2>Methods</h2>
 		<p>See the base [page:CurvePath] class for common methods.</p>
 
-		<h3>[method:null absarc]( [param:Float x], [param:Float y], [param:Float radius], [param:Float startAngle], [param:Float endAngle], [param:Float clockwise] )</h3>
+		<h3>[method:this absarc]( [param:Float x], [param:Float y], [param:Float radius], [param:Float startAngle], [param:Float endAngle], [param:Float clockwise] )</h3>
 		<p>
 			x, y -- The absolute center of the arc.<br />
 			radius -- The radius of the arc.<br />
@@ -71,7 +71,7 @@
 			Adds an absolutely positioned [page:EllipseCurve EllipseCurve] to the path.
 		</p>
 
-		<h3>[method:null absellipse]( [param:Float x], [param:Float y], [param:Float xRadius], [param:Float yRadius], [param:Float startAngle], [param:Float endAngle], [param:Float clockwise], [param:Float rotation] )</h3>
+		<h3>[method:this absellipse]( [param:Float x], [param:Float y], [param:Float xRadius], [param:Float yRadius], [param:Float startAngle], [param:Float endAngle], [param:Float clockwise], [param:Float rotation] )</h3>
 		<p>
 			x, y -- The absolute center of the ellipse.<br />
 			xRadius -- The radius of the ellipse in the x axis.<br />
@@ -84,7 +84,7 @@
 			Adds an absolutely positioned [page:EllipseCurve EllipseCurve] to the path.
 		</p>
 
-		<h3>[method:null arc]( [param:Float x], [param:Float y], [param:Float radius], [param:Float startAngle], [param:Float endAngle], [param:Float clockwise] )</h3>
+		<h3>[method:this arc]( [param:Float x], [param:Float y], [param:Float radius], [param:Float startAngle], [param:Float endAngle], [param:Float clockwise] )</h3>
 		<p>
 		x, y -- The center of the arc offset from the last call.<br />
 		radius -- The radius of the arc.<br />
@@ -96,10 +96,10 @@
 		</p>
 
 
-		<h3>[method:null bezierCurveTo]( [param:Float cp1X], [param:Float cp1Y], [param:Float cp2X], [param:Float cp2Y], [param:Float x], [param:Float y] )</h3>
+		<h3>[method:this bezierCurveTo]( [param:Float cp1X], [param:Float cp1Y], [param:Float cp2X], [param:Float cp2Y], [param:Float x], [param:Float y] )</h3>
 		<p>This creates a bezier curve from [page:.currentPoint] with (cp1X, cp1Y) and (cp2X, cp2Y) as control points and updates [page:.currentPoint] to x and y.</p>
 
-		<h3>[method:null ellipse]( [param:Float x], [param:Float y], [param:Float xRadius], [param:Float yRadius], [param:Float startAngle], [param:Float endAngle], [param:Float clockwise], [param:Float rotation] )</h3>
+		<h3>[method:this ellipse]( [param:Float x], [param:Float y], [param:Float xRadius], [param:Float yRadius], [param:Float startAngle], [param:Float endAngle], [param:Float clockwise], [param:Float rotation] )</h3>
 		<p>
 			x, y -- The center of the ellipse offset from the last call.<br />
 			xRadius -- The radius of the ellipse in the x axis.<br />
@@ -112,18 +112,18 @@
 			Adds an [page:EllipseCurve EllipseCurve] to the path, positioned relative to [page:.currentPoint].
 		</p>
 
-		<h3>[method:null lineTo]( [param:Float x], [param:Float y] )</h3>
+		<h3>[method:this lineTo]( [param:Float x], [param:Float y] )</h3>
 		<p>Connects a [page:LineCurve] from [page:.currentPoint] to x, y onto the path.</p>
 
 
-		<h3>[method:null moveTo]( [param:Float x], [param:Float y] )</h3>
+		<h3>[method:this moveTo]( [param:Float x], [param:Float y] )</h3>
 		<p>Move the [page:.currentPoint] to x, y.</p>
 
 
-		<h3>[method:null quadraticCurveTo]( [param:Float cpX], [param:Float cpY], [param:Float x], [param:Float y] )</h3>
+		<h3>[method:this quadraticCurveTo]( [param:Float cpX], [param:Float cpY], [param:Float x], [param:Float y] )</h3>
 		<p>Creates a quadratic curve from [page:.currentPoint] with cpX and cpY as control point and updates [page:.currentPoint] to x and y.</p>
 
-		<h3>[method:null setFromPoints]( [param:Array vector2s] )</h3>
+		<h3>[method:this setFromPoints]( [param:Array vector2s] )</h3>
 		<p>
 			points --  array of [page:Vector2 Vector2s].<br /><br />
 
@@ -131,7 +131,7 @@
 			array as [page:LineCurve LineCurves].
 		</p>
 
-		<h3>[method:null splineThru] ( [param:Array points] ) </h3>
+		<h3>[method:this splineThru] ( [param:Array points] ) </h3>
 		<p>
 			points - An array of [page:Vector2 Vector2s]<br /><br />
 

examples/webgl_geometry_shapes.html

@@ -184,50 +184,49 @@
 
 				// Triangle
 
-				var triangleShape = new THREE.Shape();
-				triangleShape.moveTo( 80, 20 );
-				triangleShape.lineTo( 40, 80 );
-				triangleShape.lineTo( 120, 80 );
-				triangleShape.lineTo( 80, 20 ); // close path
+				var triangleShape = new THREE.Shape()
+					.moveTo( 80, 20 )
+					.lineTo( 40, 80 )
+					.lineTo( 120, 80 )
+					.lineTo( 80, 20 ); // close path
 
 
 				// Heart
 
 				var x = 0, y = 0;
 
-				var heartShape = new THREE.Shape(); // From http://blog.burlock.org/html5/130-paths
-
-				heartShape.moveTo( x + 25, y + 25 );
-				heartShape.bezierCurveTo( x + 25, y + 25, x + 20, y, x, y );
-				heartShape.bezierCurveTo( x - 30, y, x - 30, y + 35, x - 30, y + 35 );
-				heartShape.bezierCurveTo( x - 30, y + 55, x - 10, y + 77, x + 25, y + 95 );
-				heartShape.bezierCurveTo( x + 60, y + 77, x + 80, y + 55, x + 80, y + 35 );
-				heartShape.bezierCurveTo( x + 80, y + 35, x + 80, y, x + 50, y );
-				heartShape.bezierCurveTo( x + 35, y, x + 25, y + 25, x + 25, y + 25 );
+				var heartShape = new THREE.Shape() // From http://blog.burlock.org/html5/130-paths
+					.moveTo( x + 25, y + 25 )
+					.bezierCurveTo( x + 25, y + 25, x + 20, y, x, y )
+					.bezierCurveTo( x - 30, y, x - 30, y + 35, x - 30, y + 35 )
+					.bezierCurveTo( x - 30, y + 55, x - 10, y + 77, x + 25, y + 95 )
+					.bezierCurveTo( x + 60, y + 77, x + 80, y + 55, x + 80, y + 35 )
+					.bezierCurveTo( x + 80, y + 35, x + 80, y, x + 50, y )
+					.bezierCurveTo( x + 35, y, x + 25, y + 25, x + 25, y + 25 );
 
 
 				// Square
 
 				var sqLength = 80;
 
-				var squareShape = new THREE.Shape();
-				squareShape.moveTo( 0, 0 );
-				squareShape.lineTo( 0, sqLength );
-				squareShape.lineTo( sqLength, sqLength );
-				squareShape.lineTo( sqLength, 0 );
-				squareShape.lineTo( 0, 0 );
+				var squareShape = new THREE.Shape()
+					.moveTo( 0, 0 )
+					.lineTo( 0, sqLength )
+					.lineTo( sqLength, sqLength )
+					.lineTo( sqLength, 0 )
+					.lineTo( 0, 0 );
 
 
 				// Rectangle
 
 				var rectLength = 120, rectWidth = 40;
 
-				var rectShape = new THREE.Shape();
-				rectShape.moveTo( 0, 0 );
-				rectShape.lineTo( 0, rectWidth );
-				rectShape.lineTo( rectLength, rectWidth );
-				rectShape.lineTo( rectLength, 0 );
-				rectShape.lineTo( 0, 0 );
+				var rectShape = new THREE.Shape()
+					.moveTo( 0, 0 )
+					.lineTo( 0, rectWidth )
+					.lineTo( rectLength, rectWidth )
+					.lineTo( rectLength, 0 )
+					.lineTo( 0, 0 );
 
 
 				// Rounded rectangle
@@ -251,76 +250,74 @@
 
 				// Track
 
-				var trackShape = new THREE.Shape();
-
-				trackShape.moveTo( 40, 40 );
-				trackShape.lineTo( 40, 160 );
-				trackShape.absarc( 60, 160, 20, Math.PI, 0, true );
-				trackShape.lineTo( 80, 40 );
-				trackShape.absarc( 60, 40, 20, 2 * Math.PI, Math.PI, true );
+				var trackShape = new THREE.Shape()
+					.moveTo( 40, 40 )
+					.lineTo( 40, 160 )
+					.absarc( 60, 160, 20, Math.PI, 0, true )
+					.lineTo( 80, 40 )
+					.absarc( 60, 40, 20, 2 * Math.PI, Math.PI, true );
 
 
 				// Circle
 
 				var circleRadius = 40;
-				var circleShape = new THREE.Shape();
-				circleShape.moveTo( 0, circleRadius );
-				circleShape.quadraticCurveTo( circleRadius, circleRadius, circleRadius, 0 );
-				circleShape.quadraticCurveTo( circleRadius, - circleRadius, 0, - circleRadius );
-				circleShape.quadraticCurveTo( - circleRadius, - circleRadius, - circleRadius, 0 );
-				circleShape.quadraticCurveTo( - circleRadius, circleRadius, 0, circleRadius );
+				var circleShape = new THREE.Shape()
+					.moveTo( 0, circleRadius )
+					.quadraticCurveTo( circleRadius, circleRadius, circleRadius, 0 )
+					.quadraticCurveTo( circleRadius, - circleRadius, 0, - circleRadius )
+					.quadraticCurveTo( - circleRadius, - circleRadius, - circleRadius, 0 )
+					.quadraticCurveTo( - circleRadius, circleRadius, 0, circleRadius );
 
 
 				// Fish
 
 				var x = y = 0;
 
-				var fishShape = new THREE.Shape();
-
-				fishShape.moveTo( x, y );
-				fishShape.quadraticCurveTo( x + 50, y - 80, x + 90, y - 10 );
-				fishShape.quadraticCurveTo( x + 100, y - 10, x + 115, y - 40 );
-				fishShape.quadraticCurveTo( x + 115, y, x + 115, y + 40 );
-				fishShape.quadraticCurveTo( x + 100, y + 10, x + 90, y + 10 );
-				fishShape.quadraticCurveTo( x + 50, y + 80, x, y );
+				var fishShape = new THREE.Shape()
+					.moveTo( x, y )
+					.quadraticCurveTo( x + 50, y - 80, x + 90, y - 10 )
+					.quadraticCurveTo( x + 100, y - 10, x + 115, y - 40 )
+					.quadraticCurveTo( x + 115, y, x + 115, y + 40 )
+					.quadraticCurveTo( x + 100, y + 10, x + 90, y + 10 )
+					.quadraticCurveTo( x + 50, y + 80, x, y );
 
 
 				// Arc circle
 
-				var arcShape = new THREE.Shape();
-				arcShape.moveTo( 50, 10 );
-				arcShape.absarc( 10, 10, 40, 0, Math.PI * 2, false );
+				var arcShape = new THREE.Shape()
+					.moveTo( 50, 10 )
+					.absarc( 10, 10, 40, 0, Math.PI * 2, false );
+
+				var holePath = new THREE.Path()
+					.moveTo( 20, 10 )
+					.absarc( 10, 10, 10, 0, Math.PI * 2, true )
 
-				var holePath = new THREE.Path();
-				holePath.moveTo( 20, 10 );
-				holePath.absarc( 10, 10, 10, 0, Math.PI * 2, true );
 				arcShape.holes.push( holePath );
 
 
 				// Smiley
 
-				var smileyShape = new THREE.Shape();
-				smileyShape.moveTo( 80, 40 );
-				smileyShape.absarc( 40, 40, 40, 0, Math.PI * 2, false );
+				var smileyShape = new THREE.Shape()
+					.moveTo( 80, 40 )
+					.absarc( 40, 40, 40, 0, Math.PI * 2, false );
 
-				var smileyEye1Path = new THREE.Path();
-				smileyEye1Path.moveTo( 35, 20 );
-				smileyEye1Path.absellipse( 25, 20, 10, 10, 0, Math.PI * 2, true );
+				var smileyEye1Path = new THREE.Path()
+					.moveTo( 35, 20 )
+					.absellipse( 25, 20, 10, 10, 0, Math.PI * 2, true );
 
-				smileyShape.holes.push( smileyEye1Path );
+				var smileyEye2Path = new THREE.Path()
+					.moveTo( 65, 20 )
+					.absarc( 55, 20, 10, 0, Math.PI * 2, true );
 
-				var smileyEye2Path = new THREE.Path();
-				smileyEye2Path.moveTo( 65, 20 );
-				smileyEye2Path.absarc( 55, 20, 10, 0, Math.PI * 2, true );
-				smileyShape.holes.push( smileyEye2Path );
-
-				var smileyMouthPath = new THREE.Path();
-				smileyMouthPath.moveTo( 20, 40 );
-				smileyMouthPath.quadraticCurveTo( 40, 60, 60, 40 );
-				smileyMouthPath.bezierCurveTo( 70, 45, 70, 50, 60, 60 );
-				smileyMouthPath.quadraticCurveTo( 40, 80, 20, 60 );
-				smileyMouthPath.quadraticCurveTo( 5, 50, 20, 40 );
+				var smileyMouthPath = new THREE.Path()
+					.moveTo( 20, 40 )
+					.quadraticCurveTo( 40, 60, 60, 40 )
+					.bezierCurveTo( 70, 45, 70, 50, 60, 60 )
+					.quadraticCurveTo( 40, 80, 20, 60 )
+					.quadraticCurveTo( 5, 50, 20, 40 );
 
+				smileyShape.holes.push( smileyEye1Path );
+				smileyShape.holes.push( smileyEye2Path );
 				smileyShape.holes.push( smileyMouthPath );
 
 
@@ -332,9 +329,9 @@
 				splinepts.push( new THREE.Vector2( - 30, 70 ) );
 				splinepts.push( new THREE.Vector2( 0, 0 ) );
 
-				var splineShape = new THREE.Shape();
-				splineShape.moveTo( 0, 0 );
-				splineShape.splineThru( splinepts );
+				var splineShape = new THREE.Shape()
+					.moveTo( 0, 0 )
+					.splineThru( splinepts );
 
 				var extrudeSettings = { depth: 8, bevelEnabled: true, bevelSegments: 2, steps: 2, bevelSize: 1, bevelThickness: 1 };
 

src/Three.Legacy.js

@@ -308,7 +308,7 @@ Object.assign( Path.prototype, {
 	fromPoints: function ( points ) {
 
 		console.warn( 'THREE.Path: .fromPoints() has been renamed to .setFromPoints().' );
-		this.setFromPoints( points );
+		return this.setFromPoints( points );
 
 	}
 

src/extras/core/Path.d.ts

@@ -28,11 +28,11 @@ export class Path extends CurvePath<Vector2> {
 	/**
 	 * @deprecated Use {@link Path#setFromPoints .setFromPoints()} instead.
 	 */
-	fromPoints( vectors: Vector2[] ): void;
-	setFromPoints( vectors: Vector2[] ): void;
-	moveTo( x: number, y: number ): void;
-	lineTo( x: number, y: number ): void;
-	quadraticCurveTo( aCPx: number, aCPy: number, aX: number, aY: number ): void;
+	fromPoints( vectors: Vector2[] ): this;
+	setFromPoints( vectors: Vector2[] ): this;
+	moveTo( x: number, y: number ): this;
+	lineTo( x: number, y: number ): this;
+	quadraticCurveTo( aCPx: number, aCPy: number, aX: number, aY: number ): this;
 	bezierCurveTo(
 		aCP1x: number,
 		aCP1y: number,
@@ -40,8 +40,8 @@ export class Path extends CurvePath<Vector2> {
 		aCP2y: number,
 		aX: number,
 		aY: number
-	): void;
-	splineThru( pts: Vector2[] ): void;
+	): this;
+	splineThru( pts: Vector2[] ): this;
 	arc(
 		aX: number,
 		aY: number,
@@ -49,7 +49,7 @@ export class Path extends CurvePath<Vector2> {
 		aStartAngle: number,
 		aEndAngle: number,
 		aClockwise: boolean
-	): void;
+	): this;
 	absarc(
 		aX: number,
 		aY: number,
@@ -57,7 +57,7 @@ export class Path extends CurvePath<Vector2> {
 		aStartAngle: number,
 		aEndAngle: number,
 		aClockwise: boolean
-	): void;
+	): this;
 	ellipse(
 		aX: number,
 		aY: number,
@@ -67,7 +67,7 @@ export class Path extends CurvePath<Vector2> {
 		aEndAngle: number,
 		aClockwise: boolean,
 		aRotation: number
-	): void;
+	): this;
 	absellipse(
 		aX: number,
 		aY: number,
@@ -77,6 +77,6 @@ export class Path extends CurvePath<Vector2> {
 		aEndAngle: number,
 		aClockwise: boolean,
 		aRotation: number
-	): void;
+	): this;
 
 }

src/extras/core/Path.js

@@ -41,12 +41,16 @@ Path.prototype = Object.assign( Object.create( CurvePath.prototype ), {
 
 		}
 
+		return this;
+
 	},
 
 	moveTo: function ( x, y ) {
 
 		this.currentPoint.set( x, y ); // TODO consider referencing vectors instead of copying?
 
+		return this;
+
 	},
 
 	lineTo: function ( x, y ) {
@@ -56,6 +60,8 @@ Path.prototype = Object.assign( Object.create( CurvePath.prototype ), {
 
 		this.currentPoint.set( x, y );
 
+		return this;
+
 	},
 
 	quadraticCurveTo: function ( aCPx, aCPy, aX, aY ) {
@@ -70,6 +76,8 @@ Path.prototype = Object.assign( Object.create( CurvePath.prototype ), {
 
 		this.currentPoint.set( aX, aY );
 
+		return this;
+
 	},
 
 	bezierCurveTo: function ( aCP1x, aCP1y, aCP2x, aCP2y, aX, aY ) {
@@ -85,6 +93,8 @@ Path.prototype = Object.assign( Object.create( CurvePath.prototype ), {
 
 		this.currentPoint.set( aX, aY );
 
+		return this;
+
 	},
 
 	splineThru: function ( pts /*Array of Vector*/ ) {
@@ -96,6 +106,8 @@ Path.prototype = Object.assign( Object.create( CurvePath.prototype ), {
 
 		this.currentPoint.copy( pts[ pts.length - 1 ] );
 
+		return this;
+
 	},
 
 	arc: function ( aX, aY, aRadius, aStartAngle, aEndAngle, aClockwise ) {
@@ -106,12 +118,16 @@ Path.prototype = Object.assign( Object.create( CurvePath.prototype ), {
 		this.absarc( aX + x0, aY + y0, aRadius,
 			aStartAngle, aEndAngle, aClockwise );
 
+		return this;
+
 	},
 
 	absarc: function ( aX, aY, aRadius, aStartAngle, aEndAngle, aClockwise ) {
 
 		this.absellipse( aX, aY, aRadius, aRadius, aStartAngle, aEndAngle, aClockwise );
 
+		return this;
+
 	},
 
 	ellipse: function ( aX, aY, xRadius, yRadius, aStartAngle, aEndAngle, aClockwise, aRotation ) {
@@ -121,6 +137,8 @@ Path.prototype = Object.assign( Object.create( CurvePath.prototype ), {
 
 		this.absellipse( aX + x0, aY + y0, xRadius, yRadius, aStartAngle, aEndAngle, aClockwise, aRotation );
 
+		return this;
+
 	},
 
 	absellipse: function ( aX, aY, xRadius, yRadius, aStartAngle, aEndAngle, aClockwise, aRotation ) {
@@ -145,6 +163,8 @@ Path.prototype = Object.assign( Object.create( CurvePath.prototype ), {
 		var lastPoint = curve.getPoint( 1 );
 		this.currentPoint.copy( lastPoint );
 
+		return this;
+
 	},
 
 	copy: function ( source ) {