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