Get Involved

Float3

A vector with three floating-point components x, y and z.

Header File

#include <ply-math/Vector.h>

Also included from <ply-math/Base.h>.

Data Members

 float x [code]
 float y [code]
 float z [code]

Constructors

  Float3::Float3() [code]

Constructs an uninitialized Float3.

  Float3::Float3(float t) [code]

Constructs a Float3 with all components set to t.

Float3 v = {1};
StdOut::text() << v;  // "{1, 1, 1}"
  Float3::Float3(float x, float y, float z) [code]

Constructs a Float3 from the given components.

Float3 v = {1, 0, 0};
  Float3::Float3(const Float2& v, float z) [code]

Constructs a Float3 from a Float2 and a third component.

Float2 a = {1, 2};
StdOut::text() << Float3{a, 0};  // "{1, 2, 0}"

Assignment Operator

void Float3::operator=(const Float3& arg) & [code]

Copy assignment. Declared with an lvalue ref-qualifier so that it's an error to assign to an rvalue.

a.normalized() = b;  // error

Arithmetic Operators

Float3 operator-(const Float3& a) [code]

Unary negation.

Float3 operator+(const Float3& a, const Float3& b) [code]
Float3 operator-(const Float3& a, const Float3& b) [code]
Float3 operator*(const Float3& a, const Float3& b) [code]
Float3 operator/(const Float3& a, const Float3& b) [code]

Returns a vector whose components are the result of applying the given operation to the corresponding components of a and b. Each component is acted on independently.

StdOut::text() << Float3{2, 3, 2} * Float3{4, 1, 2};  // "{8, 3, 4}"

If you specify a scalar value in place of a Float3, it will be promoted to a Float3 by replicating the value to each component.

StdOut::text() << Float3{2, 3, 2} * 2;  // "{4, 6, 4}"
StdOut::text() << 8 / Float3{2, 4, 1};  // "{4, 2, 8}"
void operator+=(Float3& a, const Float3& b) [code]
void operator-=(Float3& a, const Float3& b) [code]
void operator*=(Float3& a, const Float3& b) [code]
void operator/=(Float3& a, const Float3& b) [code]

In-place versions of the above operators.

Float3 v = {2, 3, 2};
v *= {4, 1, 2};
StdOut::text() << v;  // "{8, 3, 4}"

Comparison Functions

bool operator==(const Float3& a, const Float3& b) [code]
bool operator!=(const Float3& a, const Float3& b) [code]

Returns true if the vectors are equal (or not equal) using floating-point comparison. In particular, Float3{0.f} == Float3{-0.f} is true.

 bool isNear(const Float3& a, const Float3& b, float epsilon) [code]

Returns true if a is approximately equal to b. The tolerance is given by epsilon.

Float3 v = {0.9999f, 0.0001f, 1.9999f};
StdOut::text() << isNear(v, Float3{1, 0, 2}, 1e-3f);  // "true"
Bool3 operator<(const Float3& a, const Float3& b) [code]
Bool3 operator<=(const Float3& a, const Float3& b) [code]
Bool3 operator>(const Float3& a, const Float3& b) [code]
Bool3 operator>=(const Float3& a, const Float3& b) [code]

These functions compare each component individually. The result of each comparison is returned in a Bool3. Call all() to check if the result was true for all components, or call any() to check if the result was true for any component.

StdOut::text() << all(Float3{1, 2, 3} > Float3{0, 1, 2});  // "true"

These functions are useful for testing whether a point is inside a box. See the implementation of Box<>::contains for an example.

Geometric Functions

 float dot(const Float3& a, const Float3& b) [code]

Returns the dot product of two vectors.

StdOut::text() << dot(Float3{2, 3, 1}, Float3{4, 5, 1});  // "24"
 Float3 cross(const Float3& a, const Float3& b) [code]

Returns the cross product of two vectors.

StdOut::text() << cross(Float3{1, 0, 0}, Float3{0, 1, 0});  // "{0, 0, 1}"

Length Functions

 float Float3::length2() const [code]

Returns the square of the length of the vector.

 float Float3::length() const [code]

Returns the length of the vector. Equivalent to sqrtf(this->length2()).

 bool Float3::isUnit(float thresh = 0.001f) const [code]

Returns true if the squared length of the vector is sufficiently close to 1.0. The threshold is given by thresh.

 Float3 Float3::normalized() const [code]

Returns a unit-length vector having the same direction as this. No safety check is performed.

 Float3 Float3::safeNormalized(const Float3& fallback = {1, 0, 0}, float epsilon = 1e-20f) const [code]

Returns a unit-length vector having the same direction as this with safety checks.

Conversion Functions

 const Float2& Float3::asFloat2() const [code]

Returns a const reference to the first two components as a Float2 using type punning. This should only be used as a temporary expression.

Float3 v = {4, 5, 6};
StdOut::text() << v.asFloat2();  // "{4, 5}"
 template <typename OtherVec3>
OtherVec3 Float3::to() const [code]

Converts to another 3D vector type such as IntVec3 or Int3<s16>.

Float3 a = {4, 5, 6};
IntVec3 b = a.to<IntVec3>();

Color Functions

 float& Float3::r() [code]
 float Float3::r() const [code]
 float& Float3::g() [code]
 float Float3::g() const [code]
 float& Float3::b() [code]
 float Float3::b() const [code]

Convenience functions for interpreting the vector as a color. The r(), g() and b() functions are aliases for the x, y and z components respectively.

Float3 c = {1.0f, 0.8f, 0.7f};
StdOut::text().format("{}, {}, {}", c.r(), c.g(), c.b());  // "1.0, 0.8, 0.7"

Swizzle Functions

 Float2 Float3::swizzle(u32 i0, u32 i1) const [code]
 Float3 Float3::swizzle(u32 i0, u32 i1, u32 i2) const [code]
 Float4 Float3::swizzle(u32 i0, u32 i1, u32 i2, u32 i3) const [code]

Returns a new vector whose components are taken from the given indices. x, y and z are at indices 0, 1 and 2 respectively. Similar to GLSL swizzling except that the components are specified by numeric index, and you can't use it to modify the original vector; only to read from it.

Float3 v = {4, 5, 6};
StdOut::text() << v.swizzle(1, 0);        // "{5, 4}"
StdOut::text() << v.swizzle(2, 0, 2, 1);  // "{6, 4, 6, 5}"

These functions work correctly in the current version of all major compilers even though they use type punning, which is undefined behavior in standard C++.

Componentwise Functions

 Float3 clamp(const Float3& v, const Float3& mins, const Float3& maxs) [code]

Returns a copy of v with each component constrained to lie within the range determined by the corresponding components of mins and maxs.

Float3 v = {3, 1.5f, 0};
StdOut::text() << clamp(v, Float3{0, 1, 2}, Float3{1, 2, 3});  // "{1, 1.5, 2}"
StdOut::text() << clamp(v, 0, 1);                              // "{1, 1, 0}"
 Float3 abs(const Float3& a) [code]

Returns a vector with each component set to the absolute value of the corresponding component of a.

StdOut::text() << abs(Float3{-2, 3, 0});  // "{2, 3, 0}"
 Float3 pow(const Float3& a, const Float3& b) [code]

Returns a vector with each component set to the corresponding component of a raised to the power of the corresponding component of b.

StdOut::text() << pow(Float3{1, 2, 2}, Float3{2, 3, 1});  // "{1, 8, 2}"
StdOut::text() << pow(Float3{1, 2, 3}, 2);                // "{1, 4, 9}"
 Float3 min(const Float3& a, const Float3& b) [code]

Returns a vector with each component set to minimum of the corresponding components of a and b.

StdOut::text() << min(Float3{0, 1, 0}, Float3{1, 0, 1});  // "{0, 0, 0}"
 Float3 max(const Float3& a, const Float3& b) [code]

Returns a vector with each component set to maximum of the corresponding components of a and b.

StdOut::text() << max(Float3{0, 1, 0}, Float3{1, 0, 1});  // "{1, 1, 1}"

Rounding Functions

 Float3 roundUp(const Float3& value, float spacing = 1) [code]
 Float3 roundDown(const Float3& value, float spacing = 1) [code]
 Float3 roundNearest(const Float3& value, float spacing = 1) [code]

Returns a vector with each component set to the rounded result of the corresponding component of vec. The optional spacing argument can be used to round to arbitrary spacings. Most precise when spacing is a power of 2.

StdOut::text() << roundUp(Float3{-0.3f, 1.4f, 0.8f});  // "{0, 2, 1}"
StdOut::text() << roundDown(Float3{1.8f}, 0.5f);       // "{1.5, 1.5, 1.5}"
 bool isRounded(const Float3& value, float spacing = 1) [code]

Returns true if every component of vec is already rounded. The optional spacing argument can be used to round to arbitrary spacings. Most precise when spacing is a power of 2.

StdOut::text() << isRounded(Float3{1.5f, 0.5f, 0}, 0.5f);  // "true"