rename upstream-man-pages to upstream-doc
[clinton/guile-figl.git] / upstream-doc / man3 / glGetActiveUniformsiv.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="glGetActiveUniformsiv">
5 <refmeta>
6 <refentrytitle>glGetActiveUniformsiv</refentrytitle>
7 <manvolnum>3G</manvolnum>
8 </refmeta>
9 <refnamediv>
10 <refname>glGetActiveUniformsiv</refname>
11 <refpurpose>Returns information about several active uniform variables for the specified program object</refpurpose>
12 </refnamediv>
13 <refsynopsisdiv><title>C Specification</title>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>void <function>glGetActiveUniformsiv</function></funcdef>
17 <paramdef>GLuint <parameter>program</parameter></paramdef>
18 <paramdef>GLsizei <parameter>uniformCount</parameter></paramdef>
19 <paramdef>const GLuint *<parameter>uniformIndices</parameter></paramdef>
20 <paramdef>GLenum <parameter>pname</parameter></paramdef>
21 <paramdef>GLint *<parameter>params</parameter></paramdef>
22 </funcprototype>
23 </funcsynopsis>
24 </refsynopsisdiv>
25 <refsect1 id="parameters"><title>Parameters</title>
26 <variablelist>
27 <varlistentry>
28 <term><parameter>program</parameter></term>
29 <listitem>
30 <para>Specifies the program object to be queried.</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>uniformCount</parameter></term>
35 <listitem>
36 <para>Specifies both the number of elements in the array of indices <parameter>uniformIndices</parameter> and the
37 number of parameters written to <parameter>params</parameter> upon successful return.</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>uniformIndices</parameter></term>
42 <listitem>
43 <para>Specifies the address of an array of <parameter>uniformCount</parameter> integers containing the indices of
44 uniforms within <parameter>program</parameter> whose parameter <parameter>pname</parameter> pname.</para>
45 </listitem>
46 </varlistentry>
47 <varlistentry>
48 <term><parameter>pname</parameter></term>
49 <listitem>
50 <para>Specifies the property of the each uniform in <parameter>uniformIndices</parameter> that should be
51 written into the corresponding element of <parameter>params</parameter>.</para>
52 </listitem>
53 </varlistentry>
54 <varlistentry>
55 <term><parameter>params</parameter></term>
56 <listitem>
57 <para>Specifies the address of an array of <parameter>uniformCount</parameter> integers which are to
58 receive the value of <parameter>pname</parameter> for each uniform in <parameter>uniformIndices</parameter>.</para>
59 </listitem>
60 </varlistentry>
61 </variablelist>
62 </refsect1>
63 <refsect1 id="description"><title>Description</title>
64 <para>
65 <function>glGetActiveUniformsiv</function> queries the value of the parameter named <parameter>pname</parameter>
66 for each of the uniforms within <parameter>program</parameter> whose indices are specified in the array of
67 <parameter>uniformCount</parameter> unsigned integers <parameter>uniformIndices</parameter>. Upon success,
68 the value of the parameter for each uniform is written into the corresponding entry in the array whose
69 address is given in <parameter>params</parameter>. If an error is generated, nothing is written into
70 <parameter>params</parameter>.
71 </para>
72 <para>
73 If <parameter>pname</parameter> is <constant>GL_UNIFORM_TYPE</constant>, then an array identifying the types
74 of uniforms specified by the corresponding array of <parameter>uniformIndices</parameter> is returned. The
75 returned types can be any of the values from the following table:
76 <informaltable frame="topbot">
77 <tgroup cols="2" align="left">
78 <colspec colwidth="1.1*" />
79 <colspec colwidth="1*" />
80 <thead>
81 <row>
82 <entry rowsep="1" align="left"><emphasis role="bold">
83 Returned Symbolic Contant
84 </emphasis></entry>
85 <entry rowsep="1" align="left"><emphasis role="bold">
86 Shader Uniform Type
87 </emphasis></entry>
88 </row>
89 </thead>
90 <tbody>
91 <row>
92 <entry align="left">
93 <constant>GL_FLOAT</constant>
94 </entry>
95 <entry align="left">
96 <constant>float</constant>
97 </entry>
98 </row>
99 <row>
100 <entry align="left">
101 <constant>GL_FLOAT_VEC2</constant>
102 </entry>
103 <entry align="left">
104 <constant>vec2</constant>
105 </entry>
106 </row>
107 <row>
108 <entry align="left">
109 <constant>GL_FLOAT_VEC3</constant>
110 </entry>
111 <entry align="left">
112 <constant>vec3</constant>
113 </entry>
114 </row>
115 <row>
116 <entry align="left">
117 <constant>GL_FLOAT_VEC4</constant>
118 </entry>
119 <entry align="left">
120 <constant>vec4</constant>
121 </entry>
122 </row>
123 <row>
124 <entry align="left">
125 <constant>GL_INT</constant>
126 </entry>
127 <entry align="left">
128 <constant>int</constant>
129 </entry>
130 </row>
131 <row>
132 <entry align="left">
133 <constant>GL_INT_VEC2</constant>
134 </entry>
135 <entry align="left">
136 <constant>ivec2</constant>
137 </entry>
138 </row>
139 <row>
140 <entry align="left">
141 <constant>GL_INT_VEC3</constant>
142 </entry>
143 <entry align="left">
144 <constant>ivec3</constant>
145 </entry>
146 </row>
147 <row>
148 <entry align="left">
149 <constant>GL_INT_VEC4</constant>
150 </entry>
151 <entry align="left">
152 <constant>ivec4</constant>
153 </entry>
154 </row>
155 <row>
156 <entry align="left">
157 <constant>GL_UNSIGNED_INT</constant>
158 </entry>
159 <entry align="left">
160 <constant>unsigned int</constant>
161 </entry>
162 </row>
163 <row>
164 <entry align="left">
165 <constant>GL_UNSIGNED_INT_VEC2</constant>
166 </entry>
167 <entry align="left">
168 <constant>uvec2</constant>
169 </entry>
170 </row>
171 <row>
172 <entry align="left">
173 <constant>GL_UNSIGNED_INT_VEC3</constant>
174 </entry>
175 <entry align="left">
176 <constant>uvec3</constant>
177 </entry>
178 </row>
179 <row>
180 <entry align="left">
181 <constant>GL_UNSIGNED_INT_VEC4</constant>
182 </entry>
183 <entry align="left">
184 <constant>uvec4</constant>
185 </entry>
186 </row>
187 <row>
188 <entry align="left">
189 <constant>GL_BOOL</constant>
190 </entry>
191 <entry align="left">
192 <constant>bool</constant>
193 </entry>
194 </row>
195 <row>
196 <entry align="left">
197 <constant>GL_BOOL_VEC2</constant>
198 </entry>
199 <entry align="left">
200 <constant>bvec2</constant>
201 </entry>
202 </row>
203 <row>
204 <entry align="left">
205 <constant>GL_BOOL_VEC3</constant>
206 </entry>
207 <entry align="left">
208 <constant>bvec3</constant>
209 </entry>
210 </row>
211 <row>
212 <entry align="left">
213 <constant>GL_BOOL_VEC4</constant>
214 </entry>
215 <entry align="left">
216 <constant>bvec4</constant>
217 </entry>
218 </row>
219 <row>
220 <entry align="left">
221 <constant>GL_FLOAT_MAT2</constant>
222 </entry>
223 <entry align="left">
224 <constant>mat2</constant>
225 </entry>
226 </row>
227 <row>
228 <entry align="left">
229 <constant>GL_FLOAT_MAT3</constant>
230 </entry>
231 <entry align="left">
232 <constant>mat3</constant>
233 </entry>
234 </row>
235 <row>
236 <entry align="left">
237 <constant>GL_FLOAT_MAT4</constant>
238 </entry>
239 <entry align="left">
240 <constant>mat4</constant>
241 </entry>
242 </row>
243 <row>
244 <entry align="left">
245 <constant>GL_FLOAT_MAT2x3</constant>
246 </entry>
247 <entry align="left">
248 <constant>mat2x3</constant>
249 </entry>
250 </row>
251 <row>
252 <entry align="left">
253 <constant>GL_FLOAT_MAT2x4</constant>
254 </entry>
255 <entry align="left">
256 <constant>mat2x4</constant>
257 </entry>
258 </row>
259 <row>
260 <entry align="left">
261 <constant>GL_FLOAT_MAT3x2</constant>
262 </entry>
263 <entry align="left">
264 <constant>mat3x2</constant>
265 </entry>
266 </row>
267 <row>
268 <entry align="left">
269 <constant>GL_FLOAT_MAT3x4</constant>
270 </entry>
271 <entry align="left">
272 <constant>mat3x4</constant>
273 </entry>
274 </row>
275 <row>
276 <entry align="left">
277 <constant>GL_FLOAT_MAT4x2</constant>
278 </entry>
279 <entry align="left">
280 <constant>mat4x2</constant>
281 </entry>
282 </row>
283 <row>
284 <entry align="left">
285 <constant>GL_FLOAT_MAT4x3</constant>
286 </entry>
287 <entry align="left">
288 <constant>mat4x3</constant>
289 </entry>
290 </row>
291 <row>
292 <entry align="left">
293 <constant>GL_SAMPLER_1D</constant>
294 </entry>
295 <entry align="left">
296 <constant>sampler1D</constant>
297 </entry>
298 </row>
299 <row>
300 <entry align="left">
301 <constant>GL_SAMPLER_2D</constant>
302 </entry>
303 <entry align="left">
304 <constant>sampler2D</constant>
305 </entry>
306 </row>
307 <row>
308 <entry align="left">
309 <constant>GL_SAMPLER_3D</constant>
310 </entry>
311 <entry align="left">
312 <constant>sampler3D</constant>
313 </entry>
314 </row>
315 <row>
316 <entry align="left">
317 <constant>GL_SAMPLER_CUBE</constant>
318 </entry>
319 <entry align="left">
320 <constant>samplerCube</constant>
321 </entry>
322 </row>
323 <row>
324 <entry align="left">
325 <constant>GL_SAMPLER_1D_SHADOW</constant>
326 </entry>
327 <entry align="left">
328 <constant>sampler1DShadow</constant>
329 </entry>
330 </row>
331 <row>
332 <entry align="left">
333 <constant>GL_SAMPLER_2D_SHADOW</constant>
334 </entry>
335 <entry align="left">
336 <constant>sampler2DShadow</constant>
337 </entry>
338 </row>
339 <row>
340 <entry align="left">
341 <constant>GL_SAMPLER_1D_ARRAY</constant>
342 </entry>
343 <entry align="left">
344 <constant>sampler1DArray</constant>
345 </entry>
346 </row>
347 <row>
348 <entry align="left">
349 <constant>GL_SAMPLER_2D_ARRAY</constant>
350 </entry>
351 <entry align="left">
352 <constant>sampler2DArray</constant>
353 </entry>
354 </row>
355 <row>
356 <entry align="left">
357 <constant>GL_SAMPLER_1D_ARRAY_SHADOW</constant>
358 </entry>
359 <entry align="left">
360 <constant>sampler1DArrayShadow</constant>
361 </entry>
362 </row>
363 <row>
364 <entry align="left">
365 <constant>GL_SAMPLER_2D_ARRAY_SHADOW</constant>
366 </entry>
367 <entry align="left">
368 <constant>sampler2DArrayShadow</constant>
369 </entry>
370 </row>
371 <row>
372 <entry align="left">
373 <constant>GL_SAMPLER_2D_MULTISAMPLE</constant>
374 </entry>
375 <entry align="left">
376 <constant>sampler2DMS</constant>
377 </entry>
378 </row>
379 <row>
380 <entry align="left">
381 <constant>GL_SAMPLER_2D_MULTISAMPLE_ARRAY</constant>
382 </entry>
383 <entry align="left">
384 <constant>sampler2DMSArray</constant>
385 </entry>
386 </row>
387 <row>
388 <entry align="left">
389 <constant>GL_SAMPLER_CUBE_SHADOW</constant>
390 </entry>
391 <entry align="left">
392 <constant>samplerCubeShadow</constant>
393 </entry>
394 </row>
395 <row>
396 <entry align="left">
397 <constant>GL_SAMPLER_BUFFER</constant>
398 </entry>
399 <entry align="left">
400 <constant>samplerBuffer</constant>
401 </entry>
402 </row>
403 <row>
404 <entry align="left">
405 <constant>GL_SAMPLER_2D_RECT</constant>
406 </entry>
407 <entry align="left">
408 <constant>sampler2DRect</constant>
409 </entry>
410 </row>
411 <row>
412 <entry align="left">
413 <constant>GL_SAMPLER_2D_RECT_SHADOW</constant>
414 </entry>
415 <entry align="left">
416 <constant>sampler2DRectShadow</constant>
417 </entry>
418 </row>
419 <row>
420 <entry align="left">
421 <constant>GL_INT_SAMPLER_1D</constant>
422 </entry>
423 <entry align="left">
424 <constant>isampler1D</constant>
425 </entry>
426 </row>
427 <row>
428 <entry align="left">
429 <constant>GL_INT_SAMPLER_2D</constant>
430 </entry>
431 <entry align="left">
432 <constant>isampler2D</constant>
433 </entry>
434 </row>
435 <row>
436 <entry align="left">
437 <constant>GL_INT_SAMPLER_3D</constant>
438 </entry>
439 <entry align="left">
440 <constant>isampler3D</constant>
441 </entry>
442 </row>
443 <row>
444 <entry align="left">
445 <constant>GL_INT_SAMPLER_CUBE</constant>
446 </entry>
447 <entry align="left">
448 <constant>isamplerCube</constant>
449 </entry>
450 </row>
451 <row>
452 <entry align="left">
453 <constant>GL_INT_SAMPLER_1D_ARRAY</constant>
454 </entry>
455 <entry align="left">
456 <constant>isampler1DArray</constant>
457 </entry>
458 </row>
459 <row>
460 <entry align="left">
461 <constant>GL_INT_SAMPLER_2D_ARRAY</constant>
462 </entry>
463 <entry align="left">
464 <constant>isampler2DArray</constant>
465 </entry>
466 </row>
467 <row>
468 <entry align="left">
469 <constant>GL_INT_SAMPLER_2D_MULTISAMPLE</constant>
470 </entry>
471 <entry align="left">
472 <constant>isampler2DMS</constant>
473 </entry>
474 </row>
475 <row>
476 <entry align="left">
477 <constant>GL_INT_SAMPLER_2D_MULTISAMPLE_ARRAY</constant>
478 </entry>
479 <entry align="left">
480 <constant>isampler2DMSArray</constant>
481 </entry>
482 </row>
483 <row>
484 <entry align="left">
485 <constant>GL_INT_SAMPLER_BUFFER</constant>
486 </entry>
487 <entry align="left">
488 <constant>isamplerBuffer</constant>
489 </entry>
490 </row>
491 <row>
492 <entry align="left">
493 <constant>GL_INT_SAMPLER_2D_RECT</constant>
494 </entry>
495 <entry align="left">
496 <constant>isampler2DRect</constant>
497 </entry>
498 </row>
499 <row>
500 <entry align="left">
501 <constant>GL_UNSIGNED_INT_SAMPLER_1D</constant>
502 </entry>
503 <entry align="left">
504 <constant>usampler1D</constant>
505 </entry>
506 </row>
507 <row>
508 <entry align="left">
509 <constant>GL_UNSIGNED_INT_SAMPLER_2D</constant>
510 </entry>
511 <entry align="left">
512 <constant>usampler2D</constant>
513 </entry>
514 </row>
515 <row>
516 <entry align="left">
517 <constant>GL_UNSIGNED_INT_SAMPLER_3D</constant>
518 </entry>
519 <entry align="left">
520 <constant>usampler3D</constant>
521 </entry>
522 </row>
523 <row>
524 <entry align="left">
525 <constant>GL_UNSIGNED_INT_SAMPLER_CUBE</constant>
526 </entry>
527 <entry align="left">
528 <constant>usamplerCube</constant>
529 </entry>
530 </row>
531 <row>
532 <entry align="left">
533 <constant>GL_UNSIGNED_INT_SAMPLER_1D_ARRAY</constant>
534 </entry>
535 <entry align="left">
536 <constant>usampler2DArray</constant>
537 </entry>
538 </row>
539 <row>
540 <entry align="left">
541 <constant>GL_UNSIGNED_INT_SAMPLER_2D_ARRAY</constant>
542 </entry>
543 <entry align="left">
544 <constant>usampler2DArray</constant>
545 </entry>
546 </row>
547 <row>
548 <entry align="left">
549 <constant>GL_UNSIGNED_INT_SAMPLER_2D_MULTISAMPLE</constant>
550 </entry>
551 <entry align="left">
552 <constant>usampler2DMS</constant>
553 </entry>
554 </row>
555 <row>
556 <entry align="left">
557 <constant>GL_UNSIGNED_INT_SAMPLER_2D_MULTISAMPLE_ARRAY</constant>
558 </entry>
559 <entry align="left">
560 <constant>usampler2DMSArray</constant>
561 </entry>
562 </row>
563 <row>
564 <entry align="left">
565 <constant>GL_UNSIGNED_INT_SAMPLER_BUFFER</constant>
566 </entry>
567 <entry align="left">
568 <constant>usamplerBuffer</constant>
569 </entry>
570 </row>
571 <row>
572 <entry align="left">
573 <constant>GL_UNSIGNED_INT_SAMPLER_2D_RECT</constant>
574 </entry>
575 <entry align="left">
576 <constant>usampler2DRect</constant>
577 </entry>
578 </row>
579 </tbody>
580 </tgroup>
581 </informaltable>
582 </para>
583 <para>
584 If <parameter>pname</parameter> is <constant>GL_UNIFORM_SIZE</constant>, then an array identifying the
585 size of the uniforms specified by the corresponding array of <parameter>uniformIndices</parameter> is
586 returned. The sizes returned are in units of the type returned by a query of <constant>GL_UNIFORM_TYPE</constant>.
587 For active uniforms that are arrays, the size is the number of active elements in the array;
588 for all other uniforms, the size is one.
589 </para>
590 <para>
591 If <parameter>pname</parameter> is <constant>GL_UNIFORM_NAME_LENGTH</constant>, then an array identifying the
592 length, including the terminating null character, of the uniform name strings specified by the corresponding
593 array of <parameter>uniformIndices</parameter> is returned.
594 </para>
595 <para>
596 If <parameter>pname</parameter> is <constant>GL_UNIFORM_BLOCK_INDEX</constant>, then an array identifying the
597 the uniform block index of each of the uniforms specified by the corresponding array of <parameter>uniformIndices</parameter>
598 is returned. The uniform block index of a uniform associated with the default uniform block is -1.
599 </para>
600 <para>
601 If <parameter>pname</parameter> is <constant>GL_UNIFORM_OFFSET</constant>, then an array of uniform buffer
602 offsets is returned. For uniforms in a named uniform block, the returned value will be its offset, in basic
603 machine units, relative to the beginning of the uniform block in the buffer object data store. For uniforms
604 in the default uniform block, -1 will be returned.
605 </para>
606 <para>
607 If <parameter>pname</parameter> is <constant>GL_UNIFORM_ARRAY_STRIDE</constant>, then an array identifying the
608 stride between elements, in basic machine units, of each of the uniforms specified by the corresponding array of
609 <parameter>uniformIndices</parameter> is returned. The stride of a uniform associated with the default uniform
610 block is -1. Note that this information only makes sense for uniforms that are arrays. For uniforms that are
611 not arrays, but are declared in a named uniform block, an array stride of zero is returned.
612 </para>
613 <para>
614 If <parameter>pname</parameter> is <constant>GL_UNIFORM_MATRIX_STRIDE</constant>, then an array identifying the stride
615 between columns of a column-major matrix or rows of a row-major matrix, in basic machine units, of each of the uniforms
616 specified by the corresponding array of <parameter>uniformIndices</parameter> is returned. The matrix stride of a
617 uniform associated with the default uniform block is -1. Note that this information only makes sense for uniforms
618 that are matrices. For uniforms that are not matrices, but are declared in a named uniform block, a matrix stride of
619 zero is returned.
620 </para>
621 <para>
622 If <parameter>pname</parameter> is <constant>GL_UNIFORM_IS_ROW_MAJOR</constant>, then an array identifying whether each
623 of the uniforms specified by the corresponding array of <parameter>uniformIndices</parameter> is a row-major matrix or not is returned. A
624 value of one indicates a row-major matrix, and a value of zero indicates a column-major matrix, a matrix in the default
625 uniform block, or a non-matrix.
626 </para>
627 </refsect1>
628 <refsect1 id="errors"><title>Errors</title>
629 <para><constant>GL_INVALID_VALUE</constant> is generated if
630 <parameter>program</parameter> is not a value generated by
631 OpenGL.</para>
632
633 <para><constant>GL_INVALID_OPERATION</constant> is generated if
634 <parameter>program</parameter> is not a program object.</para>
635
636 <para><constant>GL_INVALID_VALUE</constant> is generated if
637 <parameter>uniformCount</parameter> is greater than or equal to the
638 value of <constant>GL_ACTIVE_UNIFORMS</constant> for
639 <parameter>program</parameter>.</para>
640
641 <para><constant>GL_INVALID_ENUM</constant> is generated if <parameter>pname</parameter>
642 is not an accepted token.</para>
643 </refsect1>
644 <refsect1 id="associatedgets"><title>Associated Gets</title>
645 <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
646 with argument <constant>GL_MAX_VERTEX_UNIFORM_COMPONENTS</constant>,
647 <constant>GL_MAX_GEOMETRY_UNIFORM_COMPONENTS</constant>,
648 <constant>GL_MAX_FRAGMENT_UNIFORM_COMPONENTS</constant>, or
649 <constant>GL_MAX_COMBINED_UNIFORM_COMPONENTS</constant>.</para>
650
651 <para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
652 with argument <constant>GL_ACTIVE_UNIFORMS</constant> or
653 <constant>GL_ACTIVE_UNIFORM_MAX_LENGTH</constant>.</para>
654
655 <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
656 </refsect1>
657 <refsect1 id="seealso"><title>See Also</title>
658 <para><citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>,
659 <citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>,
660 <citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>,
661 <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
662 <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>,
663 <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry></para>
664 </refsect1>
665 <refsect1 id="Copyright"><title>Copyright</title>
666 <para>
667 Copyright <trademark class="copyright"></trademark> 2011 Khronos Group
668 This material may be distributed subject to the terms and conditions set forth in
669 the Open Publication License, v 1.0, 8 June 1999.
670 <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
671 </para>
672 </refsect1>
673 </refentry>