upstream-man-pages/man2/xhtml/glUseProgram.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glUseProgram</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glUseProgram"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glUseProgram — Installs a program object as part of current rendering state</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glUseProgram</b>(</code></td><td>GLuint  </td><td><var class="pdparam">program</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>program</code></em></span></dt><dd><p>Specifies the handle of the program object
   4                     whose executables are to be used as part of current
   5                     rendering state.</p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p><code class="function">glUseProgram</code> installs the program
   6         object specified by <em class="parameter"><code>program</code></em> as part of
   7         current rendering state. One or more executables are created in
   8         a program object by successfully attaching shader objects to it
   9         with
  10         <a class="citerefentry" href="glAttachShader.xml"><span class="citerefentry"><span class="refentrytitle">glAttachShader</span></span></a>,
  11         successfully compiling the shader objects with
  12         <a class="citerefentry" href="glCompileShader.xml"><span class="citerefentry"><span class="refentrytitle">glCompileShader</span></span></a>,
  13         and successfully linking the program object with
  14         <a class="citerefentry" href="glLinkProgram.xml"><span class="citerefentry"><span class="refentrytitle">glLinkProgram</span></span></a>.
  15         </p><p>A program object will contain an executable that will run
  16         on the vertex processor if it contains one or more shader
  17         objects of type <code class="constant">GL_VERTEX_SHADER</code> that have
  18         been successfully compiled and linked. Similarly, a program
  19         object will contain an executable that will run on the fragment
  20         processor if it contains one or more shader objects of type
  21         <code class="constant">GL_FRAGMENT_SHADER</code> that have been
  22         successfully compiled and linked.</p><p>Successfully installing an executable on a programmable
  23         processor will cause the corresponding fixed functionality of
  24         OpenGL to be disabled. Specifically, if an executable is
  25         installed on the vertex processor, the OpenGL fixed
  26         functionality will be disabled as follows.</p><div class="itemizedlist"><ul type="disc"><li><p>The modelview matrix is not applied to vertex
  27                 coordinates.</p></li><li><p>The projection matrix is not applied to vertex
  28                 coordinates.</p></li><li><p>The texture matrices are not applied to texture
  29                 coordinates.</p></li><li><p>Normals are not transformed to eye
  30                 coordinates.</p></li><li><p>Normals are not rescaled or normalized.</p></li><li><p>Normalization of
  31                 <code class="constant">GL_AUTO_NORMAL</code> evaluated normals is
  32                 not performed.</p></li><li><p>Texture coordinates are not generated
  33                 automatically.</p></li><li><p>Per-vertex lighting is not performed.</p></li><li><p>Color material computations are not
  34                 performed.</p></li><li><p>Color index lighting is not performed.</p></li><li><p>This list also applies when setting the current
  35                 raster position.</p></li></ul></div><p>The executable that is installed on the vertex processor
  36         is expected to implement any or all of the desired functionality
  37         from the preceding list. Similarly, if an executable is
  38         installed on the fragment processor, the OpenGL fixed
  39         functionality will be disabled as follows.</p><div class="itemizedlist"><ul type="disc"><li><p>Texture environment and texture functions are not
  40                 applied.</p></li><li><p>Texture application is not applied.</p></li><li><p>Color sum is not applied.</p></li><li><p>Fog is not applied.</p></li></ul></div><p>Again, the fragment shader that is installed is expected
  41         to implement any or all of the desired functionality from the
  42         preceding list.</p><p>While a program object is in use, applications are free to
  43         modify attached shader objects, compile attached shader objects,
  44         attach additional shader objects, and detach or delete shader
  45         objects. None of these operations will affect the executables
  46         that are part of the current state. However, relinking the
  47         program object that is currently in use will install the program
  48         object as part of the current rendering state if the link
  49         operation was successful (see
  50         <a class="citerefentry" href="glLinkProgram.xml"><span class="citerefentry"><span class="refentrytitle">glLinkProgram</span></span></a>
  51         ). If the program object currently in use is relinked
  52         unsuccessfully, its link status will be set to
  53         <code class="constant">GL_FALSE</code>, but the executables and
  54         associated state will remain part of the current state until a
  55         subsequent call to <code class="function">glUseProgram</code> removes it
  56         from use. After it is removed from use, it cannot be made part
  57         of current state until it has been successfully relinked.</p><p>If <em class="parameter"><code>program</code></em> contains shader objects
  58         of type <code class="constant">GL_VERTEX_SHADER</code> but it does not
  59         contain shader objects of type
  60         <code class="constant">GL_FRAGMENT_SHADER</code>, an executable will be
  61         installed on the vertex processor, but fixed functionality will
  62         be used for fragment processing. Similarly, if
  63         <em class="parameter"><code>program</code></em> contains shader objects of type
  64         <code class="constant">GL_FRAGMENT_SHADER</code> but it does not contain
  65         shader objects of type <code class="constant">GL_VERTEX_SHADER</code>, an
  66         executable will be installed on the fragment processor, but
  67         fixed functionality will be used for vertex processing. If
  68         <em class="parameter"><code>program</code></em> is 0, the programmable processors
  69         will be disabled, and fixed functionality will be used for both
  70         vertex and fragment processing.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p><code class="function">glUseProgram</code> is available only if the
  71         GL version is 2.0 or greater.</p><p>While a program object is in use, the state that controls
  72         the disabled fixed functionality may also be updated using the
  73         normal OpenGL calls.</p><p>Like display lists and texture objects, the name space for
  74         program objects may be shared across a set of contexts, as long
  75         as the server sides of the contexts share the same address
  76         space. If the name space is shared across contexts, any attached
  77         objects and the data associated with those attached objects are
  78         shared as well.</p><p>Applications are responsible for providing the
  79         synchronization across API calls when objects are accessed from
  80         different execution threads.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p><code class="constant">GL_INVALID_VALUE</code> is generated if
  81         <em class="parameter"><code>program</code></em> is neither 0 nor a value
  82         generated by OpenGL.</p><p><code class="constant">GL_INVALID_OPERATION</code> is generated if
  83         <em class="parameter"><code>program</code></em> is not a program object.</p><p><code class="constant">GL_INVALID_OPERATION</code> is generated if
  84         <em class="parameter"><code>program</code></em> could not be made part of current
  85         state.</p><p><code class="constant">GL_INVALID_OPERATION</code> is generated if
  86         <code class="function">glUseProgram</code> is executed between the
  87         execution of
  88         <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
  89         and the corresponding execution of
  90         <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p><a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a>
  91         with the argument <code class="constant">GL_CURRENT_PROGRAM</code></p><p><a class="citerefentry" href="glGetActiveAttrib.xml"><span class="citerefentry"><span class="refentrytitle">glGetActiveAttrib</span></span></a>
  92         with a valid program object and the index of an active attribute
  93         variable</p><p><a class="citerefentry" href="glGetActiveUniform.xml"><span class="citerefentry"><span class="refentrytitle">glGetActiveUniform</span></span></a>
  94         with a valid program object and the index of an active uniform
  95         variable</p><p><a class="citerefentry" href="glGetAttachedShaders.xml"><span class="citerefentry"><span class="refentrytitle">glGetAttachedShaders</span></span></a>
  96         with a valid program object</p><p><a class="citerefentry" href="glGetAttribLocation.xml"><span class="citerefentry"><span class="refentrytitle">glGetAttribLocation</span></span></a>
  97         with a valid program object and the name of an attribute
  98         variable</p><p><a class="citerefentry" href="glGetProgram.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgram</span></span></a>
  99         with a valid program object and the parameter to be queried</p><p><a class="citerefentry" href="glGetProgramInfoLog.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgramInfoLog</span></span></a>
 100         with a valid program object</p><p><a class="citerefentry" href="glGetUniform.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniform</span></span></a>
 101         with a valid program object and the location of a uniform
 102         variable</p><p><a class="citerefentry" href="glGetUniformLocation.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniformLocation</span></span></a>
 103         with a valid program object and the name of a uniform
 104         variable</p><p><a class="citerefentry" href="glIsProgram.xml"><span class="citerefentry"><span class="refentrytitle">glIsProgram</span></span></a></p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p><a class="citerefentry" href="gllAttachShader.xml"><span class="citerefentry"><span class="refentrytitle">gllAttachShader</span></span></a>,
 105         <a class="citerefentry" href="glBindAttribLocation.xml"><span class="citerefentry"><span class="refentrytitle">glBindAttribLocation</span></span></a>,
 106         <a class="citerefentry" href="glCompileShader.xml"><span class="citerefentry"><span class="refentrytitle">glCompileShader</span></span></a>,
 107         <a class="citerefentry" href="glCreateProgram.xml"><span class="citerefentry"><span class="refentrytitle">glCreateProgram</span></span></a>,
 108         <a class="citerefentry" href="glDeleteProgram.xml"><span class="citerefentry"><span class="refentrytitle">glDeleteProgram</span></span></a>,
 109         <a class="citerefentry" href="glDetachShader.xml"><span class="citerefentry"><span class="refentrytitle">glDetachShader</span></span></a>,
 110         <a class="citerefentry" href="glLinkProgram.xml"><span class="citerefentry"><span class="refentrytitle">glLinkProgram</span></span></a>,
 111         <a class="citerefentry" href="glUniform.xml"><span class="citerefentry"><span class="refentrytitle">glUniform</span></span></a>,
 112         <a class="citerefentry" href="glValidateProgram.xml"><span class="citerefentry"><span class="refentrytitle">glValidateProgram</span></span></a>,
 113         <a class="citerefentry" href="glVertexAttrib.xml"><span class="citerefentry"><span class="refentrytitle">glVertexAttrib</span></span></a></p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 114             Copyright <span class="trademark"></span>© 2003-2005 3Dlabs Inc. Ltd.
 115             This material may be distributed subject to the terms and conditions set forth in
 116             the Open Publication License, v 1.0, 8 June 1999.
 117             <a class="ulink" href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>.
 118         </p></div></div></body></html>