Package org.lwjgl.opengl

Class NVCommandList


  • public class NVCommandList
extends java.lang.Object
    Native bindings to the NV_command_list extension.

    This extension adds a few new features designed to provide very low overhead batching and replay of rendering commands and state changes:

    • A state object, which stores a pre-validated representation of the state of (almost) the entire pipeline.
    • A more flexible and extensible MultiDrawIndirect (MDI) type of mechanism, using a token-based command stream, allowing to setup binding state and emit draw calls.
    • A set of functions to execute a list of the token-based command streams with state object changes interleaved with the streams.
    • Command lists enabling compilation and reuse of sequences of command streams and state object changes.

    Because state objects reflect the state of the entire pipeline, it is expected that they can be pre-validated and executed efficiently. It is also expected that when state objects are combined into a command list, the command list can diff consecutive state objects to produce a reduced/ optimized set of state changes specific to that transition.

    The token-based command stream can also be stored in regular buffer objects and therefore be modified by the server itself. This allows more complex work creation than the original MDI approach, which was limited to emitting draw calls only.

    Command structures

    typedef struct {
  uint  header;
} TerminateSequenceCommandNV;

typedef struct {
  uint  header;
} NOPCommandNV;

typedef  struct {
  uint  header;
  uint  count;
  uint  firstIndex;
  uint  baseVertex;
} DrawElementsCommandNV;

typedef  struct {
  uint  header;
  uint  count;
  uint  first;
} DrawArraysCommandNV;

typedef  struct {
  uint  header;
  uint  mode;
  uint  count;
  uint  instanceCount;
  uint  firstIndex;
  uint  baseVertex;
  uint  baseInstance;
} DrawElementsInstancedCommandNV;

typedef  struct {
  uint  header;
  uint  mode;
  uint  count;
  uint  instanceCount;
  uint  first;
  uint  baseInstance;
} DrawArraysInstancedCommandNV;

typedef struct {
  uint  header;
  uint  addressLo;
  uint  addressHi;
  uint  typeSizeInByte;
} ElementAddressCommandNV;

typedef struct {
  uint  header;
  uint  index;
  uint  addressLo;
  uint  addressHi;
} AttributeAddressCommandNV;

typedef struct {
  uint    header;
  ushort  index;
  ushort  stage;
  uint    addressLo;
  uint    addressHi;
} UniformAddressCommandNV;

typedef struct {
  uint  header;
  float red;
  float green;
  float blue;
  float alpha;
} BlendColorCommandNV;

typedef struct {
  uint  header;
  uint  frontStencilRef;
  uint  backStencilRef;
} StencilRefCommandNV;

typedef struct {
  uint  header;
  float lineWidth;
} LineWidthCommandNV;

typedef struct {
  uint  header;
  float scale;
  float bias;
} PolygonOffsetCommandNV;

typedef struct {
  uint  header;
  float alphaRef;
} AlphaRefCommandNV;

typedef struct {
  uint  header;
  uint  x;
  uint  y;
  uint  width;
  uint  height;
} ViewportCommandNV; // only ViewportIndex 0

typedef struct {
  uint  header;
  uint  x;
  uint  y;
  uint  width;
  uint  height;
} ScissorCommandNV; // only ViewportIndex 0

typedef struct {
  uint  header;
  uint  frontFace; // 0 for CW, 1 for CCW
} FrontFaceCommandNV;

    Tight packing is used for all structures.

    • Method Detail

      • glCreateStatesNV

        public static void glCreateStatesNV(java.nio.IntBuffer states)
        Returns n previously unused state object names in states, and creates a state object in the initial state for each name.
        Parameters:
        states - the buffer in which to write the created state object names

      • glCreateStatesNV

        public static int glCreateStatesNV()
        Returns n previously unused state object names in states, and creates a state object in the initial state for each name.

      • glDeleteStatesNV

        public static void glDeleteStatesNV(java.nio.IntBuffer states)
        Deletes n names of state objects given by states. Once a state object is deleted it has no contents and its name is again unused. Unused names in states are silently ignored, as is the value zero.
        Parameters:
        states - the buffer from which to read the state object names to delete

      • glDeleteStatesNV

        public static void glDeleteStatesNV(int state)
        Deletes n names of state objects given by states. Once a state object is deleted it has no contents and its name is again unused. Unused names in states are silently ignored, as is the value zero.

      • glIsStateNV

        public static boolean glIsStateNV(int state)
        Returns true if the specified name corresponds to a state object.
        Parameters:
        state - the object name to test

      • glStateCaptureNV

        public static void glStateCaptureNV(int state,
                                    int mode)
        Captures the current state of the rendering pipeline into the object indicated by state.

        The captured rendering state includes:

        • Vertex attribute enable state, formats, types, relative offsets and strides, but not bound vertex buffers or vertex unified addresses, nor their offsets, nor bound index buffers/addresses.
        • Primitive state such as primitive restart and patch parameters, provoking vertex.
        • Immediate vertex attribute values as provided by glVertexAttrib* or glVertexAttribI*
        • All active program binaries except compute (either from the active program pipeline or from UseProgram) with their current subroutine configuration excluding all default-block uniform values.
        • Rasterization, multisample fragment operation, depth, stencil, and blending state.
        • Rasterization state such as line widths, stippling, polygon modes and offsets.
        • Viewport, scissor, and depth range state.
        • Framebuffer attachment configuration: attachment state including attachment formats, drawbuffer state, and target/layer information, but not including actual attachments or sizes of attachments (these are stored separately).
        • Framebuffer attachment textures (but not residency state).
        Parameters:
        state - the state object into which to capture the current rendering state
        mode - the basic Begin mode that this state object must be used with. One of:
        POINTSLINESTRIANGLESQUADSLINES_ADJACENCYTRIANGLES_ADJACENCYPATCHES

      • glGetStageIndexNV

        public static short glGetStageIndexNV(int shadertype)
        Returns the 16bit value for a specific shader stage; the returned value is implementation specific. The value is to be used with the stage field within UniformAddressCommandNV tokens.
        Parameters:
        shadertype - the shader stage type

      • glDrawCommandsNV

        public static void glDrawCommandsNV(int primitiveMode,
                                    int buffer,
                                    org.lwjgl.PointerBuffer indirects,
                                    java.nio.IntBuffer sizes)
        Accepts arrays of buffer addresses as an array of offsets indirects into a buffer named by buffer, an array of command lengths in sizes. All arrays have count entries.
        Parameters:
        primitiveMode - the primitive mode
        buffer - the buffer object name
        indirects - the array of offsets into the buffer
        sizes - the array of command lengths

      • glDrawCommandsAddressNV

        public static void glDrawCommandsAddressNV(int primitiveMode,
                                           java.nio.LongBuffer indirects,
                                           java.nio.IntBuffer sizes)
        Accepts arrays of buffer addresses as an array of GPU addresses indirects, an array of sequence lengths in sizes. All arrays have count entries.
        Parameters:
        primitiveMode - the primitive mode
        indirects - the array of GPU addreses
        sizes - the array of command lengths

      • glDrawCommandsStatesNV

        public static void glDrawCommandsStatesNV(int buffer,
                                          org.lwjgl.PointerBuffer indirects,
                                          java.nio.IntBuffer sizes,
                                          java.nio.IntBuffer states,
                                          java.nio.IntBuffer fbos)
        Accepts arrays of buffer addresses as an array of offsets indirects into a buffer named by buffer, an array of command lengths in sizes, and an array of state object names in states, of which all names must be non-zero. Frame buffer object names are stored in fbos and can be either zero or non-zero. All arrays have count entries. The residency of textures used as attachment inside the state object's captured fbo or the passed fbo must managed explicitly.
        Parameters:
        buffer - the buffer object name
        indirects - the array of offsets into the buffer
        sizes - the array of command lengths
        states - the array of state object names
        fbos - the array of framebuffer object names

      • glDrawCommandsStatesAddressNV

        public static void glDrawCommandsStatesAddressNV(java.nio.LongBuffer indirects,
                                                 java.nio.IntBuffer sizes,
                                                 java.nio.IntBuffer states,
                                                 java.nio.IntBuffer fbos)
        Accepts arrays of buffer addresses as an array of GPU addresses indirects, an array of command lengths in sizes, and an array of state object names in states, of which all names must be non-zero. Frame buffer object names are stored in fbos and can be either zero or non-zero. All arrays have count entries. The residency of textures used as attachment inside the state object's captured fbo or the passed fbo must managed explicitly.
        Parameters:
        indirects - the array of GPU addresses
        sizes - the array of command lengths
        states - the array of state object names
        fbos - the array of framebuffer object names

      • glCreateCommandListsNV

        public static void glCreateCommandListsNV(java.nio.IntBuffer lists)
        Returns n previously unused command list names in lists, and creates a command list in the initial state for each name.
        Parameters:
        lists - the buffer in which to return the created command list names

      • glCreateCommandListsNV

        public static int glCreateCommandListsNV()
        Returns n previously unused command list names in lists, and creates a command list in the initial state for each name.

      • glDeleteCommandListsNV

        public static void glDeleteCommandListsNV(java.nio.IntBuffer lists)
        Deletes n command lists stored in lists. Once a command list is deleted it has no contents and its name is again unused. Unused names in lists are silently ignored, as is the value zero.
        Parameters:
        lists - the buffer from which to read the command list names to delete

      • glDeleteCommandListsNV

        public static void glDeleteCommandListsNV(int list)
        Deletes n command lists stored in lists. Once a command list is deleted it has no contents and its name is again unused. Unused names in lists are silently ignored, as is the value zero.

      • glIsCommandListNV

        public static boolean glIsCommandListNV(int list)
        Returns true if the specified name corresponds to a command list.
        Parameters:
        list - the object name to query

      • glListDrawCommandsStatesClientNV

        public static void glListDrawCommandsStatesClientNV(int list,
                                                    int segment,
                                                    org.lwjgl.PointerBuffer indirects,
                                                    org.lwjgl.PointerBuffer sizes,
                                                    java.nio.IntBuffer states,
                                                    java.nio.IntBuffer fbos)
        A list has multiple segments and each segment enqueues an ordered list of commands. This command enqueues the equivalent of the DrawCommandsStatesClientNV commands into the list indicated by list on the segment indicated by segment.

        A list has multiple segments and each segment enqueues an ordered list of command sequences. This command enqueues the equivalent of the DrawCommandsStatesNV commands into the list indicated by list on the segment indicated by segment except that the sequence data is copied from the sequences pointed to by the indirects pointer. The indirects pointer should point to a list of size count of pointers, each of which should point to a command sequence.

        The pre-validated state from states is saved into the command list, rather than a reference to the state object (i.e. the state objects or fbos could be deleted and the command list would be unaffected). This includes native GPU addresses for all textures indirectly referenced through the fbos passed or state objects' fbos attachments, therefore a recompile of the command list is required if such referenced textures change their allocation (for example due to resizing), as well as explicit management of the residency of the textures prior CallCommandListNV.

        ListDrawCommandsStatesClientNV performs a by-value copy of the indirect data based on the provided client-side pointers. In this case the content is fully immutable, while the buffer-based versions can change the content of the buffers at any later time.

        Parameters:
        list - the command list
        segment - the segment
        indirects - the array of GPU addresses
        sizes - the array of command lengths
        states - the array of state object names
        fbos - the array of framebuffer object names

      • glCommandListSegmentsNV

        public static void glCommandListSegmentsNV(int list,
                                           int segments)
        Indicates that list will have segments number of segments, each of which is a list of command sequences that it enqueues. This must be called before any commands are enqueued. In the initial state, a command list has a single segment.
        Parameters:
        list - the command list
        segments - the number of ordered sequences of commands

      • glCompileCommandListNV

        public static void glCompileCommandListNV(int list)
        Makes the list indicated by list switch from allowing collection of commands to allowing its execution. At this time, the implementation may generate optimized commands to transition between states as efficiently as possible.
        Parameters:
        list - the command list to compile

      • glCallCommandListNV

        public static void glCallCommandListNV(int list)
        Executes the command list indicated by list, which operates as if the DrawCommandsStates* commands were replayed in the order they were enqueued on each segment, starting from segment zero and proceeding to the maximum segment. All buffer or texture resources' residency must be managed explicitly, including texture attachments of the effective fbos during list enqueuing.
        Parameters:
        list - the command list to call

      • glCreateStatesNV

        public static void glCreateStatesNV(int[] states)
        Array version of: CreateStatesNV

      • glDeleteStatesNV

        public static void glDeleteStatesNV(int[] states)
        Array version of: DeleteStatesNV

      • glDrawCommandsNV

        public static void glDrawCommandsNV(int primitiveMode,
                                    int buffer,
                                    org.lwjgl.PointerBuffer indirects,
                                    int[] sizes)
        Array version of: DrawCommandsNV

      • glDrawCommandsAddressNV

        public static void glDrawCommandsAddressNV(int primitiveMode,
                                           long[] indirects,
                                           int[] sizes)
        Array version of: DrawCommandsAddressNV

      • glDrawCommandsStatesNV

        public static void glDrawCommandsStatesNV(int buffer,
                                          org.lwjgl.PointerBuffer indirects,
                                          int[] sizes,
                                          int[] states,
                                          int[] fbos)
        Array version of: DrawCommandsStatesNV

      • glDrawCommandsStatesAddressNV

        public static void glDrawCommandsStatesAddressNV(long[] indirects,
                                                 int[] sizes,
                                                 int[] states,
                                                 int[] fbos)
        Array version of: DrawCommandsStatesAddressNV

      • glCreateCommandListsNV

        public static void glCreateCommandListsNV(int[] lists)
        Array version of: CreateCommandListsNV

      • glDeleteCommandListsNV

        public static void glDeleteCommandListsNV(int[] lists)
        Array version of: DeleteCommandListsNV

      • glListDrawCommandsStatesClientNV

        public static void glListDrawCommandsStatesClientNV(int list,
                                                    int segment,
                                                    org.lwjgl.PointerBuffer indirects,
                                                    org.lwjgl.PointerBuffer sizes,
                                                    int[] states,
                                                    int[] fbos)
        Array version of: ListDrawCommandsStatesClientNV