# Float3

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

`#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"
``````