Class: Vec3

Vec3

Three-element vector of 32-bit floats. May reflect an ESSL vec3 uniform variable. Low-performance convenience methods reproduce operator behaviour.
operatormethod
+=add
-=sub
*=mul
/=div
+plus
-minus
*times
/over
·dot
×cross

a = b + c can be computed as var a = b.plus(c), when a does not yet exist, and performance does not matter. It is not required that c is a Vec3: it can be a vector of different length, an object literal, or its coordinates given as separate arguments.
a.set(b).add(c) is about three times faster. Variable a needs to exist, and be a Vec3. Neither b nor c are required to be Vec3s: they can be vectors of different length, object literals, or its coordinates given as separate arguments.
If a, b and c are Vec3 instances, a.setSum(b, c) can be used for optimum performance. It is seven times faster than a.set(b).add(c), or twenty times faster than a = b.plus(c).
It is recommended to use optimized methods for time-critical per-frame tasks, while programmer-friendly interfaces are useful for one-time initializations, e.g. when constructing a scene.

new Vec3( [u] [, v] [, s])

Without parameters, initializes the vector to (0, 0, 0).
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
0 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
0 Ignored if u.y is defined. Otherwise, the value for coordinate y.
s Number <optional>
0 Ignored if u.z is defined. Otherwise, the value for coordinate z.

Members


storage :Float32Array

3-element typed array for coordinate storage.
Type:
  • Float32Array

x :Number

Alias for storage[0];
Type:
  • Number

y :Number

Alias for storage[1];
Type:
  • Number

z :Number

Alias for storage[2];
Type:
  • Number

Methods


add( [u] [, v] [, s])

Simulates operator +=. Adds another vector to this vector, overwriting the contents with the result.
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
0 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
0 Ignored if u.y is defined. Otherwise, the value for coordinate y.
s Number <optional>
0 Ignored if u.z is defined. Otherwise, the value for coordinate z.
Returns:
this
Type
Vec3

addScaled(dt [, u] [, v] [, s])

Simulates += dt *. Adds another vector, scaled by `dt`, to this vector, overwriting the contents with the result.
Parameters:
Name Type Argument Default Description
dt Number Scaling factor.
u Vec3 | Object | Number <optional>
0 Any object (property x), or a numerical value.
v Number <optional>
0 Ignored if u.y is defined. Otherwise, the value for coordinate y.
s Number <optional>
0 Ignored if u.z is defined. Otherwise, the value for coordinate z.
Returns:
this
Type
Vec3

clamp( [minVal] [, maxVal])

Constrains the value of this vector to lie between two further values, elementwise, overwriting the contents with the result.
Parameters:
Name Type Argument Default Description
minVal Vec3 | Vec2 | Object | Number <optional>
0 Specifies the lower end of the range into which to constrain the elements. If a scalar is given, it applies to all channels.
maxVal Vec3 | Vec2 | Object | Number <optional>
1 Specifies the upper end of the range into which to constrain the elements. If a scalar is given, it applies to all channels.
Returns:
this
Type
Vec3

clone()

Creates a copy.
Returns:
A new instance with identical contents.
Type
Vec3

commit(gl, uniformLocation)

Sets the value of the vector to a WebGL vec3 uniform variable.
Parameters:
Name Type Description
gl WebGLRenderingContext rendering context
uniformLocation WebGLUniformLocation location of the uniform variable in the currently used WebGL program

cross( [u] [, v] [, s])

Simulates operator %times;. Computes the cross product of the vectors, returning the result in a new instance.
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
0 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
0 Ignored if u.y is defined. Otherwise, the value for coordinate y.
s Number <optional>
0 Ignored if u.z is defined. Otherwise, the value for coordinate z.
Returns:
the cross product
Type
Vec3

direction()

Scales the vector by the inverse of its length, and returns the result in a new instance.
Returns:
A unit length vector with the same direction as this.
Type
Vec3

div( [u] [, v] [, s])

Simulates operator /=. Divides, elementwise, this vector with another vector, or scalar, overwriting the contents with the result.
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
1 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
1 Ignored if u.y is defined. Otherwise, the value for coordinate y. Defaults to the value of parameter u, if it is a number.
s Number <optional>
1 Ignored if u.z is defined. Otherwise, the value for coordinate z. Defaults to the value of parameter u, if it is a number.
Returns:
this
Type
Vec3

dot( [u] [, v] [, s])

Computes the dot product with another vector.
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
0 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
0 Ignored if u.y is defined. Otherwise, the value for coordinate y.
s Number <optional>
0 Ignored if u.z is defined. Otherwise, the value for coordinate z.
Returns:
Type
Number

length()

Computes the vector length.
Returns:
Type
Number

length2()

Computes the length squared.
Returns:
x*x + y*y + z*z + w*w
Type
Number

minus( [u] [, v] [, s])

Simulates operator -. Subtracts the parameter vector from this vector, and returns the result in a new instance.
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
0 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
0 Ignored if u.y is defined. Otherwise, the value for coordinate y.
s Number <optional>
0 Ignored if u.z is defined. Otherwise, the value for coordinate z.
Returns:
the difference of the two vectors
Type
Vec3

mul( [u] [, v] [, s])

Simulates operator *=. Multiplies this vector with another vector elementwise, or scalar, overwriting the contents with the result.
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
1 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
1 Ignored if u.y is defined. Otherwise, the value for coordinate y. Defaults to the value of parameter u, if it is a number.
s Number <optional>
1 Ignored if u.z is defined. Otherwise, the value for coordinate z. Defaults to the value of parameter u, if it is a number.
Returns:
this
Type
Vec3

normalize()

Scales the vector by the inverse of its length, overwriting the contents with the result.
Returns:
this
Type
Vec3

over( [u] [, v] [, s])

Simulates operator /. Divides, elementwise, this vector with another vector, or scalar, and returns the result in a new instance.
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
1 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
1 Ignored if u.y is defined. Otherwise, the value for coordinate y. Defaults to the value of parameter u, if it is a number.
s Number <optional>
1 Ignored if u.z is defined. Otherwise, the value for coordinate z. Defaults to the value of parameter u, if it is a number.
Returns:
the elementwise product of the two vectors
Type
Vec3

plus( [u] [, v] [, s])

Simulates operator +. Adds this vector and the parameter vector, and returns the result in a new instance.
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
0 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
0 Ignored if u.y is defined. Otherwise, the value for coordinate y.
s Number <optional>
0 Ignored if u.z is defined. Otherwise, the value for coordinate z.
Returns:
the sum of the two vectors
Type
Vec3

set( [u] [, v] [, s])

Simulates operator =. Sets the coordinates from another vector, or number values. Without parameters, sets (0, 0, 0, 1).
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
0 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
0 Ignored if u.y is defined. Otherwise, the value for coordinate y.
s Number <optional>
0 Ignored if u.z is defined. Otherwise, the value for coordinate z.
Returns:
this
Type
Vec3

setClamped(b [, minVal] [, maxVal])

Fast. Constrains a value to lie between two further values, elementwise, storing the result in this vector.
Parameters:
Name Type Argument Default Description
b Vec3 The value to constrain.
minVal Vec3 | Vec2 | Object | Number <optional>
0 Specifies the lower end of the range into which to constrain the elements. If a scalar is given, it applies to all channels.
maxVal Vec3 | Vec2 | Object | Number <optional>
1 Specifies the upper end of the range into which to constrain the elements. If a scalar is given, it applies to all channels.
Returns:
this
Type
Vec3

setDifference(b, c)

Fast. Subtracts the second argument vector from the first one, storing the result in this vector.
Parameters:
Name Type Description
b Vec3 Minuend.
c Vec3 Subtrahend.
Returns:
this
Type
Vec3

setNormalized(b)

Scales the argmument vector by the inverse of its length, storing the result in this vector.
Parameters:
Name Type Description
b Vec3 The vector to normalize.
Returns:
this
Type
Vec3

setProduct(b, c)

Fast. Multiplies, elementwise, the two argument vectors, storing the result in this vector.
Parameters:
Name Type Description
b Vec3 Factor 1.
c Vec3 Factor 2.
Returns:
this
Type
Vec3

setQuotient(b, c)

Fast. Divides, elementwise, the two argument vectors, storing the result in this vector.
Parameters:
Name Type Description
b Vec3 Dividend.
c Vec3 Divisor.
Returns:
this
Type
Vec3

setRandom( [minVal] [, maxVal])

Fill the vector with random values that to lie between two further values, elementwise.
Parameters:
Name Type Argument Default Description
minVal Vec3 | Vec2 | Object | Number <optional>
0 Specifies the lower end of the random range. If a scalar is given, it applies to all channels.
maxVal Vec3 | Vec2 | Object | Number <optional>
1 Specifies the upper end of the random range. If a scalar is given, it applies to all channels.
Returns:
this
Type
Vec3

setScaled(a, s)

Fast. Scales the vector by a scalar.
Parameters:
Name Type Description
a Vec3 Vector to scale.
s Number Scale factor.
Returns:
this
Type
Vec3

setScaledByInverse(a, s)

Fast. Scales the vector by the reciprocal of scalar.
Parameters:
Name Type Description
a Vec3 Vector to scale.
s Number Scale factor inverse.
Returns:
this
Type
Vec3

setSum(b, c)

Fast. Adds the two argument vectors, storing the result in this vector.
Parameters:
Name Type Description
b Vec3 Term 1.
c Vec3 Term 2.
Returns:
this
Type
Vec3

setVectorProduct(b, c)

Fast. Computes the vector product (cross product) of the two argument vectors, storing the result in this vector.
Parameters:
Name Type Description
b Vec3 Left operand.
c Vec3 Right operand.
Returns:
this
Type
Vec3

setxyz0Transformed(v, m)

Multiplies the argument vector (considering it a row vector, augmented by 0 to a homogeneous direction vector) with the argument matrix, from the right. The contents of this are overwritten with the transformed vector with the result. See Vec3#xyz0times for a version creating a new vector instance.
Parameters:
Name Type Description
v Vec3 The vector to be transformed.
m Mat4 The 4x4 linear homogeneous transformation matrix using column-major representation.
Returns:
this
Type
Vec3

setxyz1Transformed(v, m)

Multiplies the argument vector (considering it a row vector, augmented by 1 to a homogeneous position vector) with the argument matrix, from the right. The contents of this are overwritten with the transformed vector with the result. See Vec3#xyz1times for a version creating a new vector instance.
Parameters:
Name Type Description
v Vec3 The vector to be transformed.
m Mat4 The 4x4 linear homogeneous transformation matrix using column-major representation.
Returns:
this
Type
Vec3

sub( [u] [, v] [, s])

Simulates operator -=. Subtracts another vector from this vector, overwriting the contents with the result.
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
0 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
0 Ignored if u.y is defined. Otherwise, the value for coordinate y.
s Number <optional>
0 Ignored if u.z is defined. Otherwise, the value for coordinate z.
Returns:
this
Type
Vec3

times( [u] [, v] [, s])

Simulates operator *. Multiplies this vector with another vector elementwise, or scalar, and returns the result in a new instance.
Parameters:
Name Type Argument Default Description
u Vec3 | Vec2 | Object | Number <optional>
1 Any object (properties x, y, z are interpreted as coordinates, if given), or a numerical value for coordinate x.
v Number <optional>
1 Ignored if u.y is defined. Otherwise, the value for coordinate y. Defaults to the value of parameter u, if it is a number.
s Number <optional>
1 Ignored if u.z is defined. Otherwise, the value for coordinate z. Defaults to the value of parameter u, if it is a number.
Returns:
the elementwise product of the two vectors
Type
Vec3

xyz0mul(m)

Multiplies the vector (considering it a row vector, augmented by a 0 to get a homogeneous direction vector) with a matrix, from the right. The contents of this are overwritten with the transformed vector with the result. See Vec3#xyz0times for a version creating a new vector instance.
Parameters:
Name Type Description
m Mat4 The 4x4 linear homogeneous transformation matrix using column-major representation.
Returns:
this
Type
Vec3

xyz0times(m)

Simulates operator *. Multiplies this vector, augmented with a 0 to a homogeneous direction vector, with a matrix from the right, and returns the result in a new instance.
Parameters:
Name Type Description
m Mat4 A 4x4 transformation matrix.
Returns:
the transformed vector
Type
Vec3

xyz1mul(m)

Multiplies the vector (considering it a row vector, augmented by a 1 to get a homogeneous position vector) with a matrix, from the right. The contents of this are overwritten with the transformed vector with the result. See Vec3#xyz1times for a version creating a new vector instance.
Parameters:
Name Type Description
m Mat4 The 4x4 linear homogeneous transformation matrix using column-major representation.
Returns:
this
Type
Vec3

xyz1times(m)

Simulates operator *. Multiplies this vector, augmented with a 1 to a homogeneous position vector, with a matrix from the right, and returns the result in a new instance.
Parameters:
Name Type Description
m Mat4 A 4x4 transformation matrix.
Returns:
the transformed vector
Type
Vec3

<static> random( [minVal] [, maxVal])

Return a new Vec3 with random values that to lie between two values, elementwise.
Parameters:
Name Type Argument Default Description
minVal Vec3 | Vec2 | Object | Number <optional>
0 Specifies the lower end of the random range. If a scalar is given, it applies to all channels.
maxVal Vec3 | Vec2 | Object | Number <optional>
1 Specifies the upper end of the random range. If a scalar is given, it applies to all channels.
Returns:
this
Type
Vec3