Class ARBBufferStorage


  • public class ARBBufferStorage
    extends java.lang.Object
    Native bindings to the ARB_buffer_storage extension.

    OpenGL has long supported buffer objects as a means of storing data that may be used to source vertex attributes, pixel data for textures, uniforms and other elements. In un-extended GL, buffer data stores are mutable - that is, they may be de-allocated or resized while they are in use. The ARB_texture_storage extension added immutable storage for texture object (and was subsequently incorporated into OpenGL 4.2). This extension further applies the concept of immutable storage to buffer objects. If an implementation is aware of a buffer's immutability, it may be able to make certain assumptions or apply particular optimizations in order to increase performance or reliability.

    Furthermore, this extension allows applications to pass additional information about a requested allocation to the implementation which it may use to select memory heaps, caching behavior or allocation strategies.

    Finally, this extension introduces the concept of persistent client mappings of buffer objects, which allow clients to retain pointers to a buffer's data store returned as the result of a mapping, and to issue drawing commands while those mappings are in place.

    Promoted to core in OpenGL 4.4.

    • Method Detail

      • nglBufferStorage

        public static void nglBufferStorage​(int target,
                                            long size,
                                            long data,
                                            int flags)
        Unsafe version of: BufferStorage
        Parameters:
        size - the size of the data store in basic machine units
      • glBufferStorage

        public static void glBufferStorage​(int target,
                                           long size,
                                           int flags)
        Creates the data store of a buffer object.

        The data store of the buffer object bound to target is allocated as a result of a call to this function and cannot be de-allocated until the buffer is deleted with a call to DeleteBuffers. Such a store may not be re-allocated through further calls to BufferStorage or BufferData.

        BufferStorage deletes any existing data store. If any portion of the buffer object is mapped in the current context or any context current to another thread, it is as though UnmapBuffer is executed in each such context prior to deleting the existing data store.

        Parameters:
        target - the buffer object target. One of:
        ARRAY_BUFFERELEMENT_ARRAY_BUFFERPIXEL_PACK_BUFFERPIXEL_UNPACK_BUFFER
        TRANSFORM_FEEDBACK_BUFFERUNIFORM_BUFFERTEXTURE_BUFFERCOPY_READ_BUFFER
        COPY_WRITE_BUFFERDRAW_INDIRECT_BUFFERATOMIC_COUNTER_BUFFERDISPATCH_INDIRECT_BUFFER
        SHADER_STORAGE_BUFFERPARAMETER_BUFFER_ARB
        size - the size of the data store in basic machine units
        flags - the bitwise OR of flags describing the intended usage of the buffer object's data store by the application. Valid flags and their meanings are as follows:
        • DYNAMIC_STORAGE_BIT – The contents of the data store may be updated after creation through calls to BufferSubData. If this bit is not set, the buffer content may not be directly updated by the client. The data argument may be used to specify the initial content of the buffer's data store regardless of the presence of the DYNAMIC_STORAGE_BIT. Regardless of the presence of this bit, buffers may always be updated with server-side calls such as CopyBufferSubData and ClearBufferSubData.
        • MAP_READ_BIT – The buffer's data store may be mapped by the client for read access and a pointer in the client's address space obtained that may be read from.
        • MAP_WRITE_BIT – The buffer's data store may be mapped by the client for write access and a pointer in the client's address space obtained that may be written to.
        • MAP_PERSISTENT_BIT – The client may request that the server read from or write to the buffer while it is mapped. The client's pointer to the data store remains valid so long as the data store is mapped, even during execution of drawing or dispatch commands.
        • MAP_COHERENT_BIT – Shared access to buffers that are simultaneously mapped for client access and are used by the server will be coherent, so long as that mapping is performed using MapBufferRange. That is, data written to the store by either the client or server will be immediately visible to the other with no further action taken by the application. In particular:
        • CLIENT_STORAGE_BIT – When all other criteria for the buffer storage allocation are met, this bit may be used by an implementation to determine whether to use storage that is local to the server or to the client to serve as the backing store for the buffer.

        If flags contains MAP_PERSISTENT_BIT, it must also contain at least one of MAP_READ_BIT or MAP_WRITE_BIT.

        It is an error to specify MAP_COHERENT_BIT without also specifying MAP_PERSISTENT_BIT.

      • glBufferStorage

        public static void glBufferStorage​(int target,
                                           java.nio.ByteBuffer data,
                                           int flags)
        
        public static void glBufferStorage​(int target,
                                           java.nio.ShortBuffer data,
                                           int flags)
        
        public static void glBufferStorage​(int target,
                                           java.nio.IntBuffer data,
                                           int flags)
        
        public static void glBufferStorage​(int target,
                                           java.nio.FloatBuffer data,
                                           int flags)
        
        public static void glBufferStorage​(int target,
                                           java.nio.DoubleBuffer data,
                                           int flags)
        
        Creates the data store of a buffer object.

        The data store of the buffer object bound to target is allocated as a result of a call to this function and cannot be de-allocated until the buffer is deleted with a call to DeleteBuffers. Such a store may not be re-allocated through further calls to BufferStorage or BufferData.

        BufferStorage deletes any existing data store. If any portion of the buffer object is mapped in the current context or any context current to another thread, it is as though UnmapBuffer is executed in each such context prior to deleting the existing data store.

        Parameters:
        target - the buffer object target. One of:
        ARRAY_BUFFERELEMENT_ARRAY_BUFFERPIXEL_PACK_BUFFERPIXEL_UNPACK_BUFFER
        TRANSFORM_FEEDBACK_BUFFERUNIFORM_BUFFERTEXTURE_BUFFERCOPY_READ_BUFFER
        COPY_WRITE_BUFFERDRAW_INDIRECT_BUFFERATOMIC_COUNTER_BUFFERDISPATCH_INDIRECT_BUFFER
        SHADER_STORAGE_BUFFERPARAMETER_BUFFER_ARB
        data - the address in client memory of the data that should be used to initialize the buffer's data store. If data is NULL, the data store of the buffer is created, but contains undefined data. Otherwise, data should point to an array of at least size basic machine units.
        flags - the bitwise OR of flags describing the intended usage of the buffer object's data store by the application. Valid flags and their meanings are as follows:
        • DYNAMIC_STORAGE_BIT – The contents of the data store may be updated after creation through calls to BufferSubData. If this bit is not set, the buffer content may not be directly updated by the client. The data argument may be used to specify the initial content of the buffer's data store regardless of the presence of the DYNAMIC_STORAGE_BIT. Regardless of the presence of this bit, buffers may always be updated with server-side calls such as CopyBufferSubData and ClearBufferSubData.
        • MAP_READ_BIT – The buffer's data store may be mapped by the client for read access and a pointer in the client's address space obtained that may be read from.
        • MAP_WRITE_BIT – The buffer's data store may be mapped by the client for write access and a pointer in the client's address space obtained that may be written to.
        • MAP_PERSISTENT_BIT – The client may request that the server read from or write to the buffer while it is mapped. The client's pointer to the data store remains valid so long as the data store is mapped, even during execution of drawing or dispatch commands.
        • MAP_COHERENT_BIT – Shared access to buffers that are simultaneously mapped for client access and are used by the server will be coherent, so long as that mapping is performed using MapBufferRange. That is, data written to the store by either the client or server will be immediately visible to the other with no further action taken by the application. In particular:
        • CLIENT_STORAGE_BIT – When all other criteria for the buffer storage allocation are met, this bit may be used by an implementation to determine whether to use storage that is local to the server or to the client to serve as the backing store for the buffer.

        If flags contains MAP_PERSISTENT_BIT, it must also contain at least one of MAP_READ_BIT or MAP_WRITE_BIT.

        It is an error to specify MAP_COHERENT_BIT without also specifying MAP_PERSISTENT_BIT.

      • nglNamedBufferStorageEXT

        public static void nglNamedBufferStorageEXT​(int buffer,
                                                    long size,
                                                    long data,
                                                    int flags)
        Unsafe version of: NamedBufferStorageEXT
        Parameters:
        size - the size of the data store in basic machine units
      • glNamedBufferStorageEXT

        public static void glNamedBufferStorageEXT​(int buffer,
                                                   long size,
                                                   int flags)
        Behaves similarly to BufferStorage, except that the buffer whose storage is to be defined is specified by buffer rather than by the current binding to target.
        Parameters:
        buffer - the buffer object
        size - the size of the data store in basic machine units
        flags - the bitwise OR of flags describing the intended usage of the buffer object's data store by the application. Valid flags and their meanings are as follows:
        • DYNAMIC_STORAGE_BIT – The contents of the data store may be updated after creation through calls to BufferSubData. If this bit is not set, the buffer content may not be directly updated by the client. The data argument may be used to specify the initial content of the buffer's data store regardless of the presence of the DYNAMIC_STORAGE_BIT. Regardless of the presence of this bit, buffers may always be updated with server-side calls such as CopyBufferSubData and ClearBufferSubData.
        • MAP_READ_BIT – The buffer's data store may be mapped by the client for read access and a pointer in the client's address space obtained that may be read from.
        • MAP_WRITE_BIT – The buffer's data store may be mapped by the client for write access and a pointer in the client's address space obtained that may be written to.
        • MAP_PERSISTENT_BIT – The client may request that the server read from or write to the buffer while it is mapped. The client's pointer to the data store remains valid so long as the data store is mapped, even during execution of drawing or dispatch commands.
        • MAP_COHERENT_BIT – Shared access to buffers that are simultaneously mapped for client access and are used by the server will be coherent, so long as that mapping is performed using MapBufferRange. That is, data written to the store by either the client or server will be immediately visible to the other with no further action taken by the application. In particular:
        • CLIENT_STORAGE_BIT – When all other criteria for the buffer storage allocation are met, this bit may be used by an implementation to determine whether to use storage that is local to the server or to the client to serve as the backing store for the buffer.

        If flags contains MAP_PERSISTENT_BIT, it must also contain at least one of MAP_READ_BIT or MAP_WRITE_BIT.

        It is an error to specify MAP_COHERENT_BIT without also specifying MAP_PERSISTENT_BIT.

      • glNamedBufferStorageEXT

        public static void glNamedBufferStorageEXT​(int buffer,
                                                   java.nio.ByteBuffer data,
                                                   int flags)
        
        public static void glNamedBufferStorageEXT​(int buffer,
                                                   java.nio.ShortBuffer data,
                                                   int flags)
        
        public static void glNamedBufferStorageEXT​(int buffer,
                                                   java.nio.IntBuffer data,
                                                   int flags)
        
        public static void glNamedBufferStorageEXT​(int buffer,
                                                   java.nio.FloatBuffer data,
                                                   int flags)
        
        public static void glNamedBufferStorageEXT​(int buffer,
                                                   java.nio.DoubleBuffer data,
                                                   int flags)
        
        Behaves similarly to BufferStorage, except that the buffer whose storage is to be defined is specified by buffer rather than by the current binding to target.
        Parameters:
        buffer - the buffer object
        data - the address in client memory of the data that should be used to initialize the buffer's data store. If data is NULL, the data store of the buffer is created, but contains undefined data. Otherwise, data should point to an array of at least size basic machine units.
        flags - the bitwise OR of flags describing the intended usage of the buffer object's data store by the application. Valid flags and their meanings are as follows:
        • DYNAMIC_STORAGE_BIT – The contents of the data store may be updated after creation through calls to BufferSubData. If this bit is not set, the buffer content may not be directly updated by the client. The data argument may be used to specify the initial content of the buffer's data store regardless of the presence of the DYNAMIC_STORAGE_BIT. Regardless of the presence of this bit, buffers may always be updated with server-side calls such as CopyBufferSubData and ClearBufferSubData.
        • MAP_READ_BIT – The buffer's data store may be mapped by the client for read access and a pointer in the client's address space obtained that may be read from.
        • MAP_WRITE_BIT – The buffer's data store may be mapped by the client for write access and a pointer in the client's address space obtained that may be written to.
        • MAP_PERSISTENT_BIT – The client may request that the server read from or write to the buffer while it is mapped. The client's pointer to the data store remains valid so long as the data store is mapped, even during execution of drawing or dispatch commands.
        • MAP_COHERENT_BIT – Shared access to buffers that are simultaneously mapped for client access and are used by the server will be coherent, so long as that mapping is performed using MapBufferRange. That is, data written to the store by either the client or server will be immediately visible to the other with no further action taken by the application. In particular:
        • CLIENT_STORAGE_BIT – When all other criteria for the buffer storage allocation are met, this bit may be used by an implementation to determine whether to use storage that is local to the server or to the client to serve as the backing store for the buffer.

        If flags contains MAP_PERSISTENT_BIT, it must also contain at least one of MAP_READ_BIT or MAP_WRITE_BIT.

        It is an error to specify MAP_COHERENT_BIT without also specifying MAP_PERSISTENT_BIT.

      • glBufferStorage

        public static void glBufferStorage​(int target,
                                           short[] data,
                                           int flags)
        
        public static void glBufferStorage​(int target,
                                           int[] data,
                                           int flags)
        
        public static void glBufferStorage​(int target,
                                           float[] data,
                                           int flags)
        
        public static void glBufferStorage​(int target,
                                           double[] data,
                                           int flags)
        
        Array version of: BufferStorage
      • glNamedBufferStorageEXT

        public static void glNamedBufferStorageEXT​(int buffer,
                                                   short[] data,
                                                   int flags)
        
        public static void glNamedBufferStorageEXT​(int buffer,
                                                   int[] data,
                                                   int flags)
        
        public static void glNamedBufferStorageEXT​(int buffer,
                                                   float[] data,
                                                   int flags)
        
        public static void glNamedBufferStorageEXT​(int buffer,
                                                   double[] data,
                                                   int flags)
        
        Array version of: NamedBufferStorageEXT