upstream-man-pages/man3/glValidateProgram.xml

   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="glValidateProgram">
   5     <refmeta>
   6         <refentrytitle>glValidateProgram</refentrytitle>
   7         <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10         <refname>glValidateProgram</refname>
  11         <refpurpose>Validates a program object</refpurpose>
  12     </refnamediv>
  13     <refsynopsisdiv><title>C Specification</title>
  14         <funcsynopsis>
  15             <funcprototype>
  16                 <funcdef>void <function>glValidateProgram</function></funcdef>
  17                 <paramdef>GLuint <parameter>program</parameter></paramdef>
  18             </funcprototype>
  19         </funcsynopsis>
  20     </refsynopsisdiv>
  21     <refsect1 id="parameters"><title>Parameters</title>
  22         <variablelist>
  23             <varlistentry>
  24                 <term><parameter>program</parameter></term>
  25                 <listitem>
  26                     <para>Specifies the handle of the program object to
  27                     be validated.</para>
  28                 </listitem>
  29             </varlistentry>
  30         </variablelist>
  31     </refsect1>
  32     <refsect1 id="description"><title>Description</title>
  33         <para><function>glValidateProgram</function> checks to see
  34         whether the executables contained in
  35         <parameter>program</parameter> can execute given the current
  36         OpenGL state. The information generated by the validation
  37         process will be stored in <parameter>program</parameter>'s
  38         information log. The validation information may consist of an
  39         empty string, or it may be a string containing information about
  40         how the current program object interacts with the rest of
  41         current OpenGL state. This provides a way for OpenGL
  42         implementers to convey more information about why the current
  43         program is inefficient, suboptimal, failing to execute, and so
  44         on.</para>
  45
  46         <para>The status of the validation operation will be stored as
  47         part of the program object's state. This value will be set to
  48         <constant>GL_TRUE</constant> if the validation succeeded, and
  49         <constant>GL_FALSE</constant> otherwise. It can be queried by
  50         calling
  51         <citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
  52         with arguments <parameter>program</parameter> and
  53         <constant>GL_VALIDATE_STATUS</constant>. If validation is
  54         successful, <parameter>program</parameter> is guaranteed to
  55         execute given the current state. Otherwise,
  56         <parameter>program</parameter> is guaranteed to not execute.</para>
  57
  58         <para>This function is typically useful only during application
  59         development. The informational string stored in the information
  60         log is completely implementation dependent; therefore, an
  61         application should not expect different OpenGL implementations
  62         to produce identical information strings.</para>
  63     </refsect1>
  64     <refsect1 id="notes"><title>Notes</title>
  65         <para>This function mimics the validation operation that OpenGL
  66         implementations must perform when rendering commands are issued
  67         while programmable shaders are part of current state. The error
  68         <constant>GL_INVALID_OPERATION</constant> will be generated by
  69         any command that triggers the rendering of geometry if:</para>
  70
  71         <itemizedlist>
  72             <listitem>
  73                 <para>any two active samplers in the current program
  74                 object are of different types, but refer to the same
  75                 texture image unit,</para>
  76             </listitem>
  77             <listitem>
  78             <para>the number of active samplers in the program exceeds the maximum
  79             number of texture image units allowed.</para>
  80             </listitem>
  81         </itemizedlist>
  82
  83         <para>It may be difficult or cause a performance degradation for
  84         applications to catch these errors when rendering commands are
  85         issued. Therefore, applications are advised to make calls to
  86         <function>glValidateProgram</function> to detect these issues
  87         during application development.</para>
  88     </refsect1>
  89     <refsect1 id="errors"><title>Errors</title>
  90         <para><constant>GL_INVALID_VALUE</constant> is generated if
  91         <parameter>program</parameter> is not a value generated by
  92         OpenGL.</para>
  93
  94         <para><constant>GL_INVALID_OPERATION</constant> is generated if
  95         <parameter>program</parameter> is not a program object.</para>
  96     </refsect1>
  97     <refsect1 id="associatedgets"><title>Associated Gets</title>
  98         <para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
  99         with arguments <parameter>program</parameter> and
 100         <constant>GL_VALIDATE_STATUS</constant></para>
 101
 102         <para><citerefentry><refentrytitle>glGetProgramInfoLog</refentrytitle></citerefentry>
 103         with argument <parameter>program</parameter></para>
 104
 105         <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
 106     </refsect1>
 107     <refsect1 id="seealso"><title>See Also</title>
 108         <para><citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
 109         <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry></para>
 110     </refsect1>
 111     <refsect1 id="Copyright"><title>Copyright</title>
 112         <para>
 113             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 114             This material may be distributed subject to the terms and conditions set forth in
 115             the Open Publication License, v 1.0, 8 June 1999.
 116             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 117         </para>
 118     </refsect1>
 119 </refentry>