upstream-doc/man3/glLinkProgram.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="glLinkProgram">
   5     <refmeta>
   6     <refentrytitle>glLinkProgram</refentrytitle>
   7     <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10     <refname>glLinkProgram</refname>
  11     <refpurpose>Links a program object</refpurpose>
  12     </refnamediv>
  13     <refsynopsisdiv><title>C Specification</title>
  14     <funcsynopsis>
  15         <funcprototype>
  16         <funcdef>void <function>glLinkProgram</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 to be linked.</para>
  27
  28         </listitem>
  29         </varlistentry>
  30     </variablelist>
  31     </refsect1>
  32     <refsect1 id="description"><title>Description</title>
  33     <para><function>glLinkProgram</function> links the program
  34     object specified by <parameter>program</parameter>. If any
  35     shader objects of type <constant>GL_VERTEX_SHADER</constant> are
  36     attached to <parameter>program</parameter>, they will be used to
  37     create an executable that will run on the programmable vertex
  38     processor. If any shader objects of type <constant>GL_GEOMETRY_SHADER</constant>
  39     are attached to <parameter>program</parameter>, they will be used to create
  40     an executable that will run on the programmable geometry processor.
  41     If any shader objects of type
  42     <constant>GL_FRAGMENT_SHADER</constant> are attached to
  43     <parameter>program</parameter>, they will be used to create an
  44     executable that will run on the programmable fragment
  45     processor.</para>
  46
  47     <para>The status of the link operation will be stored as part of
  48     the program object's state. This value will be set to
  49     <constant>GL_TRUE</constant> if the program object was linked
  50     without errors and is ready for use, and
  51     <constant>GL_FALSE</constant> otherwise. It can be queried by
  52     calling
  53     <citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
  54     with arguments <parameter>program</parameter> and
  55     <constant>GL_LINK_STATUS</constant>.</para>
  56
  57     <para>As a result of a successful link operation, all active
  58     user-defined uniform variables belonging to
  59     <parameter>program</parameter> will be initialized to 0, and
  60     each of the program object's active uniform variables will be
  61     assigned a location that can be queried by calling
  62     <citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>.
  63     Also, any active user-defined attribute variables that have not
  64     been bound to a generic vertex attribute index will be bound to
  65     one at this time.</para>
  66
  67     <para>Linking of a program object can fail for a number of
  68     reasons as specified in the <emphasis>OpenGL Shading Language
  69     Specification</emphasis>. The following lists some of the
  70     conditions that will cause a link error.</para>
  71
  72     <itemizedlist>
  73         <listitem>
  74         <para>The number of active attribute variables supported
  75         by the implementation has been exceeded.</para>
  76         </listitem>
  77         <listitem>
  78         <para>The storage limit for uniform variables has been
  79         exceeded.</para>
  80         </listitem>
  81         <listitem>
  82         <para>The number of active uniform variables supported
  83         by the implementation has been exceeded.</para>
  84         </listitem>
  85         <listitem>
  86         <para>The <function>main</function> function is missing
  87         for the vertex, geometry or fragment shader.</para>
  88         </listitem>
  89         <listitem>
  90         <para>A varying variable actually used in the fragment
  91         shader is not declared in the same way (or is not
  92         declared at all) in the vertex shader, or geometry shader shader if present.</para>
  93         </listitem>
  94         <listitem>
  95         <para>A reference to a function or variable name is
  96         unresolved.</para>
  97         </listitem>
  98         <listitem>
  99         <para>A shared global is declared with two different
 100         types or two different initial values.</para>
 101         </listitem>
 102         <listitem>
 103         <para>One or more of the attached shader objects has not
 104         been successfully compiled.</para>
 105         </listitem>
 106         <listitem>
 107         <para>Binding a generic attribute matrix caused some
 108         rows of the matrix to fall outside the allowed maximum
 109         of <constant>GL_MAX_VERTEX_ATTRIBS</constant>.</para>
 110         </listitem>
 111         <listitem>
 112         <para>Not enough contiguous vertex attribute slots could
 113         be found to bind attribute matrices.</para>
 114         </listitem>
 115         <listitem>
 116         <para>The program object contains objects to form a fragment shader but
 117         does not contain objects to form a vertex shader.</para>
 118         </listitem>
 119         <listitem>
 120         <para>The program object contains objects to form a geometry shader
 121         but does not contain objects to form a vertex shader.</para>
 122         </listitem>
 123         <listitem>
 124         <para>The program object contains objects to form a geometry shader
 125         and the input primitive type, output primitive type, or maximum output
 126         vertex count is not specified in any compiled geometry shader
 127         object.</para>
 128         </listitem>
 129         <listitem>
 130         <para>The program object contains objects to form a geometry shader
 131         and the input primitive type, output primitive type, or maximum output
 132         vertex count is specified differently in multiple geometry shader
 133         objects.</para>
 134         </listitem>
 135         <listitem>
 136         <para>The number of active outputs in the fragment shader is greater
 137         than the value of <constant>GL_MAX_DRAW_BUFFERS</constant>.</para>
 138         </listitem>
 139         <listitem>
 140         <para>The program has an active output assigned to a location greater
 141         than or equal to the value of <constant>GL_MAX_DUAL_SOURCE_DRAW_BUFFERS</constant>
 142         and has an active output assigned an index greater than or equal to one.</para>
 143         </listitem>
 144         <listitem>
 145         <para>More than one varying out variable is bound to the same number and index.</para>
 146         </listitem>
 147         <listitem>
 148         <para>The explicit binding assigments do not leave enough space for the linker
 149         to automatically assign a location for a varying out array, which requires
 150         multiple contiguous locations.</para>
 151         </listitem>
 152         <listitem>
 153         <para>The <parameter>count</parameter> specified by <citerefentry><refentrytitle>glTransformFeedbackVaryings</refentrytitle></citerefentry>
 154         is non-zero, but the program object has no vertex or geometry shader.</para>
 155         </listitem>
 156         <listitem>
 157         <para>Any variable name specified to <citerefentry><refentrytitle>glTransformFeedbackVaryings</refentrytitle></citerefentry>
 158         in the <parameter>varyings</parameter> array is not declared as an output in the vertex shader (or the geometry shader, if active).</para>
 159         </listitem>
 160         <listitem>
 161         <para>Any two entries in the <parameter>varyings</parameter> array given
 162         <citerefentry><refentrytitle>glTransformFeedbackVaryings</refentrytitle></citerefentry>
 163         specify the same varying variable.</para>
 164         </listitem>
 165         <listitem>
 166         <para>The total number of components to capture in any transform feedback varying variable
 167         is  greater  than  the  constant <constant>GL_MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS</constant>
 168         and the buffer mode is <constant>SEPARATE_ATTRIBS</constant>.</para>
 169         </listitem>
 170     </itemizedlist>
 171
 172     <para>When a program object has been successfully linked, the
 173     program object can be made part of current state by calling
 174     <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>.
 175     Whether or not the link operation was successful, the program
 176     object's information log will be overwritten. The information
 177     log can be retrieved by calling
 178     <citerefentry><refentrytitle>glGetProgramInfoLog</refentrytitle></citerefentry>.</para>
 179
 180     <para><function>glLinkProgram</function> will also install the
 181     generated executables as part of the current rendering state if
 182     the link operation was successful and the specified program
 183     object is already currently in use as a result of a previous
 184     call to
 185     <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>.
 186     If the program object currently in use is relinked
 187     unsuccessfully, its link status will be set to
 188     <constant>GL_FALSE</constant> , but the executables and
 189     associated state will remain part of the current state until a
 190     subsequent call to <function>glUseProgram</function> removes it
 191     from use. After it is removed from use, it cannot be made part
 192     of current state until it has been successfully relinked.</para>
 193
 194     <para>If <parameter>program</parameter> contains shader objects
 195     of type <constant>GL_VERTEX_SHADER</constant>, and optionally of type <constant>GL_GEOMETRY_SHADER</constant>,
 196     but does not contain shader objects of type
 197     <constant>GL_FRAGMENT_SHADER</constant>, the vertex shader executable will
 198     be installed on the programmable vertex processor, the geometry shader executable, if present,
 199     will be installed on the programmable geometry processor, but no executable will
 200     be installed on the fragment processor. The results of
 201     rasterizing primitives with such a program will be undefined.</para>
 202
 203     <para>The program object's information log is updated and the
 204     program is generated at the time of the link operation. After
 205     the link operation, applications are free to modify attached
 206     shader objects, compile attached shader objects, detach shader
 207     objects, delete shader objects, and attach additional shader
 208     objects. None of these operations affects the information log or
 209     the program that is part of the program object.</para>
 210     </refsect1>
 211     <refsect1 id="notes"><title>Notes</title>
 212     <para>If the link operation is unsuccessful, any information about a previous link operation on <parameter>program</parameter>
 213     is lost (i.e., a failed link does not restore the old state of <parameter>program</parameter>
 214     ). Certain information can still be retrieved from <parameter>program</parameter>
 215     even after an unsuccessful link operation. See for instance <citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
 216     and <citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>.</para>
 217     </refsect1>
 218     <refsect1 id="errors"><title>Errors</title>
 219     <para><constant>GL_INVALID_VALUE</constant>
 220     is generated if <parameter>program</parameter>
 221     is not a value generated by OpenGL.</para>
 222     <para><constant>GL_INVALID_OPERATION</constant>
 223     is generated if <parameter>program</parameter>
 224     is not a program object.</para>
 225     <para><constant>GL_INVALID_OPERATION</constant>
 226     is generated if <parameter>program</parameter> is the currently active program
 227     object and transform feedback mode is active.</para>
 228     </refsect1>
 229     <refsect1 id="associatedgets"><title>Associated Gets</title>
 230     <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 231     with the argument <constant>GL_CURRENT_PROGRAM</constant></para>
 232     <para><citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
 233     with argument <parameter>program</parameter>
 234     and the index of an active attribute variable</para>
 235     <para><citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>
 236     with argument <parameter>program</parameter>
 237     and the index of an active uniform variable<parameter></parameter></para>
 238     <para><citerefentry><refentrytitle>glGetAttachedShaders</refentrytitle></citerefentry>
 239     with argument <parameter>program</parameter></para>
 240     <para><citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>
 241     with argument <parameter>program</parameter>
 242     and an attribute variable name</para>
 243     <para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
 244     with arguments <parameter>program</parameter>
 245     and <constant>GL_LINK_STATUS</constant></para>
 246     <para><citerefentry><refentrytitle>glGetProgramInfoLog</refentrytitle></citerefentry>
 247     with argument <parameter>program</parameter></para>
 248     <para><citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>
 249     with argument <parameter>program</parameter>
 250     and a uniform variable location</para>
 251     <para><citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>
 252     with argument <parameter>program</parameter>
 253     and a uniform variable name</para>
 254     <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
 255     </refsect1>
 256     <refsect1 id="seealso"><title>See Also</title>
 257     <para><citerefentry><refentrytitle>glAttachShader</refentrytitle></citerefentry>,
 258     <citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,
 259     <citerefentry><refentrytitle>glCompileShader</refentrytitle></citerefentry>,
 260     <citerefentry><refentrytitle>glCreateProgram</refentrytitle></citerefentry>,
 261     <citerefentry><refentrytitle>glDeleteProgram</refentrytitle></citerefentry>,
 262     <citerefentry><refentrytitle>glDetachShader</refentrytitle></citerefentry>,
 263     <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>,
 264     <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>,
 265     <citerefentry><refentrytitle>glValidateProgram</refentrytitle></citerefentry></para>
 266     </refsect1>
 267     <refsect1 id="Copyright"><title>Copyright</title>
 268         <para>
 269             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 270             Copyright <trademark class="copyright"></trademark> 2010 Khronos Group.
 271             This material may be distributed subject to the terms and conditions set forth in
 272             the Open Publication License, v 1.0, 8 June 1999.
 273             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 274         </para>
 275     </refsect1>
 276 </refentry>