Subversion Repositories AndroidProjects

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"

              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">

<refentry id="glLinkProgram">

    <refmeta>

        <refentrytitle>glLinkProgram</refentrytitle>

        <manvolnum>3G</manvolnum>

    </refmeta>

    <refnamediv>

        <refname>glLinkProgram</refname>

        <refpurpose>Links a program object</refpurpose>

    </refnamediv>

    <refsynopsisdiv><title>C Specification</title>

        <funcsynopsis>

            <funcprototype>

                <funcdef>void <function>glLinkProgram</function></funcdef>

                <paramdef>GLuint <parameter>program</parameter></paramdef>

            </funcprototype>

        </funcsynopsis>

    </refsynopsisdiv>

    <refsect1 id="parameters"><title>Parameters</title>

        <variablelist>

            <varlistentry>

                <term><parameter>program</parameter></term>

                <listitem>

                    <para>Specifies the handle of the program object to be linked.</para>

                </listitem>

            </varlistentry>

        </variablelist>

    </refsect1>

    <refsect1 id="description"><title>Description</title>

        <para><function>glLinkProgram</function> links the program

        object specified by <parameter>program</parameter>. If any

        shader objects of type <constant>GL_VERTEX_SHADER</constant> are

        attached to <parameter>program</parameter>, they will be used to

        create an executable that will run on the programmable vertex

        processor. If any shader objects of type

        <constant>GL_FRAGMENT_SHADER</constant> are attached to

        <parameter>program</parameter>, they will be used to create an

        executable that will run on the programmable fragment

        processor.</para>

        <para>The status of the link operation will be stored as part of

        the program object's state. This value will be set to

        <constant>GL_TRUE</constant> if the program object was linked

        without errors and is ready for use, and

        <constant>GL_FALSE</constant> otherwise. It can be queried by

        calling

        <citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>

        with arguments <parameter>program</parameter> and

        <constant>GL_LINK_STATUS</constant>.</para>

        <para>As a result of a successful link operation, all active

        user-defined uniform variables belonging to

        <parameter>program</parameter> will be initialized to 0, and

        each of the program object's active uniform variables will be

        assigned a location that can be queried by calling

        <citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>.

        Also, any active user-defined attribute variables that have not

        been bound to a generic vertex attribute index will be bound to

        one at this time.</para>

        <para>Linking of a program object can fail for a number of

        reasons as specified in the <emphasis>OpenGL Shading Language

        Specification</emphasis>. The following lists some of the

        conditions that will cause a link error.</para>

        <itemizedlist>

            <listitem>

                <para>The number of active attribute variables supported

                by the implementation has been exceeded.</para>

            </listitem>

            <listitem>

                <para>The storage limit for uniform variables has been

                exceeded.</para>

            </listitem>

            <listitem>

                <para>The number of active uniform variables supported

                by the implementation has been exceeded.</para>

            </listitem>

            <listitem>

                <para>The <function>main</function> function is missing

                for the vertex shader or the fragment shader.</para>

            </listitem>

            <listitem>

                <para>A varying variable actually used in the fragment

                shader is not declared in the same way (or is not

                declared at all) in the vertex shader.</para>

            </listitem>

            <listitem>

                <para>A reference to a function or variable name is

                unresolved.</para>

            </listitem>

            <listitem>

                <para>A shared global is declared with two different

                types or two different initial values.</para>

            </listitem>

            <listitem>

                <para>One or more of the attached shader objects has not

                been successfully compiled.</para>

            </listitem>

            <listitem>

                <para>Binding a generic attribute matrix caused some

                rows of the matrix to fall outside the allowed maximum

                of <constant>GL_MAX_VERTEX_ATTRIBS</constant>.</para>

            </listitem>

            <listitem>

                <para>Not enough contiguous vertex attribute slots could

                be found to bind attribute matrices.</para>

            </listitem>

        </itemizedlist>

        <para>When a program object has been successfully linked, the

        program object can be made part of current state by calling

        <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>.

        Whether or not the link operation was successful, the program

        object's information log will be overwritten. The information

        log can be retrieved by calling

        <citerefentry><refentrytitle>glGetProgramInfoLog</refentrytitle></citerefentry>.</para>

        <para><function>glLinkProgram</function> will also install the

        generated executables as part of the current rendering state if

        the link operation was successful and the specified program

        object is already currently in use as a result of a previous

        call to

        <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>.

        If the program object currently in use is relinked

        unsuccessfully, its link status will be set to

        <constant>GL_FALSE</constant> , but the executables and

        associated state will remain part of the current state until a

        subsequent call to <function>glUseProgram</function> removes it

        from use. After it is removed from use, it cannot be made part

        of current state until it has been successfully relinked.</para>

        <para>If <parameter>program</parameter> contains shader objects

        of type <constant>GL_VERTEX_SHADER</constant> but does not

        contain shader objects of type

        <constant>GL_FRAGMENT_SHADER</constant>, the vertex shader will

        be linked against the implicit interface for fixed functionality

        fragment processing. Similarly, if

        <parameter>program</parameter> contains shader objects of type

        <constant>GL_FRAGMENT_SHADER</constant> but it does not contain

        shader objects of type <constant>GL_VERTEX_SHADER</constant>,

        the fragment shader will be linked against the implicit

        interface for fixed functionality vertex processing.</para>

        <para>The program object's information log is updated and the

        program is generated at the time of the link operation. After

        the link operation, applications are free to modify attached

        shader objects, compile attached shader objects, detach shader

        objects, delete shader objects, and attach additional shader

        objects. None of these operations affects the information log or

        the program that is part of the program object.</para>

    </refsect1>

    <refsect1 id="notes"><title>Notes</title>

        <para><function>glLinkProgram</function>

        is available only if the GL version is 2.0 or greater.</para>

        <para>If the link operation is unsuccessful, any information about a previous link operation on <parameter>program</parameter>

        is lost (i.e., a failed link does not restore the old state of <parameter>program</parameter>

        ). Certain information can still be retrieved from <parameter>program</parameter>

        even after an unsuccessful link operation. See for instance <citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>

        and <citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>.</para>

    </refsect1>

    <refsect1 id="errors"><title>Errors</title>

        <para><constant>GL_INVALID_VALUE</constant>

        is generated if <parameter>program</parameter>

        is not a value generated by OpenGL.</para>

        <para><constant>GL_INVALID_OPERATION</constant>

        is generated if <parameter>program</parameter>

        is not a program object.</para>

        <para><constant>GL_INVALID_OPERATION</constant>

        is generated if <function>glLinkProgram</function>

        is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>

        and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>

    </refsect1>

    <refsect1 id="associatedgets"><title>Associated Gets</title>

        <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>

        with the argument <constant>GL_CURRENT_PROGRAM</constant></para>

        <para><citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>

        with argument <parameter>program</parameter>

        and the index of an active attribute variable</para>

        <para><citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>

        with argument <parameter>program</parameter>

        and the index of an active uniform variable<parameter></parameter></para>

        <para><citerefentry><refentrytitle>glGetAttachedShaders</refentrytitle></citerefentry>

        with argument <parameter>program</parameter></para>

        <para><citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>

        with argument <parameter>program</parameter>

        and an attribute variable name</para>

        <para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>

        with arguments <parameter>program</parameter>

        and <constant>GL_LINK_STATUS</constant></para>

        <para><citerefentry><refentrytitle>glGetProgramInfoLog</refentrytitle></citerefentry>

        with argument <parameter>program</parameter></para>

        <para><citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>

        with argument <parameter>program</parameter>

        and a uniform variable location</para>

        <para><citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>

        with argument <parameter>program</parameter>

        and a uniform variable name</para>

        <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>

    </refsect1>

    <refsect1 id="seealso"><title>See Also</title>

        <para><citerefentry><refentrytitle>glAttachShader</refentrytitle></citerefentry>,

        <citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,

        <citerefentry><refentrytitle>glCompileShader</refentrytitle></citerefentry>,

        <citerefentry><refentrytitle>glCreateProgram</refentrytitle></citerefentry>,

        <citerefentry><refentrytitle>glDeleteProgram</refentrytitle></citerefentry>,

        <citerefentry><refentrytitle>glDetachShader</refentrytitle></citerefentry>,

        <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>,

        <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>,

        <citerefentry><refentrytitle>glValidateProgram</refentrytitle></citerefentry></para>

    </refsect1>

    <refsect1 id="Copyright"><title>Copyright</title>

        <para>

            Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.

            This material may be distributed subject to the terms and conditions set forth in

            the Open Publication License, v 1.0, 8 June 1999.

            <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.

        </para>

    </refsect1>

</refentry>