upstream-doc/man2/glBindAttribLocation.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="glBindAttribLocation">
   5     <refmeta>
   6         <refentrytitle>glBindAttribLocation</refentrytitle>
   7         <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10         <refname>glBindAttribLocation</refname>
  11         <refpurpose>Associates a generic vertex attribute index with a named attribute variable</refpurpose>
  12     </refnamediv>
  13     <refsynopsisdiv><title>C Specification</title>
  14         <funcsynopsis>
  15             <funcprototype>
  16                 <funcdef>void <function>glBindAttribLocation</function></funcdef>
  17                 <paramdef>GLuint <parameter>program</parameter></paramdef>
  18                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  19                 <paramdef>const GLchar *<parameter>name</parameter></paramdef>
  20             </funcprototype>
  21         </funcsynopsis>
  22     </refsynopsisdiv>
  23     <refsect1 id="parameters"><title>Parameters</title>
  24         <variablelist>
  25             <varlistentry>
  26                 <term><parameter>program</parameter></term>
  27                 <listitem>
  28                     <para>Specifies the handle of the program object in
  29                     which the association is to be made.</para>
  30                 </listitem>
  31             </varlistentry>
  32             <varlistentry>
  33                 <term><parameter>index</parameter></term>
  34                 <listitem>
  35                     <para>Specifies the index of the generic vertex
  36                     attribute to be bound.</para>
  37                 </listitem>
  38             </varlistentry>
  39             <varlistentry>
  40                 <term><parameter>name</parameter></term>
  41                 <listitem>
  42                     <para>Specifies a null terminated string containing
  43                     the name of the vertex shader attribute variable to
  44                     which <parameter>index</parameter> is to be
  45                     bound.</para>
  46                 </listitem>
  47             </varlistentry>
  48         </variablelist>
  49     </refsect1>
  50     <refsect1 id="description"><title>Description</title>
  51         <para><function>glBindAttribLocation</function> is used to
  52         associate a user-defined attribute variable in the program
  53         object specified by <parameter>program</parameter> with a
  54         generic vertex attribute index. The name of the user-defined
  55         attribute variable is passed as a null terminated string in
  56         <parameter>name</parameter>. The generic vertex attribute index
  57         to be bound to this variable is specified by
  58         <parameter>index</parameter>. When
  59         <parameter>program</parameter> is made part of current state,
  60         values provided via the generic vertex attribute
  61         <parameter>index</parameter> will modify the value of the
  62         user-defined attribute variable specified by
  63         <parameter>name</parameter>.</para>
  64
  65         <para>If <parameter>name</parameter> refers to a matrix
  66         attribute variable, <parameter>index</parameter> refers to the
  67         first column of the matrix. Other matrix columns are then
  68         automatically bound to locations <parameter>index+1</parameter>
  69         for a matrix of type mat2; <parameter>index+1</parameter> and
  70         <parameter>index+2</parameter> for a matrix of type mat3; and
  71         <parameter>index+1</parameter>, <parameter>index+2</parameter>,
  72         and <parameter>index+3</parameter> for a matrix of type
  73         mat4.</para>
  74
  75         <para>This command makes it possible for vertex shaders to use
  76         descriptive names for attribute variables rather than generic
  77         variables that are numbered from 0 to
  78         <constant>GL_MAX_VERTEX_ATTRIBS</constant> -1. The values sent
  79         to each generic attribute index are part of current state, just
  80         like standard vertex attributes such as color, normal, and
  81         vertex position. If a different program object is made current
  82         by calling
  83         <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>,
  84         the generic vertex attributes are tracked in such a way that the
  85         same values will be observed by attributes in the new program
  86         object that are also bound to
  87         <parameter>index</parameter>.</para> <para>Attribute variable
  88         name-to-generic attribute index bindings for a program object
  89         can be explicitly assigned at any time by calling
  90         <function>glBindAttribLocation</function>. Attribute bindings do
  91         not go into effect until
  92         <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
  93         is called. After a program object has been linked successfully,
  94         the index values for generic attributes remain fixed (and their
  95         values can be queried) until the next link command
  96         occurs.</para>
  97
  98         <para>Applications are not allowed to bind any of the standard
  99         OpenGL vertex attributes using this command, as they are bound
 100         automatically when needed. Any attribute binding that occurs
 101         after the program object has been linked will not take effect
 102         until the next time the program object is linked.</para>
 103     </refsect1>
 104     <refsect1 id="notes"><title>Notes</title>
 105         <para><function>glBindAttribLocation</function> is available
 106         only if the GL version is 2.0 or greater.</para>
 107
 108         <para><function>glBindAttribLocation</function> can be called
 109         before any vertex shader objects are bound to the specified
 110         program object. It is also permissible to bind a generic
 111         attribute index to an attribute variable name that is never used
 112         in a vertex shader.</para>
 113
 114         <para>If <parameter>name</parameter> was bound previously, that
 115         information is lost. Thus you cannot bind one user-defined
 116         attribute variable to multiple indices, but you can bind
 117         multiple user-defined attribute variables to the same
 118         index.</para>
 119
 120         <para>Applications are allowed to bind more than one
 121         user-defined attribute variable to the same generic vertex
 122         attribute index. This is called <emphasis>aliasing</emphasis>,
 123         and it is allowed only if just one of the aliased attributes is
 124         active in the executable program, or if no path through the
 125         shader consumes more than one attribute of a set of attributes
 126         aliased to the same location. The compiler and linker are
 127         allowed to assume that no aliasing is done and are free to
 128         employ optimizations that work only in the absence of aliasing.
 129         OpenGL implementations are not required to do error checking to
 130         detect aliasing. Because there is no way to bind standard
 131         attributes, it is not possible to alias generic attributes with
 132         conventional ones (except for generic attribute 0).</para>
 133
 134         <para>Active attributes that are not explicitly bound will be
 135         bound by the linker when
 136         <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
 137         is called. The locations assigned can be queried by calling
 138         <citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>.</para>
 139
 140         <para>OpenGL copies the <parameter>name</parameter> string when
 141         <function>glBindAttribLocation</function> is called, so an
 142         application may free its copy of the <parameter>name</parameter>
 143         string immediately after the function returns.</para>
 144     </refsect1>
 145     <refsect1 id="errors"><title>Errors</title>
 146         <para><constant>GL_INVALID_VALUE</constant> is generated if
 147         <parameter>index</parameter> is greater than or equal to
 148         <constant>GL_MAX_VERTEX_ATTRIBS</constant>.</para>
 149
 150         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 151         <parameter>name</parameter> starts with the reserved prefix
 152         &quot;gl_&quot;.</para>
 153
 154         <para><constant>GL_INVALID_VALUE</constant> is generated if
 155         <parameter>program</parameter> is not a value generated by
 156         OpenGL.</para>
 157
 158         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 159         <parameter>program</parameter> is not a program object.</para>
 160
 161         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 162         <function>glBindAttribLocation</function> is executed between
 163         the execution of
 164         <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 165         and the corresponding execution of
 166         <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
 167     </refsect1>
 168     <refsect1 id="associatedgets"><title>Associated Gets</title>
 169         <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 170         with argument <constant>GL_MAX_VERTEX_ATTRIBS</constant></para>
 171
 172         <para><citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
 173         with argument <parameter>program</parameter></para>
 174
 175         <para><citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>
 176         with arguments <parameter>program</parameter> and
 177         <parameter>name</parameter></para>
 178
 179         <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
 180     </refsect1>
 181     <refsect1 id="seealso"><title>See Also</title>
 182         <para><citerefentry><refentrytitle>glDisableVertexAttribArray</refentrytitle></citerefentry>,
 183         <citerefentry><refentrytitle>glEnableVertexAttribArray</refentrytitle></citerefentry>,
 184         <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>,
 185         <citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry>,
 186         <citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry></para>
 187     </refsect1>
 188     <refsect1 id="Copyright"><title>Copyright</title>
 189         <para>
 190             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 191             This material may be distributed subject to the terms and conditions set forth in
 192             the Open Publication License, v 1.0, 8 June 1999.
 193             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 194         </para>
 195     </refsect1>
 196 </refentry>