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=
"glGetActiveAttrib">
6 <refentrytitle>glGetActiveAttrib
</refentrytitle>
7 <manvolnum>3G
</manvolnum>
10 <refname>glGetActiveAttrib
</refname>
11 <refpurpose>Returns information about an active attribute variable for the specified program object
</refpurpose>
13 <refsynopsisdiv><title>C Specification
</title>
16 <funcdef>void
<function>glGetActiveAttrib
</function></funcdef>
17 <paramdef>GLuint
<parameter>program
</parameter></paramdef>
18 <paramdef>GLuint
<parameter>index
</parameter></paramdef>
19 <paramdef>GLsizei
<parameter>bufSize
</parameter></paramdef>
20 <paramdef>GLsizei *
<parameter>length
</parameter></paramdef>
21 <paramdef>GLint *
<parameter>size
</parameter></paramdef>
22 <paramdef>GLenum *
<parameter>type
</parameter></paramdef>
23 <paramdef>GLchar *
<parameter>name
</parameter></paramdef>
27 <refsect1 id=
"parameters"><title>Parameters
</title>
30 <term><parameter>program
</parameter></term>
32 <para>Specifies the program object to be
37 <term><parameter>index
</parameter></term>
39 <para>Specifies the index of the attribute variable
44 <term><parameter>bufSize
</parameter></term>
46 <para>Specifies the maximum number of characters
47 OpenGL is allowed to write in the character buffer
48 indicated by
<parameter>name
</parameter>.
</para>
52 <term><parameter>length
</parameter></term>
54 <para>Returns the number of characters actually
55 written by OpenGL in the string indicated by
56 <parameter>name
</parameter> (excluding the null
57 terminator) if a value other than
58 <constant>NULL
</constant> is passed.
</para>
62 <term><parameter>size
</parameter></term>
64 <para>Returns the size of the attribute
69 <term><parameter>type
</parameter></term>
71 <para>Returns the data type of the attribute
76 <term><parameter>name
</parameter></term>
78 <para>Returns a null terminated string containing
79 the name of the attribute variable.
</para>
84 <refsect1 id=
"description"><title>Description
</title>
85 <para><function>glGetActiveAttrib
</function> returns information
86 about an active attribute variable in the program object
87 specified by
<parameter>program
</parameter>. The number of
88 active attributes can be obtained by calling
89 <citerefentry><refentrytitle>glGetProgram
</refentrytitle></citerefentry>
90 with the value
<constant>GL_ACTIVE_ATTRIBUTES
</constant>. A
91 value of
0 for
<parameter>index
</parameter> selects the first
92 active attribute variable. Permissible values for
93 <parameter>index
</parameter> range from
0 to the number of
94 active attribute variables minus
1.
</para>
96 <para>A vertex shader may use either built-in attribute
97 variables, user-defined attribute variables, or both. Built-in
98 attribute variables have a prefix of
"gl_
" and
99 reference conventional OpenGL vertex attribtes (e.g.,
100 <parameter>gl_Vertex
</parameter>,
101 <parameter>gl_Normal
</parameter>, etc., see the OpenGL Shading
102 Language specification for a complete list.) User-defined
103 attribute variables have arbitrary names and obtain their values
104 through numbered generic vertex attributes. An attribute
105 variable (either built-in or user-defined) is considered active
106 if it is determined during the link operation that it may be
107 accessed during program execution. Therefore,
108 <parameter>program
</parameter> should have previously been the
110 <citerefentry><refentrytitle>glLinkProgram
</refentrytitle></citerefentry>,
111 but it is not necessary for it to have been linked
114 <para>The size of the character buffer required to store the
115 longest attribute variable name in
116 <parameter>program
</parameter> can be obtained by calling
117 <citerefentry><refentrytitle>glGetProgram
</refentrytitle></citerefentry>
119 <constant>GL_ACTIVE_ATTRIBUTE_MAX_LENGTH
</constant>. This value
120 should be used to allocate a buffer of sufficient size to store
121 the returned attribute name. The size of this character buffer
122 is passed in
<parameter>bufSize
</parameter>, and a pointer to
123 this character buffer is passed in
124 <parameter>name
</parameter>.
</para>
126 <para><function>glGetActiveAttrib
</function> returns the name of
127 the attribute variable indicated by
128 <parameter>index
</parameter>, storing it in the character buffer
129 specified by
<parameter>name
</parameter>. The string returned
130 will be null terminated. The actual number of characters written
131 into this buffer is returned in
<parameter>length
</parameter>,
132 and this count does not include the null termination character.
133 If the length of the returned string is not required, a value of
134 <constant>NULL
</constant> can be passed in the
135 <parameter>length
</parameter> argument.
</para>
137 <para>The
<parameter>type
</parameter> argument will return a
138 pointer to the attribute variable's data type. The symbolic
139 constants
<constant>GL_FLOAT
</constant>,
140 <constant>GL_FLOAT_VEC2
</constant>,
141 <constant>GL_FLOAT_VEC3
</constant>,
142 <constant>GL_FLOAT_VEC4
</constant>,
143 <constant>GL_FLOAT_MAT2
</constant>,
144 <constant>GL_FLOAT_MAT3
</constant>,
145 <constant>GL_FLOAT_MAT4
</constant>,
146 <constant>GL_FLOAT_MAT2x3
</constant>,
147 <constant>GL_FLOAT_MAT2x4
</constant>,
148 <constant>GL_FLOAT_MAT3x2
</constant>,
149 <constant>GL_FLOAT_MAT3x4
</constant>,
150 <constant>GL_FLOAT_MAT4x2
</constant>,
151 <constant>GL_FLOAT_MAT4x3
</constant>,
152 <constant>GL_INT
</constant>,
153 <constant>GL_INT_VEC2
</constant>,
154 <constant>GL_INT_VEC3
</constant>,
155 <constant>GL_INT_VEC4
</constant>,
156 <constant>GL_UNSIGNED_INT_VEC
</constant>,
157 <constant>GL_UNSIGNED_INT_VEC2
</constant>,
158 <constant>GL_UNSIGNED_INT_VEC3
</constant>, or
159 <constant>GL_UNSIGNED_INT_VEC4
</constant> may be returned. The
160 <parameter>size
</parameter> argument will return the size of the
161 attribute, in units of the type returned in
162 <parameter>type
</parameter>.
</para>
164 <para>The list of active attribute variables may include both
165 built-in attribute variables (which begin with the prefix
166 "gl_
") as well as user-defined attribute variable
169 <para>This function will return as much information as it can
170 about the specified active attribute variable. If no information
171 is available,
<parameter>length
</parameter> will be
0, and
172 <parameter>name
</parameter> will be an empty string. This
173 situation could occur if this function is called after a link
174 operation that failed. If an error occurs, the return values
175 <parameter>length
</parameter>,
<parameter>size
</parameter>,
176 <parameter>type
</parameter>, and
<parameter>name
</parameter>
177 will be unmodified.
</para>
179 <refsect1 id=
"errors"><title>Errors
</title>
180 <para><constant>GL_INVALID_VALUE
</constant> is generated if
181 <parameter>program
</parameter> is not a value generated by
184 <para><constant>GL_INVALID_OPERATION
</constant> is generated if
185 <parameter>program
</parameter> is not a program object.
</para>
187 <para><constant>GL_INVALID_VALUE
</constant> is generated if
188 <parameter>index
</parameter> is greater than or equal to the
189 number of active attribute variables in
190 <parameter>program
</parameter>.
</para>
192 <para><constant>GL_INVALID_VALUE
</constant> is generated if
193 <parameter>bufSize
</parameter> is less than
0.
</para>
195 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
196 <para><citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry>
197 with argument
<constant>GL_MAX_VERTEX_ATTRIBS
</constant>.
</para>
199 <para><citerefentry><refentrytitle>glGetProgram
</refentrytitle></citerefentry>
200 with argument
<constant>GL_ACTIVE_ATTRIBUTES
</constant> or
201 <constant>GL_ACTIVE_ATTRIBUTE_MAX_LENGTH
</constant>.
</para>
203 <para><citerefentry><refentrytitle>glIsProgram
</refentrytitle></citerefentry></para>
205 <refsect1 id=
"seealso"><title>See Also
</title>
206 <para><citerefentry><refentrytitle>glBindAttribLocation
</refentrytitle></citerefentry>,
207 <citerefentry><refentrytitle>glLinkProgram
</refentrytitle></citerefentry>,
208 <citerefentry><refentrytitle>glVertexAttrib
</refentrytitle></citerefentry>,
209 <citerefentry><refentrytitle>glVertexAttribPointer
</refentrytitle></citerefentry></para>
211 <refsect1 id=
"Copyright"><title>Copyright
</title>
213 Copyright
<trademark class=
"copyright"></trademark> 2003-
2005 3Dlabs Inc. Ltd.
214 Copyright
<trademark class=
"copyright"></trademark> 2010 Khronos Group.
215 This material may be distributed subject to the terms and conditions set forth in
216 the Open Publication License, v
1.0,
8 June
1999.
217 <ulink url=
"http://opencontent.org/openpub/">http://opencontent.org/openpub/
</ulink>.