DebugTools: deprecate templated bufferData().

As was done with GL::Buffer::data() back in 2017 -- the size parameter
is way too error prone this way (is it bytes? or multiples of
sizeof(T)?), plus arrayCast() contains a few extra checks that would
have to be replicated here to have the same level of robustness, etc.,
etc.

doc/changelog.dox

@@ -728,6 +728,11 @@ See also:
     the canvas and status elements from the JS `Module`. See
     @ref platforms-html5-apps and [mosra/magnum#481](https://github.com/mosra/magnum/pull/481)
     for details.
+-   Templated variants of @ref DebugTools::bufferData() and
+    @ref DebugTools::bufferSubData() are deprecated in favor of the
+    non-templated API together with @relativeref{Corrade,Containers::arrayCast()}.
+    A similar change was done for @ref GL::Buffer::data() in 2017 already,
+    unfortunately this helper was missed.
 -   @cpp DebugTools::GLFrameProfiler @ce is deprecated in favor of
     @ref DebugTools::FrameProfilerGL. The new name plays better with IDE
     autocompletion and makes the GL-specific class appear next to the

src/Magnum/DebugTools/BufferData.cpp

@@ -25,15 +25,37 @@
 
 #include "BufferData.h"
 
-#ifndef MAGNUM_TARGET_WEBGL
+#include <Corrade/Containers/Array.h>
 #include <Corrade/Utility/Algorithms.h>
 
-namespace Magnum { namespace DebugTools { namespace Implementation {
+#include "Magnum/GL/Buffer.h"
 
+namespace Magnum { namespace DebugTools {
+
+#ifdef MAGNUM_BUILD_DEPRECATED
+namespace Implementation {
+
+/* Used only by deprecated bufferSubData<T>() */
+/** @todo remove when not used anymore */
 void bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size, void* output) {
     Utility::copy(buffer.mapRead(offset, size), Containers::ArrayView<char>{static_cast<char*>(output), std::size_t(size)});
     buffer.unmap();
 }
 
-}}}
+}
 #endif
+
+Containers::Array<char> bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) {
+    Containers::Array<char> data{NoInit, std::size_t(size)};
+    if(size) {
+        Utility::copy(buffer.mapRead(offset, size), data);
+        buffer.unmap();
+    }
+    return data;
+}
+
+Containers::Array<char> bufferData(GL::Buffer& buffer) {
+    return bufferSubData(buffer, 0, buffer.size());
+}
+
+}}

src/Magnum/DebugTools/BufferData.h

@@ -31,17 +31,30 @@
  */
 #endif
 
+#include <Corrade/Containers/Containers.h>
+
+#include "Magnum/Magnum.h"
+#include "Magnum/GL/GL.h"
+#include "Magnum/GL/OpenGL.h"
+#include "Magnum/DebugTools/visibility.h"
+
+#ifdef MAGNUM_BUILD_DEPRECATED
 #include <Corrade/Containers/Array.h>
+#include <Corrade/Utility/Macros.h>
 
 #include "Magnum/GL/Buffer.h"
-#include "Magnum/DebugTools/visibility.h"
+#endif
 
 #if defined(MAGNUM_TARGET_GL) && !defined(MAGNUM_TARGET_WEBGL)
 namespace Magnum { namespace DebugTools {
 
+#ifdef MAGNUM_BUILD_DEPRECATED
 namespace Implementation {
+    /* Used only by deprecated bufferSubData<T>() */
+    /** @todo remove when not used anymore */
     MAGNUM_DEBUGTOOLS_EXPORT void bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size, void* output);
 }
+#endif
 
 /**
 @brief Buffer subdata
@@ -58,11 +71,27 @@ Emulates @ref GL::Buffer::subData() call on platforms that don't support it
     2.0.
 @requires_gles Buffer mapping is not available in WebGL.
 */
-template<class T> Containers::Array<T> inline bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) {
+MAGNUM_DEBUGTOOLS_EXPORT Containers::Array<char> bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size);
+
+#ifdef MAGNUM_BUILD_DEPRECATED
+/**
+@copybrief bufferSubData()
+@m_deprecated_since_latest Use non-templated @ref bufferSubData() and
+    @ref Containers::arrayCast() instead
+
+@requires_gl30 Extension @gl_extension{ARB,map_buffer_range}
+@requires_gles30 Extension @gl_extension{EXT,map_buffer_range} in OpenGL ES
+    2.0.
+@requires_gles Buffer mapping is not available in WebGL.
+*/
+template<class T> CORRADE_DEPRECATED("use non-templated bufferSubData() and Containers::arrayCast() instead") Containers::Array<T> inline bufferSubData(GL::Buffer& buffer, GLintptr offset, GLsizeiptr size) {
+    /* Yes, this should have NoInit, but let's preserve the deprecated API in
+       its original form */
     Containers::Array<T> data{std::size_t(size)};
     if(size) Implementation::bufferSubData(buffer, offset, size*sizeof(T), data);
     return data;
 }
+#endif
 
 /**
 @brief Buffer data
@@ -79,11 +108,29 @@ as OpenGL ES) by using @ref GL::Buffer::map().
     2.0.
 @requires_gles Buffer mapping is not available in WebGL.
 */
-template<class T = char> Containers::Array<T> inline bufferData(GL::Buffer& buffer) {
+MAGNUM_DEBUGTOOLS_EXPORT Containers::Array<char> bufferData(GL::Buffer& buffer);
+
+#ifdef MAGNUM_BUILD_DEPRECATED
+/**
+@copybrief bufferData()
+@m_deprecated_since_latest Use non-templated @ref bufferData() and
+    @ref Containers::arrayCast() instead
+
+@requires_gl30 Extension @gl_extension{ARB,map_buffer_range}
+@requires_gles30 Extension @gl_extension{EXT,map_buffer_range} in OpenGL ES
+    2.0.
+@requires_gles Buffer mapping is not available in WebGL.
+*/
+template<class T = char> CORRADE_DEPRECATED("use non-templated bufferData() and Containers::arrayCast() instead") Containers::Array<T> inline bufferData(GL::Buffer& buffer) {
     const Int bufferSize = buffer.size();
+    /* Yes, the assert prefix is wrong, but let's preserve the deprecated API
+       in its original form */
     CORRADE_ASSERT(bufferSize%sizeof(T) == 0, "Buffer::data(): the buffer size is" << bufferSize << "bytes, which can't be expressed as array of types with size" << sizeof(T), nullptr);
+    CORRADE_IGNORE_DEPRECATED_PUSH
     return bufferSubData<T>(buffer, 0, bufferSize/sizeof(T));
+    CORRADE_IGNORE_DEPRECATED_POP
 }
+#endif
 
 }}
 #else

src/Magnum/DebugTools/Test/BufferDataGLTest.cpp

@@ -23,9 +23,11 @@
     DEALINGS IN THE SOFTWARE.
 */
 
+#include <Corrade/Containers/Array.h>
 #include <Corrade/TestSuite/Compare/Container.h>
 
 #include "Magnum/DebugTools/BufferData.h"
+#include "Magnum/GL/Buffer.h"
 #include "Magnum/GL/Context.h"
 #include "Magnum/GL/Extensions.h"
 #include "Magnum/GL/OpenGLTester.h"