upstream-man-pages/man2/glUseProgram.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="glUseProgram">
   5     <refmeta>
   6         <refentrytitle>glUseProgram</refentrytitle>
   7         <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10         <refname>glUseProgram</refname>
  11         <refpurpose>Installs a program object as part of current rendering state</refpurpose>
  12     </refnamediv>
  13     <refsynopsisdiv><title>C Specification</title>
  14         <funcsynopsis>
  15             <funcprototype>
  16                 <funcdef>void <function>glUseProgram</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
  27                     whose executables are to be used as part of current
  28                     rendering state.</para>
  29                 </listitem>
  30             </varlistentry>
  31         </variablelist>
  32     </refsect1>
  33     <refsect1 id="description"><title>Description</title>
  34         <para><function>glUseProgram</function> installs the program
  35         object specified by <parameter>program</parameter> as part of
  36         current rendering state. One or more executables are created in
  37         a program object by successfully attaching shader objects to it
  38         with
  39         <citerefentry><refentrytitle>glAttachShader</refentrytitle></citerefentry>,
  40         successfully compiling the shader objects with
  41         <citerefentry><refentrytitle>glCompileShader</refentrytitle></citerefentry>,
  42         and successfully linking the program object with
  43         <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>.
  44         </para>
  45
  46         <para>A program object will contain an executable that will run
  47         on the vertex processor if it contains one or more shader
  48         objects of type <constant>GL_VERTEX_SHADER</constant> that have
  49         been successfully compiled and linked. Similarly, a program
  50         object will contain an executable that will run on the fragment
  51         processor if it contains one or more shader objects of type
  52         <constant>GL_FRAGMENT_SHADER</constant> that have been
  53         successfully compiled and linked.</para>
  54
  55         <para>Successfully installing an executable on a programmable
  56         processor will cause the corresponding fixed functionality of
  57         OpenGL to be disabled. Specifically, if an executable is
  58         installed on the vertex processor, the OpenGL fixed
  59         functionality will be disabled as follows.</para>
  60
  61         <itemizedlist>
  62             <listitem>
  63                 <para>The modelview matrix is not applied to vertex
  64                 coordinates.</para>
  65             </listitem>
  66             <listitem>
  67                 <para>The projection matrix is not applied to vertex
  68                 coordinates.</para>
  69             </listitem>
  70             <listitem>
  71                 <para>The texture matrices are not applied to texture
  72                 coordinates.</para>
  73             </listitem>
  74             <listitem>
  75                 <para>Normals are not transformed to eye
  76                 coordinates.</para>
  77             </listitem>
  78             <listitem>
  79                 <para>Normals are not rescaled or normalized.</para>
  80             </listitem>
  81             <listitem>
  82                 <para>Normalization of
  83                 <constant>GL_AUTO_NORMAL</constant> evaluated normals is
  84                 not performed.</para>
  85             </listitem>
  86             <listitem>
  87                 <para>Texture coordinates are not generated
  88                 automatically.</para>
  89             </listitem>
  90             <listitem>
  91                 <para>Per-vertex lighting is not performed.</para>
  92             </listitem>
  93             <listitem>
  94                 <para>Color material computations are not
  95                 performed.</para>
  96             </listitem>
  97             <listitem>
  98                 <para>Color index lighting is not performed.</para>
  99             </listitem>
 100             <listitem>
 101                 <para>This list also applies when setting the current
 102                 raster position.</para>
 103             </listitem>
 104         </itemizedlist>
 105
 106         <para>The executable that is installed on the vertex processor
 107         is expected to implement any or all of the desired functionality
 108         from the preceding list. Similarly, if an executable is
 109         installed on the fragment processor, the OpenGL fixed
 110         functionality will be disabled as follows.</para>
 111
 112         <itemizedlist>
 113             <listitem>
 114                 <para>Texture environment and texture functions are not
 115                 applied.</para>
 116             </listitem>
 117             <listitem>
 118                 <para>Texture application is not applied.</para>
 119             </listitem>
 120             <listitem>
 121                 <para>Color sum is not applied.</para>
 122             </listitem>
 123             <listitem>
 124                 <para>Fog is not applied.</para>
 125             </listitem>
 126         </itemizedlist>
 127
 128         <para>Again, the fragment shader that is installed is expected
 129         to implement any or all of the desired functionality from the
 130         preceding list.</para>
 131
 132         <para>While a program object is in use, applications are free to
 133         modify attached shader objects, compile attached shader objects,
 134         attach additional shader objects, and detach or delete shader
 135         objects. None of these operations will affect the executables
 136         that are part of the current state. However, relinking the
 137         program object that is currently in use will install the program
 138         object as part of the current rendering state if the link
 139         operation was successful (see
 140         <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
 141         ). If the program object currently in use is relinked
 142         unsuccessfully, its link status will be set to
 143         <constant>GL_FALSE</constant>, but the executables and
 144         associated state will remain part of the current state until a
 145         subsequent call to <function>glUseProgram</function> removes it
 146         from use. After it is removed from use, it cannot be made part
 147         of current state until it has been successfully relinked.</para>
 148
 149         <para>If <parameter>program</parameter> contains shader objects
 150         of type <constant>GL_VERTEX_SHADER</constant> but it does not
 151         contain shader objects of type
 152         <constant>GL_FRAGMENT_SHADER</constant>, an executable will be
 153         installed on the vertex processor, but fixed functionality will
 154         be used for fragment processing. Similarly, if
 155         <parameter>program</parameter> contains shader objects of type
 156         <constant>GL_FRAGMENT_SHADER</constant> but it does not contain
 157         shader objects of type <constant>GL_VERTEX_SHADER</constant>, an
 158         executable will be installed on the fragment processor, but
 159         fixed functionality will be used for vertex processing. If
 160         <parameter>program</parameter> is 0, the programmable processors
 161         will be disabled, and fixed functionality will be used for both
 162         vertex and fragment processing.</para>
 163     </refsect1>
 164     <refsect1 id="notes"><title>Notes</title>
 165         <para><function>glUseProgram</function> is available only if the
 166         GL version is 2.0 or greater.</para>
 167
 168         <para>While a program object is in use, the state that controls
 169         the disabled fixed functionality may also be updated using the
 170         normal OpenGL calls.</para>
 171
 172         <para>Like display lists and texture objects, the name space for
 173         program objects may be shared across a set of contexts, as long
 174         as the server sides of the contexts share the same address
 175         space. If the name space is shared across contexts, any attached
 176         objects and the data associated with those attached objects are
 177         shared as well.</para>
 178
 179         <para>Applications are responsible for providing the
 180         synchronization across API calls when objects are accessed from
 181         different execution threads.</para>
 182
 183     </refsect1>
 184     <refsect1 id="errors"><title>Errors</title>
 185         <para><constant>GL_INVALID_VALUE</constant> is generated if
 186         <parameter>program</parameter> is neither 0 nor a value
 187         generated by OpenGL.</para>
 188
 189         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 190         <parameter>program</parameter> is not a program object.</para>
 191
 192         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 193         <parameter>program</parameter> could not be made part of current
 194         state.</para>
 195
 196         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 197         <function>glUseProgram</function> is executed between the
 198         execution of
 199         <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 200         and the corresponding execution of
 201         <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
 202     </refsect1>
 203     <refsect1 id="associatedgets"><title>Associated Gets</title>
 204         <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 205         with the argument <constant>GL_CURRENT_PROGRAM</constant></para>
 206
 207         <para><citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
 208         with a valid program object and the index of an active attribute
 209         variable</para>
 210
 211         <para><citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>
 212         with a valid program object and the index of an active uniform
 213         variable</para>
 214
 215         <para><citerefentry><refentrytitle>glGetAttachedShaders</refentrytitle></citerefentry>
 216         with a valid program object</para>
 217
 218         <para><citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>
 219         with a valid program object and the name of an attribute
 220         variable</para>
 221
 222         <para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
 223         with a valid program object and the parameter to be queried</para>
 224
 225         <para><citerefentry><refentrytitle>glGetProgramInfoLog</refentrytitle></citerefentry>
 226         with a valid program object</para>
 227
 228         <para><citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>
 229         with a valid program object and the location of a uniform
 230         variable</para>
 231
 232         <para><citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>
 233         with a valid program object and the name of a uniform
 234         variable</para>
 235
 236         <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
 237     </refsect1>
 238     <refsect1 id="seealso"><title>See Also</title>
 239         <para><citerefentry><refentrytitle>gllAttachShader</refentrytitle></citerefentry>,
 240         <citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,
 241         <citerefentry><refentrytitle>glCompileShader</refentrytitle></citerefentry>,
 242         <citerefentry><refentrytitle>glCreateProgram</refentrytitle></citerefentry>,
 243         <citerefentry><refentrytitle>glDeleteProgram</refentrytitle></citerefentry>,
 244         <citerefentry><refentrytitle>glDetachShader</refentrytitle></citerefentry>,
 245         <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
 246         <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>,
 247         <citerefentry><refentrytitle>glValidateProgram</refentrytitle></citerefentry>,
 248         <citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry></para>
 249     </refsect1>
 250     <refsect1 id="Copyright"><title>Copyright</title>
 251         <para>
 252             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 253             This material may be distributed subject to the terms and conditions set forth in
 254             the Open Publication License, v 1.0, 8 June 1999.
 255             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 256         </para>
 257     </refsect1>
 258 </refentry>