Commit | Line | Data |
---|---|---|
7faf1d71 AW |
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> |