Package org.lwjgl.opengl

Class 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:

    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.

    • Method Detail

      • 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,
                                       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 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,
                                      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

      • 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,
                                         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 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
                                          java.nio.IntBuffer length,
                                          java.nio.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 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 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 java.lang.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,
                                         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 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

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

      • 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 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,
                                   java.nio.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,
                                          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,
                                               @Nullable
                                               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