Math: deprecate Frustum::planes() in favor of begin()/end().

This allows us to get rid of the StaticArrayView, which is the last
roadblock on the way to a single-header math. The planes() are now
deprecated, along with the include, and will get removed in a future
release.

doc/changelog.dox

@@ -107,6 +107,11 @@ See also:
     @ref GL::Context::DetectedDriver::SwiftShader and
     @ref GL::Context::DetectedDriver::ArmMali
 
+@subsubsection changelog-latest-new-math Math library
+
+-   @ref Math::Frustum::begin() / @ref Math::Frustum::end() accessors for
+    easy range-for access to @ref Math::Frustum planes
+
 @subsubsection changelog-latest-new-platform Platform libraries
 
 -   @ref Platform::Sdl2Application and @ref Platform::GlfwApplication are now
@@ -298,6 +303,9 @@ See also:
     are deprecated in favor of tuple-less @ref Math::ColorHsv, working
     correctly with the usual @ref Math::NoInit / @ref Math::ZeroInit tags while
     being faster to compile
+-   @cpp Math::Frustum::planes() @ce are deprecated due to redundancy, use
+    either @ref Math::Frustum::operator[](), @ref Math::Frustum::data() or
+    range access using @ref Math::Frustum::begin() / @ref Math::Frustum::end()
 -   @cpp Trade::ImporterFileCallbackPolicy @ce is deprecated as it was moved
     to @ref InputFileCallbackPolicy in the root namespace to be shared with
     APIs outside of the @ref Trade namespace

doc/snippets/MagnumMath.cpp

@@ -31,8 +31,10 @@
 #include "Magnum/Math/FunctionsBatch.h"
 #include "Magnum/Math/Bezier.h"
 #include "Magnum/Math/CubicHermite.h"
+#include "Magnum/Math/Distance.h"
 #include "Magnum/Math/DualComplex.h"
 #include "Magnum/Math/DualQuaternion.h"
+#include "Magnum/Math/Frustum.h"
 #include "Magnum/Math/Half.h"
 #include "Magnum/Math/Range.h"
 #include "Magnum/Math/Algorithms/GramSchmidt.h"
@@ -858,6 +860,15 @@ Math::Dual<Byte> integral{floatingPoint}; // {1, 2}
 /* [Dual-conversion] */
 }
 
+[](const Vector3& point){
+Frustum frustum;
+/* [Frustum-range] */
+for(Vector4 plane: frustum)
+    if(Math::Distance::pointPlaneScaled(point, plane) < 0.0f) return false;
+return true;
+/* [Frustum-range] */
+}({});
+
 {
 /* [div] */
 Int quotient, remainder;

src/Magnum/Math/Frustum.h

@@ -31,7 +31,6 @@
  */
 
 #include <Corrade/configure.h>
-#include <Corrade/Containers/ArrayView.h>
 #ifndef CORRADE_NO_DEBUG
 #include <Corrade/Utility/Debug.h>
 #endif
@@ -39,6 +38,10 @@
 #include "Magnum/Math/Matrix4.h"
 #include "Magnum/Math/Vector4.h"
 
+#ifdef MAGNUM_BUILD_DEPRECATED
+#include <Corrade/Containers/ArrayView.h> /** @todo remove when planes() is gone */
+#endif
+
 namespace Magnum { namespace Math {
 
 namespace Implementation {
@@ -116,11 +119,17 @@ template<class T> class Frustum {
         T* data() { return _data[0].data(); }
         constexpr const T* data() const { return _data[0].data(); } /**< @overload */
 
-        /** @brief Frustum planes */
-        constexpr Corrade::Containers::StaticArrayView<6, const Vector4<T>> planes() const {
+        #ifdef MAGNUM_BUILD_DEPRECATED
+        /**
+         * @brief Frustum planes
+         * @deprecated Use @ref operator[](std::size_t) const, @ref data() or
+         *      @ref begin() / @ref end() instead.
+         */
+        constexpr CORRADE_DEPRECATED("use operator[](), data() or begin() / end() instead") Corrade::Containers::StaticArrayView<6, const Vector4<T>> planes() const {
             /* GCC 4.8 needs explicit construction */
             return Corrade::Containers::StaticArrayView<6, const Vector4<T>>{_data};
         }
+        #endif
 
         /**
          * @brief Plane at given index
@@ -132,6 +141,24 @@ template<class T> class Frustum {
             return CORRADE_CONSTEXPR_ASSERT(i < 6, "Math::Frustum::operator[](): index" << i << "out of range"), _data[i];
         }
 
+        /**
+         * @brief First plane
+         *
+         * Together with @ref end() useful for range access, for example here
+         * to check for a point/frustum intersection, similarly to
+         * @ref Intersection::pointFrustum():
+         *
+         * @snippet MagnumMath.cpp Frustum-range
+         */
+        Vector4<T>* begin() { return _data; }
+        constexpr const Vector4<T>* begin() const { return _data; }     /**< @overload */
+        constexpr const Vector4<T>* cbegin() const { return _data; }    /**< @overload */
+
+        /** @brief (One after) last plane */
+        Vector4<T>* end() { return _data + 6; }
+        constexpr const Vector4<T>* end() const { return _data + 6; }   /**< @overload */
+        constexpr const Vector4<T>* cend() const { return _data + 6; }  /**< @overload */
+
         /** @brief Left plane */
         constexpr Vector4<T> left() const { return _data[0]; }
 

src/Magnum/Math/Intersection.h

@@ -418,7 +418,7 @@ The @p tanAngleSqPlusOne parameter can be precomputed like this:
 template<class T> bool rangeCone(const Range3D<T>& range, const Vector3<T>& coneOrigin, const Vector3<T>& coneNormal, const T tanAngleSqPlusOne);
 
 template<class T> bool pointFrustum(const Vector3<T>& point, const Frustum<T>& frustum) {
-    for(const Vector4<T>& plane: frustum.planes()) {
+    for(const Vector4<T>& plane: frustum) {
         /* The point is in front of one of the frustum planes (normals point
            outwards) */
         if(Distance::pointPlaneScaled<T>(point, plane) < T(0))
@@ -434,7 +434,7 @@ template<class T> bool rangeFrustum(const Range3D<T>& range, const Frustum<T>& f
     const Vector3<T> center = range.min() + range.max();
     const Vector3<T> extent = range.max() - range.min();
 
-    for(const Vector4<T>& plane: frustum.planes()) {
+    for(const Vector4<T>& plane: frustum) {
         const Vector3<T> absPlaneNormal = Math::abs(plane.xyz());
 
         const Float d = Math::dot(center, plane.xyz());
@@ -446,7 +446,7 @@ template<class T> bool rangeFrustum(const Range3D<T>& range, const Frustum<T>& f
 }
 
 template<class T> bool aabbFrustum(const Vector3<T>& aabbCenter, const Vector3<T>& aabbExtents, const Frustum<T>& frustum) {
-    for(const Vector4<T>& plane: frustum.planes()) {
+    for(const Vector4<T>& plane: frustum) {
         const Vector3<T> absPlaneNormal = Math::abs(plane.xyz());
 
         const Float d = Math::dot(aabbCenter, plane.xyz());
@@ -460,7 +460,7 @@ template<class T> bool aabbFrustum(const Vector3<T>& aabbCenter, const Vector3<T
 template<class T> bool sphereFrustum(const Vector3<T>& sphereCenter, const T sphereRadius, const Frustum<T>& frustum) {
     const T radiusSq = sphereRadius*sphereRadius;
 
-    for(const Vector4<T>& plane: frustum.planes()) {
+    for(const Vector4<T>& plane: frustum) {
         /* The sphere is in front of one of the frustum planes (normals point
            outwards) */
         if(Distance::pointPlaneScaled<T>(sphereCenter, plane) < -radiusSq)

src/Magnum/Math/Test/FrustumTest.cpp

@@ -75,6 +75,7 @@ struct FrustumTest: Corrade::TestSuite::Tester {
     void convert();
 
     void data();
+    void rangeFor();
 
     void compare();
 
@@ -98,6 +99,7 @@ FrustumTest::FrustumTest() {
               &FrustumTest::convert,
 
               &FrustumTest::data,
+              &FrustumTest::rangeFor,
 
               &FrustumTest::compare,
 
@@ -120,8 +122,12 @@ void FrustumTest::construct() {
         planes[2], planes[3],
         planes[4], planes[5]};
 
-    CORRADE_COMPARE_AS(frustum.planes(), Corrade::Containers::arrayView(planes),
-                       Corrade::TestSuite::Compare::Container);
+    CORRADE_COMPARE(frustum[0], planes[0]);
+    CORRADE_COMPARE(frustum[1], planes[1]);
+    CORRADE_COMPARE(frustum[2], planes[2]);
+    CORRADE_COMPARE(frustum[3], planes[3]);
+    CORRADE_COMPARE(frustum[4], planes[4]);
+    CORRADE_COMPARE(frustum[5], planes[5]);
 
     CORRADE_VERIFY((std::is_nothrow_constructible<Frustum, Vector4, Vector4, Vector4, Vector4, Vector4, Vector4>::value));
 }
@@ -269,7 +275,7 @@ void FrustumTest::data() {
     #if !defined(__GNUC__) || __GNUC__*100 + __GNUC_MINOR__ >= 500
     constexpr
     #endif
-    Vector4 right = a.planes()[1];
+    Vector4 right = a.cbegin()[1];
     CORRADE_COMPARE(right, (Vector4{-1.0f, 0.0f, 0.0f, 1.0f}));
 
     constexpr Vector4 bottom = a[2];
@@ -278,6 +284,12 @@ void FrustumTest::data() {
     constexpr Vector4 near = a.near();
     CORRADE_COMPARE(near, (Vector4{0.0f, 0.0f, 1.0f, 1.0f}));
 
+    #if !defined(CORRADE_MSVC2015_COMPATIBILITY) && (!defined(__GNUC__) || __GNUC__*100 + __GNUC_MINOR__ >= 500)
+    constexpr
+    #endif
+    Vector4 far = *(a.cend() - 1);
+    CORRADE_COMPARE(far, (Vector4{0.0f, 0.0f, -1.0f, 1.0f}));
+
     #ifndef CORRADE_MSVC2015_COMPATIBILITY /* Apparently dereferencing pointer is verboten */
     constexpr
     #endif
@@ -290,6 +302,18 @@ void FrustumTest::data() {
     CORRADE_COMPARE(out.str(), "Math::Frustum::operator[](): index 6 out of range\n");
 }
 
+void FrustumTest::rangeFor() {
+    Frustum a;
+    Vector4 sum{3.0f};
+    Int i = 0;
+    for(const Vector4& plane: a) {
+        ++i;
+        sum *= plane;
+    }
+    CORRADE_COMPARE(i, 6);
+    CORRADE_COMPARE(sum, (Vector4{0.0f, 0.0f, 0.0f, 3.0f}));
+}
+
 void FrustumTest::compare() {
     Frustum a{
         {-1.0f,  2.0f, -3.0f, 0.1f},

src/Magnum/Math/Test/IntersectionBenchmark.cpp

@@ -34,7 +34,7 @@
 namespace Magnum { namespace Math { namespace Test { namespace {
 
 template<class T> bool rangeFrustumNaive(const Math::Range3D<T>& box, const Math::Frustum<T>& frustum) {
-    for(const Math::Vector4<T>& plane: frustum.planes()) {
+    for(const Math::Vector4<T>& plane: frustum) {
         bool cornerHit = 0;
 
         for(UnsignedByte c = 0; c != 8; ++c) {