upstream-man-pages/man2/glVertexAttrib.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="glVertexAttrib">
   5     <refmeta>
   6         <refentrytitle>glVertexAttrib</refentrytitle>
   7         <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10         <refname>glVertexAttrib</refname>
  11         <refpurpose>Specifies the value of a generic vertex attribute</refpurpose>
  12     </refnamediv>
  13     <refsynopsisdiv><title>C Specification</title>
  14         <funcsynopsis>
  15             <funcprototype>
  16                 <funcdef>void <function>glVertexAttrib1f</function></funcdef>
  17                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  18                 <paramdef>GLfloat <parameter>v0</parameter></paramdef>
  19             </funcprototype>
  20             <funcprototype>
  21                 <funcdef>void <function>glVertexAttrib1s</function></funcdef>
  22                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  23                 <paramdef>GLshort <parameter>v0</parameter></paramdef>
  24             </funcprototype>
  25             <funcprototype>
  26                 <funcdef>void <function>glVertexAttrib1d</function></funcdef>
  27                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  28                 <paramdef>GLdouble <parameter>v0</parameter></paramdef>
  29             </funcprototype>
  30             <funcprototype>
  31                 <funcdef>void <function>glVertexAttrib2f</function></funcdef>
  32                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  33                 <paramdef>GLfloat <parameter>v0</parameter></paramdef>
  34                 <paramdef>GLfloat <parameter>v1</parameter></paramdef>
  35             </funcprototype>
  36             <funcprototype>
  37                 <funcdef>void <function>glVertexAttrib2s</function></funcdef>
  38                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  39                 <paramdef>GLshort <parameter>v0</parameter></paramdef>
  40                 <paramdef>GLshort <parameter>v1</parameter></paramdef>
  41             </funcprototype>
  42             <funcprototype>
  43                 <funcdef>void <function>glVertexAttrib2d</function></funcdef>
  44                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  45                 <paramdef>GLdouble <parameter>v0</parameter></paramdef>
  46                 <paramdef>GLdouble <parameter>v1</parameter></paramdef>
  47             </funcprototype>
  48             <funcprototype>
  49                 <funcdef>void <function>glVertexAttrib3f</function></funcdef>
  50                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  51                 <paramdef>GLfloat <parameter>v0</parameter></paramdef>
  52                 <paramdef>GLfloat <parameter>v1</parameter></paramdef>
  53                 <paramdef>GLfloat <parameter>v2</parameter></paramdef>
  54             </funcprototype>
  55             <funcprototype>
  56                 <funcdef>void <function>glVertexAttrib3s</function></funcdef>
  57                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  58                 <paramdef>GLshort <parameter>v0</parameter></paramdef>
  59                 <paramdef>GLshort <parameter>v1</parameter></paramdef>
  60                 <paramdef>GLshort <parameter>v2</parameter></paramdef>
  61             </funcprototype>
  62             <funcprototype>
  63                 <funcdef>void <function>glVertexAttrib3d</function></funcdef>
  64                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  65                 <paramdef>GLdouble <parameter>v0</parameter></paramdef>
  66                 <paramdef>GLdouble <parameter>v1</parameter></paramdef>
  67                 <paramdef>GLdouble <parameter>v2</parameter></paramdef>
  68             </funcprototype>
  69             <funcprototype>
  70                 <funcdef>void <function>glVertexAttrib4f</function></funcdef>
  71                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  72                 <paramdef>GLfloat <parameter>v0</parameter></paramdef>
  73                 <paramdef>GLfloat <parameter>v1</parameter></paramdef>
  74                 <paramdef>GLfloat <parameter>v2</parameter></paramdef>
  75                 <paramdef>GLfloat <parameter>v3</parameter></paramdef>
  76             </funcprototype>
  77             <funcprototype>
  78                 <funcdef>void <function>glVertexAttrib4s</function></funcdef>
  79                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  80                 <paramdef>GLshort <parameter>v0</parameter></paramdef>
  81                 <paramdef>GLshort <parameter>v1</parameter></paramdef>
  82                 <paramdef>GLshort <parameter>v2</parameter></paramdef>
  83                 <paramdef>GLshort <parameter>v3</parameter></paramdef>
  84             </funcprototype>
  85             <funcprototype>
  86                 <funcdef>void <function>glVertexAttrib4d</function></funcdef>
  87                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  88                 <paramdef>GLdouble <parameter>v0</parameter></paramdef>
  89                 <paramdef>GLdouble <parameter>v1</parameter></paramdef>
  90                 <paramdef>GLdouble <parameter>v2</parameter></paramdef>
  91                 <paramdef>GLdouble <parameter>v3</parameter></paramdef>
  92             </funcprototype>
  93             <funcprototype>
  94                 <funcdef>void <function>glVertexAttrib4Nub</function></funcdef>
  95                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  96                 <paramdef>GLubyte <parameter>v0</parameter></paramdef>
  97                 <paramdef>GLubyte <parameter>v1</parameter></paramdef>
  98                 <paramdef>GLubyte <parameter>v2</parameter></paramdef>
  99                 <paramdef>GLubyte <parameter>v3</parameter></paramdef>
 100             </funcprototype>
 101         </funcsynopsis>
 102     </refsynopsisdiv>
 103     <refsect1 id="parameters"><title>Parameters</title>
 104         <variablelist>
 105             <varlistentry>
 106                 <term><parameter>index</parameter></term>
 107                 <listitem>
 108                     <para>Specifies the index of the generic vertex
 109                     attribute to be modified.</para>
 110                 </listitem>
 111             </varlistentry>
 112             <varlistentry>
 113                 <term>
 114                     <parameter>v0</parameter>,
 115                     <parameter>v1</parameter>,
 116                     <parameter>v2</parameter>,
 117                     <parameter>v3</parameter>
 118                 </term>
 119                 <listitem>
 120                     <para>Specifies the new values to be used for the
 121                     specified vertex attribute.</para>
 122                 </listitem>
 123             </varlistentry>
 124         </variablelist>
 125     </refsect1>
 126     <refsynopsisdiv><title>C Specification</title>
 127         <funcsynopsis>
 128             <funcprototype>
 129                 <funcdef>void <function>glVertexAttrib1fv</function></funcdef>
 130                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 131                 <paramdef>const GLfloat *<parameter>v</parameter></paramdef>
 132             </funcprototype>
 133             <funcprototype>
 134                 <funcdef>void <function>glVertexAttrib1sv</function></funcdef>
 135                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 136                 <paramdef>const GLshort *<parameter>v</parameter></paramdef>
 137             </funcprototype>
 138             <funcprototype>
 139                 <funcdef>void <function>glVertexAttrib1dv</function></funcdef>
 140                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 141                 <paramdef>const GLdouble *<parameter>v</parameter></paramdef>
 142             </funcprototype>
 143             <funcprototype>
 144                 <funcdef>void <function>glVertexAttrib2fv</function></funcdef>
 145                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 146                 <paramdef>const GLfloat *<parameter>v</parameter></paramdef>
 147             </funcprototype>
 148             <funcprototype>
 149                 <funcdef>void <function>glVertexAttrib2sv</function></funcdef>
 150                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 151                 <paramdef>const GLshort *<parameter>v</parameter></paramdef>
 152             </funcprototype>
 153             <funcprototype>
 154                 <funcdef>void <function>glVertexAttrib2dv</function></funcdef>
 155                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 156                 <paramdef>const GLdouble *<parameter>v</parameter></paramdef>
 157             </funcprototype>
 158             <funcprototype>
 159                 <funcdef>void <function>glVertexAttrib3fv</function></funcdef>
 160                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 161                 <paramdef>const GLfloat *<parameter>v</parameter></paramdef>
 162             </funcprototype>
 163             <funcprototype>
 164                 <funcdef>void <function>glVertexAttrib3sv</function></funcdef>
 165                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 166                 <paramdef>const GLshort *<parameter>v</parameter></paramdef>
 167             </funcprototype>
 168             <funcprototype>
 169                 <funcdef>void <function>glVertexAttrib3dv</function></funcdef>
 170                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 171                 <paramdef>const GLdouble *<parameter>v</parameter></paramdef>
 172             </funcprototype>
 173             <funcprototype>
 174                 <funcdef>void <function>glVertexAttrib4fv</function></funcdef>
 175                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 176                 <paramdef>const GLfloat *<parameter>v</parameter></paramdef>
 177             </funcprototype>
 178             <funcprototype>
 179                 <funcdef>void <function>glVertexAttrib4sv</function></funcdef>
 180                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 181                 <paramdef>const GLshort *<parameter>v</parameter></paramdef>
 182             </funcprototype>
 183             <funcprototype>
 184                 <funcdef>void <function>glVertexAttrib4dv</function></funcdef>
 185                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 186                 <paramdef>const GLdouble *<parameter>v</parameter></paramdef>
 187             </funcprototype>
 188             <funcprototype>
 189                 <funcdef>void <function>glVertexAttrib4iv</function></funcdef>
 190                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 191                 <paramdef>const GLint *<parameter>v</parameter></paramdef>
 192             </funcprototype>
 193             <funcprototype>
 194                 <funcdef>void <function>glVertexAttrib4bv</function></funcdef>
 195                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 196                 <paramdef>const GLbyte *<parameter>v</parameter></paramdef>
 197             </funcprototype>
 198             <funcprototype>
 199                 <funcdef>void <function>glVertexAttrib4ubv</function></funcdef>
 200                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 201                 <paramdef>const GLubyte *<parameter>v</parameter></paramdef>
 202             </funcprototype>
 203             <funcprototype>
 204                 <funcdef>void <function>glVertexAttrib4usv</function></funcdef>
 205                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 206                 <paramdef>const GLushort *<parameter>v</parameter></paramdef>
 207             </funcprototype>
 208             <funcprototype>
 209                 <funcdef>void <function>glVertexAttrib4uiv</function></funcdef>
 210                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 211                 <paramdef>const GLuint *<parameter>v</parameter></paramdef>
 212             </funcprototype>
 213             <funcprototype>
 214                 <funcdef>void <function>glVertexAttrib4Nbv</function></funcdef>
 215                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 216                 <paramdef>const GLbyte *<parameter>v</parameter></paramdef>
 217             </funcprototype>
 218             <funcprototype>
 219                 <funcdef>void <function>glVertexAttrib4Nsv</function></funcdef>
 220                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 221                 <paramdef>const GLshort *<parameter>v</parameter></paramdef>
 222             </funcprototype>
 223             <funcprototype>
 224                 <funcdef>void <function>glVertexAttrib4Niv</function></funcdef>
 225                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 226                 <paramdef>const GLint *<parameter>v</parameter></paramdef>
 227             </funcprototype>
 228             <funcprototype>
 229                 <funcdef>void <function>glVertexAttrib4Nubv</function></funcdef>
 230                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 231                 <paramdef>const GLubyte *<parameter>v</parameter></paramdef>
 232             </funcprototype>
 233             <funcprototype>
 234                 <funcdef>void <function>glVertexAttrib4Nusv</function></funcdef>
 235                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 236                 <paramdef>const GLushort *<parameter>v</parameter></paramdef>
 237             </funcprototype>
 238             <funcprototype>
 239                 <funcdef>void <function>glVertexAttrib4Nuiv</function></funcdef>
 240                 <paramdef>GLuint <parameter>index</parameter></paramdef>
 241                 <paramdef>const GLuint *<parameter>v</parameter></paramdef>
 242             </funcprototype>
 243         </funcsynopsis>
 244     </refsynopsisdiv>
 245     <refsect1 id="parameters2"><title>Parameters</title>
 246         <variablelist>
 247             <varlistentry>
 248                 <term><parameter>index</parameter></term>
 249                 <listitem>
 250                     <para>Specifies the index of the generic vertex
 251                     attribute to be modified.</para>
 252                 </listitem>
 253             </varlistentry>
 254             <varlistentry>
 255                 <term><parameter>v</parameter></term>
 256                 <listitem>
 257                     <para>Specifies a pointer to an array of values to
 258                     be used for the generic vertex attribute.</para>
 259                 </listitem>
 260             </varlistentry>
 261         </variablelist>
 262     </refsect1>
 263     <refsect1 id="description"><title>Description</title>
 264         <para>OpenGL defines a number of standard vertex attributes that
 265         applications can modify with standard API entry points (color,
 266         normal, texture coordinates, etc.). The
 267         <function>glVertexAttrib</function> family of entry points
 268         allows an application to pass generic vertex attributes in
 269         numbered locations.</para>
 270
 271         <para>Generic attributes are defined as four-component values
 272         that are organized into an array. The first entry of this array
 273         is numbered 0, and the size of the array is specified by the
 274         implementation-dependent constant
 275         <constant>GL_MAX_VERTEX_ATTRIBS</constant>. Individual elements
 276         of this array can be modified with a
 277         <function>glVertexAttrib</function> call that specifies the
 278         index of the element to be modified and a value for that
 279         element.</para>
 280
 281         <para>These commands can be used to specify one, two, three, or
 282         all four components of the generic vertex attribute specified by
 283         <parameter>index</parameter>. A <function>1</function> in the
 284         name of the command indicates that only one value is passed, and
 285         it will be used to modify the first component of the generic
 286         vertex attribute. The second and third components will be set to
 287         0, and the fourth component will be set to 1. Similarly, a
 288         <function>2</function> in the name of the command indicates that
 289         values are provided for the first two components, the third
 290         component will be set to 0, and the fourth component will be set
 291         to 1. A <function>3</function> in the name of the command
 292         indicates that values are provided for the first three
 293         components and the fourth component will be set to 1, whereas a
 294         <function>4</function> in the name indicates that values are
 295         provided for all four components.</para>
 296
 297         <para>The letters <function>s</function>,
 298         <function>f</function>, <function>i</function>,
 299         <function>d</function>, <function>ub</function>,
 300         <function>us</function>, and <function>ui</function> indicate
 301         whether the arguments are of type short, float, int, double,
 302         unsigned byte, unsigned short, or unsigned int. When
 303         <function>v</function> is appended to the name, the commands can
 304         take a pointer to an array of such values. The commands
 305         containing <function>N</function> indicate that the arguments
 306         will be passed as fixed-point values that are scaled to a
 307         normalized range according to the component conversion rules
 308         defined by the OpenGL specification. Signed values are
 309         understood to represent fixed-point values in the range [-1,1],
 310         and unsigned values are understood to represent fixed-point
 311         values in the range [0,1].</para>
 312
 313         <para>OpenGL Shading Language attribute variables are allowed to
 314         be of type mat2, mat3, or mat4. Attributes of these types may be
 315         loaded using the <function>glVertexAttrib</function> entry
 316         points. Matrices must be loaded into successive generic
 317         attribute slots in column major order, with one column of the
 318         matrix in each generic attribute slot.</para>
 319
 320         <para>A user-defined attribute variable declared in a vertex
 321         shader can be bound to a generic attribute index by calling
 322         <citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>.
 323         This allows an application to use more descriptive variable
 324         names in a vertex shader. A subsequent change to the specified
 325         generic vertex attribute will be immediately reflected as a
 326         change to the corresponding attribute variable in the vertex
 327         shader.</para>
 328
 329         <para>The binding between a generic vertex attribute index and a
 330         user-defined attribute variable in a vertex shader is part of
 331         the state of a program object, but the current value of the
 332         generic vertex attribute is not. The value of each generic
 333         vertex attribute is part of current state, just like standard
 334         vertex attributes, and it is maintained even if a different
 335         program object is used.</para>
 336
 337         <para>An application may freely modify generic vertex attributes
 338         that are not bound to a named vertex shader attribute variable.
 339         These values are simply maintained as part of current state and
 340         will not be accessed by the vertex shader. If a generic vertex
 341         attribute bound to an attribute variable in a vertex shader is
 342         not updated while the vertex shader is executing, the vertex
 343         shader will repeatedly use the current value for the generic
 344         vertex attribute.</para>
 345
 346         <para>The generic vertex attribute with index 0 is the same as
 347         the vertex position attribute previously defined by OpenGL. A
 348         <citerefentry><refentrytitle>glVertex2</refentrytitle></citerefentry>,
 349         <citerefentry><refentrytitle>glVertex3</refentrytitle></citerefentry>,
 350         or
 351         <citerefentry><refentrytitle>glVertex4</refentrytitle></citerefentry>
 352         command is completely equivalent to the corresponding
 353         <function>glVertexAttrib</function> command with an index
 354         argument of 0. A vertex shader can access generic vertex
 355         attribute 0 by using the built-in attribute variable
 356         <parameter>gl_Vertex</parameter>. There are no current values
 357         for generic vertex attribute 0. This is the only generic vertex
 358         attribute with this property; calls to set other standard vertex
 359         attributes can be freely mixed with calls to set any of the
 360         other generic vertex attributes.</para>
 361     </refsect1>
 362     <refsect1 id="notes"><title>Notes</title>
 363         <para><function>glVertexAttrib</function> is available only if
 364         the GL version is 2.0 or greater.</para>
 365
 366         <para>Generic vertex attributes can be updated at any time. In
 367         particular, <function>glVertexAttrib</function> can be called
 368         between a call to
 369         <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 370         and the corresponding call to
 371         <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
 372
 373         <para>It is possible for an application to bind more than one
 374         attribute name to the same generic vertex attribute index. This
 375         is referred to as aliasing, and it is allowed only if just one
 376         of the aliased attribute variables is active in the vertex
 377         shader, or if no path through the vertex shader consumes more
 378         than one of the attributes aliased to the same location. OpenGL
 379         implementations are not required to do error checking to detect
 380         aliasing, they are allowed to assume that aliasing will not
 381         occur, and they are allowed to employ optimizations that work
 382         only in the absence of aliasing.</para>
 383
 384         <para>There is no provision for binding standard vertex
 385         attributes; therefore, it is not possible to alias generic
 386         attributes with standard attributes.</para>
 387     </refsect1>
 388     <refsect1 id="errors"><title>Errors</title>
 389         <para><constant>GL_INVALID_VALUE</constant> is generated if
 390         <parameter>index</parameter> is greater than or equal to
 391         <constant>GL_MAX_VERTEX_ATTRIBS</constant>.</para>
 392     </refsect1>
 393     <refsect1 id="associatedgets"><title>Associated Gets</title>
 394         <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 395         with the argument <constant>GL_CURRENT_PROGRAM</constant></para>
 396
 397         <para><citerefentry><refentrytitle>glGetActiveAttrib</refentrytitle></citerefentry>
 398         with argument <parameter>program</parameter> and the index of an active
 399         attribute variable</para>
 400
 401         <para><citerefentry><refentrytitle>glGetAttribLocation</refentrytitle></citerefentry>
 402         with argument <parameter>program</parameter> and an attribute
 403         variable name</para>
 404
 405         <para><citerefentry><refentrytitle>glGetVertexAttrib</refentrytitle></citerefentry>
 406         with arguments <constant>GL_CURRENT_VERTEX_ATTRIB</constant> and
 407         <parameter>index</parameter></para>
 408     </refsect1>
 409     <refsect1 id="seealso"><title>See Also</title>
 410         <para><citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,
 411         <citerefentry><refentrytitle>glVertex</refentrytitle></citerefentry>,
 412         <citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry></para>
 413     </refsect1>
 414     <refsect1 id="Copyright"><title>Copyright</title>
 415         <para>
 416             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 417             This material may be distributed subject to the terms and conditions set forth in
 418             the Open Publication License, v 1.0, 8 June 1999.
 419             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 420         </para>
 421     </refsect1>
 422 </refentry>