rename upstream-man-pages to upstream-doc

[clinton/guile-figl.git] / upstream-doc / man3 / glDrawArraysInstanced.xml

<?xml version="1.0" encoding="UTF-8"?>\r
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"\r
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">\r
<refentry id="glDrawArraysInstanced">\r
    <refmeta>\r
        <refmetainfo>\r
            <copyright>\r
                <year>2010</year>\r
                <holder>Khronos Group</holder>\r
            </copyright>\r
        </refmetainfo>\r
        <refentrytitle>glDrawArraysInstanced</refentrytitle>\r
        <manvolnum>3G</manvolnum>\r
    </refmeta>\r
    <refnamediv>\r
        <refname>glDrawArraysInstanced</refname>\r
        <refpurpose>draw multiple instances of a range of elements</refpurpose>\r
    </refnamediv>\r
    <refsynopsisdiv><title>C Specification</title>\r
        <funcsynopsis>\r
            <funcprototype>\r
                <funcdef>void <function>glDrawArraysInstanced</function></funcdef>\r
                <paramdef>GLenum <parameter>mode</parameter></paramdef>\r
                <paramdef>GLint <parameter>first</parameter></paramdef>\r
                <paramdef>GLsizei <parameter>count</parameter></paramdef>\r
                <paramdef>GLsizei <parameter>primcount</parameter></paramdef>\r
            </funcprototype>\r
        </funcsynopsis>\r
    </refsynopsisdiv>\r
    <refsect1 id="parameters"><title>Parameters</title>\r
        <variablelist>\r
        <varlistentry>\r
            <term><parameter>mode</parameter></term>\r
            <listitem>\r
                <para>\r
                    Specifies what kind of primitives to render. Symbolic constants <constant>GL_POINTS</constant>,\r
                    <constant>GL_LINE_STRIP</constant>, <constant>GL_LINE_LOOP</constant>, <constant>GL_LINES</constant>,\r
                    <constant>GL_TRIANGLE_STRIP</constant>, <constant>GL_TRIANGLE_FAN</constant>, <constant>GL_TRIANGLES</constant>\r
                    <constant>GL_LINES_ADJACENCY</constant>, <constant>GL_LINE_STRIP_ADJACENCY</constant>,\r
                    <constant>GL_TRIANGLES_ADJACENCY</constant> and<constant>GL_TRIANGLE_STRIP_ADJACENCY</constant>\r
                    are accepted.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        <varlistentry>\r
            <term><parameter>first</parameter></term>\r
            <listitem>\r
                <para>\r
                    Specifies the starting index in the enabled arrays.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        <varlistentry>\r
            <term><parameter>count</parameter></term>\r
            <listitem>\r
                <para>\r
                    Specifies the number of indices to be rendered.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        <varlistentry>\r
            <term><parameter>primcount</parameter></term>\r
            <listitem>\r
                <para>\r
                    Specifies the number of instances of the specified range of indices to be rendered.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        </variablelist>\r
    </refsect1>\r
    <refsect1 id="description"><title>Description</title>\r
        <para>\r
            <function>glDrawArraysInstanced</function> behaves identically to <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>\r
            except that <parameter>primcount</parameter> instances of the range of elements are executed and the value of the internal counter\r
            <parameter>instanceID</parameter> advances for each iteration. <parameter>instanceID</parameter> is an internal 32-bit integer counter\r
            that may be read by a vertex shader as <constant>gl_InstanceID</constant>.\r
        </para>\r
        <para>\r
            <function>glDrawArraysInstanced</function> has the same effect as:\r
            <programlisting><![CDATA[    if ( mode or count is invalid )\r
        generate appropriate error\r
    else {\r
        for (int i = 0; i < primcount ; i++) {\r
            instanceID = i;\r
            glDrawArrays(mode, first, count);\r
        }\r
        instanceID = 0;\r
    }]]></programlisting>\r
        </para>\r
    </refsect1>\r
    <refsect1 id="notes"><title>Notes</title>\r
        <para>\r
            <function>glDrawArraysInstanced</function> is available only if the GL version is 3.1 or greater.\r
        </para>\r
        <para>\r
            <constant>GL_LINE_STRIP_ADJACENCY</constant>,\r
            <constant>GL_LINES_ADJACENCY</constant>,\r
            <constant>GL_TRIANGLE_STRIP_ADJACENCY</constant> and\r
            <constant>GL_TRIANGLES_ADJACENCY</constant>\r
            are available only if the GL version is 3.2 or greater.\r
        </para>\r
    </refsect1>\r
    <refsect1 id="errors"><title>Errors</title>\r
        <para>\r
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not one of \r
            the accepted values.\r
        </para>\r
        <para>\r
            <constant>GL_INVALID_OPERATION</constant> is generated if a geometry shader is active and <parameter>mode</parameter>\r
            is incompatible with the input primitive type of the geometry shader in the currently installed program object.\r
        </para>\r
        <para>\r
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>count</parameter> or <parameter>primcount</parameter> are negative.\r
        </para>\r
        <para>\r
            <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to an\r
            enabled array and the buffer object's data store is currently mapped.\r
        </para>\r
    </refsect1>\r
    <refsect1 id="seealso"><title>See Also</title>\r
        <para>\r
            <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,\r
            <citerefentry><refentrytitle>glDrawElementsInstanced</refentrytitle></citerefentry>\r
        </para>\r
    </refsect1>\r
    <refsect1 id="Copyright"><title>Copyright</title>\r
        <para>\r
            Copyright <trademark class="copyright"></trademark> 2010 Khronos Group. \r
            This material may be distributed subject to the terms and conditions set forth in \r
            the Open Publication License, v 1.0, 8 June 1999.\r
            <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.\r
        </para>\r
    </refsect1>\r
</refentry>\r