Commit | Line | Data |
---|---|---|
7faf1d71 AW |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd"> | |
3 | <!-- saved from url=(0013)about:internet --> | |
4 | <?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" /><link rel="stylesheet" type="text/css" href="opengl-man.css" /><title>glLinkProgram - OpenGL 4 Reference Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glLinkProgram"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glLinkProgram — Links a program object</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><p><code class="funcdef">void <b class="fsfunc">glLinkProgram</b>(</code>GLuint <var class="pdparam">program</var><code>)</code>;</p></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 to be linked.</p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p><code class="function">glLinkProgram</code> links the program | |
5 | object specified by <em class="parameter"><code>program</code></em>. If any | |
6 | shader objects of type <code class="constant">GL_VERTEX_SHADER</code> are | |
7 | attached to <em class="parameter"><code>program</code></em>, they will be used to | |
8 | create an executable that will run on the programmable vertex | |
9 | processor. If any shader objects of type <code class="constant">GL_GEOMETRY_SHADER</code> | |
10 | are attached to <em class="parameter"><code>program</code></em>, they will be used to create | |
11 | an executable that will run on the programmable geometry processor. | |
12 | If any shader objects of type | |
13 | <code class="constant">GL_FRAGMENT_SHADER</code> are attached to | |
14 | <em class="parameter"><code>program</code></em>, they will be used to create an | |
15 | executable that will run on the programmable fragment | |
16 | processor.</p><p>The status of the link operation will be stored as part of | |
17 | the program object's state. This value will be set to | |
18 | <code class="constant">GL_TRUE</code> if the program object was linked | |
19 | without errors and is ready for use, and | |
20 | <code class="constant">GL_FALSE</code> otherwise. It can be queried by | |
21 | calling | |
22 | <a href="glGetProgram.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgram</span></span></a> | |
23 | with arguments <em class="parameter"><code>program</code></em> and | |
24 | <code class="constant">GL_LINK_STATUS</code>.</p><p>As a result of a successful link operation, all active | |
25 | user-defined uniform variables belonging to | |
26 | <em class="parameter"><code>program</code></em> will be initialized to 0, and | |
27 | each of the program object's active uniform variables will be | |
28 | assigned a location that can be queried by calling | |
29 | <a href="glGetUniformLocation.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniformLocation</span></span></a>. | |
30 | Also, any active user-defined attribute variables that have not | |
31 | been bound to a generic vertex attribute index will be bound to | |
32 | one at this time.</p><p>Linking of a program object can fail for a number of | |
33 | reasons as specified in the <span class="emphasis"><em>OpenGL Shading Language | |
34 | Specification</em></span>. The following lists some of the | |
35 | conditions that will cause a link error.</p><div class="itemizedlist"><ul type="disc"><li><p>The number of active attribute variables supported | |
36 | by the implementation has been exceeded.</p></li><li><p>The storage limit for uniform variables has been | |
37 | exceeded.</p></li><li><p>The number of active uniform variables supported | |
38 | by the implementation has been exceeded.</p></li><li><p>The <code class="function">main</code> function is missing | |
39 | for the vertex, geometry or fragment shader.</p></li><li><p>A varying variable actually used in the fragment | |
40 | shader is not declared in the same way (or is not | |
41 | declared at all) in the vertex shader, or geometry shader shader if present.</p></li><li><p>A reference to a function or variable name is | |
42 | unresolved.</p></li><li><p>A shared global is declared with two different | |
43 | types or two different initial values.</p></li><li><p>One or more of the attached shader objects has not | |
44 | been successfully compiled.</p></li><li><p>Binding a generic attribute matrix caused some | |
45 | rows of the matrix to fall outside the allowed maximum | |
46 | of <code class="constant">GL_MAX_VERTEX_ATTRIBS</code>.</p></li><li><p>Not enough contiguous vertex attribute slots could | |
47 | be found to bind attribute matrices.</p></li><li><p>The program object contains objects to form a fragment shader but | |
48 | does not contain objects to form a vertex shader.</p></li><li><p>The program object contains objects to form a geometry shader | |
49 | but does not contain objects to form a vertex shader.</p></li><li><p>The program object contains objects to form a geometry shader | |
50 | and the input primitive type, output primitive type, or maximum output | |
51 | vertex count is not specified in any compiled geometry shader | |
52 | object.</p></li><li><p>The program object contains objects to form a geometry shader | |
53 | and the input primitive type, output primitive type, or maximum output | |
54 | vertex count is specified differently in multiple geometry shader | |
55 | objects.</p></li><li><p>The number of active outputs in the fragment shader is greater | |
56 | than the value of <code class="constant">GL_MAX_DRAW_BUFFERS</code>.</p></li><li><p>The program has an active output assigned to a location greater | |
57 | than or equal to the value of <code class="constant">GL_MAX_DUAL_SOURCE_DRAW_BUFFERS</code> | |
58 | and has an active output assigned an index greater than or equal to one.</p></li><li><p>More than one varying out variable is bound to the same number and index.</p></li><li><p>The explicit binding assigments do not leave enough space for the linker | |
59 | to automatically assign a location for a varying out array, which requires | |
60 | multiple contiguous locations.</p></li><li><p>The <em class="parameter"><code>count</code></em> specified by <a href="glTransformFeedbackVaryings.xml"><span class="citerefentry"><span class="refentrytitle">glTransformFeedbackVaryings</span></span></a> | |
61 | is non-zero, but the program object has no vertex or geometry shader.</p></li><li><p>Any variable name specified to <a href="glTransformFeedbackVaryings.xml"><span class="citerefentry"><span class="refentrytitle">glTransformFeedbackVaryings</span></span></a> | |
62 | in the <em class="parameter"><code>varyings</code></em> array is not declared as an output in the vertex shader (or the geometry shader, if active).</p></li><li><p>Any two entries in the <em class="parameter"><code>varyings</code></em> array given | |
63 | <a href="glTransformFeedbackVaryings.xml"><span class="citerefentry"><span class="refentrytitle">glTransformFeedbackVaryings</span></span></a> | |
64 | specify the same varying variable.</p></li><li><p>The total number of components to capture in any transform feedback varying variable | |
65 | is greater than the constant <code class="constant">GL_MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS</code> | |
c7b31271 | 66 | and the buffer mode is <code class="constant">GL_SEPARATE_ATTRIBS</code>.</p></li></ul></div><p>When a program object has been successfully linked, the |
7faf1d71 AW |
67 | program object can be made part of current state by calling |
68 | <a href="glUseProgram.xml"><span class="citerefentry"><span class="refentrytitle">glUseProgram</span></span></a>. | |
69 | Whether or not the link operation was successful, the program | |
70 | object's information log will be overwritten. The information | |
71 | log can be retrieved by calling | |
72 | <a href="glGetProgramInfoLog.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgramInfoLog</span></span></a>.</p><p><code class="function">glLinkProgram</code> will also install the | |
73 | generated executables as part of the current rendering state if | |
74 | the link operation was successful and the specified program | |
75 | object is already currently in use as a result of a previous | |
76 | call to | |
77 | <a href="glUseProgram.xml"><span class="citerefentry"><span class="refentrytitle">glUseProgram</span></span></a>. | |
78 | If the program object currently in use is relinked | |
79 | unsuccessfully, its link status will be set to | |
80 | <code class="constant">GL_FALSE</code> , but the executables and | |
81 | associated state will remain part of the current state until a | |
82 | subsequent call to <code class="function">glUseProgram</code> removes it | |
83 | from use. After it is removed from use, it cannot be made part | |
84 | of current state until it has been successfully relinked.</p><p>If <em class="parameter"><code>program</code></em> contains shader objects | |
85 | of type <code class="constant">GL_VERTEX_SHADER</code>, and optionally of type <code class="constant">GL_GEOMETRY_SHADER</code>, | |
86 | but does not contain shader objects of type | |
87 | <code class="constant">GL_FRAGMENT_SHADER</code>, the vertex shader executable will | |
88 | be installed on the programmable vertex processor, the geometry shader executable, if present, | |
89 | will be installed on the programmable geometry processor, but no executable will | |
90 | be installed on the fragment processor. The results of | |
91 | rasterizing primitives with such a program will be undefined.</p><p>The program object's information log is updated and the | |
92 | program is generated at the time of the link operation. After | |
93 | the link operation, applications are free to modify attached | |
94 | shader objects, compile attached shader objects, detach shader | |
95 | objects, delete shader objects, and attach additional shader | |
96 | objects. None of these operations affects the information log or | |
97 | the program that is part of the program object.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>If the link operation is unsuccessful, any information about a previous link operation on <em class="parameter"><code>program</code></em> | |
98 | is lost (i.e., a failed link does not restore the old state of <em class="parameter"><code>program</code></em> | |
99 | ). Certain information can still be retrieved from <em class="parameter"><code>program</code></em> | |
100 | even after an unsuccessful link operation. See for instance <a href="glGetActiveAttrib.xml"><span class="citerefentry"><span class="refentrytitle">glGetActiveAttrib</span></span></a> | |
101 | and <a href="glGetActiveUniform.xml"><span class="citerefentry"><span class="refentrytitle">glGetActiveUniform</span></span></a>.</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> | |
102 | is generated if <em class="parameter"><code>program</code></em> | |
103 | is not a value generated by OpenGL.</p><p><code class="constant">GL_INVALID_OPERATION</code> | |
104 | is generated if <em class="parameter"><code>program</code></em> | |
105 | is not a program object.</p><p><code class="constant">GL_INVALID_OPERATION</code> | |
106 | is generated if <em class="parameter"><code>program</code></em> is the currently active program | |
107 | object and transform feedback mode is active.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p><a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> | |
108 | with the argument <code class="constant">GL_CURRENT_PROGRAM</code></p><p><a href="glGetActiveAttrib.xml"><span class="citerefentry"><span class="refentrytitle">glGetActiveAttrib</span></span></a> | |
109 | with argument <em class="parameter"><code>program</code></em> | |
110 | and the index of an active attribute variable</p><p><a href="glGetActiveUniform.xml"><span class="citerefentry"><span class="refentrytitle">glGetActiveUniform</span></span></a> | |
111 | with argument <em class="parameter"><code>program</code></em> | |
112 | and the index of an active uniform variable<em class="parameter"><code></code></em></p><p><a href="glGetAttachedShaders.xml"><span class="citerefentry"><span class="refentrytitle">glGetAttachedShaders</span></span></a> | |
113 | with argument <em class="parameter"><code>program</code></em></p><p><a href="glGetAttribLocation.xml"><span class="citerefentry"><span class="refentrytitle">glGetAttribLocation</span></span></a> | |
114 | with argument <em class="parameter"><code>program</code></em> | |
115 | and an attribute variable name</p><p><a href="glGetProgram.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgram</span></span></a> | |
116 | with arguments <em class="parameter"><code>program</code></em> | |
117 | and <code class="constant">GL_LINK_STATUS</code></p><p><a href="glGetProgramInfoLog.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgramInfoLog</span></span></a> | |
118 | with argument <em class="parameter"><code>program</code></em></p><p><a href="glGetUniform.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniform</span></span></a> | |
119 | with argument <em class="parameter"><code>program</code></em> | |
120 | and a uniform variable location</p><p><a href="glGetUniformLocation.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniformLocation</span></span></a> | |
121 | with argument <em class="parameter"><code>program</code></em> | |
122 | and a uniform variable name</p><p><a 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 href="glAttachShader.xml"><span class="citerefentry"><span class="refentrytitle">glAttachShader</span></span></a>, | |
123 | <a href="glBindAttribLocation.xml"><span class="citerefentry"><span class="refentrytitle">glBindAttribLocation</span></span></a>, | |
124 | <a href="glCompileShader.xml"><span class="citerefentry"><span class="refentrytitle">glCompileShader</span></span></a>, | |
125 | <a href="glCreateProgram.xml"><span class="citerefentry"><span class="refentrytitle">glCreateProgram</span></span></a>, | |
126 | <a href="glDeleteProgram.xml"><span class="citerefentry"><span class="refentrytitle">glDeleteProgram</span></span></a>, | |
127 | <a href="glDetachShader.xml"><span class="citerefentry"><span class="refentrytitle">glDetachShader</span></span></a>, | |
128 | <a href="glUniform.xml"><span class="citerefentry"><span class="refentrytitle">glUniform</span></span></a>, | |
129 | <a href="glUseProgram.xml"><span class="citerefentry"><span class="refentrytitle">glUseProgram</span></span></a>, | |
130 | <a href="glValidateProgram.xml"><span class="citerefentry"><span class="refentrytitle">glValidateProgram</span></span></a></p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p> | |
131 | Copyright <span class="trademark"></span>© 2003-2005 3Dlabs Inc. Ltd. | |
132 | Copyright <span class="trademark"></span>© 2010 Khronos Group. | |
133 | This material may be distributed subject to the terms and conditions set forth in | |
134 | the Open Publication License, v 1.0, 8 June 1999. | |
135 | <a href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>. | |
136 | </p></div></div></body></html> |