template<UnsignedInt dimensions, class T>
Magnum::Math::Range class

N-dimensional range.

Axis-aligned line (in 1D), rectangle (in 2D) or box (in 3D). The minimal coordinate is inclusive, maximal exclusive. See Range1D, Range2D and Range3D specializations for given dimension count.

Use in generic code

While Range2D and Range3D have a vector underlying type, Range1D is just a scalar. This makes common usage simpler, but may break in generic code that expects a vector type for any dimension. Solution is to unconditionally cast the value to a vector type or explicitly specify template parameters to choose a vector function overload. For example:

Math::Vector<dimensions, T> min = range.min(); // works for 1D, 2D and 3D

T c = Math::max<dimensions, T>(a.size(), b.size()).product(); // vector max()

Public types

using VectorType = Implementation::RangeTraits<dimensions, T>::Type
Underlying vector type.

Public static functions

static auto fromSize(const VectorType& min, const VectorType& size) -> Range<dimensions, T>
Create a range from minimal coordinates and size.
static auto fromCenter(const VectorType& center, const VectorType& halfSize) -> Range<dimensions, T>
Create a range from center and half size.

Constructors, destructors, conversion operators

Range() constexpr noexcept
Default constructor.
Range(ZeroInitT) explicit constexpr noexcept
Construct a zero range.
Range(Magnum::NoInitT) explicit noexcept
Construct without initializing the contents.
Range(const VectorType& min, const VectorType& max) constexpr noexcept
Construct a range from minimal and maximal coordinates.
Range(const Vector<dimensions, T>& min, const Vector<dimensions, T>& max) constexpr noexcept
Range(const Containers::Pair<VectorType, VectorType>& minmax) constexpr noexcept
Construct a range from a pair of minimal and maximal coordinates.
Range(const Containers::Pair<Vector<dimensions, T>, Vector<dimensions, T>>& minmax) constexpr noexcept
template<class U>
Range(const Range<dimensions, U>& other) explicit constexpr noexcept
Construct range from another of different type.
template<class U, class V = decltype(Implementation::RangeConverter<dimensions, T, U>::from(std::declval<U>()))>
Range(const U& other) explicit constexpr
Construct range from external representation.
template<class U, class V = decltype(Implementation::RangeConverter<dimensions, T, U>::to(std::declval<Range<dimensions, T>>()))>
operator U() const explicit constexpr
Convert range to external representation.

Public functions

auto operator==(const Range<dimensions, T>& other) const -> bool
Equality comparison.
auto operator!=(const Range<dimensions, T>& other) const -> bool
Non-equality comparison.
auto data() -> T*
Raw data.
auto data() const -> const T*
auto min() -> VectorType&
Minimal coordinates (inclusive)
auto min() const -> const VectorType constexpr
auto max() -> VectorType&
Maximal coordinates (exclusive)
auto max() const -> const VectorType constexpr
auto size() const -> VectorType
Range size.
auto center() const -> VectorType
Range center.
auto translated(const VectorType& vector) const -> Range<dimensions, T>
Translated range.
auto padded(const VectorType& padding) const -> Range<dimensions, T>
Padded range.
auto scaled(const VectorType& scaling) const -> Range<dimensions, T>
Scaled range.
auto scaled(T scaling) const -> Range<dimensions, T> new in Git master
auto scaledFromCenter(const VectorType& scaling) const -> Range<dimensions, T>
Range scaled from the center.
auto scaledFromCenter(T scaling) const -> Range<dimensions, T> new in Git master
auto contains(const VectorType& b) const -> bool
Whether given point is contained inside the range.
auto contains(const Range<dimensions, T>& b) const -> bool
Whether another range is fully contained inside this range.

Typedef documentation

template<UnsignedInt dimensions, class T>
typedef Implementation::RangeTraits<dimensions, T>::Type Magnum::Math::Range<dimensions, T>::VectorType

Underlying vector type.

T in 1D, Vector2<T> in 2D, Vector3<T> in 3D.

Function documentation

template<UnsignedInt dimensions, class T>
static Range<dimensions, T> Magnum::Math::Range<dimensions, T>::fromSize(const VectorType& min, const VectorType& size)

Create a range from minimal coordinates and size.

Parameters
min Minimal coordinates
size Range size

template<UnsignedInt dimensions, class T>
static Range<dimensions, T> Magnum::Math::Range<dimensions, T>::fromCenter(const VectorType& center, const VectorType& halfSize)

Create a range from center and half size.

Parameters
center Range center
halfSize Half size

For creating integer center ranges you can use fromSize() together with padded(), for example:

Vector2i center, filterRadius;
auto filterArea = Range2Di::fromSize(center, Vector2i{1}).padded(filterRadius);

template<UnsignedInt dimensions, class T>
Magnum::Math::Range<dimensions, T>::Range() constexpr noexcept

Default constructor.

Equivalent to Range(ZeroInitT).

template<UnsignedInt dimensions, class T>
Magnum::Math::Range<dimensions, T>::Range(ZeroInitT) explicit constexpr noexcept

Construct a zero range.

Construct a zero-size range positioned at origin.

template<UnsignedInt dimensions, class T>
Magnum::Math::Range<dimensions, T>::Range(const Vector<dimensions, T>& min, const Vector<dimensions, T>& max) constexpr noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions, class T>
Magnum::Math::Range<dimensions, T>::Range(const Containers::Pair<VectorType, VectorType>& minmax) constexpr noexcept

Construct a range from a pair of minimal and maximal coordinates.

Useful in combination with e.g. minmax(), here for example to calculate bounds of a triangle:

Vector3 a, b, c;
Range3D bounds = Math::minmax({a, b, c});

template<UnsignedInt dimensions, class T>
Magnum::Math::Range<dimensions, T>::Range(const Containers::Pair<Vector<dimensions, T>, Vector<dimensions, T>>& minmax) constexpr noexcept

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions, class T> template<class U>
Magnum::Math::Range<dimensions, T>::Range(const Range<dimensions, U>& other) explicit constexpr noexcept

Construct range from another of different type.

Performs only default casting on the values, no rounding or anything else. Example usage:

Range2D floatingPoint{{1.3f, 2.7f}, {-15.0f, 7.0f}};
Range2Di integral{floatingPoint}; // {{1, 2}, {-15, 7}}

template<UnsignedInt dimensions, class T>
T* Magnum::Math::Range<dimensions, T>::data()

Raw data.

Contrary to what Doxygen shows, returns reference to an one-dimensional fixed-size array of dimensions*2 elements, i.e. T(&)[dimensions*2].

template<UnsignedInt dimensions, class T>
const T* Magnum::Math::Range<dimensions, T>::data() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions, class T>
VectorType& Magnum::Math::Range<dimensions, T>::min()

Minimal coordinates (inclusive)

Denoted as $ \operatorname{min}(A) $ in related math equations.

template<UnsignedInt dimensions, class T>
const VectorType Magnum::Math::Range<dimensions, T>::min() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions, class T>
VectorType& Magnum::Math::Range<dimensions, T>::max()

Maximal coordinates (exclusive)

Denoted as $ \operatorname{max}(A) $ in related math equations.

template<UnsignedInt dimensions, class T>
const VectorType Magnum::Math::Range<dimensions, T>::max() const constexpr

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions, class T>
VectorType Magnum::Math::Range<dimensions, T>::size() const

Range size.

template<UnsignedInt dimensions, class T>
VectorType Magnum::Math::Range<dimensions, T>::center() const

Range center.

template<UnsignedInt dimensions, class T>
Range<dimensions, T> Magnum::Math::Range<dimensions, T>::translated(const VectorType& vector) const

Translated range.

Translates the minimal and maximal coordinates by given amount. Size remains the same.

template<UnsignedInt dimensions, class T>
Range<dimensions, T> Magnum::Math::Range<dimensions, T>::padded(const VectorType& padding) const

Padded range.

Translates the minimal and maximal coordinates by given amount. Center remains the same.

template<UnsignedInt dimensions, class T>
Range<dimensions, T> Magnum::Math::Range<dimensions, T>::scaled(const VectorType& scaling) const

Scaled range.

Multiplies the minimal and maximal coordinates by given amount. Center doesn't remain the same, use scaledFromCenter() for that operation.

template<UnsignedInt dimensions, class T>
Range<dimensions, T> Magnum::Math::Range<dimensions, T>::scaled(T scaling) const new in Git master

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions, class T>
Range<dimensions, T> Magnum::Math::Range<dimensions, T>::scaledFromCenter(const VectorType& scaling) const

Range scaled from the center.

Scales the size, while center remains the same.

template<UnsignedInt dimensions, class T>
Range<dimensions, T> Magnum::Math::Range<dimensions, T>::scaledFromCenter(T scaling) const new in Git master

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<UnsignedInt dimensions, class T>
bool Magnum::Math::Range<dimensions, T>::contains(const VectorType& b) const

Whether given point is contained inside the range.

Returns true if the following holds for all dimensions $ i $ , false otherwise.

\[ \bigwedge_i (b_i \ge \operatorname{min}(A)_i) \land (b_i < \operatorname{max}(A)_i) \]

The range minimum is interpreted as inclusive, maximum as exclusive. Results are undefined if the range has negative size.

template<UnsignedInt dimensions, class T>
bool Magnum::Math::Range<dimensions, T>::contains(const Range<dimensions, T>& b) const

Whether another range is fully contained inside this range.

Returns true if the following holds for all dimensions $ i $ , false otherwise.

\[ \bigwedge_i (\operatorname{min}(B)_i \ge \operatorname{min}(A)_i) \land (\operatorname{max}(B)_i \le \operatorname{max}(A)_i) \]

Results are undefined if the range has negative size.

template<UnsignedInt dimensions, class T> template<UnsignedInt dimensions, class T>
Range<dimensions, T> join(const Range<dimensions, T>& a, const Range<dimensions, T>& b)

Join two ranges.

Returns a range that contains both input ranges. If one of the ranges is empty, only the other is returned. Results are undefined if any range has a negative size.

template<UnsignedInt dimensions, class T> template<UnsignedInt dimensions, class T>
Range<dimensions, T> join(const Range<dimensions, T>& a, const Vector<dimensions, T>& b) new in Git master

Join a range and a point.

Returns a range that contains both the input range and the point. Compared to join(const Range<dimensions, T>&, const Range<dimensions, T>&) there's no special casing for an empty range. Results are undefined if the range has a negative size.

template<UnsignedInt dimensions, class T> template<UnsignedInt dimensions, class T>
Range<dimensions, T> intersect(const Range<dimensions, T>& a, const Range<dimensions, T>& b)

Intersect two ranges.

Returns a range that covers the intersection of both ranges. If the intersection is empty, a default-constructed range is returned. The range minimum is interpreted as inclusive, maximum as exclusive. Results are undefined if any range has a negative size.

template<UnsignedInt dimensions, class T> template<UnsignedInt dimensions, class T>
bool intersects(const Range<dimensions, T>& a, const Range<dimensions, T>& b)

Whether two ranges intersect.

Returns true if the following holds for all dimensions $ i $ , false otherwise.

\[ \bigwedge_i (\operatorname{max}(A)_i > \operatorname{min}(B)_i) \land (\operatorname{min}(A)_i < \operatorname{max}(B)_i) \]

The range minimum is interpreted as inclusive, maximum as exclusive. Results are undefined if any range has a negative size.

template<UnsignedInt dimensions, class T> template<UnsignedInt dimensions, class T>
Debug& operator<<(Debug& debug, const Range<dimensions, T>& value)

Debug output operator.