Package org.lwjgl.opengl

Class NVCommandList

java.lang.Object
org.lwjgl.opengl.NVCommandList
public class NVCommandList extends 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.

  • Field Details

    • GL_TERMINATE_SEQUENCE_COMMAND_NV

      public static final int GL_TERMINATE_SEQUENCE_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_NOP_COMMAND_NV

      public static final int GL_NOP_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_DRAW_ELEMENTS_COMMAND_NV

      public static final int GL_DRAW_ELEMENTS_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_DRAW_ARRAYS_COMMAND_NV

      public static final int GL_DRAW_ARRAYS_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_DRAW_ELEMENTS_STRIP_COMMAND_NV

      public static final int GL_DRAW_ELEMENTS_STRIP_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_DRAW_ARRAYS_STRIP_COMMAND_NV

      public static final int GL_DRAW_ARRAYS_STRIP_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_DRAW_ELEMENTS_INSTANCED_COMMAND_NV

      public static final int GL_DRAW_ELEMENTS_INSTANCED_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_DRAW_ARRAYS_INSTANCED_COMMAND_NV

      public static final int GL_DRAW_ARRAYS_INSTANCED_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_ELEMENT_ADDRESS_COMMAND_NV

      public static final int GL_ELEMENT_ADDRESS_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_ATTRIBUTE_ADDRESS_COMMAND_NV

      public static final int GL_ATTRIBUTE_ADDRESS_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_UNIFORM_ADDRESS_COMMAND_NV

      public static final int GL_UNIFORM_ADDRESS_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_BLEND_COLOR_COMMAND_NV

      public static final int GL_BLEND_COLOR_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_STENCIL_REF_COMMAND_NV

      public static final int GL_STENCIL_REF_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_LINE_WIDTH_COMMAND_NV

      public static final int GL_LINE_WIDTH_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_POLYGON_OFFSET_COMMAND_NV

      public static final int GL_POLYGON_OFFSET_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_ALPHA_REF_COMMAND_NV

      public static final int GL_ALPHA_REF_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_VIEWPORT_COMMAND_NV

      public static final int GL_VIEWPORT_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_SCISSOR_COMMAND_NV

      public static final int GL_SCISSOR_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

    • GL_FRONT_FACE_COMMAND_NV

      public static final int GL_FRONT_FACE_COMMAND_NV
      Used in DrawCommandsStates buffer formats, in GetCommandHeaderNV to return the header.
      See Also:

  • Method Details

    • nglCreateStatesNV

      public static void nglCreateStatesNV(int n, long states)
      Unsafe version of: CreateStatesNV
      Parameters:
      n - the number of state object names to create

    • glCreateStatesNV

      public static void glCreateStatesNV(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.

    • nglDeleteStatesNV

      public static void nglDeleteStatesNV(int n, long states)
      Unsafe version of: DeleteStatesNV
      Parameters:
      n - the number of state object names to delete

    • glDeleteStatesNV

      public static void glDeleteStatesNV(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

    • glGetCommandHeaderNV

      public static int glGetCommandHeaderNV(int tokenID, int size)
      Returns the encoded 32bit header value for a given command; the returned value is implementation specific.
      Parameters:
      tokenID - the command to query. One of:
      TERMINATE_SEQUENCE_COMMAND_NVNOP_COMMAND_NVDRAW_ELEMENTS_COMMAND_NV
      DRAW_ARRAYS_COMMAND_NVDRAW_ELEMENTS_STRIP_COMMAND_NVDRAW_ARRAYS_STRIP_COMMAND_NV
      DRAW_ELEMENTS_INSTANCED_COMMAND_NVDRAW_ARRAYS_INSTANCED_COMMAND_NVELEMENT_ADDRESS_COMMAND_NV
      ATTRIBUTE_ADDRESS_COMMAND_NVUNIFORM_ADDRESS_COMMAND_NVBLEND_COLOR_COMMAND_NV
      STENCIL_REF_COMMAND_NVLINE_WIDTH_COMMAND_NVPOLYGON_OFFSET_COMMAND_NV
      ALPHA_REF_COMMAND_NVVIEWPORT_COMMAND_NVSCISSOR_COMMAND_NV
      FRONT_FACE_COMMAND_NV
      size - provided as basic consistency check, since the size of each structure is fixed and no padding is allowed. The value is the sum of the header and the command specific structure.

    • 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

    • nglDrawCommandsNV

      public static void nglDrawCommandsNV(int primitiveMode, int buffer, long indirects, long sizes, int count)
      Unsafe version of: DrawCommandsNV
      Parameters:
      count - the number of commands

    • glDrawCommandsNV

      public static void glDrawCommandsNV(int primitiveMode, int buffer, org.lwjgl.PointerBuffer indirects, 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

    • nglDrawCommandsAddressNV

      public static void nglDrawCommandsAddressNV(int primitiveMode, long indirects, long sizes, int count)
      Unsafe version of: DrawCommandsAddressNV
      Parameters:
      count - the number of commands

    • glDrawCommandsAddressNV

      public static void glDrawCommandsAddressNV(int primitiveMode, LongBuffer indirects, 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

    • nglDrawCommandsStatesNV

      public static void nglDrawCommandsStatesNV(int buffer, long indirects, long sizes, long states, long fbos, int count)
      Unsafe version of: DrawCommandsStatesNV
      Parameters:
      count - the number of commands

    • glDrawCommandsStatesNV

      public static void glDrawCommandsStatesNV(int buffer, org.lwjgl.PointerBuffer indirects, IntBuffer sizes, IntBuffer states, 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

    • nglDrawCommandsStatesAddressNV

      public static void nglDrawCommandsStatesAddressNV(long indirects, long sizes, long states, long fbos, int count)
      Unsafe version of: DrawCommandsStatesAddressNV
      Parameters:
      count - the number of commands

    • glDrawCommandsStatesAddressNV

      public static void glDrawCommandsStatesAddressNV(LongBuffer indirects, IntBuffer sizes, IntBuffer states, 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

    • nglCreateCommandListsNV

      public static void nglCreateCommandListsNV(int n, long lists)
      Unsafe version of: CreateCommandListsNV
      Parameters:
      n - the number of command list names to create

    • glCreateCommandListsNV

      public static void glCreateCommandListsNV(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.

    • nglDeleteCommandListsNV

      public static void nglDeleteCommandListsNV(int n, long lists)
      Unsafe version of: DeleteCommandListsNV
      Parameters:
      n - the number of command list names to delete

    • glDeleteCommandListsNV

      public static void glDeleteCommandListsNV(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

    • nglListDrawCommandsStatesClientNV

      public static void nglListDrawCommandsStatesClientNV(int list, int segment, long indirects, long sizes, long states, long fbos, int count)
      Unsafe version of: ListDrawCommandsStatesClientNV
      Parameters:
      count - the number of commands

    • glListDrawCommandsStatesClientNV

      public static void glListDrawCommandsStatesClientNV(int list, int segment, org.lwjgl.PointerBuffer indirects, IntBuffer sizes, IntBuffer states, 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, int[] sizes, int[] states, int[] fbos)
      Array version of: ListDrawCommandsStatesClientNV