upstream-man-pages/man2/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
  39         <constant>GL_FRAGMENT_SHADER</constant> are attached to
  40         <parameter>program</parameter>, they will be used to create an
  41         executable that will run on the programmable fragment
  42         processor.</para>
  43
  44         <para>The status of the link operation will be stored as part of
  45         the program object's state. This value will be set to
  46         <constant>GL_TRUE</constant> if the program object was linked
  47         without errors and is ready for use, and
  48         <constant>GL_FALSE</constant> otherwise. It can be queried by
  49         calling
  50         <citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
  51         with arguments <parameter>program</parameter> and
  52         <constant>GL_LINK_STATUS</constant>.</para>
  53
  54         <para>As a result of a successful link operation, all active
  55         user-defined uniform variables belonging to
  56         <parameter>program</parameter> will be initialized to 0, and
  57         each of the program object's active uniform variables will be
  58         assigned a location that can be queried by calling
  59         <citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>.
  60         Also, any active user-defined attribute variables that have not
  61         been bound to a generic vertex attribute index will be bound to
  62         one at this time.</para>
  63
  64         <para>Linking of a program object can fail for a number of
  65         reasons as specified in the <emphasis>OpenGL Shading Language
  66         Specification</emphasis>. The following lists some of the
  67         conditions that will cause a link error.</para>
  68
  69         <itemizedlist>
  70             <listitem>
  71                 <para>The number of active attribute variables supported
  72                 by the implementation has been exceeded.</para>
  73             </listitem>
  74             <listitem>
  75                 <para>The storage limit for uniform variables has been
  76                 exceeded.</para>
  77             </listitem>
  78             <listitem>
  79                 <para>The number of active uniform variables supported
  80                 by the implementation has been exceeded.</para>
  81             </listitem>
  82             <listitem>
  83                 <para>The <function>main</function> function is missing
  84                 for the vertex shader or the fragment shader.</para>
  85             </listitem>
  86             <listitem>
  87                 <para>A varying variable actually used in the fragment
  88                 shader is not declared in the same way (or is not
  89                 declared at all) in the vertex shader.</para>
  90             </listitem>
  91             <listitem>
  92                 <para>A reference to a function or variable name is
  93                 unresolved.</para>
  94             </listitem>
  95             <listitem>
  96                 <para>A shared global is declared with two different
  97                 types or two different initial values.</para>
  98             </listitem>
  99             <listitem>
 100                 <para>One or more of the attached shader objects has not
 101                 been successfully compiled.</para>
 102             </listitem>
 103             <listitem>
 104                 <para>Binding a generic attribute matrix caused some
 105                 rows of the matrix to fall outside the allowed maximum
 106                 of <constant>GL_MAX_VERTEX_ATTRIBS</constant>.</para>
 107             </listitem>
 108             <listitem>
 109                 <para>Not enough contiguous vertex attribute slots could
 110                 be found to bind attribute matrices.</para>
 111             </listitem>
 112         </itemizedlist>
 113
 114         <para>When a program object has been successfully linked, the
 115         program object can be made part of current state by calling
 116         <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>.
 117         Whether or not the link operation was successful, the program
 118         object's information log will be overwritten. The information
 119         log can be retrieved by calling
 120         <citerefentry><refentrytitle>glGetProgramInfoLog</refentrytitle></citerefentry>.</para>
 121
 122         <para><function>glLinkProgram</function> will also install the
 123         generated executables as part of the current rendering state if
 124         the link operation was successful and the specified program
 125         object is already currently in use as a result of a previous
 126         call to
 127         <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>.
 128         If the program object currently in use is relinked
 129         unsuccessfully, its link status will be set to
 130         <constant>GL_FALSE</constant> , but the executables and
 131         associated state will remain part of the current state until a
 132         subsequent call to <function>glUseProgram</function> removes it
 133         from use. After it is removed from use, it cannot be made part
 134         of current state until it has been successfully relinked.</para>
 135
 136         <para>If <parameter>program</parameter> contains shader objects
 137         of type <constant>GL_VERTEX_SHADER</constant> but does not
 138         contain shader objects of type
 139         <constant>GL_FRAGMENT_SHADER</constant>, the vertex shader will
 140         be linked against the implicit interface for fixed functionality
 141         fragment processing. Similarly, if
 142         <parameter>program</parameter> contains shader objects of type
 143         <constant>GL_FRAGMENT_SHADER</constant> but it does not contain
 144         shader objects of type <constant>GL_VERTEX_SHADER</constant>,
 145         the fragment shader will be linked against the implicit
 146         interface for fixed functionality vertex processing.</para>
 147
 148         <para>The program object's information log is updated and the
 149         program is generated at the time of the link operation. After
 150         the link operation, applications are free to modify attached
 151         shader objects, compile attached shader objects, detach shader
 152         objects, delete shader objects, and attach additional shader
 153         objects. None of these operations affects the information log or
 154         the program that is part of the program object.</para>
 155     </refsect1>
 156     <refsect1 id="notes"><title>Notes</title>
 157         <para><function>glLinkProgram</function>
 158         is available only if the GL version is 2.0 or greater.</para>
 159         <para>If the link operation is unsuccessful, any information about a previous link operation on <parameter>program</parameter>
 160         is lost (i.e., a failed link does not restore the old state of <parameter>program</parameter>
 161         ). Certain information can still be retrieved from <parameter>program</parameter>
 162         even after an unsuccessful link operation. See for instance <citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
 163         and <citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>.</para>
 164     </refsect1>
 165     <refsect1 id="errors"><title>Errors</title>
 166         <para><constant>GL_INVALID_VALUE</constant>
 167         is generated if <parameter>program</parameter>
 168         is not a value generated by OpenGL.</para>
 169         <para><constant>GL_INVALID_OPERATION</constant>
 170         is generated if <parameter>program</parameter>
 171         is not a program object.</para>
 172         <para><constant>GL_INVALID_OPERATION</constant>
 173         is generated if <function>glLinkProgram</function>
 174         is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 175         and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
 176     </refsect1>
 177     <refsect1 id="associatedgets"><title>Associated Gets</title>
 178         <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 179         with the argument <constant>GL_CURRENT_PROGRAM</constant></para>
 180         <para><citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
 181         with argument <parameter>program</parameter>
 182         and the index of an active attribute variable</para>
 183         <para><citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>
 184         with argument <parameter>program</parameter>
 185         and the index of an active uniform variable<parameter></parameter></para>
 186         <para><citerefentry><refentrytitle>glGetAttachedShaders</refentrytitle></citerefentry>
 187         with argument <parameter>program</parameter></para>
 188         <para><citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>
 189         with argument <parameter>program</parameter>
 190         and an attribute variable name</para>
 191         <para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
 192         with arguments <parameter>program</parameter>
 193         and <constant>GL_LINK_STATUS</constant></para>
 194         <para><citerefentry><refentrytitle>glGetProgramInfoLog</refentrytitle></citerefentry>
 195         with argument <parameter>program</parameter></para>
 196         <para><citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>
 197         with argument <parameter>program</parameter>
 198         and a uniform variable location</para>
 199         <para><citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>
 200         with argument <parameter>program</parameter>
 201         and a uniform variable name</para>
 202         <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
 203     </refsect1>
 204     <refsect1 id="seealso"><title>See Also</title>
 205         <para><citerefentry><refentrytitle>glAttachShader</refentrytitle></citerefentry>,
 206         <citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,
 207         <citerefentry><refentrytitle>glCompileShader</refentrytitle></citerefentry>,
 208         <citerefentry><refentrytitle>glCreateProgram</refentrytitle></citerefentry>,
 209         <citerefentry><refentrytitle>glDeleteProgram</refentrytitle></citerefentry>,
 210         <citerefentry><refentrytitle>glDetachShader</refentrytitle></citerefentry>,
 211         <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>,
 212         <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>,
 213         <citerefentry><refentrytitle>glValidateProgram</refentrytitle></citerefentry></para>
 214     </refsect1>
 215     <refsect1 id="Copyright"><title>Copyright</title>
 216         <para>
 217             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 218             This material may be distributed subject to the terms and conditions set forth in
 219             the Open Publication License, v 1.0, 8 June 1999.
 220             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 221         </para>
 222     </refsect1>
 223 </refentry>