Opentk/Source/Bind/Specifications/Docs/glVertexAttrib.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="glVertexAttrib">
    <refmeta>
	<refentrytitle>glVertexAttrib</refentrytitle>
	<manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
	<refname>glVertexAttrib</refname>
	<refpurpose>Specifies the value of a generic vertex attribute</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
	<funcsynopsis>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib1f</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLfloat <parameter>v0</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib1s</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLshort <parameter>v0</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib1d</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLdouble <parameter>v0</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib2f</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLfloat <parameter>v0</parameter></paramdef>
		<paramdef>GLfloat <parameter>v1</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib2s</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLshort <parameter>v0</parameter></paramdef>
		<paramdef>GLshort <parameter>v1</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib2d</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLdouble <parameter>v0</parameter></paramdef>
		<paramdef>GLdouble <parameter>v1</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib3f</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLfloat <parameter>v0</parameter></paramdef>
		<paramdef>GLfloat <parameter>v1</parameter></paramdef>
		<paramdef>GLfloat <parameter>v2</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib3s</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLshort <parameter>v0</parameter></paramdef>
		<paramdef>GLshort <parameter>v1</parameter></paramdef>
		<paramdef>GLshort <parameter>v2</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib3d</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLdouble <parameter>v0</parameter></paramdef>
		<paramdef>GLdouble <parameter>v1</parameter></paramdef>
		<paramdef>GLdouble <parameter>v2</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4f</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLfloat <parameter>v0</parameter></paramdef>
		<paramdef>GLfloat <parameter>v1</parameter></paramdef>
		<paramdef>GLfloat <parameter>v2</parameter></paramdef>
		<paramdef>GLfloat <parameter>v3</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4s</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLshort <parameter>v0</parameter></paramdef>
		<paramdef>GLshort <parameter>v1</parameter></paramdef>
		<paramdef>GLshort <parameter>v2</parameter></paramdef>
		<paramdef>GLshort <parameter>v3</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4d</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLdouble <parameter>v0</parameter></paramdef>
		<paramdef>GLdouble <parameter>v1</parameter></paramdef>
		<paramdef>GLdouble <parameter>v2</parameter></paramdef>
		<paramdef>GLdouble <parameter>v3</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4Nub</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>GLubyte <parameter>v0</parameter></paramdef>
		<paramdef>GLubyte <parameter>v1</parameter></paramdef>
		<paramdef>GLubyte <parameter>v2</parameter></paramdef>
		<paramdef>GLubyte <parameter>v3</parameter></paramdef>
	    </funcprototype>
	</funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
	<variablelist>
	    <varlistentry>
		<term><parameter>index</parameter></term>
		<listitem>
		    <para>Specifies the index of the generic vertex
		    attribute to be modified.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term>
		    <parameter>v0</parameter>,
		    <parameter>v1</parameter>,
		    <parameter>v2</parameter>,
		    <parameter>v3</parameter>
		</term>
		<listitem>
		    <para>Specifies the new values to be used for the
		    specified vertex attribute.</para>
		</listitem>
	    </varlistentry>
	</variablelist>
    </refsect1>
    <refsynopsisdiv><title>C Specification</title>
	<funcsynopsis>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib1fv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLfloat *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib1sv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLshort *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib1dv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLdouble *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib2fv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLfloat *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib2sv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLshort *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib2dv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLdouble *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib3fv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLfloat *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib3sv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLshort *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib3dv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLdouble *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4fv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLfloat *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4sv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLshort *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4dv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLdouble *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4iv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLint *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4bv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLbyte *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4ubv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLubyte *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4usv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLushort *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4uiv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLuint *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4Nbv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLbyte *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4Nsv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLshort *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4Niv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLint *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4Nubv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLubyte *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4Nusv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLushort *<parameter>v</parameter></paramdef>
	    </funcprototype>
	    <funcprototype>
		<funcdef>void <function>glVertexAttrib4Nuiv</function></funcdef>
		<paramdef>GLuint <parameter>index</parameter></paramdef>
		<paramdef>const GLuint *<parameter>v</parameter></paramdef>
	    </funcprototype>
	</funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters2"><title>Parameters</title>
	<variablelist>
	    <varlistentry>
		<term><parameter>index</parameter></term>
		<listitem>
		    <para>Specifies the index of the generic vertex
		    attribute to be modified.</para>
		</listitem>
	    </varlistentry>
	    <varlistentry>
		<term><parameter>v</parameter></term>
		<listitem>
		    <para>Specifies a pointer to an array of values to
		    be used for the generic vertex attribute.</para>
		</listitem>
	    </varlistentry>
	</variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
	<para>OpenGL defines a number of standard vertex attributes that
	applications can modify with standard API entry points (color,
	normal, texture coordinates, etc.). The
	<function>glVertexAttrib</function> family of entry points
	allows an application to pass generic vertex attributes in
	numbered locations.</para>

	<para>Generic attributes are defined as four-component values
	that are organized into an array. The first entry of this array
	is numbered 0, and the size of the array is specified by the
	implementation-dependent constant
	<constant>GL_MAX_VERTEX_ATTRIBS</constant>. Individual elements
	of this array can be modified with a
	<function>glVertexAttrib</function> call that specifies the
	index of the element to be modified and a value for that
	element.</para>

	<para>These commands can be used to specify one, two, three, or
	all four components of the generic vertex attribute specified by
	<parameter>index</parameter>. A <function>1</function> in the
	name of the command indicates that only one value is passed, and
	it will be used to modify the first component of the generic
	vertex attribute. The second and third components will be set to
	0, and the fourth component will be set to 1. Similarly, a
	<function>2</function> in the name of the command indicates that
	values are provided for the first two components, the third
	component will be set to 0, and the fourth component will be set
	to 1. A <function>3</function> in the name of the command
	indicates that values are provided for the first three
	components and the fourth component will be set to 1, whereas a
	<function>4</function> in the name indicates that values are
	provided for all four components.</para>

	<para>The letters <function>s</function>,
	<function>f</function>, <function>i</function>,
	<function>d</function>, <function>ub</function>,
	<function>us</function>, and <function>ui</function> indicate
	whether the arguments are of type short, float, int, double,
	unsigned byte, unsigned short, or unsigned int. When
	<function>v</function> is appended to the name, the commands can
	take a pointer to an array of such values. The commands
	containing <function>N</function> indicate that the arguments
	will be passed as fixed-point values that are scaled to a
	normalized range according to the component conversion rules
	defined by the OpenGL specification. Signed values are
	understood to represent fixed-point values in the range [-1,1],
	and unsigned values are understood to represent fixed-point
	values in the range [0,1].</para>

	<para>OpenGL Shading Language attribute variables are allowed to
	be of type mat2, mat3, or mat4. Attributes of these types may be
	loaded using the <function>glVertexAttrib</function> entry
	points. Matrices must be loaded into successive generic
	attribute slots in column major order, with one column of the
	matrix in each generic attribute slot.</para>

	<para>A user-defined attribute variable declared in a vertex
	shader can be bound to a generic attribute index by calling
	<citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>.
	This allows an application to use more descriptive variable
	names in a vertex shader. A subsequent change to the specified
	generic vertex attribute will be immediately reflected as a
	change to the corresponding attribute variable in the vertex
	shader.</para>

	<para>The binding between a generic vertex attribute index and a
	user-defined attribute variable in a vertex shader is part of
	the state of a program object, but the current value of the
	generic vertex attribute is not. The value of each generic
	vertex attribute is part of current state, just like standard
	vertex attributes, and it is maintained even if a different
	program object is used.</para>

	<para>An application may freely modify generic vertex attributes
	that are not bound to a named vertex shader attribute variable.
	These values are simply maintained as part of current state and
	will not be accessed by the vertex shader. If a generic vertex
	attribute bound to an attribute variable in a vertex shader is
	not updated while the vertex shader is executing, the vertex
	shader will repeatedly use the current value for the generic
	vertex attribute.</para>

	<para>The generic vertex attribute with index 0 is the same as
	the vertex position attribute previously defined by OpenGL. A
	<citerefentry><refentrytitle>glVertex2</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glVertex3</refentrytitle></citerefentry>,
	or
	<citerefentry><refentrytitle>glVertex4</refentrytitle></citerefentry>
	command is completely equivalent to the corresponding
	<function>glVertexAttrib</function> command with an index
	argument of 0. A vertex shader can access generic vertex
	attribute 0 by using the built-in attribute variable
	<parameter>gl_Vertex</parameter>. There are no current values
	for generic vertex attribute 0. This is the only generic vertex
	attribute with this property; calls to set other standard vertex
	attributes can be freely mixed with calls to set any of the
	other generic vertex attributes.</para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
	<para><function>glVertexAttrib</function> is available only if
	the GL version is 2.0 or greater.</para>

	<para>Generic vertex attributes can be updated at any time. In
	particular, <function>glVertexAttrib</function> can be called
	between a call to
	<citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
	and the corresponding call to
	<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>

	<para>It is possible for an application to bind more than one
	attribute name to the same generic vertex attribute index. This
	is referred to as aliasing, and it is allowed only if just one
	of the aliased attribute variables is active in the vertex
	shader, or if no path through the vertex shader consumes more
	than one of the attributes aliased to the same location. OpenGL
	implementations are not required to do error checking to detect
	aliasing, they are allowed to assume that aliasing will not
	occur, and they are allowed to employ optimizations that work
	only in the absence of aliasing.</para>

	<para>There is no provision for binding standard vertex
	attributes; therefore, it is not possible to alias generic
	attributes with standard attributes.</para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
	<para><constant>GL_INVALID_VALUE</constant> is generated if
	<parameter>index</parameter> is greater than or equal to
	<constant>GL_MAX_VERTEX_ATTRIBS</constant>.</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>glGetAttribLocation</refentrytitle></citerefentry>
	with argument <parameter>program</parameter> and an attribute
	variable name</para>

	<para><citerefentry><refentrytitle>glGetVertexAttrib</refentrytitle></citerefentry>
	with arguments <constant>GL_CURRENT_VERTEX_ATTRIB</constant> and
	<parameter>index</parameter></para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
	<para><citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,
	<citerefentry><refentrytitle>glVertex</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>