#ifndef Magnum_Buffer_h
#define Magnum_Buffer_h
/*
    This file is part of Magnum.

    Copyright © 2010, 2011, 2012, 2013, 2014
              Vladimír Vondruš <mosra@centrum.cz>

    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
*/

/** @file
 * @brief Class @ref Magnum::Buffer, enum @ref Magnum::BufferUsage
 */

#include <cstddef>
#include <array>
#include <vector>
#include <Corrade/Containers/Array.h>
#include <Corrade/Containers/EnumSet.h>
#include <Corrade/Utility/Assert.h>

#include "Magnum/AbstractObject.h"
#include "Magnum/Magnum.h"

namespace Magnum {

/**
@brief %Buffer usage

@see @ref Buffer, @ref Buffer::setData(Containers::ArrayReference<const void>, BufferUsage)
*/
enum class BufferUsage: GLenum {
    /** Set once by the application and used infrequently for drawing. */
    StreamDraw = GL_STREAM_DRAW,

    #ifndef MAGNUM_TARGET_GLES2
    /**
     * Set once as output from an OpenGL command and used infequently for
     * drawing.
     * @requires_gles30 Only @ref Magnum::BufferUsage::StreamDraw "BufferUsage::StreamDraw"
     *      is available in OpenGL ES 2.0.
     */
    StreamRead = GL_STREAM_READ,

    /**
     * Set once as output from an OpenGL command and used infrequently for
     * drawing or copying to other buffers.
     * @requires_gles30 Only @ref Magnum::BufferUsage::StreamDraw "BufferUsage::StreamDraw"
     *      is available in OpenGL ES 2.0.
     */
    StreamCopy = GL_STREAM_COPY,
    #endif

    /** Set once by the application and used frequently for drawing. */
    StaticDraw = GL_STATIC_DRAW,

    #ifndef MAGNUM_TARGET_GLES2
    /**
     * Set once as output from an OpenGL command and queried many times by the
     * application.
     * @requires_gles30 Only @ref Magnum::BufferUsage::StaticDraw "BufferUsage::StaticDraw"
     *      is available in OpenGL ES 2.0.
     */
    StaticRead = GL_STATIC_READ,

    /**
     * Set once as output from an OpenGL command and used frequently for
     * drawing or copying to other buffers.
     * @requires_gles30 Only @ref Magnum::BufferUsage::StaticDraw "BufferUsage::StaticDraw"
     *      is available in OpenGL ES 2.0.
     */
    StaticCopy = GL_STATIC_COPY,
    #endif

    /**
     * Updated frequently by the application and used frequently for drawing or
     * copying to other images.
     */
    DynamicDraw = GL_DYNAMIC_DRAW,

    #ifndef MAGNUM_TARGET_GLES2
    /**
     * Updated frequently as output from OpenGL command and queried many times
     * from the application.
     * @requires_gles30 Only @ref Magnum::BufferUsage::DynamicDraw "BufferUsage::DynamicDraw"
     *      is available in OpenGL ES 2.0.
     */
    DynamicRead = GL_DYNAMIC_READ,

    /**
     * Updated frequently as output from OpenGL command and used frequently for
     * drawing or copying to other images.
     * @requires_gles30 Only @ref Magnum::BufferUsage::DynamicDraw "BufferUsage::DynamicDraw"
     *      is available in OpenGL ES 2.0.
     */
    DynamicCopy = GL_DYNAMIC_COPY
    #endif
};

namespace Implementation { struct BufferState; }

/**
@brief %Buffer

Encapsulates one OpenGL buffer object and provides functions for convenient
data updates.

@section Buffer-data Data updating

Default way to set or update buffer data with @ref setData() or @ref setSubData()
is to use @ref Corrade::Containers::ArrayReference. See its documentation for
more information about automatic conversions etc.
@code
Containers::ArrayReference<Vector3> data;
buffer.setData(data, BufferUsage::StaticDraw);
@endcode
There is also overload for array-like containers from STL, such as `std::vector`
or `std::array`:
@code
std::vector<Vector3> data;
buffer.setData(data, BufferUsage::StaticDraw);
@endcode

@subsection Buffer-data-mapping Memory mapping

%Buffer data can be also updated asynchronously. First you need to allocate
the buffer to desired size by passing `nullptr` to @ref setData(), e.g.:
@code
buffer.setData({nullptr, 200*sizeof(Vector3)}, BufferUsage::StaticDraw);
@endcode
Then you can map the buffer to client memory and operate with the memory
directly. After you are done with the operation, call @ref unmap() to unmap the
buffer again.
@code
Vector3* data = static_cast<Vector3*>(buffer.map(0, 200*sizeof(Vector3), Buffer::MapFlag::Write|Buffer::MapFlag::InvalidateBuffer));
for(std::size_t i = 0; i != 200; ++i)
    data[i] = ...;
CORRADE_INTERNAL_ASSERT_OUTPUT(buffer.unmap());
@endcode
If you are updating only a few discrete portions of the buffer, you can use
@ref MapFlag::FlushExplicit and @ref flushMappedRange() to reduce number of
memory operations performed by OpenGL on unmapping. Example:
@code
Vector3* data = static_cast<Vector3*>(buffer.map(0, 200*sizeof(Vector3), Buffer::MapFlag::Write|Buffer::MapFlag::FlushExplicit));
for(std::size_t i: {7, 27, 56, 128}) {
    data[i] = ...;
    buffer.flushMappedRange(i*sizeof(Vector3), sizeof(Vector3));
}
CORRADE_INTERNAL_ASSERT_OUTPUT(buffer.unmap());
@endcode

@section Buffer-webgl-restrictions WebGL and NaCl restrictions

Buffers in @ref MAGNUM_TARGET_WEBGL "WebGL" and @ref CORRADE_TARGET_NACL "NaCl"
need to be bound only to one unique target, i.e., @ref Buffer bound to
@ref Buffer::Target::Array cannot be later rebound to
@ref Buffer::Target::ElementArray. However, %Magnum by default uses any
sufficient target when binding the buffer internally (e.g. for setting data).
To avoid GL errors, set target hint to desired target, either in constructor or
using @ref Buffer::setTargetHint():
@code
Buffer vertices{Buffer::Target::Array};
Buffer indices{Buffer::Target::ElementArray};
@endcode

To ease up the development, @ref Mesh checks proper target hint when adding
vertex and index buffers in both WebGL and NaCl.

@section Buffer-performance-optimization Performance optimizations

The engine tracks currently bound buffers to avoid unnecessary calls to
@fn_gl{BindBuffer}. If the buffer is already bound to some target, functions
@ref copy(), @ref setData(), @ref setSubData(), @ref map(), @ref flushMappedRange()
and @ref unmap() use that target instead of binding the buffer to some specific
target. You can also use @ref setTargetHint() to possibly reduce unnecessary
rebinding. %Buffer limits and implementation-defined values (such as
@ref maxUniformBindings()) are cached, so repeated queries don't result in
repeated @fn_gl{Get} calls.

If extension @extension{EXT,direct_state_access} is available, functions
@ref copy(), @ref setData(), @ref setSubData(), @ref map(), @ref flushMappedRange()
and @ref unmap() use DSA functions to avoid unnecessary calls to
@fn_gl{BindBuffer}. See their respective documentation for more information.

You can use functions @ref invalidateData() and @ref invalidateSubData() if you
don't need buffer data anymore to avoid unnecessary memory operations performed
by OpenGL in order to preserve the data. If running on OpenGL ES or extension
@extension{ARB,invalidate_subdata} (part of OpenGL 4.3) is not available, these
functions do nothing.
 */
class MAGNUM_EXPORT Buffer: public AbstractObject {
    friend struct Implementation::BufferState;

    public:
        /**
         * @brief %Buffer target
         *
         * @see @ref bind(Target), @ref unbind(Target)
         */
        enum class Target: GLenum {
            /** Used for storing vertex attributes. */
            Array = GL_ARRAY_BUFFER,

            #ifndef MAGNUM_TARGET_GLES
            /**
             * Used for storing atomic counters.
             * @requires_gl42 %Extension @extension{ARB,shader_atomic_counters}
             * @requires_gl Atomic counters are not available in OpenGL ES.
             */
            AtomicCounter = GL_ATOMIC_COUNTER_BUFFER,
            #endif

            #ifndef MAGNUM_TARGET_GLES2
            /**
             * Source for copies. See @ref copy().
             * @requires_gl31 %Extension @extension{ARB,copy_buffer}
             * @requires_gles30 Buffer copying is not available in OpenGL ES
             *      2.0.
             */
            CopyRead = GL_COPY_READ_BUFFER,

            /**
             * Target for copies. See @ref copy().
             * @requires_gl31 %Extension @extension{ARB,copy_buffer}
             * @requires_gles30 Buffer copying is not available in OpenGL ES
             *      2.0.
             */
            CopyWrite = GL_COPY_WRITE_BUFFER,
            #endif

            #ifndef MAGNUM_TARGET_GLES
            /**
             * Indirect compute dispatch commands.
             * @requires_gl43 %Extension @extension{ARB,compute_shader}
             * @requires_gl Compute shaders are not available in OpenGL ES.
             */
            DispatchIndirect = GL_DISPATCH_INDIRECT_BUFFER,

            /**
             * Used for supplying arguments for indirect drawing.
             * @requires_gl40 %Extension @extension{ARB,draw_indirect}
             * @requires_gl Indirect drawing not available in OpenGL ES.
             */
            DrawIndirect = GL_DRAW_INDIRECT_BUFFER,
            #endif

            /** Used for storing vertex indices. */
            ElementArray = GL_ELEMENT_ARRAY_BUFFER

            #ifndef MAGNUM_TARGET_GLES2
            ,

            /**
             * Target for pixel pack operations.
             * @requires_gles30 Pixel buffer objects are not available in
             *      OpenGL ES 2.0.
             */
            PixelPack = GL_PIXEL_PACK_BUFFER,

            /**
             * Source for texture update operations.
             * @requires_gles30 Pixel buffer objects are not available in
             *      OpenGL ES 2.0.
             */
            PixelUnpack = GL_PIXEL_UNPACK_BUFFER,
            #endif

            #ifndef MAGNUM_TARGET_GLES
            /**
             * Used for shader storage.
             * @requires_gl43 %Extension @extension{ARB,shader_storage_buffer_object}
             * @requires_gl Shader storage is not available in OpenGL ES.
             */
            ShaderStorage = GL_SHADER_STORAGE_BUFFER,

            /**
             * Source for texel fetches. See @ref BufferTexture.
             * @requires_gl31 %Extension @extension{ARB,texture_buffer_object}
             * @requires_gl Texture buffers are not available in OpenGL ES.
             */
            Texture = GL_TEXTURE_BUFFER,
            #endif

            #ifndef MAGNUM_TARGET_GLES2
            /**
             * Target for transform feedback.
             * @requires_gl30 %Extension @extension{EXT,transform_feedback}
             * @requires_gles30 Transform feedback is not available in OpenGL
             *      ES 2.0.
             */
            TransformFeedback = GL_TRANSFORM_FEEDBACK_BUFFER,

            /**
             * Used for storing uniforms.
             * @requires_gl31 %Extension @extension{ARB,uniform_buffer_object}
             * @requires_gles30 Uniform buffers are not available in OpenGL ES
             *      2.0.
             */
            Uniform = GL_UNIFORM_BUFFER
            #endif
        };

        #ifdef MAGNUM_BUILD_DEPRECATED
        /**
         * @copybrief BufferUsage
         * @deprecated Use @ref Magnum::BufferUsage "BufferUsage" instead.
         */
        typedef CORRADE_DEPRECATED("use BufferUsage instead") BufferUsage Usage;
        #endif

        /**
         * @brief Memory mapping access
         *
         * @see @ref map(MapAccess), @ref mapSub()
         * @requires_es_extension %Extension @es_extension{OES,mapbuffer} or
         *      @es_extension{CHROMIUM,map_sub}
         * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
         *      instead, as it has more complete set of features.
         */
        enum class MapAccess: GLenum {
            #ifndef MAGNUM_TARGET_GLES
            /**
             * Map buffer for reading only.
             * @requires_gl Only @ref Magnum::Buffer::MapAccess "MapAccess::WriteOnly"
             *      is available in OpenGL ES.
             */
            ReadOnly = GL_READ_ONLY,
            #endif

            /** Map buffer for writing only. */
            #ifdef MAGNUM_TARGET_GLES
            WriteOnly = GL_WRITE_ONLY_OES
            #else
            WriteOnly = GL_WRITE_ONLY,

            /**
             * Map buffer for both reading and writing.
             * @requires_gl Only @ref Magnum::Buffer::MapAccess "MapAccess::WriteOnly"
             *      is available in OpenGL ES.
             */
            ReadWrite = GL_READ_WRITE
            #endif
        };

        /**
         * @brief Memory mapping flag
         *
         * @see @ref MapFlags, @ref map(GLintptr, GLsizeiptr, MapFlags)
         * @requires_gl30 %Extension @extension{ARB,map_buffer_range}
         * @requires_gles30 %Extension @es_extension{EXT,map_buffer_range} in
         *      OpenGL ES 2.0
         */
        enum class MapFlag: GLbitfield {
            /** Map buffer for reading. */
            #ifndef MAGNUM_TARGET_GLES2
            Read = GL_MAP_READ_BIT,
            #else
            Read = GL_MAP_READ_BIT_EXT,
            #endif

            /** Map buffer for writing. */
            #ifndef MAGNUM_TARGET_GLES2
            Write = GL_MAP_WRITE_BIT,
            #else
            Write = GL_MAP_WRITE_BIT_EXT,
            #endif

            /**
             * Previous contents of the entire buffer may be discarded. May not
             * be used in combination with @ref MapFlag::Read.
             * @see @ref invalidateData()
             */
            #ifndef MAGNUM_TARGET_GLES2
            InvalidateBuffer = GL_MAP_INVALIDATE_BUFFER_BIT,
            #else
            InvalidateBuffer = GL_MAP_INVALIDATE_BUFFER_BIT_EXT,
            #endif

            /**
             * Previous contents of mapped range may be discarded. May not be
             * used in combination with @ref MapFlag::Read.
             * @see @ref invalidateSubData()
             */
            #ifndef MAGNUM_TARGET_GLES2
            InvalidateRange = GL_MAP_INVALIDATE_RANGE_BIT,
            #else
            InvalidateRange = GL_MAP_INVALIDATE_RANGE_BIT_EXT,
            #endif

            /**
             * Only one or more discrete subranges of the mapping will be
             * modified. See @ref flushMappedRange() for more information. May
             * only be used in conjuction with @ref MapFlag::Write.
             */
            #ifndef MAGNUM_TARGET_GLES2
            FlushExplicit = GL_MAP_FLUSH_EXPLICIT_BIT,
            #else
            FlushExplicit = GL_MAP_FLUSH_EXPLICIT_BIT_EXT,
            #endif

            /**
             * No pending operations on the buffer should be synchronized
             * before mapping.
             */
            #ifndef MAGNUM_TARGET_GLES2
            Unsynchronized = GL_MAP_UNSYNCHRONIZED_BIT
            #else
            Unsynchronized = GL_MAP_UNSYNCHRONIZED_BIT_EXT
            #endif
        };

        /**
         * @brief Memory mapping flags
         *
         * @see @ref map(GLintptr, GLsizeiptr, MapFlags)
         * @requires_gl30 %Extension @extension{ARB,map_buffer_range}
         * @requires_gles30 %Extension @es_extension{EXT,map_buffer_range} in
         *      OpenGL ES 2.0
         */
        typedef Containers::EnumSet<MapFlag, GLbitfield> MapFlags;

        #ifndef MAGNUM_TARGET_GLES
        /**
         * @brief Minimal supported mapping alignment
         *
         * The result is cached, repeated queries don't result in repeated
         * OpenGL calls. If extension @extension{ARB,map_buffer_alignment} is
         * not available, returns `0`.
         * @see @ref map(), @fn_gl{Get} with @def_gl{MIN_MAP_BUFFER_ALIGNMENT}
         * @requires_gl No minimal value is specified for OpenGL ES.
         */
        static Int minMapAlignment();

        /**
         * @brief Max supported atomic counter buffer binding count
         *
         * The result is cached, repeated queries don't result in repeated
         * OpenGL calls. If extension @extension{ARB,shader_atomic_counters} is
         * not available, returns `0`.
         * @see @fn_gl{Get} with @def_gl{MAX_ATOMIC_COUNTER_BUFFER_BINDINGS}
         * @requires_gl Atomic counters are not available in OpenGL ES.
         */
        static Int maxAtomicCounterBindings();

        /**
         * @brief Max supported shader storage buffer binding count
         *
         * The result is cached, repeated queries don't result in repeated
         * OpenGL calls. If extension @extension{ARB,shader_storage_buffer_object}
         * is not available, returns `0`.
         * @see @fn_gl{Get} with @def_gl{MAX_SHADER_STORAGE_BUFFER_BINDINGS}
         * @requires_gl Atomic counters are not available in OpenGL ES.
         */
        static Int maxShaderStorageBindings();

        /**
         * @brief Alignment of shader storage buffer binding offset
         *
         * The result is cached, repeated queries don't result in repeated
         * OpenGL calls. If extension @extension{ARB,shader_storage_buffer_object}
         * is not available, returns `0`.
         * @see @fn_gl{Get} with @def_gl{SHADER_STORAGE_BUFFER_OFFSET_ALIGNMENT}
         * @requires_gl Atomic counters are not available in OpenGL ES.
         */
        static Int shaderStorageOffsetAlignment();
        #endif

        #ifndef MAGNUM_TARGET_GLES2
        /**
         * @brief Max supported uniform buffer binding count
         *
         * The result is cached, repeated queries don't result in repeated
         * OpenGL calls. If extension @extension{ARB,uniform_buffer_object}
         * is not available, returns `0`.
         * @see @fn_gl{Get} with @def_gl{MAX_UNIFORM_BUFFER_BINDINGS}
         * @requires_gles30 Uniform blocks are not available in OpenGL ES 2.0.
         */
        static Int maxUniformBindings();
        #endif

        /**
         * @brief Unbind any buffer from given target
         * @param target    %Target
         *
         * @see @fn_gl{BindBuffer}
         */
        static void unbind(Target target) { bind(target, 0); }

        #ifndef MAGNUM_TARGET_GLES2
        /**
         * @brief Copy one buffer to another
         * @param read          %Buffer from which to read
         * @param write         %Buffer to which to copy
         * @param readOffset    Offset in the read buffer
         * @param writeOffset   Offset in the write buffer
         * @param size          Data size
         *
         * If @extension{EXT,direct_state_access} is not available and the
         * buffers aren't already bound somewhere, they are bound to
         * @ref Target::CopyRead and @ref Target::CopyWrite before the copy is
         * performed.
         * @see @fn_gl{BindBuffer} and @fn_gl{CopyBufferSubData} or
         *      @fn_gl_extension{NamedCopyBufferSubData,EXT,direct_state_access}
         * @requires_gl31 %Extension @extension{ARB,copy_buffer}
         * @requires_gles30 %Buffer copying is not available in OpenGL ES 2.0.
         */
        static void copy(Buffer& read, Buffer& write, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size);
        #endif

        /**
         * @brief Constructor
         * @param targetHint    Target hint, see @ref setTargetHint() for more
         *      information
         *
         * Creates new OpenGL buffer.
         * @see @fn_gl{GenBuffers}
         */
        explicit Buffer(Target targetHint = Target::Array);

        /** @brief Copying is not allowed */
        Buffer(const Buffer&) = delete;

        /** @brief Move constructor */
        Buffer(Buffer&& other) noexcept;

        /**
         * @brief Destructor
         *
         * Deletes associated OpenGL buffer.
         * @see @fn_gl{DeleteBuffers}
         */
        ~Buffer();

        /** @brief Copying is not allowed */
        Buffer& operator=(const Buffer&) = delete;

        /** @brief Move assignment */
        Buffer& operator=(Buffer&& other) noexcept;

        /** @brief OpenGL buffer ID */
        GLuint id() const { return _id; }

        /**
         * @brief %Buffer label
         *
         * The result is *not* cached, repeated queries will result in repeated
         * OpenGL calls. If OpenGL 4.3 is not supported and neither
         * @extension{KHR,debug} nor @extension2{EXT,debug_label} desktop or ES
         * extension is available, this function returns empty string.
         * @see @fn_gl{GetObjectLabel} with @def_gl{BUFFER} or
         *      @fn_gl_extension2{GetObjectLabel,EXT,debug_label} with
         *      @def_gl{BUFFER_OBJECT_EXT}
         */
        std::string label() const;

        /**
         * @brief Set buffer label
         * @return Reference to self (for method chaining)
         *
         * Default is empty string. If OpenGL 4.3 is not supported and neither
         * @extension{KHR,debug} nor @extension2{EXT,debug_label} desktop or ES
         * extension is available, this function does nothing.
         * @see @ref maxLabelLength(), @fn_gl{ObjectLabel} with @def_gl{BUFFER}
         *      or @fn_gl_extension2{LabelObject,EXT,debug_label} with
         *      @def_gl{BUFFER_OBJECT_EXT}
         */
        Buffer& setLabel(const std::string& label);

        /** @brief Target hint */
        Target targetHint() const { return _targetHint; }

        /**
         * @brief Set target hint
         * @return Reference to self (for method chaining)
         *
         * If @extension{EXT,direct_state_access} is not available, the buffer
         * must be internally bound to some target before any operation. You
         * can specify target which will always be used when binding the buffer
         * internally, possibly saving some calls to @fn_gl{BindBuffer}.
         *
         * Default target hint is @ref Target::Array.
         * @see @ref setData(), @ref setSubData()
         * @todo Target::ElementArray cannot be used when no VAO is bound -
         *      http://www.opengl.org/wiki/Vertex_Specification#Index_buffers
         *      ... damned GL state
         */
        Buffer& setTargetHint(Target hint) {
            _targetHint = hint;
            return *this;
        }

        /**
         * @brief Bind buffer
         * @param target    %Target
         *
         * @see @fn_gl{BindBuffer}
         * @todo Allow binding to Target::ElementArray only if VAO is bound
         *      to avoid potential issues?
         * @todo Don't allow user to bind buffers?
         * @bug Binding to ElementArray if any VAO is active will corrupt the mesh
         */
        void bind(Target target) { bind(target, _id); }

        /**
         * @brief %Buffer size
         *
         * If @extension{EXT,direct_state_access} is not available and the
         * buffer is not already bound somewhere, it is bound to hinted target
         * before the operation.
         * @see @fn_gl{BindBuffer} and @fn_gl{GetBufferParameter} or
         *      @fn_gl_extension{GetNamedBufferParameter,EXT,direct_state_access}
         *      with @def_gl{BUFFER_SIZE}
         */
        Int size();

        #ifndef MAGNUM_TARGET_GLES
        /**
         * @brief %Buffer data
         *
         * Returns data of whole buffer. If @extension{EXT,direct_state_access}
         * is not available and the buffer is not already bound somewhere, it
         * is bound to hinted target before the operation.
         * @see @ref size(), @ref subData(), @ref setData(), @fn_gl{BindBuffer}
         *      and @fn_gl{GetBufferParameter} or
         *      @fn_gl_extension{GetNamedBufferParameter,EXT,direct_state_access}
         *      with @def_gl{BUFFER_SIZE}, @fn_gl{GetBufferSubData} or
         *      @fn_gl_extension{GetNamedBufferSubData,EXT,direct_state_access}
         * @requires_gl %Buffer data queries are not available in OpenGL ES.
         *      Use @ref Magnum::Buffer::map() "map()" instead.
         */
        template<class T = unsigned char> Containers::Array<T> data();

        /**
         * @brief %Buffer subdata
         * @param offset    Byte offset in the buffer
         * @param size      Data size (count of @p T values)
         *
         * Returns data of given buffer portion. If @extension{EXT,direct_state_access}
         * is not available and the buffer is not already bound somewhere, it
         * is bound to hinted target before the operation.
         * @see @ref size(), @ref data(), @ref setSubData(), @fn_gl{BindBuffer}
         *      and @fn_gl{GetBufferSubData} or
         *      @fn_gl_extension{GetNamedBufferSubData,EXT,direct_state_access}
         * @requires_gl %Buffer data queries are not available in OpenGL ES.
         *      Use @ref Magnum::Buffer::map() "map()" instead.
         */
        template<class T = unsigned char> Containers::Array<T> subData(GLintptr offset, GLsizeiptr size);
        #endif

        /**
         * @brief Set buffer data
         * @param data      Data
         * @param usage     %Buffer usage
         * @return Reference to self (for method chaining)
         *
         * If @extension{EXT,direct_state_access} is not available and the
         * buffer is not already bound somewhere, it is bound to hinted target
         * before the operation.
         * @see @ref setTargetHint(), @fn_gl{BindBuffer} and @fn_gl{BufferData}
         *      or @fn_gl_extension{NamedBufferData,EXT,direct_state_access}
         */
        Buffer& setData(Containers::ArrayReference<const void> data, BufferUsage usage);

        /** @overload */
        template<class T> Buffer& setData(const std::vector<T>& data, BufferUsage usage) {
            setData({data.data(), data.size()}, usage);
            return *this;
        }

        /** @overload */
        template<std::size_t size, class T> Buffer& setData(const std::array<T, size>& data, BufferUsage usage) {
            setData({data.data(), data.size()}, usage);
            return *this;
        }

        /**
         * @brief Set buffer subdata
         * @param offset    Offset in the buffer
         * @param data      Data
         * @return Reference to self (for method chaining)
         *
         * If @extension{EXT,direct_state_access} is not available and the
         * buffer is not already bound somewhere, it is bound to hinted target
         * before the operation.
         * @see @ref setTargetHint(), @fn_gl{BindBuffer} and @fn_gl{BufferSubData}
         *      or @fn_gl_extension{NamedBufferSubData,EXT,direct_state_access}
         */
        Buffer& setSubData(GLintptr offset, Containers::ArrayReference<const void> data);

        /** @overload */
        template<class T> Buffer& setSubData(GLintptr offset, const std::vector<T>& data) {
            setSubData(offset, {data.data(), data.size()});
            return *this;
        }

        /** @overload */
        template<std::size_t size, class T> Buffer& setSubData(GLintptr offset, const std::array<T, size>& data) {
            setSubData(offset, {data.data(), data.size()});
            return *this;
        }

        /**
         * @brief Invalidate buffer data
         * @return Reference to self (for method chaining)
         *
         * If running on OpenGL ES or extension @extension{ARB,invalidate_subdata}
         * (part of OpenGL 4.3) is not available, this function does nothing.
         * @see @ref MapFlag::InvalidateBuffer, @fn_gl{InvalidateBufferData}
         */
        Buffer& invalidateData();

        /**
         * @brief Invalidate buffer subdata
         * @param offset    Offset into the buffer
         * @param length    Length of the invalidated range
         * @return Reference to self (for method chaining)
         *
         * If running on OpenGL ES or extension @extension{ARB,invalidate_subdata}
         * (part of OpenGL 4.3) is not available, this function does nothing.
         * @see @ref MapFlag::InvalidateRange, @fn_gl{InvalidateBufferData}
         */
        Buffer& invalidateSubData(GLintptr offset, GLsizeiptr length);

        /**
         * @brief Map buffer to client memory
         * @param access    Access
         * @return Pointer to buffer data
         *
         * If @extension{EXT,direct_state_access} is not available and the
         * buffer is not already bound somewhere, it is bound to hinted target
         * before the operation.
         * @see @ref minMapAlignment(), @ref unmap(), @ref setTargetHint(),
         *      @fn_gl{BindBuffer} and @fn_gl{MapBuffer} or
         *      @fn_gl_extension{MapNamedBuffer,EXT,direct_state_access}
         * @requires_es_extension %Extension @es_extension{OES,mapbuffer} in
         *      OpenGL ES 2.0, use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
         *      in OpenGL ES 3.0 instead.
         * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
         *      instead, as it has more complete set of features.
         */
        void* map(MapAccess access);

        #if defined(MAGNUM_TARGET_GLES2) || defined(DOXYGEN_GENERATING_OUTPUT)
        /**
         * @brief Map portion of buffer to client memory
         * @param offset    Offset into the buffer
         * @param length    Length of the mapped memory
         * @param access    Access
         * @return Pointer to buffer data
         *
         * If the buffer is not already bound somewhere, it is bound to hinted
         * target before the operation.
         * @see @ref unmapSub(), @ref setTargetHint(),
         *      @fn_gl_extension{MapBufferSubData,CHROMIUM,map_sub}
         * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use
         *      @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
         *      instead.
         * @requires_es_extension %Extension @es_extension{CHROMIUM,map_sub}
         * @deprecated_gl Prefer to use @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
         *      instead, as it has more complete set of features.
         */
        void* mapSub(GLintptr offset, GLsizeiptr length, MapAccess access);
        #endif

        /**
         * @brief Map buffer to client memory
         * @param offset    Offset into the buffer
         * @param length    Length of the mapped memory
         * @param flags     Flags. At least @ref MapFlag::Read or
         *      @ref MapFlag::Write must be specified.
         * @return Pointer to buffer data
         *
         * If @extension{EXT,direct_state_access} is not available and the
         * buffer is not already bound somewhere, it is bound to hinted target
         * before the operation.
         * @see @ref minMapAlignment(), @ref flushMappedRange(), @ref unmap(),
         *      @ref map(MapAccess), @ref setTargetHint(), @fn_gl{BindBuffer}
         *      and @fn_gl{MapBufferRange} or @fn_gl_extension{MapNamedBufferRange,EXT,direct_state_access}
         * @requires_gl30 %Extension @extension{ARB,map_buffer_range}
         * @requires_gles30 %Extension @es_extension{EXT,map_buffer_range} in
         *      OpenGL ES 2.0
         */
        void* map(GLintptr offset, GLsizeiptr length, MapFlags flags);

        /**
         * @brief Flush mapped range
         * @param offset    Offset relative to start of mapped range
         * @param length    Length of the flushed memory
         * @return Reference to self (for method chaining)
         *
         * Flushes specified subsection of mapped range. Use only if you called
         * @ref map() with @ref MapFlag::FlushExplicit flag. See
         * @ref Buffer-data-mapping "class documentation" for usage example.
         *
         * If @extension{EXT,direct_state_access} is not available and the
         * buffer is not already bound somewhere, it is bound to hinted target
         * before the operation.
         * @see @ref setTargetHint(), @fn_gl{BindBuffer} and @fn_gl{FlushMappedBufferRange}
         *      or @fn_gl_extension{FlushMappedNamedBufferRange,EXT,direct_state_access}
         * @requires_gl30 %Extension @extension{ARB,map_buffer_range}
         * @requires_gles30 %Extension @es_extension{EXT,map_buffer_range} in
         *      OpenGL ES 2.0
         */
        Buffer& flushMappedRange(GLintptr offset, GLsizeiptr length);

        /**
         * @brief Unmap buffer
         * @return `False` if the data have become corrupt during the time
         *      the buffer was mapped (e.g. after screen was resized), `true`
         *      otherwise.
         *
         * Unmaps buffer previously mapped with @ref map(), invalidating the
         * pointer returned by these functions. If @extension{EXT,direct_state_access}
         * is not available and the buffer is not already bound somewhere, it
         * is bound to hinted target before the operation.
         * @see setTargetHint(), @fn_gl{BindBuffer} and @fn_gl{UnmapBuffer} or
         *      @fn_gl_extension{UnmapNamedBuffer,EXT,direct_state_access}
         * @requires_gles30 %Extension @es_extension{OES,mapbuffer} in OpenGL
         *      ES 2.0
         */
        bool unmap();

        #if defined(MAGNUM_TARGET_GLES2) || defined(DOXYGEN_GENERATING_OUTPUT)
        /**
         * @brief Unmap portion of buffer
         *
         * Unmaps portion of buffer previously mapped with @ref mapSub(),
         * invalidating the pointer returned by the function.
         * @see @fn_gl_extension{UnmapBufferSubData,CHROMIUM,map_sub}
         * @requires_gles20 Not available in ES 3.0 or desktop OpenGL. Use
         *      @ref Magnum::Buffer::map(GLintptr, GLsizeiptr, MapFlags) "map(GLintptr, GLsizeiptr, MapFlags)"
         *      instead.
         * @requires_es_extension %Extension @es_extension{CHROMIUM,map_sub}
         */
        void unmapSub();
        #endif

    private:
        static void bind(Target hint, GLuint id);
        Target MAGNUM_LOCAL bindInternal(Target hint);

        #ifndef MAGNUM_TARGET_GLES2
        static void MAGNUM_LOCAL copyImplementationDefault(Buffer& read, Buffer& write, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size);
        #ifndef MAGNUM_TARGET_GLES
        static void MAGNUM_LOCAL copyImplementationDSA(Buffer& read, Buffer& write, GLintptr readOffset, GLintptr writeOffset, GLsizeiptr size);
        #endif
        #endif

        #ifndef MAGNUM_TARGET_GLES
        void subDataInternal(GLintptr offset, GLsizeiptr size, GLvoid* data);
        #endif

        void MAGNUM_LOCAL getParameterImplementationDefault(GLenum value, GLint* data);
        #ifndef MAGNUM_TARGET_GLES
        void MAGNUM_LOCAL getParameterImplementationDSA(GLenum value, GLint* data);
        #endif

        #ifndef MAGNUM_TARGET_GLES
        void MAGNUM_LOCAL getSubDataImplementationDefault(GLintptr offset, GLsizeiptr size, GLvoid* data);
        void MAGNUM_LOCAL getSubDataImplementationDSA(GLintptr offset, GLsizeiptr size, GLvoid* data);
        #endif

        void MAGNUM_LOCAL dataImplementationDefault(GLsizeiptr size, const GLvoid* data, BufferUsage usage);
        #ifndef MAGNUM_TARGET_GLES
        void MAGNUM_LOCAL dataImplementationDSA(GLsizeiptr size, const GLvoid* data, BufferUsage usage);
        #endif

        void MAGNUM_LOCAL subDataImplementationDefault(GLintptr offset, GLsizeiptr size, const GLvoid* data);
        #ifndef MAGNUM_TARGET_GLES
        void MAGNUM_LOCAL subDataImplementationDSA(GLintptr offset, GLsizeiptr size, const GLvoid* data);
        #endif

        void MAGNUM_LOCAL invalidateImplementationNoOp();
        #ifndef MAGNUM_TARGET_GLES
        void MAGNUM_LOCAL invalidateImplementationARB();
        #endif

        void MAGNUM_LOCAL invalidateSubImplementationNoOp(GLintptr offset, GLsizeiptr length);
        #ifndef MAGNUM_TARGET_GLES
        void MAGNUM_LOCAL invalidateSubImplementationARB(GLintptr offset, GLsizeiptr length);
        #endif

        void MAGNUM_LOCAL * mapImplementationDefault(MapAccess access);
        #ifndef MAGNUM_TARGET_GLES
        void MAGNUM_LOCAL * mapImplementationDSA(MapAccess access);
        #endif

        void MAGNUM_LOCAL * mapRangeImplementationDefault(GLintptr offset, GLsizeiptr length, MapFlags access);
        #ifndef MAGNUM_TARGET_GLES
        void MAGNUM_LOCAL * mapRangeImplementationDSA(GLintptr offset, GLsizeiptr length, MapFlags access);
        #endif

        void MAGNUM_LOCAL flushMappedRangeImplementationDefault(GLintptr offset, GLsizeiptr length);
        #ifndef MAGNUM_TARGET_GLES
        void MAGNUM_LOCAL flushMappedRangeImplementationDSA(GLintptr offset, GLsizeiptr length);
        #endif

        bool MAGNUM_LOCAL unmapImplementationDefault();
        #ifndef MAGNUM_TARGET_GLES
        bool MAGNUM_LOCAL unmapImplementationDSA();
        #endif

        GLuint _id;
        Target _targetHint;
        #ifdef CORRADE_TARGET_NACL
        void* _mappedBuffer;
        #endif
};

CORRADE_ENUMSET_OPERATORS(Buffer::MapFlags)

/** @debugoperatorclassenum{Magnum::Buffer,Magnum::Buffer::Target} */
Debug MAGNUM_EXPORT operator<<(Debug debug, Buffer::Target value);

inline Buffer::Buffer(Buffer&& other) noexcept: _id(other._id), _targetHint(other._targetHint) {
    other._id = 0;
}

inline Buffer& Buffer::operator=(Buffer&& other) noexcept {
    std::swap(_id, other._id);
    std::swap(_targetHint, other._targetHint);
    return *this;
}

#ifndef MAGNUM_TARGET_GLES
template<class T> Containers::Array<T> inline Buffer::data() {
    const Int bufferSize = size();
    #ifndef CORRADE_GCC45_COMPATIBILITY
    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);
    #else
    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), {});
    #endif
    return subData<T>(0, bufferSize/sizeof(T));
}

template<class T> Containers::Array<T> inline Buffer::subData(const GLintptr offset, const GLsizeiptr size) {
    Containers::Array<T> data(size);
    if(size) subDataInternal(offset, size*sizeof(T), data);
    return std::move(data);
}
#endif

}

#endif