Class ARBUniformBufferObject

java.lang.Object
org.lwjgl.opengl.ARBUniformBufferObject

public class ARBUniformBufferObject extends 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:

  1. restructure their uniform data definitions into arrays or
  2. 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:

  1. A uniform is "active" if it exists in the database and has a valid u_index.
  2. A "uniform block" is "active" if it exists in the database and has a valid ub_index.
  3. 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.
  4. An inactive uniform has u_index == INVALID_INDEX.
  5. An inactive uniform block has ub_index == INVALID_INDEX.
  6. A u_index or ub_index of INVALID_INDEX generates the INVALID_VALUE error if given as a function argument.
  7. 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.
  8. An active uniform that is a member of the default uniform block has location ≥ 0 and it has offset == stride == -1.
  9. An active uniform that is a member of a named uniform block has location == -1.
  10. A uniform location of -1 is silently ignored if given as a function argument.
  11. Uniform block declarations may not be nested

Requires OpenGL 2.0 or ARB_shader_objects and OpenGL 1.5 or ARB_vertex_buffer_object. Promoted to core in OpenGL 3.1.

  • Field Details

    • GL_UNIFORM_BUFFER

      public static final int GL_UNIFORM_BUFFER
      Accepted by the target parameters of BindBuffer, BufferData, BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData, and GetBufferPointerv.
      See Also:
    • GL_UNIFORM_BUFFER_BINDING

      public static final int GL_UNIFORM_BUFFER_BINDING
      Accepted by the pname parameter of GetIntegeri_v, GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_UNIFORM_BUFFER_START

      public static final int GL_UNIFORM_BUFFER_START
      Accepted by the pname parameter of GetIntegeri_v.
      See Also:
    • GL_UNIFORM_BUFFER_SIZE

      public static final int GL_UNIFORM_BUFFER_SIZE
      Accepted by the pname parameter of GetIntegeri_v.
      See Also:
    • GL_MAX_VERTEX_UNIFORM_BLOCKS

      public static final int GL_MAX_VERTEX_UNIFORM_BLOCKS
      Accepted by the pname parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_MAX_GEOMETRY_UNIFORM_BLOCKS

      public static final int GL_MAX_GEOMETRY_UNIFORM_BLOCKS
      Accepted by the pname parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_MAX_FRAGMENT_UNIFORM_BLOCKS

      public static final int GL_MAX_FRAGMENT_UNIFORM_BLOCKS
      Accepted by the pname parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_MAX_COMBINED_UNIFORM_BLOCKS

      public static final int GL_MAX_COMBINED_UNIFORM_BLOCKS
      Accepted by the pname parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_MAX_UNIFORM_BUFFER_BINDINGS

      public static final int GL_MAX_UNIFORM_BUFFER_BINDINGS
      Accepted by the pname parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_MAX_UNIFORM_BLOCK_SIZE

      public static final int GL_MAX_UNIFORM_BLOCK_SIZE
      Accepted by the pname parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS

      public static final int GL_MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS
      Accepted by the pname parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS

      public static final int GL_MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS
      Accepted by the pname parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS

      public static final int GL_MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS
      Accepted by the pname parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_UNIFORM_BUFFER_OFFSET_ALIGNMENT

      public static final int GL_UNIFORM_BUFFER_OFFSET_ALIGNMENT
      Accepted by the pname parameter of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev.
      See Also:
    • GL_ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH

      public static final int GL_ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH
      Accepted by the pname parameter of GetProgramiv.
      See Also:
    • GL_ACTIVE_UNIFORM_BLOCKS

      public static final int GL_ACTIVE_UNIFORM_BLOCKS
      Accepted by the pname parameter of GetProgramiv.
      See Also:
    • GL_UNIFORM_TYPE

      public static final int GL_UNIFORM_TYPE
      Accepted by the pname parameter of GetActiveUniformsiv.
      See Also:
    • GL_UNIFORM_SIZE

      public static final int GL_UNIFORM_SIZE
      Accepted by the pname parameter of GetActiveUniformsiv.
      See Also:
    • GL_UNIFORM_NAME_LENGTH

      public static final int GL_UNIFORM_NAME_LENGTH
      Accepted by the pname parameter of GetActiveUniformsiv.
      See Also:
    • GL_UNIFORM_BLOCK_INDEX

      public static final int GL_UNIFORM_BLOCK_INDEX
      Accepted by the pname parameter of GetActiveUniformsiv.
      See Also:
    • GL_UNIFORM_OFFSET

      public static final int GL_UNIFORM_OFFSET
      Accepted by the pname parameter of GetActiveUniformsiv.
      See Also:
    • GL_UNIFORM_ARRAY_STRIDE

      public static final int GL_UNIFORM_ARRAY_STRIDE
      Accepted by the pname parameter of GetActiveUniformsiv.
      See Also:
    • GL_UNIFORM_MATRIX_STRIDE

      public static final int GL_UNIFORM_MATRIX_STRIDE
      Accepted by the pname parameter of GetActiveUniformsiv.
      See Also:
    • GL_UNIFORM_IS_ROW_MAJOR

      public static final int GL_UNIFORM_IS_ROW_MAJOR
      Accepted by the pname parameter of GetActiveUniformsiv.
      See Also:
    • GL_UNIFORM_BLOCK_BINDING

      public static final int GL_UNIFORM_BLOCK_BINDING
      Accepted by the pname parameter of GetActiveUniformBlockiv.
      See Also:
    • GL_UNIFORM_BLOCK_DATA_SIZE

      public static final int GL_UNIFORM_BLOCK_DATA_SIZE
      Accepted by the pname parameter of GetActiveUniformBlockiv.
      See Also:
    • GL_UNIFORM_BLOCK_NAME_LENGTH

      public static final int GL_UNIFORM_BLOCK_NAME_LENGTH
      Accepted by the pname parameter of GetActiveUniformBlockiv.
      See Also:
    • GL_UNIFORM_BLOCK_ACTIVE_UNIFORMS

      public static final int GL_UNIFORM_BLOCK_ACTIVE_UNIFORMS
      Accepted by the pname parameter of GetActiveUniformBlockiv.
      See Also:
    • GL_UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICES

      public static final int GL_UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICES
      Accepted by the pname parameter of GetActiveUniformBlockiv.
      See Also:
    • GL_UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER

      public static final int GL_UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER
      Accepted by the pname parameter of GetActiveUniformBlockiv.
      See Also:
    • GL_UNIFORM_BLOCK_REFERENCED_BY_GEOMETRY_SHADER

      public static final int GL_UNIFORM_BLOCK_REFERENCED_BY_GEOMETRY_SHADER
      Accepted by the pname parameter of GetActiveUniformBlockiv.
      See Also:
    • GL_UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER

      public static final int GL_UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER
      Accepted by the pname parameter of GetActiveUniformBlockiv.
      See Also:
    • GL_INVALID_INDEX

      public static final int GL_INVALID_INDEX
      Returned by GetActiveUniformsiv and GetUniformBlockIndex.
      See Also:
  • Method Details

    • nglGetUniformIndices

      public static void nglGetUniformIndices(int program, int uniformCount, long uniformNames, long uniformIndices)
      Unsafe version of: GetUniformIndices
      Parameters:
      uniformCount - the number of uniforms whose indices to query
    • glGetUniformIndices

      public static void glGetUniformIndices(int program, PointerBuffer uniformNames, 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 query
      uniformNames - an array of pointers to buffers containing the names of the queried uniforms
      uniformIndices - an array that will receive the indices of the uniforms
    • glGetUniformIndices

      public static void glGetUniformIndices(int program, CharSequence[] uniformNames, 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 query
      uniformNames - an array of pointers to buffers containing the names of the queried uniforms
      uniformIndices - an array that will receive the indices of the uniforms
    • glGetUniformIndices

      public static int glGetUniformIndices(int program, 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
    • nglGetActiveUniformsiv

      public static void nglGetActiveUniformsiv(int program, int uniformCount, long uniformIndices, int pname, long params)
      Unsafe version of: GetActiveUniformsiv
      Parameters:
      uniformCount - the number of elements in the array of indices uniformIndices and the number of parameters written to params upon successful return
    • glGetActiveUniformsiv

      public static void glGetActiveUniformsiv(int program, IntBuffer uniformIndices, int pname, IntBuffer params)
      Returns information about several active uniform variables for the specified program object.
      Parameters:
      program - the program object to be queried
      uniformIndices - an array of uniformCount integers containing the indices of uniforms within program
      pname - the property of the each uniform in uniformIndices that should be written into the corresponding element of params
      params - an array of uniformCount integers which are to receive the value of pname for each uniform in uniformIndices
    • 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 queried
      pname - the property of the each uniform in uniformIndices that should be written into the corresponding element of params
    • nglGetActiveUniformName

      public static void nglGetActiveUniformName(int program, int uniformIndex, int bufSize, long length, long uniformName)
      Unsafe version of: GetActiveUniformName
      Parameters:
      bufSize - the size of the buffer, in units of GLchar, of the buffer whose address is specified in uniformName
    • glGetActiveUniformName

      public static void glGetActiveUniformName(int program, int uniformIndex, @Nullable IntBuffer length, ByteBuffer uniformName)
      Queries the name of an active uniform.
      Parameters:
      program - the program containing the active uniform index uniformIndex
      uniformIndex - the index of the active uniform whose name to query
      length - the address of a variable that will receive the number of characters that were or would have been written to the buffer addressed by uniformName
      uniformName - the address of a buffer into which the GL will place the name of the active uniform at uniformIndex within program
    • glGetActiveUniformName

      public static String glGetActiveUniformName(int program, int uniformIndex, int bufSize)
      Queries the name of an active uniform.
      Parameters:
      program - the program containing the active uniform index uniformIndex
      uniformIndex - the index of the active uniform whose name to query
      bufSize - the size of the buffer, in units of GLchar, of the buffer whose address is specified in uniformName
    • glGetActiveUniformName

      public static String glGetActiveUniformName(int program, int uniformIndex)
      Queries the name of an active uniform.
      Parameters:
      program - the program containing the active uniform index uniformIndex
      uniformIndex - the index of the active uniform whose name to query
    • nglGetUniformBlockIndex

      public static int nglGetUniformBlockIndex(int program, long uniformBlockName)
      Unsafe version of: GetUniformBlockIndex
    • glGetUniformBlockIndex

      public static int glGetUniformBlockIndex(int program, ByteBuffer uniformBlockName)
      Retrieves the index of a named uniform block.
      Parameters:
      program - the name of a program containing the uniform block
      uniformBlockName - an array of characters to containing the name of the uniform block whose index to retrieve
    • glGetUniformBlockIndex

      public static int glGetUniformBlockIndex(int program, CharSequence uniformBlockName)
      Retrieves the index of a named uniform block.
      Parameters:
      program - the name of a program containing the uniform block
      uniformBlockName - an array of characters to containing the name of the uniform block whose index to retrieve
    • nglGetActiveUniformBlockiv

      public static void nglGetActiveUniformBlockiv(int program, int uniformBlockIndex, int pname, long params)
      Unsafe version of: GetActiveUniformBlockiv
    • glGetActiveUniformBlockiv

      public static void glGetActiveUniformBlockiv(int program, int uniformBlockIndex, int pname, IntBuffer params)
      Queries information about an active uniform block.
      Parameters:
      program - the name of a program containing the uniform block
      uniformBlockIndex - the index of the uniform block within program
      pname - the name of the parameter to query. One of:
      UNIFORM_BLOCK_BINDINGUNIFORM_BLOCK_DATA_SIZE
      UNIFORM_BLOCK_NAME_LENGTHUNIFORM_BLOCK_ACTIVE_UNIFORMS
      UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICESUNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER
      UNIFORM_BLOCK_REFERENCED_BY_GEOMETRY_SHADERUNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER
      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 block
      uniformBlockIndex - the index of the uniform block within program
      pname - the name of the parameter to query. One of:
      UNIFORM_BLOCK_BINDINGUNIFORM_BLOCK_DATA_SIZE
      UNIFORM_BLOCK_NAME_LENGTHUNIFORM_BLOCK_ACTIVE_UNIFORMS
      UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICESUNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER
      UNIFORM_BLOCK_REFERENCED_BY_GEOMETRY_SHADERUNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER
    • nglGetActiveUniformBlockName

      public static void nglGetActiveUniformBlockName(int program, int uniformBlockIndex, int bufSize, long length, long uniformBlockName)
      Unsafe version of: GetActiveUniformBlockName
      Parameters:
      bufSize - the size of the buffer addressed by uniformBlockName
    • glGetActiveUniformBlockName

      public static void glGetActiveUniformBlockName(int program, int uniformBlockIndex, @Nullable IntBuffer length, ByteBuffer uniformBlockName)
      Retrieves the name of an active uniform block.
      Parameters:
      program - the name of a program containing the uniform block
      uniformBlockIndex - the index of the uniform block within program
      length - the address of a variable to receive the number of characters that were written to uniformBlockName
      uniformBlockName - an array of characters to receive the name of the uniform block at uniformBlockIndex
    • glGetActiveUniformBlockName

      public static 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 block
      uniformBlockIndex - the index of the uniform block within program
      bufSize - the size of the buffer addressed by uniformBlockName
    • glGetActiveUniformBlockName

      public static String glGetActiveUniformBlockName(int program, int uniformBlockIndex)
      Retrieves the name of an active uniform block.
      Parameters:
      program - the name of a program containing the uniform block
      uniformBlockIndex - the index of the uniform block within program
    • 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_BUFFERUNIFORM_BUFFERATOMIC_COUNTER_BUFFERSHADER_STORAGE_BUFFER
      index - the index of the binding point within the array specified by target
      buffer - a buffer object to bind to the specified binding point
      offset - the starting offset in basic machine units into the buffer object buffer
      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_BUFFERUNIFORM_BUFFERATOMIC_COUNTER_BUFFERSHADER_STORAGE_BUFFER
      index - the index of the binding point within the array specified by target
      buffer - a buffer object to bind to the specified binding point
    • nglGetIntegeri_v

      public static void nglGetIntegeri_v(int target, int index, long data)
      Unsafe version of: GetIntegeri_v
    • glGetIntegeri_v

      public static void glGetIntegeri_v(int target, int index, IntBuffer data)
      Queries the integer value of an indexed state variable.
      Parameters:
      target - the indexed state to query
      index - the index of the element being queried
      data - 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 query
      index - 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 assign
      uniformBlockIndex - the index of the active uniform block within program whose binding to assign
      uniformBlockBinding - the binding point to which to bind the uniform block with index uniformBlockIndex within program
    • glGetUniformIndices

      public static void glGetUniformIndices(int program, 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, @Nullable int[] length, 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, @Nullable int[] length, ByteBuffer uniformBlockName)
      Array version of: GetActiveUniformBlockName
    • glGetIntegeri_v

      public static void glGetIntegeri_v(int target, int index, int[] data)
      Array version of: GetIntegeri_v