2013-10-24 07:03:15 +00:00
<?xml version="1.0" encoding="UTF-8"?>
< !DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id= "glDrawElementsInstancedBaseInstance" >
2013-11-03 11:43:50 +00:00
<refentryinfo >
<copyright >
<year > 2011-2013</year>
<holder > Khronos Group</holder>
</copyright>
</refentryinfo>
2013-10-24 07:03:15 +00:00
<refmeta >
<refentrytitle > glDrawElementsInstancedBaseInstance</refentrytitle>
<manvolnum > 3G</manvolnum>
</refmeta>
<refnamediv >
<refname > glDrawElementsInstancedBaseInstance</refname>
<refpurpose > draw multiple instances of a set of elements with offset applied to instanced attributes</refpurpose>
</refnamediv>
<refsynopsisdiv > <title > C Specification</title>
<funcsynopsis >
<funcprototype >
<funcdef > void <function > glDrawElementsInstancedBaseInstance</function> </funcdef>
<paramdef > GLenum <parameter > mode</parameter> </paramdef>
<paramdef > GLsizei <parameter > count</parameter> </paramdef>
<paramdef > GLenum <parameter > type</parameter> </paramdef>
<paramdef > const void * <parameter > indices</parameter> </paramdef>
<paramdef > GLsizei <parameter > primcount</parameter> </paramdef>
<paramdef > GLuitn <parameter > baseinstance</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id= "parameters" > <title > Parameters</title>
<variablelist >
<varlistentry >
<term > <parameter > mode</parameter> </term>
<listitem >
<para >
Specifies what kind of primitives to render.
Symbolic constants
<constant > GL_POINTS</constant> ,
<constant > GL_LINE_STRIP</constant> ,
<constant > GL_LINE_LOOP</constant> ,
<constant > GL_LINES</constant> ,
<constant > GL_LINE_STRIP_ADJACENCY</constant> ,
<constant > GL_LINES_ADJACENCY</constant> ,
<constant > GL_TRIANGLE_STRIP</constant> ,
<constant > GL_TRIANGLE_FAN</constant> ,
<constant > GL_TRIANGLES</constant> ,
<constant > GL_TRIANGLE_STRIP_ADJACENCY</constant> ,
<constant > GL_TRIANGLES_ADJACENCY</constant> and <constant > GL_PATCHES</constant>
are accepted.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > count</parameter> </term>
<listitem >
<para >
Specifies the number of elements to be rendered.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > type</parameter> </term>
<listitem >
<para >
Specifies the type of the values in <parameter > indices</parameter> . Must be one of <constant > GL_UNSIGNED_BYTE</constant> ,
<constant > GL_UNSIGNED_SHORT</constant> , or <constant > GL_UNSIGNED_INT</constant> .
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > indices</parameter> </term>
<listitem >
<para >
Specifies a pointer to the location where the indices are stored.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > primcount</parameter> </term>
<listitem >
<para >
Specifies the number of instances of the specified range of indices to be rendered.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > baseinstance</parameter> </term>
<listitem >
<para >
Specifies the base instance for use in fetching instanced vertex attributes.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id= "description" > <title > Description</title>
<para >
<function > glDrawElementsInstancedBaseInstance</function> behaves identically to <citerefentry > <refentrytitle > glDrawElements</refentrytitle> </citerefentry>
except that <parameter > primcount</parameter> instances of the set of elements are executed and the value of the internal counter
<parameter > instanceID</parameter> advances for each iteration. <parameter > instanceID</parameter> is an internal 32-bit integer counter
that may be read by a vertex shader as <constant > gl_InstanceID</constant> .
</para>
<para >
<function > glDrawElementsInstancedBaseInstance</function> has the same effect as:
<programlisting > < ![CDATA[ if (mode, count, or type is invalid )
generate appropriate error
else {
for (int i = 0; i < primcount ; i + + ) {
instanceID = i;
glDrawElements(mode, count, type, indices);
}
instanceID = 0;
}]]></programlisting>
</para>
<para >
Specific vertex attributes may be classified as <emphasis > instanced</emphasis> through the use of
<citerefentry > <refentrytitle > glVertexAttribDivisor</refentrytitle> </citerefentry> . Instanced vertex attributes
supply per-instance vertex data to the vertex shader. The index of the vertex fetched from the enabled instanced vertex
attribute arrays is calculated as
2013-11-03 11:43:50 +00:00
<inlineequation >
<mml:math >
<mml:mrow >
<mml:mfenced open = '⌊' close = '⌋' >
<mml:mfrac >
<mml:mrow >
<mml:mi > gl</mml:mi>
<mml:mo > _</mml:mo>
<mml:mi > InstanceID</mml:mi>
</mml:mrow>
<mml:mi > divisor</mml:mi>
</mml:mfrac>
</mml:mfenced>
<mml:mo lspace= '2px' rspace= '2px' > + </mml:mo>
<mml:mi > baseInstance</mml:mi>
</mml:mrow>
</mml:math>
</inlineequation> . Note that
<parameter > baseinstance</parameter> does not affect the
shader-visible value of <constant > gl_InstanceID</constant> .
2013-10-24 07:03:15 +00:00
</para>
</refsect1>
<refsect1 id= "notes" > <title > Notes</title>
<para >
<function > glDrawElementsInstancedBaseInstance</function> is available only if the GL version is 4.2 or greater.
</para>
<para >
<constant > GL_LINE_STRIP_ADJACENCY</constant> ,
<constant > GL_LINES_ADJACENCY</constant> ,
<constant > GL_TRIANGLE_STRIP_ADJACENCY</constant> and
<constant > GL_TRIANGLES_ADJACENCY</constant>
are available only if the GL version is 3.2 or greater.
</para>
</refsect1>
<refsect1 id= "errors" > <title > Errors</title>
<para >
<constant > GL_INVALID_ENUM</constant> is generated if <parameter > mode</parameter> is not one of <constant > GL_POINTS</constant> ,
<constant > GL_LINE_STRIP</constant> , <constant > GL_LINE_LOOP</constant> , <constant > GL_LINES</constant> ,
<constant > GL_TRIANGLE_STRIP</constant> , <constant > GL_TRIANGLE_FAN</constant> , or <constant > GL_TRIANGLES</constant> .
</para>
<para >
<constant > GL_INVALID_VALUE</constant> is generated if <parameter > count</parameter> or <parameter > primcount</parameter> are negative.
</para>
<para >
<constant > GL_INVALID_OPERATION</constant> is generated if a geometry shader is active and <parameter > mode</parameter>
is incompatible with the input primitive type of the geometry shader in the currently installed program object.
</para>
<para >
<constant > GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to an
enabled array and the buffer object's data store is currently mapped.
</para>
</refsect1>
<refsect1 id= "seealso" > <title > See Also</title>
<para >
<citerefentry > <refentrytitle > glDrawElements</refentrytitle> </citerefentry> ,
<citerefentry > <refentrytitle > glDrawArraysInstanced</refentrytitle> </citerefentry>
</para>
</refsect1>
<refsect1 id= "Copyright" > <title > Copyright</title>
<para >
2013-11-03 11:43:50 +00:00
Copyright <trademark class= "copyright" > </trademark> 2011-2013 Khronos Group.
This material may be distributed subject to the terms and conditions set forth in
2013-10-24 07:03:15 +00:00
the Open Publication License, v 1.0, 8 June 1999.
<ulink url= "http://opencontent.org/openpub/" > http://opencontent.org/openpub/</ulink> .
</para>
</refsect1>
</refentry>
