[clinton/guile-figl.git] / upstream-doc / man4 / glBeginConditionalRender.xml

<?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="glBeginConditionalRender">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>2010</year>
                <holder>Khronos Group</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glBeginConditionalRender</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glBeginConditionalRender</refname>
        <refpurpose>start conditional rendering</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glBeginConditionalRender</function></funcdef>
                <paramdef>GLuint <parameter>id</parameter></paramdef>
                <paramdef>GLenum <parameter>mode</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>id</parameter></term>
            <listitem>
                <para>
                    Specifies the name of an occlusion query object whose results are used to determine if the rendering commands are discarded.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>mode</parameter></term>
            <listitem>
                <para>
                    Specifies how <function>glBeginConditionalRender</function> interprets the results of the occlusion query.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glEndConditionalRender</function></funcdef>
                <paramdef><parameter>void</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="description"><title>Description</title>
        <para>
            Conditional rendering is started using <function>glBeginConditionalRender</function> and ended using <function>glEndConditionalRender</function>.
            During conditional rendering, all vertex array commands, as well as <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry> and
            <citerefentry><refentrytitle>glClearBuffer</refentrytitle></citerefentry> have no effect if the (<constant>GL_SAMPLES_PASSED</constant>) result
            of the query object <parameter>id</parameter> is zero, or if the (<constant>GL_ANY_SAMPLES_PASSED</constant>) result is <constant>GL_FALSE</constant>.
            The results of commands setting the current vertex state, such as <citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry> are
            undefined. If the (<constant>GL_SAMPLES_PASSED</constant>) result is non-zero or if the (<constant>GL_ANY_SAMPLES_PASSED</constant>) result is
            <constant>GL_TRUE</constant>, such commands are not discarded. The <parameter>id</parameter> parameter to <function>glBeginConditionalRender</function>
            must be the name of a query object previously returned from a call to <citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>.
            <parameter>mode</parameter> specifies how the results of the query object are to be interpreted. If <parameter>mode</parameter> is
            <constant>GL_QUERY_WAIT</constant>, the GL waits for the results of the query to be available and then uses the results to determine if subsequent
            rendering commands are discarded. If <parameter>mode</parameter> is <constant>GL_QUERY_NO_WAIT</constant>, the GL may choose to unconditionally
            execute the subsequent rendering commands without waiting for the query to complete.
        </para>
        <para>
            If <parameter>mode</parameter> is <constant>GL_QUERY_BY_REGION_WAIT</constant>, the GL will also wait for occlusion query results and discard
            rendering commands if the result of the occlusion query is zero. If the query result is non-zero, subsequent rendering commands are executed,
            but the GL may discard the results of the commands for any region of the framebuffer that did not contribute to the sample count in the specified
            occlusion query. Any such discarding is done in an implementation-dependent manner, but the rendering command results may not be discarded for
            any samples that contributed to the occlusion query sample count. If <parameter>mode</parameter> is <constant>GL_QUERY_BY_REGION_NO_WAIT</constant>,
            the GL operates as in <constant>GL_QUERY_BY_REGION_WAIT</constant>, but may choose to unconditionally execute the subsequent rendering commands
            without waiting for the query to complete.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            <function>glBeginConditionalRender</function> and <function>glEndConditionalRender</function> are available only if the GL version is 3.0 or greater.
        </para>
        <para>
            The <constant>GL_ANY_SAMPLES_PASSED</constant> query result is available only if the GL version is 3.3 or greater.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>id</parameter> is not the name of an existing query object.
        </para>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not one of the accepted tokens.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <function>glBeginConditionalRender</function> is called while conditional rendering is active,
            or if <function>glEndConditionalRender</function> is called while conditional rendering is inactive.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> is the name of a query object with a target other than
            <constant>GL_SAMPLES_PASSED</constant> or <constant>GL_ANY_SAMPLES_PASSED</constant>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> is the name of a query currently in progress.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glDeleteQueries</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glBeginQuery</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 2009 Khronos Group. 
            This material may be distributed subject to the terms and conditions set forth in 
            the Open Publication License, v 1.0, 8 June 1999.
            <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
        </para>
    </refsect1>
</refentry>
Commit	Line	Data
7faf1d71 AW	1	<?xml version="1.0" encoding="UTF-8"?>
	2	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
	3	"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
	4	<refentry id="glBeginConditionalRender">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>2010</year>
	9	<holder>Khronos Group</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glBeginConditionalRender</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glBeginConditionalRender</refname>
	17	<refpurpose>start conditional rendering</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>void <function>glBeginConditionalRender</function></funcdef>
	23	<paramdef>GLuint <parameter>id</parameter></paramdef>
	24	<paramdef>GLenum <parameter>mode</parameter></paramdef>
	25	</funcprototype>
	26	</funcsynopsis>
	27	</refsynopsisdiv>
	28	<refsect1 id="parameters"><title>Parameters</title>
	29	<variablelist>
	30	<varlistentry>
	31	<term><parameter>id</parameter></term>
	32	<listitem>
	33	<para>
	34	Specifies the name of an occlusion query object whose results are used to determine if the rendering commands are discarded.
	35	</para>
	36	</listitem>
	37	</varlistentry>
	38	<varlistentry>
	39	<term><parameter>mode</parameter></term>
	40	<listitem>
	41	<para>
	42	Specifies how <function>glBeginConditionalRender</function> interprets the results of the occlusion query.
	43	</para>
	44	</listitem>
	45	</varlistentry>
	46	</variablelist>
	47	</refsect1>
	48	<refsynopsisdiv><title>C Specification</title>
	49	<funcsynopsis>
	50	<funcprototype>
	51	<funcdef>void <function>glEndConditionalRender</function></funcdef>
	52	<paramdef><parameter>void</parameter></paramdef>
	53	</funcprototype>
	54	</funcsynopsis>
	55	</refsynopsisdiv>
	56	<refsect1 id="description"><title>Description</title>
	57	<para>
	58	Conditional rendering is started using <function>glBeginConditionalRender</function> and ended using <function>glEndConditionalRender</function>.
	59	During conditional rendering, all vertex array commands, as well as <citerefentry><refentrytitle>glClear</refentrytitle></citerefentry> and
	60	<citerefentry><refentrytitle>glClearBuffer</refentrytitle></citerefentry> have no effect if the (<constant>GL_SAMPLES_PASSED</constant>) result
	61	of the query object <parameter>id</parameter> is zero, or if the (<constant>GL_ANY_SAMPLES_PASSED</constant>) result is <constant>GL_FALSE</constant>.
	62	The results of commands setting the current vertex state, such as <citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry> are
	63	undefined. If the (<constant>GL_SAMPLES_PASSED</constant>) result is non-zero or if the (<constant>GL_ANY_SAMPLES_PASSED</constant>) result is
	64	<constant>GL_TRUE</constant>, such commands are not discarded. The <parameter>id</parameter> parameter to <function>glBeginConditionalRender</function>
65	must be the name of a query object previously returned from a call to <citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>.
66	<parameter>mode</parameter> specifies how the results of the query object are to be interpreted. If <parameter>mode</parameter> is
67	<constant>GL_QUERY_WAIT</constant>, the GL waits for the results of the query to be available and then uses the results to determine if subsequent
68	rendering commands are discarded. If <parameter>mode</parameter> is <constant>GL_QUERY_NO_WAIT</constant>, the GL may choose to unconditionally
69	execute the subsequent rendering commands without waiting for the query to complete.
70	</para>
71	<para>
72	If <parameter>mode</parameter> is <constant>GL_QUERY_BY_REGION_WAIT</constant>, the GL will also wait for occlusion query results and discard
73	rendering commands if the result of the occlusion query is zero. If the query result is non-zero, subsequent rendering commands are executed,
74	but the GL may discard the results of the commands for any region of the framebuffer that did not contribute to the sample count in the specified
75	occlusion query. Any such discarding is done in an implementation-dependent manner, but the rendering command results may not be discarded for
76	any samples that contributed to the occlusion query sample count. If <parameter>mode</parameter> is <constant>GL_QUERY_BY_REGION_NO_WAIT</constant>,
77	the GL operates as in <constant>GL_QUERY_BY_REGION_WAIT</constant>, but may choose to unconditionally execute the subsequent rendering commands
78	without waiting for the query to complete.
79	</para>
80	</refsect1>
81	<refsect1 id="notes"><title>Notes</title>
82	<para>
83	<function>glBeginConditionalRender</function> and <function>glEndConditionalRender</function> are available only if the GL version is 3.0 or greater.
84	</para>
85	<para>
86	The <constant>GL_ANY_SAMPLES_PASSED</constant> query result is available only if the GL version is 3.3 or greater.
87	</para>
88	</refsect1>
89	<refsect1 id="errors"><title>Errors</title>
90	<para>
91	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>id</parameter> is not the name of an existing query object.
92	</para>
93	<para>
94	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>mode</parameter> is not one of the accepted tokens.
95	</para>
96	<para>
97	<constant>GL_INVALID_OPERATION</constant> is generated if <function>glBeginConditionalRender</function> is called while conditional rendering is active,
98	or if <function>glEndConditionalRender</function> is called while conditional rendering is inactive.
99	</para>
100	<para>
101	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> is the name of a query object with a target other than
102	<constant>GL_SAMPLES_PASSED</constant> or <constant>GL_ANY_SAMPLES_PASSED</constant>.
103	</para>
104	<para>
105	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>id</parameter> is the name of a query currently in progress.
106	</para>
107	</refsect1>
108	<refsect1 id="seealso"><title>See Also</title>
109	<para>
110	<citerefentry><refentrytitle>glGenQueries</refentrytitle></citerefentry>,
111	<citerefentry><refentrytitle>glDeleteQueries</refentrytitle></citerefentry>,
112	<citerefentry><refentrytitle>glBeginQuery</refentrytitle></citerefentry>
113	</para>
114	</refsect1>
115	<refsect1 id="Copyright"><title>Copyright</title>
116	<para>
117	Copyright <trademark class="copyright"></trademark> 2009 Khronos Group.
118	This material may be distributed subject to the terms and conditions set forth in
119	the Open Publication License, v 1.0, 8 June 1999.
120	<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
121	</para>
122	</refsect1>
123	</refentry>