upstream-man-pages/man2/glVertexAttribPointer.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="glVertexAttribPointer">
   5     <refmeta>
   6         <refentrytitle>glVertexAttribPointer</refentrytitle>
   7         <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10         <refname>glVertexAttribPointer</refname>
  11         <refpurpose>define an array of generic vertex attribute data</refpurpose>
  12     </refnamediv>
  13     <refsynopsisdiv><title>C Specification</title>
  14         <funcsynopsis>
  15             <funcprototype>
  16                 <funcdef>void <function>glVertexAttribPointer</function></funcdef>
  17                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  18                 <paramdef>GLint <parameter>size</parameter></paramdef>
  19                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  20                 <paramdef>GLboolean <parameter>normalized</parameter></paramdef>
  21                 <paramdef>GLsizei <parameter>stride</parameter></paramdef>
  22                 <paramdef>const GLvoid * <parameter>pointer</parameter></paramdef>
  23             </funcprototype>
  24         </funcsynopsis>
  25     </refsynopsisdiv>
  26     <refsect1 id="parameters"><title>Parameters</title>
  27         <variablelist>
  28             <varlistentry>
  29                 <term><parameter>index</parameter></term>
  30                 <listitem>
  31                     <para>Specifies the index of the generic vertex
  32                     attribute to be modified.</para>
  33                 </listitem>
  34             </varlistentry>
  35             <varlistentry>
  36                 <term><parameter>size</parameter></term>
  37                 <listitem>
  38                     <para>Specifies the number of components per
  39                     generic vertex attribute. Must
  40                     be 1, 2, 3, or 4. The initial value is 4.</para>
  41                 </listitem>
  42             </varlistentry>
  43             <varlistentry>
  44                 <term><parameter>type</parameter></term>
  45                 <listitem>
  46                     <para>Specifies the data type of each component in
  47                     the array. Symbolic constants
  48                     <constant>GL_BYTE</constant>,
  49                     <constant>GL_UNSIGNED_BYTE</constant>,
  50                     <constant>GL_SHORT</constant>,
  51                     <constant>GL_UNSIGNED_SHORT</constant>,
  52                     <constant>GL_INT</constant>,
  53                     <constant>GL_UNSIGNED_INT</constant>,
  54                     <constant>GL_FLOAT</constant>, or
  55                     <constant>GL_DOUBLE</constant> are
  56                     accepted. The initial value is <constant>GL_FLOAT</constant>.</para>
  57                 </listitem>
  58             </varlistentry>
  59             <varlistentry>
  60                 <term><parameter>normalized</parameter></term>
  61                 <listitem>
  62                     <para>Specifies whether fixed-point data values
  63                     should be normalized (<constant>GL_TRUE</constant>)
  64                     or converted directly as fixed-point values
  65                     (<constant>GL_FALSE</constant>) when they are
  66                     accessed.</para>
  67                 </listitem>
  68             </varlistentry>
  69             <varlistentry>
  70                 <term><parameter>stride</parameter></term>
  71                 <listitem>
  72                     <para>Specifies the byte offset between consecutive
  73                     generic vertex attributes. If <parameter>stride</parameter>
  74                     is 0, the generic vertex attributes are
  75                     understood to be tightly packed in the
  76                     array. The initial value is 0.</para>
  77                 </listitem>
  78             </varlistentry>
  79             <varlistentry>
  80                 <term><parameter>pointer</parameter></term>
  81                 <listitem>
  82                     <para>Specifies a pointer to the first component of
  83                     the first generic vertex attribute in the array. The initial value is 0.</para>
  84                 </listitem>
  85             </varlistentry>
  86         </variablelist>
  87     </refsect1>
  88     <refsect1 id="description"><title>Description</title>
  89         <para><function>glVertexAttribPointer</function> specifies the
  90         location and data format of the array of generic vertex attributes at index <parameter>index</parameter>
  91         to use when rendering. <parameter>size</parameter>
  92         specifies the number of components per attribute and must be 1,
  93         2, 3, or 4. <parameter>type</parameter> specifies the data type
  94         of each component, and <parameter>stride</parameter> specifies
  95         the byte stride from one attribute to the next, allowing vertices and
  96         attributes to be packed into a single array or
  97         stored in separate arrays.
  98         If set to <constant>GL_TRUE</constant>,
  99         <parameter>normalized</parameter> indicates that values stored
 100         in an integer format are to be mapped to the range [-1,1] (for
 101         signed values) or [0,1] (for unsigned values) when they are
 102         accessed and converted to floating point. Otherwise, values will
 103         be converted to floats directly without normalization.</para>
 104
 105         <para>If a non-zero named buffer object is bound to the <constant>GL_ARRAY_BUFFER</constant> target
 106         (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a generic vertex attribute array is
 107         specified, <parameter>pointer</parameter> is treated as a byte offset into the buffer object's data store.
 108         Also, the buffer object binding (<constant>GL_ARRAY_BUFFER_BINDING</constant>) is saved as generic vertex attribute array
 109         client-side state (<constant>GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING</constant>) for index <parameter>index</parameter>.</para>
 110
 111         <para>When a generic vertex attribute array is specified,
 112         <parameter>size</parameter>, <parameter>type</parameter>,
 113         <parameter>normalized</parameter>,
 114         <parameter>stride</parameter>, and
 115         <parameter>pointer</parameter> are saved as client-side
 116         state, in addition to the current vertex array buffer object binding.</para>
 117
 118         <para>To enable and disable a generic vertex attribute array,
 119         call
 120         <citerefentry><refentrytitle>glEnableVertexAttribArray</refentrytitle></citerefentry>
 121         and
 122         <citerefentry><refentrytitle>glDisableVertexAttribArray</refentrytitle></citerefentry>
 123         with <parameter>index</parameter>. If enabled, the generic
 124         vertex attribute array is used when
 125         <citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
 126         <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
 127         <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>,
 128         <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
 129         <citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>, or
 130         <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>
 131         is called.</para>
 132     </refsect1>
 133     <refsect1 id="notes"><title>Notes</title>
 134         <para><function>glVertexAttribPointer</function> is available
 135         only if the GL version is 2.0 or greater.</para>
 136
 137         <para>Each generic vertex attribute array is initially disabled
 138         and isn't accessed when
 139         <citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
 140         <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>, or <citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>
 141         is called.</para>
 142
 143         <para>Execution of <function>glVertexAttribPointer</function> is
 144         not allowed between the execution of
 145         <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 146         and the corresponding execution of
 147         <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>,
 148         but an error may or may not be generated. If no error is
 149         generated, the operation is undefined.</para>
 150
 151         <para><function>glVertexAttribPointer</function> is typically
 152         implemented on the client side.</para>
 153
 154         <para>Generic vertex attribute array parameters are client-side
 155         state and are therefore not saved or restored by
 156         <citerefentry><refentrytitle>glPushAttrib</refentrytitle></citerefentry>
 157         and
 158         <citerefentry><refentrytitle>glPopAttrib</refentrytitle></citerefentry>.
 159         Use
 160         <citerefentry><refentrytitle>glPushClientAttrib</refentrytitle></citerefentry>
 161         and
 162         <citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry>
 163         instead.</para>
 164     </refsect1>
 165     <refsect1 id="errors"><title>Errors</title>
 166         <para><constant>GL_INVALID_VALUE</constant> is generated if
 167         <parameter>index</parameter> is greater than or equal to
 168         <constant>GL_MAX_VERTEX_ATTRIBS</constant>.</para>
 169
 170         <para><constant>GL_INVALID_VALUE</constant> is generated if
 171         <parameter>size</parameter> is not 1, 2, 3, or 4.</para>
 172
 173         <para><constant>GL_INVALID_ENUM</constant> is generated if
 174         <parameter>type</parameter> is not an accepted value.</para>
 175
 176         <para><constant>GL_INVALID_VALUE</constant> is generated if
 177         <parameter>stride</parameter> is negative.</para>
 178     </refsect1>
 179     <refsect1 id="associatedgets"><title>Associated Gets</title>
 180         <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 181         with argument <constant>GL_MAX_VERTEX_ATTRIBS</constant></para>
 182
 183         <para><citerefentry><refentrytitle>glGetVertexAttrib</refentrytitle></citerefentry>
 184         with arguments <parameter>index</parameter> and <constant>GL_VERTEX_ATTRIB_ARRAY_ENABLED</constant></para>
 185
 186         <para><citerefentry><refentrytitle>glGetVertexAttrib</refentrytitle></citerefentry>
 187         with arguments <parameter>index</parameter> and <constant>GL_VERTEX_ATTRIB_ARRAY_SIZE</constant></para>
 188
 189         <para><citerefentry><refentrytitle>glGetVertexAttrib</refentrytitle></citerefentry>
 190         with arguments <parameter>index</parameter> and <constant>GL_VERTEX_ATTRIB_ARRAY_TYPE</constant></para>
 191
 192         <para><citerefentry><refentrytitle>glGetVertexAttrib</refentrytitle></citerefentry>
 193         with arguments <parameter>index</parameter> and <constant>GL_VERTEX_ATTRIB_ARRAY_NORMALIZED</constant></para>
 194
 195         <para><citerefentry><refentrytitle>glGetVertexAttrib</refentrytitle></citerefentry>
 196         with arguments <parameter>index</parameter> and <constant>GL_VERTEX_ATTRIB_ARRAY_STRIDE</constant></para>
 197
 198         <para><citerefentry><refentrytitle>glGetVertexAttrib</refentrytitle></citerefentry>
 199         with arguments <parameter>index</parameter> and <constant>GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING</constant></para>
 200
 201         <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument
 202         <constant>GL_ARRAY_BUFFER_BINDING</constant></para>
 203
 204         <para><citerefentry><refentrytitle>glGetVertexAttribPointerv</refentrytitle></citerefentry>
 205         with arguments <parameter>index</parameter> and
 206         <constant>GL_VERTEX_ATTRIB_ARRAY_POINTER</constant></para>
 207     </refsect1>
 208     <refsect1 id="seealso"><title>See Also</title>
 209         <para><citerefentry><refentrytitle>glArrayElement</refentrytitle></citerefentry>,
 210         <citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,
 211         <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
 212         <citerefentry><refentrytitle>glColorPointer</refentrytitle></citerefentry>,
 213         <citerefentry><refentrytitle>glDisableVertexAttribArray</refentrytitle></citerefentry>,
 214         <citerefentry><refentrytitle>glDrawArrays</refentrytitle></citerefentry>,
 215         <citerefentry><refentrytitle>glDrawElements</refentrytitle></citerefentry>,
 216         <citerefentry><refentrytitle>glDrawRangeElements</refentrytitle></citerefentry>,
 217         <citerefentry><refentrytitle>glEnableVertexAttribArray</refentrytitle></citerefentry>,
 218         <citerefentry><refentrytitle>glEdgeFlagPointer</refentrytitle></citerefentry>,
 219         <citerefentry><refentrytitle>glFogCoordPointer</refentrytitle></citerefentry>,
 220         <citerefentry><refentrytitle>glIndexPointer</refentrytitle></citerefentry>,
 221         <citerefentry><refentrytitle>glInterleavedArrays</refentrytitle></citerefentry>,
 222         <citerefentry><refentrytitle>glMultiDrawArrays</refentrytitle></citerefentry>,
 223         <citerefentry><refentrytitle>glMultiDrawElements</refentrytitle></citerefentry>,
 224         <citerefentry><refentrytitle>glNormalPointer</refentrytitle></citerefentry>,
 225         <citerefentry><refentrytitle>glPopClientAttrib</refentrytitle></citerefentry>,
 226         <citerefentry><refentrytitle>glPushClientAttrib</refentrytitle></citerefentry>,
 227         <citerefentry><refentrytitle>glSecondaryColorPointer</refentrytitle></citerefentry>,
 228         <citerefentry><refentrytitle>glTexCoordPointer</refentrytitle></citerefentry>,
 229         <citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry>,
 230         <citerefentry><refentrytitle>glVertexPointer</refentrytitle></citerefentry>
 231         </para>
 232     </refsect1>
 233     <refsect1 id="Copyright"><title>Copyright</title>
 234         <para>
 235             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 236             This material may be distributed subject to the terms and conditions set forth in
 237             the Open Publication License, v 1.0, 8 June 1999.
 238             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 239         </para>
 240     </refsect1>
 241 </refentry>