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