Package org.lwjgl.opengl

Class ARBBufferStorage

java.lang.Object

org.lwjgl.opengl.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.

Field Summary

Fields

Modifier and Type	Field and Description
static int	GL_BUFFER_IMMUTABLE_STORAGE GL_BUFFER_STORAGE_FLAGS Accepted by the pname parameter of GetBufferParameter{i|i64}v.
static int	GL_CLIENT_MAPPED_BUFFER_BARRIER_BIT Accepted by the barriers parameter of MemoryBarrier.
static int	GL_CLIENT_STORAGE_BIT GL_DYNAMIC_STORAGE_BIT GL_MAP_COHERENT_BIT GL_MAP_PERSISTENT_BIT Accepted in the flags parameter of BufferStorage and NamedBufferStorageEXT.

Method Summary

Modifier and Type	Method and Description
static void	glBufferStorage(int target, java.nio.ByteBuffer data, int flags) Creates the data store of a buffer object.
static void	glBufferStorage(int target, double[] data, int flags) Array version of: BufferStorage
static void	glBufferStorage(int target, java.nio.DoubleBuffer data, int flags) Creates the data store of a buffer object.
static void	glBufferStorage(int target, float[] data, int flags) Array version of: BufferStorage
static void	glBufferStorage(int target, java.nio.FloatBuffer data, int flags) Creates the data store of a buffer object.
static void	glBufferStorage(int target, int[] data, int flags) Array version of: BufferStorage
static void	glBufferStorage(int target, java.nio.IntBuffer data, int flags) Creates the data store of a buffer object.
static void	glBufferStorage(int target, long size, int flags) Creates the data store of a buffer object.
static void	glBufferStorage(int target, short[] data, int flags) Array version of: BufferStorage
static void	glBufferStorage(int target, java.nio.ShortBuffer data, int flags) Creates the data store of a buffer object.
static void	glNamedBufferStorageEXT(int buffer, java.nio.ByteBuffer 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.
static void	glNamedBufferStorageEXT(int buffer, double[] data, int flags) Array version of: NamedBufferStorageEXT
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.
static void	glNamedBufferStorageEXT(int buffer, float[] data, int flags) Array version of: NamedBufferStorageEXT
static void	glNamedBufferStorageEXT(int buffer, java.nio.FloatBuffer 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.
static void	glNamedBufferStorageEXT(int buffer, int[] data, int flags) Array version of: NamedBufferStorageEXT
static void	glNamedBufferStorageEXT(int buffer, java.nio.IntBuffer 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.
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.
static void	glNamedBufferStorageEXT(int buffer, short[] data, int flags) Array version of: NamedBufferStorageEXT
static void	glNamedBufferStorageEXT(int buffer, java.nio.ShortBuffer 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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GL_MAP_PERSISTENT_BIT, GL_MAP_COHERENT_BIT, GL_DYNAMIC_STORAGE_BIT, GL_CLIENT_STORAGE_BIT

Accepted in the flags parameter of BufferStorage and NamedBufferStorageEXT.

GL_BUFFER_IMMUTABLE_STORAGE, GL_BUFFER_STORAGE_FLAGS

Accepted by the pname parameter of GetBufferParameter{i|i64}v.

GL_CLIENT_MAPPED_BUFFER_BARRIER_BIT

Accepted by the barriers parameter of MemoryBarrier.

Method Detail

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_BUFFER	ELEMENT_ARRAY_BUFFER	PIXEL_PACK_BUFFER	PIXEL_UNPACK_BUFFER
TRANSFORM_FEEDBACK_BUFFER	UNIFORM_BUFFER	TEXTURE_BUFFER	COPY_READ_BUFFER
COPY_WRITE_BUFFER	DRAW_INDIRECT_BUFFER	ATOMIC_COUNTER_BUFFER	DISPATCH_INDIRECT_BUFFER
SHADER_STORAGE_BUFFER	PARAMETER_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:
  • If MAP_COHERENT_BIT is not set and the client performs a write followed by a call to the MemoryBarrier command with the CLIENT_MAPPED_BUFFER_BARRIER_BIT set, then in subsequent commands the server will see the writes.
  • If MAP_COHERENT_BIT is set and the client performs a write, then in subsequent commands the server will see the writes.
  • If MAP_COHERENT_BIT is not set and the server performs a write, the application must call MemoryBarrier with the CLIENT_MAPPED_BUFFER_BARRIER_BIT set and then call FenceSync with SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the CPU will see the writes after the sync is complete.
  • If MAP_COHERENT_BIT is set and the server does a write, the app must call FenceSync with SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the CPU will see the writes after the sync is complete.
• 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_BUFFER	ELEMENT_ARRAY_BUFFER	PIXEL_PACK_BUFFER	PIXEL_UNPACK_BUFFER
TRANSFORM_FEEDBACK_BUFFER	UNIFORM_BUFFER	TEXTURE_BUFFER	COPY_READ_BUFFER
COPY_WRITE_BUFFER	DRAW_INDIRECT_BUFFER	ATOMIC_COUNTER_BUFFER	DISPATCH_INDIRECT_BUFFER
SHADER_STORAGE_BUFFER	PARAMETER_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:
  • If MAP_COHERENT_BIT is not set and the client performs a write followed by a call to the MemoryBarrier command with the CLIENT_MAPPED_BUFFER_BARRIER_BIT set, then in subsequent commands the server will see the writes.
  • If MAP_COHERENT_BIT is set and the client performs a write, then in subsequent commands the server will see the writes.
  • If MAP_COHERENT_BIT is not set and the server performs a write, the application must call MemoryBarrier with the CLIENT_MAPPED_BUFFER_BARRIER_BIT set and then call FenceSync with SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the CPU will see the writes after the sync is complete.
  • If MAP_COHERENT_BIT is set and the server does a write, the app must call FenceSync with SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the CPU will see the writes after the sync is complete.
• 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,
                                           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:
  • If MAP_COHERENT_BIT is not set and the client performs a write followed by a call to the MemoryBarrier command with the CLIENT_MAPPED_BUFFER_BARRIER_BIT set, then in subsequent commands the server will see the writes.
  • If MAP_COHERENT_BIT is set and the client performs a write, then in subsequent commands the server will see the writes.
  • If MAP_COHERENT_BIT is not set and the server performs a write, the application must call MemoryBarrier with the CLIENT_MAPPED_BUFFER_BARRIER_BIT set and then call FenceSync with SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the CPU will see the writes after the sync is complete.
  • If MAP_COHERENT_BIT is set and the server does a write, the app must call FenceSync with SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the CPU will see the writes after the sync is complete.
• 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:
  • If MAP_COHERENT_BIT is not set and the client performs a write followed by a call to the MemoryBarrier command with the CLIENT_MAPPED_BUFFER_BARRIER_BIT set, then in subsequent commands the server will see the writes.
  • If MAP_COHERENT_BIT is set and the client performs a write, then in subsequent commands the server will see the writes.
  • If MAP_COHERENT_BIT is not set and the server performs a write, the application must call MemoryBarrier with the CLIENT_MAPPED_BUFFER_BARRIER_BIT set and then call FenceSync with SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the CPU will see the writes after the sync is complete.
  • If MAP_COHERENT_BIT is set and the server does a write, the app must call FenceSync with SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the CPU will see the writes after the sync is complete.
• 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