Vec3
3-dimensional vector.
const v = new pc.Vec3(1, 2, 3);
Summary
Static Properties
BACK | A constant vector set to [0, 0, 1].[read only] |
DOWN | A constant vector set to [0, -1, 0].[read only] |
FORWARD | A constant vector set to [0, 0, -1].[read only] |
LEFT | A constant vector set to [-1, 0, 0].[read only] |
ONE | A constant vector set to [1, 1, 1].[read only] |
RIGHT | A constant vector set to [1, 0, 0].[read only] |
UP | A constant vector set to [0, 1, 0].[read only] |
ZERO | A constant vector set to [0, 0, 0].[read only] |
Properties
x | The first component of the vector. |
y | The second component of the vector. |
z | The third component of the vector. |
Methods
add | Adds a 3-dimensional vector to another in place. |
add2 | Adds two 3-dimensional vectors together and returns the result. |
addScalar | Adds a number to each element of a vector. |
addScaled | Adds a 3-dimensional vector scaled by scalar value. |
ceil | Each element is rounded up to the next largest integer. |
clone | Returns an identical copy of the specified 3-dimensional vector. |
copy | Copies the contents of a source 3-dimensional vector to a destination 3-dimensional vector. |
cross | Returns the result of a cross product operation performed on the two specified 3-dimensional vectors. |
distance | Returns the distance between the two specified 3-dimensional vectors. |
div | Divides a 3-dimensional vector by another in place. |
div2 | Divides one 3-dimensional vector by another and writes the result to the specified vector. |
divScalar | Divides each element of a vector by a number. |
dot | Returns the result of a dot product operation performed on the two specified 3-dimensional vectors. |
equals | Reports whether two vectors are equal. |
equalsApprox | Reports whether two vectors are equal using an absolute error tolerance. |
floor | Each element is set to the largest integer less than or equal to its value. |
length | Returns the magnitude of the specified 3-dimensional vector. |
lengthSq | Returns the magnitude squared of the specified 3-dimensional vector. |
lerp | Returns the result of a linear interpolation between two specified 3-dimensional vectors. |
max | Each element is assigned a value from rhs parameter if it is larger. |
min | Each element is assigned a value from rhs parameter if it is smaller. |
mul | Multiplies a 3-dimensional vector to another in place. |
mul2 | Returns the result of multiplying the specified 3-dimensional vectors together. |
mulScalar | Multiplies each element of a vector by a number. |
normalize | Returns this 3-dimensional vector converted to a unit vector in place. |
project | Projects this 3-dimensional vector onto the specified vector. |
round | Each element is rounded up or down to the nearest integer. |
set | Sets the specified 3-dimensional vector to the supplied numerical values. |
sub | Subtracts a 3-dimensional vector from another in place. |
sub2 | Subtracts two 3-dimensional vectors from one another and returns the result. |
subScalar | Subtracts a number from each element of a vector. |
toString | Converts the vector to string form. |
Details
Static Properties
BACK | A constant vector set to [0, 0, 1]. [read only] |
DOWN | A constant vector set to [0, -1, 0]. [read only] |
FORWARD | A constant vector set to [0, 0, -1]. [read only] |
LEFT | A constant vector set to [-1, 0, 0]. [read only] |
ONE | A constant vector set to [1, 1, 1]. [read only] |
RIGHT | A constant vector set to [1, 0, 0]. [read only] |
UP | A constant vector set to [0, 1, 0]. [read only] |
ZERO | A constant vector set to [0, 0, 0]. [read only] |
Constructor
Vec3([x], [y], [z])
Creates a new Vec3 object.
const v = new pc.Vec3(1, 2, 3);
Parameters
x | number, number[] | The x value. Defaults to 0. If x is an array of length 3, the array will be used to populate all components. |
y | number | The y value. Defaults to 0. |
z | number | The z value. Defaults to 0. |
Properties
Methods
add(rhs)
Adds a 3-dimensional vector to another in place.
const a = new pc.Vec3(10, 10, 10);
const b = new pc.Vec3(20, 20, 20);
a.add(b);
// Outputs [30, 30, 30]
console.log("The result of the addition is: " + a.toString());
Parameters
rhs | Vec3 | The vector to add to the specified vector. |
Returns
Vec3Self for chaining.
add2(lhs, rhs)
Adds two 3-dimensional vectors together and returns the result.
const a = new pc.Vec3(10, 10, 10);
const b = new pc.Vec3(20, 20, 20);
const r = new pc.Vec3();
r.add2(a, b);
// Outputs [30, 30, 30]
console.log("The result of the addition is: " + r.toString());
Parameters
lhs | Vec3 | The first vector operand for the addition. |
rhs | Vec3 | The second vector operand for the addition. |
Returns
Vec3Self for chaining.
addScalar(scalar)
Adds a number to each element of a vector.
const vec = new pc.Vec3(3, 4, 5);
vec.addScalar(2);
// Outputs [5, 6, 7]
console.log("The result of the addition is: " + vec.toString());
Parameters
scalar | number | The number to add. |
Returns
Vec3Self for chaining.
addScaled(rhs, scalar)
Adds a 3-dimensional vector scaled by scalar value. Does not modify the vector being added.
const vec = new pc.Vec3(1, 2, 3);
vec.addScaled(pc.Vec3.UP, 2);
// Outputs [1, 4, 3]
console.log("The result of the addition is: " + vec.toString());
Parameters
rhs | Vec3 | The vector to add to the specified vector. |
scalar | number | The number to multiply the added vector with. |
Returns
Vec3Self for chaining.
ceil([src])
Each element is rounded up to the next largest integer.
Parameters
src | Vec3 | The vector to ceil. If not set, the operation is done in place. |
Returns
Vec3Self for chaining.
clone()
Returns an identical copy of the specified 3-dimensional vector.
const v = new pc.Vec3(10, 20, 30);
const vclone = v.clone();
console.log("The result of the cloning is: " + vclone.toString());
Returns
thisA 3-dimensional vector containing the result of the cloning.
copy(rhs)
Copies the contents of a source 3-dimensional vector to a destination 3-dimensional vector.
const src = new pc.Vec3(10, 20, 30);
const dst = new pc.Vec3();
dst.copy(src);
console.log("The two vectors are " + (dst.equals(src) ? "equal" : "different"));
Parameters
rhs | Vec3 | A vector to copy to the specified vector. |
Returns
Vec3Self for chaining.
cross(lhs, rhs)
Returns the result of a cross product operation performed on the two specified 3-dimensional vectors.
const back = new pc.Vec3().cross(pc.Vec3.RIGHT, pc.Vec3.UP);
// Prints the Z axis (i.e. [0, 0, 1])
console.log("The result of the cross product is: " + back.toString());
Parameters
lhs | Vec3 | The first 3-dimensional vector operand of the cross product. |
rhs | Vec3 | The second 3-dimensional vector operand of the cross product. |
Returns
Vec3Self for chaining.
distance(rhs)
Returns the distance between the two specified 3-dimensional vectors.
const v1 = new pc.Vec3(5, 10, 20);
const v2 = new pc.Vec3(10, 20, 40);
const d = v1.distance(v2);
console.log("The distance between v1 and v2 is: " + d);
Parameters
rhs | Vec3 | The second 3-dimensional vector to test. |
Returns
numberThe distance between the two vectors.
div(rhs)
Divides a 3-dimensional vector by another in place.
const a = new pc.Vec3(4, 9, 16);
const b = new pc.Vec3(2, 3, 4);
a.div(b);
// Outputs [2, 3, 4]
console.log("The result of the division is: " + a.toString());
Parameters
rhs | Vec3 | The vector to divide the specified vector by. |
Returns
Vec3Self for chaining.
div2(lhs, rhs)
Divides one 3-dimensional vector by another and writes the result to the specified vector.
const a = new pc.Vec3(4, 9, 16);
const b = new pc.Vec3(2, 3, 4);
const r = new pc.Vec3();
r.div2(a, b);
// Outputs [2, 3, 4]
console.log("The result of the division is: " + r.toString());
Parameters
lhs | Vec3 | The dividend vector (the vector being divided). |
rhs | Vec3 | The divisor vector (the vector dividing the dividend). |
Returns
Vec3Self for chaining.
divScalar(scalar)
Divides each element of a vector by a number.
const vec = new pc.Vec3(3, 6, 9);
vec.divScalar(3);
// Outputs [1, 2, 3]
console.log("The result of the division is: " + vec.toString());
Parameters
scalar | number | The number to divide by. |
Returns
Vec3Self for chaining.
dot(rhs)
Returns the result of a dot product operation performed on the two specified 3-dimensional vectors.
const v1 = new pc.Vec3(5, 10, 20);
const v2 = new pc.Vec3(10, 20, 40);
const v1dotv2 = v1.dot(v2);
console.log("The result of the dot product is: " + v1dotv2);
Parameters
rhs | Vec3 | The second 3-dimensional vector operand of the dot product. |
Returns
numberThe result of the dot product operation.
equals(rhs)
Reports whether two vectors are equal.
const a = new pc.Vec3(1, 2, 3);
const b = new pc.Vec3(4, 5, 6);
console.log("The two vectors are " + (a.equals(b) ? "equal" : "different"));
Parameters
rhs | Vec3 | The vector to compare to the specified vector. |
Returns
booleanTrue if the vectors are equal and false otherwise.
equalsApprox(rhs, [epsilon])
Reports whether two vectors are equal using an absolute error tolerance.
const a = new pc.Vec3();
const b = new pc.Vec3();
console.log("The two vectors are approximately " + (a.equalsApprox(b, 1e-9) ? "equal" : "different"));
Parameters
rhs | Vec3 | The vector to be compared against. |
epsilon | number | The maximum difference between each component of the two vectors. Defaults to 1e-6. |
Returns
booleanTrue if the vectors are equal and false otherwise.
floor([src])
Each element is set to the largest integer less than or equal to its value.
Parameters
src | Vec3 | The vector to floor. If not set, the operation is done in place. |
Returns
Vec3Self for chaining.
length()
Returns the magnitude of the specified 3-dimensional vector.
const vec = new pc.Vec3(3, 4, 0);
const len = vec.length();
// Outputs 5
console.log("The length of the vector is: " + len);
Returns
numberThe magnitude of the specified 3-dimensional vector.
lengthSq()
Returns the magnitude squared of the specified 3-dimensional vector.
const vec = new pc.Vec3(3, 4, 0);
const len = vec.lengthSq();
// Outputs 25
console.log("The length squared of the vector is: " + len);
Returns
numberThe magnitude of the specified 3-dimensional vector.
lerp(lhs, rhs, alpha)
Returns the result of a linear interpolation between two specified 3-dimensional vectors.
const a = new pc.Vec3(0, 0, 0);
const b = new pc.Vec3(10, 10, 10);
const r = new pc.Vec3();
r.lerp(a, b, 0); // r is equal to a
r.lerp(a, b, 0.5); // r is 5, 5, 5
r.lerp(a, b, 1); // r is equal to b
Parameters
lhs | Vec3 | The 3-dimensional to interpolate from. |
rhs | Vec3 | The 3-dimensional to interpolate to. |
alpha | number | The value controlling the point of interpolation. Between 0 and 1, the linear interpolant will occur on a straight line between lhs and rhs. Outside of this range, the linear interpolant will occur on a ray extrapolated from this line. |
Returns
Vec3Self for chaining.
max(rhs)
Each element is assigned a value from rhs parameter if it is larger.
Parameters
rhs | Vec3 | The 3-dimensional vector used as the source of elements to compare to. |
Returns
Vec3Self for chaining.
min(rhs)
Each element is assigned a value from rhs parameter if it is smaller.
Parameters
rhs | Vec3 | The 3-dimensional vector used as the source of elements to compare to. |
Returns
Vec3Self for chaining.
mul(rhs)
Multiplies a 3-dimensional vector to another in place.
const a = new pc.Vec3(2, 3, 4);
const b = new pc.Vec3(4, 5, 6);
a.mul(b);
// Outputs 8, 15, 24
console.log("The result of the multiplication is: " + a.toString());
Parameters
rhs | Vec3 | The 3-dimensional vector used as the second multiplicand of the operation. |
Returns
Vec3Self for chaining.
mul2(lhs, rhs)
Returns the result of multiplying the specified 3-dimensional vectors together.
const a = new pc.Vec3(2, 3, 4);
const b = new pc.Vec3(4, 5, 6);
const r = new pc.Vec3();
r.mul2(a, b);
// Outputs 8, 15, 24
console.log("The result of the multiplication is: " + r.toString());
Parameters
lhs | Vec3 | The 3-dimensional vector used as the first multiplicand of the operation. |
rhs | Vec3 | The 3-dimensional vector used as the second multiplicand of the operation. |
Returns
Vec3Self for chaining.
mulScalar(scalar)
Multiplies each element of a vector by a number.
const vec = new pc.Vec3(3, 6, 9);
vec.mulScalar(3);
// Outputs [9, 18, 27]
console.log("The result of the multiplication is: " + vec.toString());
Parameters
scalar | number | The number to multiply by. |
Returns
Vec3Self for chaining.
normalize([src])
Returns this 3-dimensional vector converted to a unit vector in place. If the vector has a length of zero, the vector's elements will be set to zero.
const v = new pc.Vec3(25, 0, 0);
v.normalize();
// Outputs 1, 0, 0
console.log("The result of the vector normalization is: " + v.toString());
Parameters
src | Vec3 | The vector to normalize. If not set, the operation is done in place. |
Returns
Vec3Self for chaining.
project(rhs)
Projects this 3-dimensional vector onto the specified vector.
const v = new pc.Vec3(5, 5, 5);
const normal = new pc.Vec3(1, 0, 0);
v.project(normal);
// Outputs 5, 0, 0
console.log("The result of the vector projection is: " + v.toString());
Parameters
rhs | Vec3 | The vector onto which the original vector will be projected on. |
Returns
Vec3Self for chaining.
round([src])
Each element is rounded up or down to the nearest integer.
Parameters
src | Vec3 | The vector to round. If not set, the operation is done in place. |
Returns
Vec3Self for chaining.
set(x, y, z)
Sets the specified 3-dimensional vector to the supplied numerical values.
const v = new pc.Vec3();
v.set(5, 10, 20);
// Outputs 5, 10, 20
console.log("The result of the vector set is: " + v.toString());
Parameters
x | number | The value to set on the first component of the vector. |
y | number | The value to set on the second component of the vector. |
z | number | The value to set on the third component of the vector. |
Returns
Vec3Self for chaining.
sub(rhs)
Subtracts a 3-dimensional vector from another in place.
const a = new pc.Vec3(10, 10, 10);
const b = new pc.Vec3(20, 20, 20);
a.sub(b);
// Outputs [-10, -10, -10]
console.log("The result of the subtraction is: " + a.toString());
Parameters
rhs | Vec3 | The vector to subtract from the specified vector. |
Returns
Vec3Self for chaining.
sub2(lhs, rhs)
Subtracts two 3-dimensional vectors from one another and returns the result.
const a = new pc.Vec3(10, 10, 10);
const b = new pc.Vec3(20, 20, 20);
const r = new pc.Vec3();
r.sub2(a, b);
// Outputs [-10, -10, -10]
console.log("The result of the subtraction is: " + r.toString());
Parameters
lhs | Vec3 | The first vector operand for the subtraction. |
rhs | Vec3 | The second vector operand for the subtraction. |
Returns
Vec3Self for chaining.