<!DOCTYPE refentry [ <!ENTITY % mathent SYSTEM "math.ent"> %mathent; ]>

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="glPrimitiveBoundingBox">
    <info>
        <copyright>
            <year>2015</year>
            <holder>Khronos Group</holder>
        </copyright>
    </info>
    <refmeta>
        <refentrytitle>glPrimitiveBoundingBox</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glPrimitiveBoundingBox</refname>
        <refpurpose>set the bounding box for a primitive</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glPrimitiveBoundingBox</function></funcdef>
                <paramdef>GLfloat <parameter>minX</parameter></paramdef>
                <paramdef>GLfloat <parameter>minY</parameter></paramdef>
                <paramdef>GLfloat <parameter>minZ</parameter></paramdef>
                <paramdef>GLfloat <parameter>minW</parameter></paramdef>
                <paramdef>GLfloat <parameter>maxX</parameter></paramdef>
                <paramdef>GLfloat <parameter>maxY</parameter></paramdef>
                <paramdef>GLfloat <parameter>maxZ</parameter></paramdef>
                <paramdef>GLfloat <parameter>maxW</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 xml:id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>minX</parameter></term>
            <term><parameter>minY</parameter></term>
            <term><parameter>minZ</parameter></term>
            <term><parameter>minW</parameter></term>
            <listitem>
                <para>
                    Specify the minimum clip space cooridnate of the bounding box. The initial value is (-1, -1, -1, -1).
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>maxX</parameter></term>
            <term><parameter>maxY</parameter></term>
            <term><parameter>maxZ</parameter></term>
            <term><parameter>maxW</parameter></term>
            <listitem>
                <para>
                    Specify the maximum clip space cooridnate of the bounding box. The initial value is (1, 1, 1, 1).
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 xml:id="description"><title>Description</title>
        <para>
            <function>glPrimitiveBoundingBox</function> specifies a clip space bounding box which may allow
            implementations to optimize performance if the application
            provides bounds of primitives that will be generated by the tessellation
            primitive generator or the geometry shader prior to executing those stages.
            If the provided bounds are incorrect and primitives extend beyond them, the
            rasterizer may or may not generate fragments for the portions of primitives
            outside the bounds.
        </para>
        <para>
            The bounding box in clip space is composed of 16 vertices formed by all
            combinations of the minimum and maximum values for each dimension. This
            bounding box is clipped against 
            <inlineequation><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
                <!-- eqn: w sub c > 0:-->
                <mml:msub><mml:mi mathvariant="italic">w</mml:mi>
                <mml:mi mathvariant="italic">c</mml:mi>
                </mml:msub>
                <mml:mo>&gt;</mml:mo>
                <mml:mn>0</mml:mn>
            </mml:math></inlineequation>
            and projected to three dimensions
            by dividing 
            <inlineequation><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
                <!-- eqn: x sub c > 0:-->
                <mml:msub><mml:mi mathvariant="italic">x</mml:mi>
                <mml:mi mathvariant="italic">c</mml:mi>
                </mml:msub>
            </mml:math></inlineequation>,
            <inlineequation><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
                <!-- eqn: y sub c > 0:-->
                <mml:msub><mml:mi mathvariant="italic">y</mml:mi>
                <mml:mi mathvariant="italic">c</mml:mi>
                </mml:msub>
            </mml:math></inlineequation>, and            
            <inlineequation><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
                <!-- eqn: z sub c > 0:-->
                <mml:msub><mml:mi mathvariant="italic">z</mml:mi>
                <mml:mi mathvariant="italic">c</mml:mi>
                </mml:msub>
            </mml:math></inlineequation> by            
            <inlineequation><mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
                <!-- eqn: w sub c > 0:-->
                <mml:msub><mml:mi mathvariant="italic">w</mml:mi>
                <mml:mi mathvariant="italic">c</mml:mi>
                </mml:msub>
            </mml:math></inlineequation>            
            for each vertex. The viewport transform
            is then applied to each vertex to produce a three-dimensional bounding
            volume in window coordinates. The window space bounding volume is expanded in the X and Y dimensions to
            accommodate the rasterization rules for the primitive type, and to fall on
            fragment boundaries.
        </para>
        <para>
            If tessellation is active, each invocation of the tessellation control
            shader may re-specify the bounding box by writing to the built-in
            <citerefentry><refentrytitle>gl_BoundingBox</refentrytitle></citerefentry>[] variable. 
            If the shader statically assigns a value to
            any part of this variable, then gl_BoundingBox[0] is used instead of
            <parameter>minX</parameter>, <parameter>minY</parameter>, <parameter>minZ</parameter>, 
            <parameter>minW</parameter>, and gl_BoundingBox[1] is used instead of
            <parameter>maxX</parameter>, <parameter>maxY</parameter>, <parameter>maxZ</parameter>, 
            <parameter>maxW</parameter>.  If the shader contains a static assignment
            to gl_BoundingBox[] and there is an execution path through the shader
            that does not write all components of gl_BoundingBox[], the value of
            unwritten components and corresponding bounding box coordinates is undefined
            for executions of the shader that take that path.
       </para> 
    </refsect1>
    <refsect1 xml:id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PRIMITIVE_BOUNDING_BOX</constant>
        </para>
    </refsect1>
    <refsect1 xml:id="versions">
        <title>API Version Support</title>
        <informaltable>
            <tgroup cols="5" align="left">
                <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apifunchead.xml" xpointer="xpointer(/*/*)"/>
                <tbody>
                    <row>
                        <entry>glPrimitiveBoundingBox</entry>
                        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='es32']/*)"/>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
    </refsect1>
    <refsect1 xml:id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"/> 2015 Khronos Group.
            This document is licensed under the SGI Free Software B License.
            For details, see
            <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</link>.
        </para>
    </refsect1>
</refentry>
