Class ARBUniformBufferObject
- java.lang.Object
-
- org.lwjgl.opengl.ARBUniformBufferObject
-
public class ARBUniformBufferObject extends java.lang.Object
Native bindings to the ARB_uniform_buffer_object extension.This extension introduces the concept of a group of GLSL uniforms known as a "uniform block", and the API mechanisms to store "uniform blocks" in GL buffer objects.
The extension also defines both a standard cross-platform layout in memory for uniform block data, as well as mechanisms to allow the GL to optimize the data layout in an implementation-defined manner.
Prior to this extension, the existing interface for modification of uniform values allowed modification of large numbers of values using glUniform* calls, but only for a single uniform name (or a uniform array) at a time. However, updating uniforms in this manner may not map well to heterogenous uniform data structures defined for a GL application and in these cases, the application is forced to either:
- restructure their uniform data definitions into arrays or
- make an excessive number of calls through the GL interface to one of the Uniform* variants.
These solutions have their disadvantages. Solution A imposes considerable development overhead on the application developer. Solution B may impose considerable run-time overhead on the application if the number of uniforms modified in a given frame of rendering is sufficiently large.
This extension provides a better alternative to either (A) or (B) by allowing buffer object backing for the storage associated with all uniforms of a given GLSL program.
Storing uniform blocks in buffer objects enables several key use cases:
- sharing of uniform data storage between program objects and between program stages
- rapid swapping of sets of previously defined uniforms by storing sets of uniform data on the GL server
- rapid updates of uniform data from both the client and the server
The data storage for a uniform block can be declared to use one of three layouts in memory: packed, shared, or std140.
- "packed" uniform blocks have an implementation-dependent data layout for efficiency, and unused uniforms may be eliminated by the compiler to save space.
- "shared" uniform blocks, the default layout, have an implementation-dependent data layout for efficiency, but the layout will be uniquely determined by the structure of the block, allowing data storage to be shared across programs.
- "std140" uniform blocks have a standard cross-platform cross-vendor layout (see below). Unused uniforms will not be eliminated.
Any uniforms not declared in a named uniform block are said to be part of the "default uniform block".
While uniforms in the default uniform block are updated with glUniform* entry points and can have static initializers, uniforms in named uniform blocks are not. Instead, uniform block data is updated using the routines that update buffer objects and can not use static initializers.
Rules and Concepts Guiding this Specification:
For reference, a uniform has a "uniform index" (subsequently referred to as "u_index) and also a "uniform location" to efficiently identify it in the uniform data store of the implementation. We subsequently refer to this uniform data store of the implementation as the "uniform database".
A "uniform block" only has a "uniform block index" used for queries and connecting the "uniform block" to a buffer object. A "uniform block" has no "location" because "uniform blocks" are not updated directly. The buffer object APIs are used instead.
Properties of Uniforms and uniform blocks:
- A uniform is "active" if it exists in the database and has a valid u_index.
- A "uniform block" is "active" if it exists in the database and has a valid ub_index.
- Uniforms and "uniform blocks" can be inactive because they don't exist in the source, or because they have been removed by dead code elimination.
- An inactive uniform has u_index ==
INVALID_INDEX
. - An inactive uniform block has ub_index ==
INVALID_INDEX
. - A u_index or ub_index of
INVALID_INDEX
generates theINVALID_VALUE
error if given as a function argument. - The default uniform block, which is not assigned any ub_index, uses a private, internal data storage, and does not have any buffer object associated with it.
- An active uniform that is a member of the default uniform block has location >= 0 and it has offset == stride == -1.
- An active uniform that is a member of a named uniform block has location == -1.
- A uniform location of -1 is silently ignored if given as a function argument.
- Uniform block declarations may not be nested
Requires
OpenGL 2.0
orARB_shader_objects
andOpenGL 1.5
orARB_vertex_buffer_object
. Promoted to core inOpenGL 3.1
.
-
-
Field Summary
Fields Modifier and Type Field and Description static int
GL_ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH
GL_ACTIVE_UNIFORM_BLOCKSAccepted by thepname
parameter of GetProgramiv.static int
GL_INVALID_INDEX
Returned by GetActiveUniformsiv and GetUniformBlockIndex.static int
GL_MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS
GL_MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS
GL_MAX_COMBINED_UNIFORM_BLOCKS
GL_MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS
GL_MAX_FRAGMENT_UNIFORM_BLOCKS
GL_MAX_GEOMETRY_UNIFORM_BLOCKS
GL_MAX_UNIFORM_BLOCK_SIZE
GL_MAX_UNIFORM_BUFFER_BINDINGS
GL_MAX_VERTEX_UNIFORM_BLOCKSAccepted by thepname
parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.static int
GL_UNIFORM_ARRAY_STRIDE
Accepted by thepname
parameter of GetActiveUniformsiv.static int
GL_UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICES
GL_UNIFORM_BLOCK_ACTIVE_UNIFORMS
GL_UNIFORM_BLOCK_BINDING
GL_UNIFORM_BLOCK_DATA_SIZEAccepted by thepname
parameter of GetActiveUniformBlockiv.static int
GL_UNIFORM_BLOCK_INDEX
Accepted by thepname
parameter of GetActiveUniformsiv.static int
GL_UNIFORM_BLOCK_NAME_LENGTH
GL_UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER
GL_UNIFORM_BLOCK_REFERENCED_BY_GEOMETRY_SHADER
GL_UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADERAccepted by thepname
parameter of GetActiveUniformBlockiv.static int
GL_UNIFORM_BUFFER
Accepted by thetarget
parameters of BindBuffer, BufferData, BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData, and GetBufferPointerv.static int
GL_UNIFORM_BUFFER_BINDING
Accepted by thepname
parameter of GetIntegeri_v, GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.static int
GL_UNIFORM_BUFFER_OFFSET_ALIGNMENT
Accepted by thepname
parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.static int
GL_UNIFORM_BUFFER_SIZE
GL_UNIFORM_BUFFER_STARTAccepted by thepname
parameter of GetIntegeri_v.static int
GL_UNIFORM_IS_ROW_MAJOR
GL_UNIFORM_MATRIX_STRIDE
GL_UNIFORM_NAME_LENGTH
GL_UNIFORM_OFFSET
GL_UNIFORM_SIZE
GL_UNIFORM_TYPEAccepted by thepname
parameter of GetActiveUniformsiv.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method and Description static void
glBindBufferBase(int target, int index, int buffer)
Binds a buffer object to an indexed buffer target.static void
glBindBufferRange(int target, int index, int buffer, long offset, long size)
Binds a range within a buffer object to an indexed buffer target.static int
glGetActiveUniformBlocki(int program, int uniformBlockIndex, int pname)
Queries information about an active uniform block.static void
glGetActiveUniformBlockiv(int program, int uniformBlockIndex, int pname, int[] params)
Array version of:GetActiveUniformBlockiv
static void
glGetActiveUniformBlockiv(int program, int uniformBlockIndex, int pname, java.nio.IntBuffer params)
Queries information about an active uniform block.static java.lang.String
glGetActiveUniformBlockName(int program, int uniformBlockIndex)
Retrieves the name of an active uniform block.static java.lang.String
glGetActiveUniformBlockName(int program, int uniformBlockIndex, int bufSize)
Retrieves the name of an active uniform block.static void
glGetActiveUniformBlockName(int program, int uniformBlockIndex, int[] length, java.nio.ByteBuffer uniformBlockName)
Array version of:GetActiveUniformBlockName
static void
glGetActiveUniformBlockName(int program, int uniformBlockIndex, java.nio.IntBuffer length, java.nio.ByteBuffer uniformBlockName)
Retrieves the name of an active uniform block.static java.lang.String
glGetActiveUniformName(int program, int uniformIndex)
Queries the name of an active uniform.static java.lang.String
glGetActiveUniformName(int program, int uniformIndex, int bufSize)
Queries the name of an active uniform.static void
glGetActiveUniformName(int program, int uniformIndex, int[] length, java.nio.ByteBuffer uniformName)
Array version of:GetActiveUniformName
static void
glGetActiveUniformName(int program, int uniformIndex, java.nio.IntBuffer length, java.nio.ByteBuffer uniformName)
Queries the name of an active uniform.static int
glGetActiveUniformsi(int program, int uniformIndex, int pname)
Returns information about several active uniform variables for the specified program object.static void
glGetActiveUniformsiv(int program, int[] uniformIndices, int pname, int[] params)
Array version of:GetActiveUniformsiv
static void
glGetActiveUniformsiv(int program, java.nio.IntBuffer uniformIndices, int pname, java.nio.IntBuffer params)
Returns information about several active uniform variables for the specified program object.static void
glGetIntegeri_v(int target, int index, int[] data)
Array version of:GetIntegeri_v
static void
glGetIntegeri_v(int target, int index, java.nio.IntBuffer data)
Queries the integer value of an indexed state variable.static int
glGetIntegeri(int target, int index)
Queries the integer value of an indexed state variable.static int
glGetUniformBlockIndex(int program, java.nio.ByteBuffer uniformBlockName)
Retrieves the index of a named uniform block.static int
glGetUniformBlockIndex(int program, java.lang.CharSequence uniformBlockName)
Retrieves the index of a named uniform block.static int
glGetUniformIndices(int program, java.lang.CharSequence uniformName)
Retrieves the indices of a number of uniforms within a program objectstatic void
glGetUniformIndices(int program, java.lang.CharSequence[] uniformNames, java.nio.IntBuffer uniformIndices)
Retrieves the indices of a number of uniforms within a program objectstatic void
glGetUniformIndices(int program, org.lwjgl.PointerBuffer uniformNames, int[] uniformIndices)
Array version of:GetUniformIndices
static void
glGetUniformIndices(int program, org.lwjgl.PointerBuffer uniformNames, java.nio.IntBuffer uniformIndices)
Retrieves the indices of a number of uniforms within a program objectstatic void
glUniformBlockBinding(int program, int uniformBlockIndex, int uniformBlockBinding)
Assigns a binding point to an active uniform block.
-
-
-
Field Detail
-
GL_UNIFORM_BUFFER
Accepted by thetarget
parameters of BindBuffer, BufferData, BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData, and GetBufferPointerv.
-
GL_UNIFORM_BUFFER_BINDING
Accepted by thepname
parameter of GetIntegeri_v, GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
-
GL_UNIFORM_BUFFER_START, GL_UNIFORM_BUFFER_SIZE
Accepted by thepname
parameter of GetIntegeri_v.
-
GL_MAX_VERTEX_UNIFORM_BLOCKS, GL_MAX_GEOMETRY_UNIFORM_BLOCKS, GL_MAX_FRAGMENT_UNIFORM_BLOCKS, GL_MAX_COMBINED_UNIFORM_BLOCKS, GL_MAX_UNIFORM_BUFFER_BINDINGS, GL_MAX_UNIFORM_BLOCK_SIZE, GL_MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS, GL_MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS, GL_MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS, GL_UNIFORM_BUFFER_OFFSET_ALIGNMENT
Accepted by thepname
parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
-
GL_ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH, GL_ACTIVE_UNIFORM_BLOCKS
Accepted by thepname
parameter of GetProgramiv.
-
GL_UNIFORM_TYPE, GL_UNIFORM_SIZE, GL_UNIFORM_NAME_LENGTH, GL_UNIFORM_BLOCK_INDEX, GL_UNIFORM_OFFSET, GL_UNIFORM_ARRAY_STRIDE, GL_UNIFORM_MATRIX_STRIDE, GL_UNIFORM_IS_ROW_MAJOR
Accepted by thepname
parameter of GetActiveUniformsiv.
-
GL_UNIFORM_BLOCK_BINDING, GL_UNIFORM_BLOCK_DATA_SIZE, GL_UNIFORM_BLOCK_NAME_LENGTH, GL_UNIFORM_BLOCK_ACTIVE_UNIFORMS, GL_UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICES, GL_UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER, GL_UNIFORM_BLOCK_REFERENCED_BY_GEOMETRY_SHADER, GL_UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER
Accepted by thepname
parameter of GetActiveUniformBlockiv.
-
GL_INVALID_INDEX
Returned by GetActiveUniformsiv and GetUniformBlockIndex.
-
-
Method Detail
-
glGetUniformIndices
public static void glGetUniformIndices(int program, org.lwjgl.PointerBuffer uniformNames, java.nio.IntBuffer uniformIndices) public static void glGetUniformIndices(int program, java.lang.CharSequence[] uniformNames, java.nio.IntBuffer uniformIndices)
Retrieves the indices of a number of uniforms within a program object- Parameters:
program
- the name of a program containing uniforms whose indices to queryuniformNames
- an array of pointers to buffers containing the names of the queried uniformsuniformIndices
- an array that will receive the indices of the uniforms
-
glGetUniformIndices
public static int glGetUniformIndices(int program, java.lang.CharSequence uniformName)
Retrieves the indices of a number of uniforms within a program object- Parameters:
program
- the name of a program containing uniforms whose indices to query
-
glGetActiveUniformsiv
public static void glGetActiveUniformsiv(int program, java.nio.IntBuffer uniformIndices, int pname, java.nio.IntBuffer params)
Returns information about several active uniform variables for the specified program object.- Parameters:
program
- the program object to be querieduniformIndices
- an array ofuniformCount
integers containing the indices of uniforms withinprogram
pname
- the property of the each uniform inuniformIndices
that should be written into the corresponding element ofparams
params
- an array ofuniformCount
integers which are to receive the value ofpname
for each uniform inuniformIndices
-
glGetActiveUniformsi
public static int glGetActiveUniformsi(int program, int uniformIndex, int pname)
Returns information about several active uniform variables for the specified program object.- Parameters:
program
- the program object to be queriedpname
- the property of the each uniform inuniformIndices
that should be written into the corresponding element ofparams
-
glGetActiveUniformName
public static void glGetActiveUniformName(int program, int uniformIndex, java.nio.IntBuffer length, java.nio.ByteBuffer uniformName)
Queries the name of an active uniform.- Parameters:
program
- the program containing the active uniform indexuniformIndex
uniformIndex
- the index of the active uniform whose name to querylength
- the address of a variable that will receive the number of characters that were or would have been written to the buffer addressed byuniformName
uniformName
- the address of a buffer into which the GL will place the name of the active uniform atuniformIndex
withinprogram
-
glGetActiveUniformName
public static java.lang.String glGetActiveUniformName(int program, int uniformIndex, int bufSize)
Queries the name of an active uniform.- Parameters:
program
- the program containing the active uniform indexuniformIndex
uniformIndex
- the index of the active uniform whose name to querybufSize
- the size of the buffer, in units ofGLchar
, of the buffer whose address is specified inuniformName
-
glGetActiveUniformName
public static java.lang.String glGetActiveUniformName(int program, int uniformIndex)
Queries the name of an active uniform.- Parameters:
program
- the program containing the active uniform indexuniformIndex
uniformIndex
- the index of the active uniform whose name to query
-
glGetUniformBlockIndex
public static int glGetUniformBlockIndex(int program, java.nio.ByteBuffer uniformBlockName) public static int glGetUniformBlockIndex(int program, java.lang.CharSequence uniformBlockName)
Retrieves the index of a named uniform block.- Parameters:
program
- the name of a program containing the uniform blockuniformBlockName
- an array of characters to containing the name of the uniform block whose index to retrieve
-
glGetActiveUniformBlockiv
public static void glGetActiveUniformBlockiv(int program, int uniformBlockIndex, int pname, java.nio.IntBuffer params)
Queries information about an active uniform block.- Parameters:
program
- the name of a program containing the uniform blockuniformBlockIndex
- the index of the uniform block withinprogram
pname
- the name of the parameter to query. One of:params
- the address of a variable to receive the result of the query
-
glGetActiveUniformBlocki
public static int glGetActiveUniformBlocki(int program, int uniformBlockIndex, int pname)
Queries information about an active uniform block.- Parameters:
program
- the name of a program containing the uniform blockuniformBlockIndex
- the index of the uniform block withinprogram
pname
- the name of the parameter to query. One of:
-
glGetActiveUniformBlockName
public static void glGetActiveUniformBlockName(int program, int uniformBlockIndex, java.nio.IntBuffer length, java.nio.ByteBuffer uniformBlockName)
Retrieves the name of an active uniform block.- Parameters:
program
- the name of a program containing the uniform blockuniformBlockIndex
- the index of the uniform block withinprogram
length
- the address of a variable to receive the number of characters that were written touniformBlockName
uniformBlockName
- an array of characters to receive the name of the uniform block atuniformBlockIndex
-
glGetActiveUniformBlockName
public static java.lang.String glGetActiveUniformBlockName(int program, int uniformBlockIndex, int bufSize)
Retrieves the name of an active uniform block.- Parameters:
program
- the name of a program containing the uniform blockuniformBlockIndex
- the index of the uniform block withinprogram
bufSize
- the size of the buffer addressed byuniformBlockName
-
glGetActiveUniformBlockName
public static java.lang.String glGetActiveUniformBlockName(int program, int uniformBlockIndex)
Retrieves the name of an active uniform block.- Parameters:
program
- the name of a program containing the uniform blockuniformBlockIndex
- the index of the uniform block withinprogram
-
glBindBufferRange
public static void glBindBufferRange(int target, int index, int buffer, long offset, long size)
Binds a range within a buffer object to an indexed buffer target.- Parameters:
target
- the target of the bind operation. One of:TRANSFORM_FEEDBACK_BUFFER
UNIFORM_BUFFER
ATOMIC_COUNTER_BUFFER
SHADER_STORAGE_BUFFER
index
- the index of the binding point within the array specified bytarget
buffer
- a buffer object to bind to the specified binding pointoffset
- the starting offset in basic machine units into the buffer objectbuffer
size
- the amount of data in machine units that can be read from the buffer object while used as an indexed target
-
glBindBufferBase
public static void glBindBufferBase(int target, int index, int buffer)
Binds a buffer object to an indexed buffer target.- Parameters:
target
- the target of the bind operation. One of:TRANSFORM_FEEDBACK_BUFFER
UNIFORM_BUFFER
ATOMIC_COUNTER_BUFFER
SHADER_STORAGE_BUFFER
index
- the index of the binding point within the array specified bytarget
buffer
- a buffer object to bind to the specified binding point
-
glGetIntegeri_v
public static void glGetIntegeri_v(int target, int index, java.nio.IntBuffer data)
Queries the integer value of an indexed state variable.- Parameters:
target
- the indexed state to queryindex
- the index of the element being querieddata
- a scalar or buffer in which to place the returned data
-
glGetIntegeri
public static int glGetIntegeri(int target, int index)
Queries the integer value of an indexed state variable.- Parameters:
target
- the indexed state to queryindex
- the index of the element being queried
-
glUniformBlockBinding
public static void glUniformBlockBinding(int program, int uniformBlockIndex, int uniformBlockBinding)
Assigns a binding point to an active uniform block.- Parameters:
program
- the name of a program object containing the active uniform block whose binding to assignuniformBlockIndex
- the index of the active uniform block withinprogram
whose binding to assignuniformBlockBinding
- the binding point to which to bind the uniform block with indexuniformBlockIndex
withinprogram
-
glGetUniformIndices
public static void glGetUniformIndices(int program, org.lwjgl.PointerBuffer uniformNames, int[] uniformIndices)
Array version of:GetUniformIndices
-
glGetActiveUniformsiv
public static void glGetActiveUniformsiv(int program, int[] uniformIndices, int pname, int[] params)
Array version of:GetActiveUniformsiv
-
glGetActiveUniformName
public static void glGetActiveUniformName(int program, int uniformIndex, int[] length, java.nio.ByteBuffer uniformName)
Array version of:GetActiveUniformName
-
glGetActiveUniformBlockiv
public static void glGetActiveUniformBlockiv(int program, int uniformBlockIndex, int pname, int[] params)
Array version of:GetActiveUniformBlockiv
-
glGetActiveUniformBlockName
public static void glGetActiveUniformBlockName(int program, int uniformBlockIndex, int[] length, java.nio.ByteBuffer uniformBlockName)
Array version of:GetActiveUniformBlockName
-
glGetIntegeri_v
public static void glGetIntegeri_v(int target, int index, int[] data)
Array version of:GetIntegeri_v
-
-