upstream-man-pages/man4/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 <function>mat2</function>; <parameter>index+1</parameter> and
  70     <parameter>index+2</parameter> for a matrix of type <function>mat3</function>; and
  71     <parameter>index+1</parameter>, <parameter>index+2</parameter>,
  72     and <parameter>index+3</parameter> for a matrix of type
  73     <function>mat4</function>.</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.
  80     If a different program object is made current by calling
  81     <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>,
  82     the generic vertex attributes are tracked in such a way that the
  83     same values will be observed by attributes in the new program
  84     object that are also bound to
  85     <parameter>index</parameter>.</para> <para>Attribute variable
  86     name-to-generic attribute index bindings for a program object
  87     can be explicitly assigned at any time by calling
  88     <function>glBindAttribLocation</function>. Attribute bindings do
  89     not go into effect until
  90     <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
  91     is called. After a program object has been linked successfully,
  92     the index values for generic attributes remain fixed (and their
  93     values can be queried) until the next link command
  94     occurs.</para>
  95
  96     <para>Any attribute binding that occurs after the program object has been linked will not take effect
  97     until the next time the program object is linked.</para>
  98     </refsect1>
  99     <refsect1 id="notes"><title>Notes</title>
 100     <para><function>glBindAttribLocation</function> can be called
 101     before any vertex shader objects are bound to the specified
 102     program object. It is also permissible to bind a generic
 103     attribute index to an attribute variable name that is never used
 104     in a vertex shader.</para>
 105
 106     <para>If <parameter>name</parameter> was bound previously, that
 107     information is lost. Thus you cannot bind one user-defined
 108     attribute variable to multiple indices, but you can bind
 109     multiple user-defined attribute variables to the same
 110     index.</para>
 111
 112     <para>Applications are allowed to bind more than one
 113     user-defined attribute variable to the same generic vertex
 114     attribute index. This is called <emphasis>aliasing</emphasis>,
 115     and it is allowed only if just one of the aliased attributes is
 116     active in the executable program, or if no path through the
 117     shader consumes more than one attribute of a set of attributes
 118     aliased to the same location. The compiler and linker are
 119     allowed to assume that no aliasing is done and are free to
 120     employ optimizations that work only in the absence of aliasing.
 121     OpenGL implementations are not required to do error checking to
 122     detect aliasing.</para>
 123
 124     <para>Active attributes that are not explicitly bound will be
 125     bound by the linker when
 126     <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>
 127     is called. The locations assigned can be queried by calling
 128     <citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>.</para>
 129
 130     <para>OpenGL copies the <parameter>name</parameter> string when
 131     <function>glBindAttribLocation</function> is called, so an
 132     application may free its copy of the <parameter>name</parameter>
 133     string immediately after the function returns.</para>
 134
 135     <para>Generic attribute locations may be specified in the shader source
 136     text using a <function>location</function> layout qualifier. In this case,
 137     the location of the attribute specified in the shader's source takes precedence
 138     and may be queried by calling <citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>.
 139     </para>
 140     </refsect1>
 141     <refsect1 id="errors"><title>Errors</title>
 142     <para><constant>GL_INVALID_VALUE</constant> is generated if
 143     <parameter>index</parameter> is greater than or equal to
 144     <constant>GL_MAX_VERTEX_ATTRIBS</constant>.</para>
 145
 146     <para><constant>GL_INVALID_OPERATION</constant> is generated if
 147     <parameter>name</parameter> starts with the reserved prefix
 148     &quot;gl_&quot;.</para>
 149
 150     <para><constant>GL_INVALID_VALUE</constant> is generated if
 151     <parameter>program</parameter> is not a value generated by
 152     OpenGL.</para>
 153
 154     <para><constant>GL_INVALID_OPERATION</constant> is generated if
 155     <parameter>program</parameter> is not a program object.</para>
 156
 157     </refsect1>
 158     <refsect1 id="associatedgets"><title>Associated Gets</title>
 159     <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 160     with argument <constant>GL_MAX_VERTEX_ATTRIBS</constant></para>
 161
 162     <para><citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
 163     with argument <parameter>program</parameter></para>
 164
 165     <para><citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>
 166     with arguments <parameter>program</parameter> and
 167     <parameter>name</parameter></para>
 168
 169     <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
 170     </refsect1>
 171     <refsect1 id="seealso"><title>See Also</title>
 172     <para><citerefentry><refentrytitle>glDisableVertexAttribArray</refentrytitle></citerefentry>,
 173     <citerefentry><refentrytitle>glEnableVertexAttribArray</refentrytitle></citerefentry>,
 174     <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry>,
 175     <citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry>,
 176     <citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry></para>
 177     </refsect1>
 178     <refsect1 id="Copyright"><title>Copyright</title>
 179         <para>
 180             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 181             This material may be distributed subject to the terms and conditions set forth in
 182             the Open Publication License, v 1.0, 8 June 1999.
 183             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 184         </para>
 185     </refsect1>
 186 </refentry>