upstream-man-pages/man4/xhtml/glLinkProgram.xml

   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>
  66         and the buffer mode is <code class="constant">SEPARATE_ATTRIBS</code>.</p></li></ul></div><p>When a program object has been successfully linked, the
  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>