blob: 50517402322f462bc57b7019903a17ada26f9ccc [file] [log] [blame]
Name
ARB_draw_indirect
Name Strings
GL_ARB_draw_indirect
Contact
Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com)
Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com)
Contributors
Barthold Lichtenbelt, NVIDIA
Bill Licea-Kane, AMD
Bruce Merry, ARM
Graham Sellers, AMD
Greg Roth, NVIDIA
Nick Haemel, AMD
Pierre Boudier, AMD
Piers Daniell, NVIDIA
Notice
Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Specification Update Policy
Khronos-approved extension specifications are updated in response to
issues and bugs prioritized by the Khronos OpenGL Working Group. For
extensions which have been promoted to a core Specification, fixes will
first appear in the latest version of that core Specification, and will
eventually be backported to the extension document. This policy is
described in more detail at
https://www.khronos.org/registry/OpenGL/docs/update_policy.php
Status
Complete. Approved by the ARB at the 2010/01/22 F2F meeting.
Approved by the Khronos Board of Promoters on March 10, 2010.
Version
Last Modified Date: 09/17/2012
Revision: 7
Number
ARB Extension #87
Dependencies
OpenGL 3.1 is required.
This extension is written against the OpenGL 3.2 specification with
the Compatibility Profile.
This extension interacts with NV_vertex_buffer_unified_memory.
This extension interacts with ARB_instanced_arrays.
This extension interacts with ARB_compatibility.
Overview
This extension provides a mechanism for supplying the arguments to a
DrawArraysInstanced or DrawElementsInstancedBaseVertex from buffer object
memory. This is not particularly useful for applications where the CPU
knows the values of the arguments beforehand, but is helpful when the
values will be generated on the GPU through any mechanism that can write
to a buffer object including image stores, atomic counters, or compute
interop. This allows the GPU to consume these arguments without a round-
trip to the CPU or the expensive synchronization that would involve. This
is similar to the DrawTransformFeedbackEXT command from
EXT_transform_feedback2, but offers much more flexibility in both
generating the arguments and in the type of Draws that can be accomplished.
IP Status
No known IP claims.
New Procedures and Functions
void DrawArraysIndirect(enum mode, const void *indirect);
void DrawElementsIndirect(enum mode, enum type, const void *indirect);
New Tokens
Accepted by the <target> parameters of BindBuffer, BufferData,
BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData,
GetBufferPointerv, MapBufferRange, FlushMappedBufferRange,
GetBufferParameteriv, and CopyBufferSubData:
DRAW_INDIRECT_BUFFER 0x8F3F
Accepted by the <value> parameter of GetIntegerv, GetBooleanv, GetFloatv,
and GetDoublev:
DRAW_INDIRECT_BUFFER_BINDING 0x8F43
Additions to Chapter 2 of the OpenGL 3.2 Specification (OpenGL Operation)
Add to Section 2.8.1 p. 40 (Drawing Commands)
The command
DrawArraysIndirect(enum mode, const void *indirect);
behaves as follows:
typedef struct {
GLuint count;
GLuint primCount;
GLuint first;
GLuint reservedMustBeZero;
} DrawArraysIndirectCommand;
if (mode is invalid) {
generate appropriate error
} else {
DrawArraysIndirectCommand *cmd = (DrawArraysIndirectCommand *)indirect;
DrawArraysInstanced(mode, cmd->first, cmd->count, cmd->primCount);
}
As with regular DrawArraysInstanced commands, the vertex attributes
may be sourced from client arrays or vertex buffer objects (if buffers
are bound). Unlike regular DrawArraysInstanced commands, the <first>
argument is unsigned and cannot cause an error. The results are undefined
if <reservedMustBeZero> is non-zero and may not result in program
termination.
The command
DrawElementsIndirect(enum mode, enum type, const void *indirect);
behaves as follows:
typedef struct {
GLuint count;
GLuint primCount;
GLuint firstIndex;
GLint baseVertex;
GLuint reservedMustBeZero;
} DrawElementsIndirectCommand;
if (mode or type is invalid, or no index buffer) {
generate appropriate error
} else {
DrawElementsIndirectCommand *cmd = (DrawElementsIndirectCommand *)indirect;
DrawElementsInstancedBaseVertex(mode, cmd->count, type,
cmd->firstIndex * size-of-type, cmd->primCount, cmd->baseVertex);
}
As with regular DrawElementsInstancedBaseVertex commands, the vertex
attributes may be sourced from client arrays or vertex buffer objects
(if objects are bound). Unlike regular DrawElementsInstancedBaseVertex
commands, the indices may not come from a client array and must come from
an index buffer. If no element array buffer is bound, an INVALID_OPERATION
error is generated. The results are undefined if <reservedMustBeZero> is
non-zero and may not result in program termination.
All elements of DrawArraysIndirectCommand and
DrawElementsIndirectCommand are 32bit values, and both structures are
tightly packed.
Add to Section 2.9 (Buffer Objects)
Add to Table 2.7 (p. 48):
Target name Purpose Described in sections(s)
----------------------- ---------- -------------------------
DRAW_INDIRECT_BUFFER Indirect draw commands 2.9.9
Add a new Section 2.9.9 (Indirect Commands in Buffer Objects)
Arguments to DrawArraysIndirect and DrawElementsIndirect commands
may be stored in buffer objects.
Initially zero is bound to DRAW_INDIRECT_BUFFER. In the
compatibility profile, this indicates that DrawArraysIndirect and
DrawElementsIndirect are to source their arguments directly from the
pointer passed as their <indirect> parameters. In the core profile,
an INVALID_OPERATION error is generated if zero is bound to
DRAW_INDIRECT_BUFFER and DrawArraysIndirect or DrawElementsIndirect
is called.
A buffer object is bound to DRAW_INDIRECT_BUFFER by calling
BindBuffer with <target> set to DRAW_INDIRECT_BUFFER, and <buffer>
set to the name of the buffer object. If no corresponding buffer
object exists, one is initialized as defined in section 2.9.
While a non-zero buffer object name is bound to DRAW_INDIRECT_BUFFER,
DrawArraysIndirect and DrawElementsIndirect source their arguments
from that buffer object, using their <indirect> parameters as offsets
into the buffer object in the same fashion as described in section 2.9.3.
An INVALID_OPERATION error is generated if the commands source data
beyond the end of the buffer object or if <indirect> is not word aligned.
Additions to Chapter 3 of the OpenGL 3.2 Specification (Rasterization)
None.
Additions to Chapter 4 of the OpenGL 3.2 Specification (Per-Fragment
Operations and the Frame Buffer)
None.
Additions to Chapter 5 of the OpenGL 3.2 Specification (Special Functions)
None.
Additions to Chapter 6 of the OpenGL 3.2 Specification (State and
State Requests)
None.
Additions to Appendix A of the OpenGL 3.2 Specification (Invariance)
None.
Additions to the AGL/GLX/WGL Specifications
None.
GLX Protocol
TBD.
Errors
INVALID_ENUM is generated by DrawArraysIndirect/DrawElementsIndirect
if <mode> is not a valid begin mode.
INVALID_ENUM is generated by DrawElementsIndirect if <type> is not
one of UNSIGNED_BYTE, UNSIGNED_SHORT, or UNSIGNED_INT.
INVALID_OPERATION is generated by DrawElementsIndirect if no buffer
is bound to ELEMENT_ARRAY_BUFFER.
INVALID_OPERATION is generated by DrawArraysIndirect and
DrawElementsIndirect if zero is bound to DRAW_INDIRECT_BUFFER and if
the OpenGL context implements the core profile.
INVALID_OPERATION is generated by DrawArraysIndirect and
DrawElementsIndirect if commands source data beyond the end of a buffer
object or if <indirect> is not word aligned.
New State
Update Table 6.11, p. 405 (Vertex Array Data not in Vertex Array objects)
Get Value Type Get Command Initial Value Sec Attribute
--------- ---- ----------- ------------- --- ---------
DRAW_INDIRECT_BUFFER_BINDING Z+ GetIntegerv 0 2.9 none
New Implementation Dependent State
None.
Dependencies on NV_vertex_buffer_unified_memory
If NV_vertex_buffer_unified_memory is supported, the following additional
edits are required:
Accepted by the <cap> parameter of GetBufferParameterui64vNV:
DRAW_INDIRECT_BUFFER.
Accepted by the <cap> parameter of DisableClientState,
EnableClientState, IsEnabled:
DRAW_INDIRECT_UNIFIED_NV 0x8F40
Accepted by the <pname> parameter of BufferAddressRangeNV
and the <value> parameter of GetIntegerui64vNV:
DRAW_INDIRECT_ADDRESS_NV 0x8F41
Accepted by the <value> parameter of GetIntegerv:
DRAW_INDIRECT_LENGTH_NV 0x8F42
In Section 2.8.1, mention that vertex attributes and indices may be
sourced from GPU addresses if VERTEX_ATTRIB_ARRAY_UNIFIED_NV/
ELEMENT_ARRAY_UNIFIED_NV are enabled.
Add to Section 2.9:
While DRAW_INDIRECT_UNIFIED_NV is enabled, DrawArraysIndirect and
DrawElementsIndirect, source their arguments from the address
specified by the command BufferAddressRange where <pname> is
DRAW_INDIRECT_ADDRESS_NV and <index> is zero, added to the <indirect>
parameter. If the commands source data beyond and including (<address>
+ <length>), an INVALID_OPERATION error will be generated. If the draw
indirect address range does not belong to a buffer object that is
resident at the time of the Draw, undefined results, possibly
including program termination, may occur.
INVALID_OPERATION is generated by DrawElementsIndirect if no buffer
is bound to ELEMENT_ARRAY_BUFFER and DRAW_INDIRECT_UNIFIED_NV is
disabled.
INVALID_OPERATION is generated by DrawArraysIndirect and
DrawElementsIndirect if DRAW_INDIRECT_UNIFIED_NV is enabled and
commands source data beyond and including (address + length).
Update Table 6.11:
Get Value Type Get Command Initial Value Sec Attribute
--------- ---- ----------- ------------- --- ---------
DRAW_INDIRECT_UNIFIED_NV B IsEnabled FALSE 2.9 none
DRAW_INDIRECT_ADDRESS_NV Z64+ GetIntegerui64vNV 0 2.9 none
DRAW_INDIRECT_LENGTH_NV Z+ GetIntegerv 0 2.9 none
Dependencies on NV_vertex_buffer_unified_memory and ARB_compatibility
If the context version is greater than 3.0 and does not include
ARB_compatibility functionality, then EnableClientState and
DisableClientState have been deprecated and removed. This extension
adds back those commands if NV_vertex_buffer_unified_memory is supported,
but only requires that they accept the DRAW_INDIRECT_UNIFIED_NV token.
Dependencies on ARB_compatibility
When the ARB_compatibility extension is not supported, client arrays
cannot be used to source vertex attribute data.
Dependencies on ARB_instanced_arrays
This extension does not require ARB_instanced_arrays, but reserves
space in the Command structures such that a future extension could
add a "firstInstance" member which would initialize the instance
counter used for computing which vertex attrib array element to use.
Note that ARB_instanced_arrays does not currently support
"firstInstance", it only has a frequency divider.
Issues
(1) What is this good for?
RESOLVED: Compute interoperability. Recirculating results written via
image stores or atomic counters.
(2) Should we allow indirect draws from client memory? Should we have a
buffer object binding for this?
RESOLVED: YES. Although, using client vertex arrays would somewhat defeat
the purpose of this extension. Note that this issue only applies to
implementations supporting the ARB_compatibility extension.
One non-obvious restriction is that DrawElementsIndirect doesn't accept
an <indices> parameter, so an index buffer is required.
(3) How do we specify the index size for DrawElements calls?
RESOLVED: Passed into the command, not pulled out of the struct.
(4) For DrawElements calls, in what unit are the offsets into the index
buffer.
RESOLVED: In indices, not in bytes.
(5) Should the new state be part of the VAO?
RESOLVED: No.
(6) Should gl.h/glext.h provide structure definitions?
RESOLVED. No. It is not possible to define the structures in such a way
that all compilers would pack them correctly.
Revision History
Rev. Date Author Changes
---- -------- -------- ------------------------------------------------
7 09/17/2012 Jon Leech Remove BindBufferRange/Base from commands for
which DRAW_INDIRECT_BUFFER is a valid target
(Bug 7794).
6 03/07/2012 Jon Leech Add missing error when no indirect buffer is
bound and the indirect draw commands are
called (Bug 7211).
5 12/07/2009 pdaniell Remove ARB suffix from new tokens for core spec.
4 10/29/2009 pdaniell Convert to ARB.
3 10/21/2009 pdaniell Minor edits based on Bruce's feedback. Added
full list of Get* calls for new
DRAW_INDIRECT_BUFFER_BINDING_EXT token.
Specified behavior when reservedMustBeZero is
non-zero. Added INVALID_VALUE error when
<indirect> is not a multiple of GLuint.
2 jbolz Internal revisions.
1 pbrown Internal revisions.