rename upstream-man-pages to upstream-doc

[clinton/guile-figl.git] / upstream-doc / man2 / glGetAttribLocation.xml

<?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="glGetAttribLocation">
    <refmeta>
	<refentrytitle>glGetAttribLocation</refentrytitle>
	<manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
	<refname>glGetAttribLocation</refname>
	<refpurpose>Returns the location of an attribute variable</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
	<funcsynopsis>
	    <funcprototype>
		<funcdef>GLint <function>glGetAttribLocation</function></funcdef>
		<paramdef>GLuint <parameter>program</parameter></paramdef>
		<paramdef>const GLchar *<parameter>name</parameter></paramdef>
	    </funcprototype>
	</funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
	<variablelist>
	    <varlistentry>
		<term><parameter>program</parameter></term>
		<listitem>
		    <para>Specifies the program object to be
		    queried.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><parameter>name</parameter></term>
		<listitem>
		    <para>Points to a null terminated string containing
		    the name of the attribute variable whose location is
		    to be queried.</para>
		</listitem>
	    </varlistentry>
	</variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
	<para><function>glGetAttribLocation</function> queries the
	previously linked program object specified by
	<parameter>program</parameter> for the attribute variable
	specified by <parameter>name</parameter> and returns the index
	of the generic vertex attribute that is bound to that attribute
	variable. If <parameter>name</parameter> is a matrix attribute
	variable, the index of the first column of the matrix is
	returned. If the named attribute variable is not an active
	attribute in the specified program object or if
	<parameter>name</parameter> starts with the reserved prefix
	&quot;gl_&quot;, a value of -1 is returned.</para>

	<para>The association between an attribute variable name and a
	generic attribute index can be specified at any time by calling
	<citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>.
	Attribute bindings do not go into effect until
	<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
	is called. After a program object has been linked successfully,
	the index values for attribute variables remain fixed until the
	next link command occurs. The attribute values can only be
	queried after a link if the link was successful.
	<function>glGetAttribLocation</function> returns the binding
	that actually went into effect the last time
	<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
	was called for the specified program object. Attribute bindings
	that have been specified since the last link operation are not
	returned by <function>glGetAttribLocation</function>.</para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
	<para><function>glGetAttribLocation</function> is available only
	if the GL version is 2.0 or greater.</para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
	<para><constant>GL_INVALID_OPERATION</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
	<parameter>program</parameter> has not been successfully
	linked.</para>

	<para><constant>GL_INVALID_OPERATION</constant> is generated if
	<function>glGetAttribLocation</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>glGetActiveAttrib</refentrytitle></citerefentry>
	with argument <parameter>program</parameter> and the index of an
	active attribute</para>

	<para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
	<para><citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glVertexAttribPointer</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>