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">
6 <refentrytitle>glVertexAttribPointer
</refentrytitle>
7 <manvolnum>3G
</manvolnum>
10 <refname>glVertexAttribPointer
</refname>
11 <refpurpose>define an array of generic vertex attribute data
</refpurpose>
13 <refsynopsisdiv><title>C Specification
</title>
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>
26 <refsect1 id=
"parameters"><title>Parameters
</title>
29 <term><parameter>index
</parameter></term>
31 <para>Specifies the index of the generic vertex
32 attribute to be modified.
</para>
36 <term><parameter>size
</parameter></term>
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>
44 <term><parameter>type
</parameter></term>
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>
60 <term><parameter>normalized
</parameter></term>
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
70 <term><parameter>stride
</parameter></term>
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>
80 <term><parameter>pointer
</parameter></term>
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>
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>
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>
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>
118 <para>To enable and disable a generic vertex attribute array,
120 <citerefentry><refentrytitle>glEnableVertexAttribArray
</refentrytitle></citerefentry>
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>
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>
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>
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>
151 <para><function>glVertexAttribPointer
</function> is typically
152 implemented on the client side.
</para>
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>
158 <citerefentry><refentrytitle>glPopAttrib
</refentrytitle></citerefentry>.
160 <citerefentry><refentrytitle>glPushClientAttrib
</refentrytitle></citerefentry>
162 <citerefentry><refentrytitle>glPopClientAttrib
</refentrytitle></citerefentry>
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>
170 <para><constant>GL_INVALID_VALUE
</constant> is generated if
171 <parameter>size
</parameter> is not
1,
2,
3, or
4.
</para>
173 <para><constant>GL_INVALID_ENUM
</constant> is generated if
174 <parameter>type
</parameter> is not an accepted value.
</para>
176 <para><constant>GL_INVALID_VALUE
</constant> is generated if
177 <parameter>stride
</parameter> is negative.
</para>
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>
183 <para><citerefentry><refentrytitle>glGetVertexAttrib
</refentrytitle></citerefentry>
184 with arguments
<parameter>index
</parameter> and
<constant>GL_VERTEX_ATTRIB_ARRAY_ENABLED
</constant></para>
186 <para><citerefentry><refentrytitle>glGetVertexAttrib
</refentrytitle></citerefentry>
187 with arguments
<parameter>index
</parameter> and
<constant>GL_VERTEX_ATTRIB_ARRAY_SIZE
</constant></para>
189 <para><citerefentry><refentrytitle>glGetVertexAttrib
</refentrytitle></citerefentry>
190 with arguments
<parameter>index
</parameter> and
<constant>GL_VERTEX_ATTRIB_ARRAY_TYPE
</constant></para>
192 <para><citerefentry><refentrytitle>glGetVertexAttrib
</refentrytitle></citerefentry>
193 with arguments
<parameter>index
</parameter> and
<constant>GL_VERTEX_ATTRIB_ARRAY_NORMALIZED
</constant></para>
195 <para><citerefentry><refentrytitle>glGetVertexAttrib
</refentrytitle></citerefentry>
196 with arguments
<parameter>index
</parameter> and
<constant>GL_VERTEX_ATTRIB_ARRAY_STRIDE
</constant></para>
198 <para><citerefentry><refentrytitle>glGetVertexAttrib
</refentrytitle></citerefentry>
199 with arguments
<parameter>index
</parameter> and
<constant>GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING
</constant></para>
201 <para><citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
202 <constant>GL_ARRAY_BUFFER_BINDING
</constant></para>
204 <para><citerefentry><refentrytitle>glGetVertexAttribPointerv
</refentrytitle></citerefentry>
205 with arguments
<parameter>index
</parameter> and
206 <constant>GL_VERTEX_ATTRIB_ARRAY_POINTER
</constant></para>
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>
233 <refsect1 id=
"Copyright"><title>Copyright
</title>
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>.