Merge pull request #21102 from marcofugaro/damp

Add MathUtils.damp() for framerate independent lerping

docs/api/en/math/MathUtils.html

@@ -53,6 +53,17 @@ <h3>[method:Float lerp]( [param:Float x], [param:Float y], [param:Float t] )</h3
 		and [page:Float t] = 1 will return [page:Float y].
 		</p>
 
+		<h3>[method:Float damp]( [param:Float x], [param:Float y], [param:Float lambda], [param:Float dt] )</h3>
+		<p>
+		[page:Float x] - Current point. <br />
+		[page:Float y] - Target point. <br />
+		[page:Float lambda] - A higher lambda value will make the movement more sudden, and a lower value will make the movement more gradual. <br />
+		[page:Float dt] - Delta time in seconds.<br><br />
+
+		Smoothly interpolate a number from [page:Float x] toward [page:Float y] in a spring-like manner using the [page:Float dt] to maintain frame rate independent movement.
+		For details, see [link:http://www.rorydriscoll.com/2016/03/07/frame-rate-independent-damping-using-lerp/ Frame rate independent damping using lerp].
+		</p>
+
 		<h3>[method:Float mapLinear]( [param:Float x], [param:Float a1], [param:Float a2], [param:Float b1], [param:Float b2] )</h3>
 		<p>
 		[page:Float x] — Value to be mapped.<br />

docs/api/zh/math/MathUtils.html

@@ -50,6 +50,17 @@ <h3>[method:Float lerp]( [param:Float x], [param:Float y], [param:Float t] )</h3
 		如果 [page:Float t] = 1 将会返回 [page:Float y].
 		</p>
 
+		<h3>[method:Float damp]( [param:Float x], [param:Float y], [param:Float lambda], [param:Float dt] )</h3>
+		<p>
+		[page:Float x] - Current point. <br />
+		[page:Float y] - Target point. <br />
+		[page:Float lambda] - A higher lambda value will make the movement more sudden, and a lower value will make the movement more gradual. <br />
+		[page:Float dt] - Delta time in seconds.<br><br />
+
+		Smoothly interpolate a number from [page:Float x] toward [page:Float y] in a spring-like manner using the [page:Float dt] to maintain frame rate independent movement.
+		For details, see [link:http://www.rorydriscoll.com/2016/03/07/frame-rate-independent-damping-using-lerp/ Frame rate independent damping using lerp].
+		</p>
+
 		<h3>[method:Float mapLinear]( [param:Float x], [param:Float a1], [param:Float a2], [param:Float b1], [param:Float b2] )</h3>
 		<p>
 		[page:Float x] — 用于映射的值。<br />

src/math/MathUtils.d.ts

@@ -85,6 +85,18 @@ export namespace MathUtils {
 	 */
 	export function lerp( x: number, y: number, t: number ): number;
 
+	/**
+	 * Smoothly interpolate a number from x toward y in a spring-like
+	 * manner using the dt to maintain frame rate independent movement.
+	 *
+	 * @param x Current point.
+	 * @param y Target point.
+	 * @param lambda A higher lambda value will make the movement more sudden, and a lower value will make the movement more gradual.
+	 * @param dt Delta time in seconds.
+	 * @return {number}
+	 */
+	export function damp( x: number, y: number, lambda: number, dt: number ): number;
+
 	/**
 	 * Returns a value that alternates between 0 and length.
 	 *

src/math/MathUtils.js

@@ -62,6 +62,14 @@ const MathUtils = {
 
 	},
 
+	// http://www.rorydriscoll.com/2016/03/07/frame-rate-independent-damping-using-lerp/
+
+	damp: function ( x, y, lambda, dt ) {
+
+		return MathUtils.lerp( x, y, 1 - Math.exp( - lambda * dt ) );
+
+	},
+
 	// https://www.desmos.com/calculator/vcsjnyz7x4
 
 	pingpong: function ( x, length = 1 ) {

test/unit/src/math/MathUtils.tests.js

@@ -55,6 +55,13 @@ export default QUnit.module( 'Maths', () => {
 
 		} );
 
+		QUnit.test( "damp", ( assert ) => {
+
+			assert.strictEqual( MathUtils.damp( 1, 2, 0, 0.016 ), 1, "Value equal to lower boundary" );
+			assert.strictEqual( MathUtils.damp( 1, 2, 10, 0.016 ), 1.1478562110337887, "Value within range" );
+
+		} );
+
 		QUnit.test( "smoothstep", ( assert ) => {
 
 			assert.strictEqual( MathUtils.smoothstep( - 1, 0, 2 ), 0, "Value lower than minimum" );