JSDoc: Namespace: utils

A bunch of utility functions used throughout the library.

Source:

core/SPE.utils.js, line 6

Members

(static) types :String

A map of types used by `SPE.utils.ensureTypedArg` and `SPE.utils.ensureArrayTypedArg` to compare types against.

Type:

String

Properties:

Name	Type	Description
`BOOLEAN`	String	Boolean type.
`STRING`	String	String type.
`NUMBER`	String	Number type.
`OBJECT`	String	Object type.

Source:

core/SPE.utils.js, line 13

Methods

(static) arrayValuesAreEqual(array) → {Boolean}

Check if all items in an array are equal. Uses strict equality.

Parameters:

Name	Type	Description
`array`	Array	The array of values to check equality of.

Source:

core/SPE.utils.js, line 369

Returns:

Whether the array's values are all equal or not.

Type: Boolean

(static) clamp(value, min, max) → {Number}

Clamp a number to between the given min and max values.

Parameters:

Name	Type	Description
`value`	Number	The number to clamp.
`min`	Number	The minimum value.
`max`	Number	The maximum value.

Source:

core/SPE.utils.js, line 230

Returns:

The clamped number.

Type: Number

(static) ensureArrayInstanceOf(arg, instance, defaultValue) → {Object}

Given an array of values, ensure the instances of all items in the array matches the given instance constructor falling back to a default value if the check fails. If given value isn't an Array, delegates to `SPE.utils.ensureInstanceOf`.

Parameters:

Name	Type	Description
`arg`	Array \| Object	The value to perform the instanceof check on.
`instance`	function	The constructor of the instance to check against.
`defaultValue`	Object	A default fallback value if instance check fails

Source:

core/SPE.utils.js, line 124

Returns:

The given value if type check passes, or the default value if it fails.

Type: Object

(static) ensureArrayTypedArg(arg, type, defaultValue) → {boolean|string|number|object}

Given an array of values, a type, and a default value, ensure the given array's contents ALL adhere to the provided type, returning the default value if type check fails. If the given value to check isn't an Array, delegates to SPE.utils.ensureTypedArg.

Parameters:

Name	Type	Description
`arg`	Array \| boolean \| string \| number \| object	The array of values to check type of.
`type`	String	The type that should be adhered to.
`defaultValue`	boolean \| string \| number \| object	A default fallback value.

Source:

core/SPE.utils.js, line 72

Returns:

The given value if type check passes, or the default value if it fails.

Type: boolean | string | number | object

(static) ensureInstanceOf(arg, instance, defaultValue) → {Object}

Ensures the given value is an instance of a constructor function.

Parameters:

Name	Type	Description
`arg`	Object	The value to check instance of.
`instance`	function	The constructor of the instance to check against.
`defaultValue`	Object	A default fallback value if instance check fails

Source:

core/SPE.utils.js, line 101

Returns:

The given value if type check passes, or the default value if it fails.

Type: Object

(static) ensureTypedArg(arg, type, defaultValue) → {boolean|string|number|object}

Given a value, a type, and a default value to fallback to, ensure the given argument adheres to the type requesting, returning the default value if type check is false.

Parameters:

Name	Type	Description
`arg`	boolean \| string \| number \| object	The value to perform a type-check on.
`type`	String	The type the `arg` argument should adhere to.
`defaultValue`	boolean \| string \| number \| object	A default value to fallback on if the type check fails.

Source:

core/SPE.utils.js, line 49

Returns:

The given value if type check passes, or the default value if it fails.

Type: boolean | string | number | object

(static) ensureValueOverLifetimeCompliance(property, minLength, maxLength)

Ensures that any "value-over-lifetime" properties of an emitter are of the correct length (as dictated by `SPE.valueOverLifetimeLength`). Delegates to `SPE.utils.interpolateArray` for array resizing. If properties aren't arrays, then property values are put into one.

Parameters:

Name	Type	Description
`property`	Object	The property of an SPE.Emitter instance to check compliance of.
`minLength`	Number	The minimum length of the array to create.
`maxLength`	Number	The maximum length of the array to create.

Source:

core/SPE.utils.js, line 157

(static) interpolateArray(srcArray, newLength) → {Array}

Performs linear interpolation (lerp) on an array. For example, lerping [1, 10], with a `newLength` of 10 will produce [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]. Delegates to `SPE.utils.lerpTypeAgnostic` to perform the actual interpolation.

Parameters:

Name	Type	Description
`srcArray`	Array	The array to lerp.
`newLength`	Number	The length the array should be interpolated to.

Source:

core/SPE.utils.js, line 197

Returns:

The interpolated array.

Type: Array

(static) lerp(start, end, delta) → {Number}

Perform a linear interpolation operation on two numbers.

Parameters:

Name	Type	Description
`start`	Number	The start value.
`end`	Number	The end value.
`delta`	Number	The position to interpolate to.

Source:

core/SPE.utils.js, line 329

Returns:

The result of the lerp operation.

Type: Number

(static) lerpTypeAgnostic(start, end, delta) → {number|object|undefined}

Linearly interpolates two values of various types. The given values must be of the same type for the interpolation to work.

Parameters:

Name	Type	Description
`start`	number \| Object	The start value of the lerp.
`end`	number \| object	The end value of the lerp.
`delta`	Number	The delta posiiton of the lerp operation. Ideally between 0 and 1 (inclusive).

Source:

core/SPE.utils.js, line 280

Returns:

The result of the operation. Result will be undefined if the start and end arguments aren't a supported type, or if their types do not match.

Type: number | object | undefined

(static) randomColor(attribute, index, base, spread)

Given an SPE.Shader attribute instance, and various other settings, assign Color values to the attribute.

Parameters:

Name	Type	Description
`attribute`	Object	The instance of SPE.ShaderAttribute to save the result to.
`index`	Number	The offset in the attribute's TypedArray to save the result from.
`base`	Object	THREE.Color instance describing the start color.
`spread`	Object	THREE.Vector3 instance describing the random variance to apply to the start color.

Source:

core/SPE.utils.js, line 454

(static) randomFloat(base, spread) → {Number}

Given a start value and a spread value, create and return a random number.

Parameters:

Name	Type	Description
`base`	Number	The start value.
`spread`	Number	The size of the random variance to apply.

Source:

core/SPE.utils.js, line 409

Returns:

A randomised number.

Type: Number

(static) randomVector3(attribute, index, base, spread, spreadClamp)

Given an SPE.ShaderAttribute instance, and various other settings, assign values to the attribute's array in a `vec3` format.

Parameters:

Name	Type	Description
`attribute`	Object	The instance of SPE.ShaderAttribute to save the result to.
`index`	Number	The offset in the attribute's TypedArray to save the result from.
`base`	Object	THREE.Vector3 instance describing the start value.
`spread`	Object	THREE.Vector3 instance describing the random variance to apply to the start value.
`spreadClamp`	Object	THREE.Vector3 instance describing the multiples to clamp the randomness to.

Source:

core/SPE.utils.js, line 426

(static) randomVector3OnDisc(attribute, index, base, radius, radiusSpread, radiusScale, radiusSpreadClamp)

Assigns a random vector 3 value to an SPE.ShaderAttribute instance, projecting the given values onto a 2d-disc.

Parameters:

Name	Type	Description
`attribute`	Object	The instance of SPE.ShaderAttribute to save the result to.
`index`	Number	The offset in the attribute's TypedArray to save the result from.
`base`	Object	THREE.Vector3 instance describing the origin of the transform.
`radius`	Number	The radius of the sphere to project onto.
`radiusSpread`	Number	The amount of randomness to apply to the projection result
`radiusScale`	Object	THREE.Vector3 instance describing the scale of each axis of the disc. The z-component is ignored.
`radiusSpreadClamp`	Number	What numeric multiple the projected value should be clamped to.

Source:

core/SPE.utils.js, line 577

(static) randomVector3OnSphere(attribute, index, base, radius, radiusSpread, radiusScale, radiusSpreadClamp)

Assigns a random vector 3 value to an SPE.ShaderAttribute instance, projecting the given values onto a sphere.

Parameters:

Name	Type	Description
`attribute`	Object	The instance of SPE.ShaderAttribute to save the result to.
`index`	Number	The offset in the attribute's TypedArray to save the result from.
`base`	Object	THREE.Vector3 instance describing the origin of the transform.
`radius`	Number	The radius of the sphere to project onto.
`radiusSpread`	Number	The amount of randomness to apply to the projection result
`radiusScale`	Object	THREE.Vector3 instance describing the scale of each axis of the sphere.
`radiusSpreadClamp`	Number	What numeric multiple the projected value should be clamped to.

Source:

core/SPE.utils.js, line 519

(static) roundToNearestMultiple(n, multiple) → {Number}

Rounds a number to a nearest multiple.

Parameters:

Name	Type	Description
`n`	Number	The number to round.
`multiple`	Number	The multiple to round to.

Source:

core/SPE.utils.js, line 341

Returns:

The result of the round operation.

Type: Number

(static) zeroToEpsilon(value, randomise) → {Number}

If the given value is less than the epsilon value, then return a randomised epsilon value if specified, or just the epsilon value if not. Works for negative numbers as well as positive.

Parameters:

Name	Type	Description
`value`	Number	The value to perform the operation on.
`randomise`	Boolean	Whether the value should be randomised.

Source:

core/SPE.utils.js, line 245

Returns:

The result of the operation.

Type: Number