rename upstream-man-pages to upstream-doc
[clinton/guile-figl.git] / upstream-doc / man4 / glGetProgramResource.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="glGetProgramResource">
5 <refmeta>
6 <refmetainfo>
7 <copyright>
8 <year>2012</year>
9 <holder>Khronos Group</holder>
10 </copyright>
11 </refmetainfo>
12 <refentrytitle>glGetProgramResource</refentrytitle>
13 <manvolnum>3G</manvolnum>
14 </refmeta>
15 <refnamediv>
16 <refname>glGetProgramResource</refname>
17 <refpurpose>retrieve values for multiple properties of a single active resource within a program object</refpurpose>
18 </refnamediv>
19 <refsynopsisdiv><title>C Specification</title>
20 <funcsynopsis>
21 <funcprototype>
22 <funcdef>void <function>glGetProgramResourceiv</function></funcdef>
23 <paramdef>GLuint <parameter>program</parameter></paramdef>
24 <paramdef>GLenum <parameter>programInterface</parameter></paramdef>
25 <paramdef>GLuint <parameter>index</parameter></paramdef>
26 <paramdef>GLsizei <parameter>propCount</parameter></paramdef>
27 <paramdef>const Glenum * <parameter>props</parameter></paramdef>
28 <paramdef>GLsizei <parameter>bufSize</parameter></paramdef>
29 <paramdef>GLsizei * <parameter>length</parameter></paramdef>
30 <paramdef>GLint * <parameter>params</parameter></paramdef>
31 </funcprototype>
32 </funcsynopsis>
33 </refsynopsisdiv>
34 <refsect1 id="parameters"><title>Parameters</title>
35 <variablelist>
36 <varlistentry>
37 <term><parameter>program</parameter></term>
38 <listitem>
39 <para>
40 The name of a program object whose resources to query.
41 </para>
42 </listitem>
43 </varlistentry>
44 <varlistentry>
45 <term><parameter>programInterface</parameter></term>
46 <listitem>
47 <para>
48 A token identifying the interface within <parameter>program</parameter> containing the resource named <parameter>name</parameter>.
49 </para>
50 </listitem>
51 </varlistentry>
52 </variablelist>
53 </refsect1>
54 <refsect1 id="description"><title>Description</title>
55 <para>
56 <function>glGetProgramResourceiv</function> returns values for multiple properties of a single active resource with an
57 index of <parameter>index</parameter> in the interface <parameter>programInterface</parameter> of program object
58 <parameter>program</parameter>. For each resource, values for <parameter>propCount</parameter> properties specified
59 by the array <parameter>props</parameter> are returned. <parameter>propCount</parameter> may not be zero.
60 An error is generated if any value
61 in <parameter>props</parameter> is not one of the properties described immediately belowor if any value in <parameter>props</parameter> is not
62 allowed for <parameter>programInterface</parameter>. The set of allowed <parameter>programInterface</parameter>
63 values for each property can be found in the following table:
64 </para>
65 <informaltable frame="topbot">
66 <tgroup cols="2" align="left">
67 <colspec colnum="1" colname="col1" colwidth="1*"/>
68 <colspec colnum="2" colname="col2" colwidth="2*"/>
69 <thead>
70 <row>
71 <entry morerows="1" rowsep="1" align="center">Property</entry>
72 <entry morerows="1" rowsep="1" align="center">Supported Interfaces</entry>
73 </row>
74 </thead>
75 <tbody>
76 <row>
77 <entry align="left"><constant>GL_NAME_LENGTH</constant></entry>
78 <entry align="left">Any except <constant>GL_ATOMIC_COUNTER_BUFFER</constant></entry>
79 </row>
80 <row>
81 <entry align="left"><constant>GL_TYPE</constant></entry>
82 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_PROGRAM_INPUT</constant>, <constant>GL_PROGRAM_OUTPUT</constant>, <constant>GL_TRANSFORM_FEEDBACK_VARYING</constant>, <constant>GL_BUFFER_VARIABLE</constant></entry>
83 </row>
84 <row>
85 <entry align="left"><constant>GL_ARRAY_SIZE</constant></entry>
86 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_BUFFER_VARIABLE</constant>, <constant>GL_PROGRAM_INPUT</constant>,
87 <constant>GL_PROGRAM_OUTPUT, VERTEX_SUBROUTINE_UNIFORM</constant>, <constant>GL_TESS_CONTROL_SUBROUTINE_UNIFORM</constant>,
88 <constant>GL_TESS_EVALUATION_SUBROUTINE_UNIFORM</constant>, <constant>GL_GEOMETRY_SUBROUTINE_UNIFORM</constant>,
89 <constant>GL_FRAGMENT_SUBROUTINE_UNIFORM</constant>, <constant>GL_COMPUTE_SUBROUTINE_UNIFORM</constant>, <constant>GL_TRANSFORM_FEEDBACK_VARYING</constant></entry>
90 </row>
91 <row>
92 <entry align="left"><constant>GL_OFFSET</constant></entry>
93 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_BUFFER_VARIABLE</constant></entry>
94 </row>
95 <row>
96 <entry align="left"><constant>GL_BLOCK_INDEX</constant></entry>
97 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_BUFFER_VARIABLE</constant></entry>
98 </row>
99 <row>
100 <entry align="left"><constant>GL_ARRAY_STRIDE</constant></entry>
101 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_BUFFER_VARIABLE</constant></entry>
102 </row>
103 <row>
104 <entry align="left"><constant>GL_MATRIX_STRIDE</constant></entry>
105 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_BUFFER_VARIABLE</constant></entry>
106 </row>
107 <row>
108 <entry align="left"><constant>GL_IS_ROW_MAJOR</constant></entry>
109 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_BUFFER_VARIABLE</constant></entry>
110 </row>
111 <row>
112 <entry align="left"><constant>GL_ATOMIC_COUNTER_BUFFER_INDEX</constant></entry>
113 <entry align="left"><constant>GL_UNIFORM</constant></entry>
114 </row>
115 <row>
116 <entry align="left"><constant>GL_TEXTURE_BUFFER</constant></entry>
117 <entry align="left"><emph>none</emph></entry>
118 </row>
119 <row>
120 <entry align="left"><constant>GL_BUFFER_BINDING</constant></entry>
121 <entry align="left"><constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_BUFFER</constant>, <constant>GL_SHADER_STORAGE_BLOCK</constant></entry>
122 </row>
123 <row>
124 <entry align="left"><constant>GL_BUFFER_DATA_SIZE</constant></entry>
125 <entry align="left"><constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_BUFFER</constant>, <constant>GL_SHADER_STORAGE_BLOCK</constant></entry>
126 </row>
127 <row>
128 <entry align="left"><constant>GL_NUM_ACTIVE_VARIABLES</constant></entry>
129 <entry align="left"><constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_BUFFER</constant>, <constant>GL_SHADER_STORAGE_BLOCK</constant></entry>
130 </row>
131 <row>
132 <entry align="left"><constant>GL_ACTIVE_VARIABLES</constant></entry>
133 <entry align="left"><constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_BUFFER</constant>, <constant>GL_SHADER_STORAGE_BLOCK</constant></entry>
134 </row>
135 <row>
136 <entry align="left"><constant>GL_REFERENCED_BY_VERTEX_SHADER</constant></entry>
137 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_SHADER</constant>,
138 <constant>GL_BUFFER</constant>, <constant>GL_SHADER_STORAGE_BLOCK</constant>, <constant>GL_BUFFER_VARIABLE</constant>,
139 <constant>GL_PROGRAM_INPUT</constant>, <constant>GL_PROGRAM_OUTPUT</constant></entry>
140 </row>
141 <row>
142 <entry align="left"><constant>GL_REFERENCED_BY_TESS_CONTROL_SHADER</constant></entry>
143 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_SHADER</constant>,
144 <constant>GL_BUFFER</constant>, <constant>GL_SHADER_STORAGE_BLOCK</constant>, <constant>GL_BUFFER_VARIABLE</constant>,
145 <constant>GL_PROGRAM_INPUT</constant>, <constant>GL_PROGRAM_OUTPUT</constant></entry>
146 </row>
147 <row>
148 <entry align="left"><constant>GL_REFERENCED_BY_TESS_EVALUATION_SHADER</constant></entry>
149 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_SHADER</constant>,
150 <constant>GL_BUFFER</constant>, <constant>GL_SHADER_STORAGE_BLOCK</constant>, <constant>GL_BUFFER_VARIABLE</constant>,
151 <constant>GL_PROGRAM_INPUT</constant>, <constant>GL_PROGRAM_OUTPUT</constant></entry>
152 </row>
153 <row>
154 <entry align="left"><constant>GL_REFERENCED_BY_GEOMETRY_SHADER</constant></entry>
155 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_SHADER</constant>,
156 <constant>GL_BUFFER</constant>, <constant>GL_SHADER_STORAGE_BLOCK</constant>, <constant>GL_BUFFER_VARIABLE</constant>,
157 <constant>GL_PROGRAM_INPUT</constant>, <constant>GL_PROGRAM_OUTPUT</constant></entry>
158 </row>
159 <row>
160 <entry align="left"><constant>GL_REFERENCED_BY_FRAGMENT_SHADER</constant></entry>
161 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_SHADER</constant>,
162 <constant>GL_BUFFER</constant>, <constant>GL_SHADER_STORAGE_BLOCK</constant>, <constant>GL_BUFFER_VARIABLE</constant>,
163 <constant>GL_PROGRAM_INPUT</constant>, <constant>GL_PROGRAM_OUTPUT</constant></entry>
164 </row>
165 <row>
166 <entry align="left"><constant>GL_REFERENCED_BY_COMPUTE_SHADER</constant></entry>
167 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_UNIFORM_BLOCK</constant>, <constant>GL_ATOMIC_COUNTER_SHADER</constant>,
168 <constant>GL_BUFFER</constant>, <constant>GL_SHADER_STORAGE_BLOCK</constant>, <constant>GL_BUFFER_VARIABLE</constant>,
169 <constant>GL_PROGRAM_INPUT</constant>, <constant>GL_PROGRAM_OUTPUT</constant></entry>
170 </row>
171 <row>
172 <entry align="left"><constant>GL_NUM_COMPATIBLE_SUBROUTINES</constant></entry>
173 <entry align="left"><constant>GL_VERTEX_SUBROUTINE_UNIFORM</constant>, <constant>GL_TESS_CONTROL_SUBROUTINE_UNIFORM</constant>,
174 <constant>GL_TESS_EVALUATION_SUBROUTINE_UNIFORM</constant>, <constant>GL_GEOMETRY_SUBROUTINE_UNIFORM</constant>,
175 <constant>GL_FRAGMENT_SUBROUTINE_UNIFORM</constant>, <constant>GL_COMPUTE_SUBROUTINE_UNIFORM</constant></entry>
176 </row>
177 <row>
178 <entry align="left"><constant>GL_COMPATIBLE_SUBROUTINES</constant></entry>
179 <entry align="left"><constant>GL_VERTEX_SUBROUTINE_UNIFORM</constant>, <constant>GL_TESS_CONTROL_SUBROUTINE_UNIFORM</constant>,
180 <constant>GL_TESS_EVALUATION_SUBROUTINE_UNIFORM</constant>, <constant>GL_GEOMETRY_SUBROUTINE_UNIFORM</constant>,
181 <constant>GL_FRAGMENT_SUBROUTINE_UNIFORM</constant>, <constant>GL_COMPUTE_SUBROUTINE_UNIFORM</constant></entry>
182 </row>
183 <row>
184 <entry align="left"><constant>GL_TOP_LEVEL_ARRAY_SIZE</constant></entry>
185 <entry align="left"><constant>GL_BUFFER_VARIABLE</constant></entry>
186 </row>
187 <row>
188 <entry align="left"><constant>GL_TOP_LEVEL_ARRAY_STRIDE</constant></entry>
189 <entry align="left"><constant>GL_BUFFER_VARIABLE</constant></entry>
190 </row>
191 <row>
192 <entry align="left"><constant>GL_LOCATION</constant></entry>
193 <entry align="left"><constant>GL_UNIFORM</constant>, <constant>GL_PROGRAM_INPUT</constant>, <constant>GL_PROGRAM_OUTPUT</constant>,
194 <constant>GL_VERTEX_SUBROUTINE_UNIFORM</constant>, <constant>GL_TESS_CONTROL_SUBROUTINE_UNIFORM</constant>,
195 <constant>GL_TESS_EVALUATION_SUBROUTINE_UNIFORM</constant>, <constant>GL_GEOMETRY_SUBROUTINE_UNIFORM</constant>,
196 <constant>GL_FRAGMENT_SUBROUTINE_UNIFORM</constant>, <constant>GL_COMPUTE_SUBROUTINE_UNIFORM</constant></entry>
197 </row>
198 <row>
199 <entry align="left"><constant>GL_LOCATION_INDEX</constant></entry>
200 <entry align="left"><constant>GL_PROGRAM_OUTPUT</constant></entry>
201 </row>
202 <row>
203 <entry align="left"><constant>GL_IS_PER_PATCH</constant></entry>
204 <entry align="left"><constant>GL_PROGRAM_INPUT</constant>, <constant>GL_PROGRAM_OUTPUT</constant></entry>
205 </row>
206 </tbody>
207 </tgroup>
208 </informaltable>
209
210 <para>
211 For the property <constant>GL_NAME_LENGTH</constant>, a single integer identifying the length of
212 the name string associated with an active variable, interface block, or
213 subroutine is written to <parameter>params</parameter>. The name length includes a terminating
214 null character.
215
216 For the property <constant>GL_TYPE</constant>, a single integer identifying the type of an active
217 variable is written to <parameter>params</parameter>. The integer returned is one of the
218 values found in table 2.16.
219
220 For the property <constant>GL_ARRAY_SIZE</constant>, a single integer identifying the number of
221 active array elements of an active variable is written to <parameter>params</parameter>. The
222 array size returned is in units of the type associated with the property
223 TYPE. For active variables not corresponding to an array of basic types,
224 the value zero is written to <parameter>params</parameter>.
225
226 For the property <constant>GL_BLOCK_INDEX</constant>, a single integer identifying the index of
227 the active interface block containing an active variable is written to
228 <parameter>params</parameter>. If the variable is not the member of an interface block, the
229 value -1 is written to <parameter>params</parameter>.
230
231 For the property <constant>GL_OFFSET</constant>, a single integer identifying the offset of an
232 active variable is written to <parameter>params</parameter>. For active variables backed by a
233 buffer object, the value written is the offset, in basic machine units,
234 relative to the base of buffer range holding the values of the variable.
235 For active variables not backed by a buffer object, an offset of -1 is
236 written to <parameter>params</parameter>.
237
238 For the property <constant>GL_ARRAY_STRIDE</constant>, a single integer identifying the stride
239 between array elements in an active variable is written to <parameter>params</parameter>. For
240 active variables declared as an array of basic types, the value written is
241 the difference, in basic machine units, between the offsets of consecutive
242 elements in an array. For active variables not declared as an array of
243 basic types, zero is written to <parameter>params</parameter>. For active variables not backed
244 by a buffer object, -1 is written to <parameter>params</parameter>, regardless of the variable
245 type.
246
247 For the property <constant>GL_MATRIX_STRIDE</constant>, a single integer identifying the stride
248 between columns of a column-major matrix or rows of a row-major matrix is
249 written to <parameter>params</parameter>. For active variables declared a single matrix or
250 array of matrices, the value written is the difference, in basic machine
251 units, between the offsets of consecutive columns or rows in each matrix.
252 For active variables not declared as a matrix or array of matrices, zero
253 is written to <parameter>params</parameter>. For active variables not backed by a buffer
254 object, -1 is written to <parameter>params</parameter>, regardless of the variable type.
255
256 For the property <constant>GL_IS_ROW_MAJOR</constant>, a single integer identifying whether an
257 active variable is a row-major matrix is written to <parameter>params</parameter>. For active
258 variables backed by a buffer object, declared as a single matrix or array
259 of matrices, and stored in row-major order, one is written to <parameter>params</parameter>.
260 For all other active variables, zero is written to <parameter>params</parameter>.
261
262 For the property <constant>GL_ATOMIC_COUNTER_BUFFER_INDEX</constant>, a single integer identifying
263 the index of the active atomic counter buffer containing an active
264 variable is written to <parameter>params</parameter>. If the variable is not an atomic counter
265 uniform, the value -1 is written to <parameter>params</parameter>.
266
267 For the property <constant>GL_BUFFER_BINDING</constant>, to index of the buffer binding point
268 associated with the active uniform block, shader storage block, or atomic
269 counter buffer is written to <parameter>params</parameter>.
270
271 For the property <constant>GL_BUFFER_DATA_SIZE</constant>, then the implementation-dependent
272 minimum total buffer object size, in basic machine units, required to hold
273 all active variables associated with an active uniform block, shader
274 storage block, or atomic counter buffer is written to <parameter>params</parameter>. If the
275 final member of an active shader storage block is array with no declared
276 size, the minimum buffer size is computed assuming the array was declared
277 as an array with one element.
278
279 For the property <constant>GL_NUM_ACTIVE_VARIABLES</constant>, the number of active variables
280 associated with an active uniform block, shader storage block, or atomic
281 counter buffer is written to <parameter>params</parameter>.
282
283 For the property <constant>GL_of ACTIVE_VARIABLES</constant>, an array of active variable indices
284 associated with an active uniform block, shader storage block, or atomic
285 counter buffer is written to <parameter>params</parameter>. The number of values written to
286 <parameter>params</parameter> for an active resource is given by the value of the property
287 <constant>GL_NUM_ACTIVE_VARIABLES</constant> for the resource.
288
289 For the properties <constant>GL_REFERENCED_BY_VERTEX_SHADER</constant>,
290 <constant>GL_REFERENCED_BY_TESS_CONTROL_SHADER</constant>, <constant>GL_REFERENCED_BY_TESS_EVALUATION_SHADER</constant>,
291 <constant>GL_REFERENCED_BY_GEOMETRY_SHADER</constant>, <constant>GL_REFERENCED_BY_FRAGMENT_SHADER</constant>, and
292 <constant>GL_REFERENCED_BY_COMPUTE_SHADER</constant>, a single integer is written to <parameter>params</parameter>,
293 identifying whether the active resource is referenced by the vertex,
294 tessellation control, tessellation evaluation, geometry, or fragment
295 shaders, respectively, in the program object. The value one is written to
296 <parameter>params</parameter> if an active variable is referenced by the corresponding shader,
297 or if an active uniform block, shader storage block, or atomic counter
298 buffer contains at least one variable referenced by the corresponding
299 shader. Otherwise, the value zero is written to <parameter>params</parameter>.
300
301 For the property <constant>GL_TOP_LEVEL_ARRAY_SIZE</constant>, a single integer identifying the
302 number of active array elements of the top-level shader storage block
303 member containing to the active variable is written to <parameter>params</parameter>. If the
304 top-level block member is not declared as an array, the value one is
305 written to <parameter>params</parameter>. If the top-level block member is an array with no
306 declared size, the value zero is written to <parameter>params</parameter>.
307
308 For the property <constant>GL_TOP_LEVEL_ARRAY_STRIDE</constant>, a single integer identifying the
309 stride between array elements of the top-level shader storage block member
310 containing the active variable is written to <parameter>params</parameter>. For top-level
311 block members declared as arrays, the value written is the difference, in
312 basic machine units, between the offsets of the active variable for
313 consecutive elements in the top-level array. For top-level block members
314 not declared as an array, zero is written to <parameter>params</parameter>.
315
316 For the property <constant>GL_LOCATION</constant>, a single integer identifying the assigned
317 location for an active uniform, input, output, or subroutine uniform
318 variable is written to <parameter>params</parameter>. For input, output, or uniform variables
319 with locations specified by a layout qualifier, the specified location is
320 used. For vertex shader input or fragment shader output variables without
321 a layout qualifier, the location assigned when a program is linked is
322 written to <parameter>params</parameter>. For all other input and output variables, the value
323 -1 is written to <parameter>params</parameter>. For uniforms in uniform blocks, the value -1
324 is written to <parameter>params</parameter>.
325
326 For the property <constant>GL_LOCATION_INDEX</constant>, a single integer identifying the fragment
327 color index of an active fragment shader output variable is written to
328 <parameter>params</parameter>. If the active variable is an output for a non-fragment shader,
329 the value -1 will be written to <parameter>params</parameter>.
330
331 For the property <constant>GL_IS_PER_PATCH</constant>, a single integer identifying whether the
332 input or output is a per-patch attribute. If the active variable is a
333 per-patch attribute (declared with the <code>patch</code> qualifier), the value one
334 is written to <parameter>params</parameter>; otherwise, the value zero is written to <parameter>params</parameter>.
335 </para>
336 </refsect1>
337 <refsect1 id="errors"><title>Errors</title>
338 <para>
339 <constant>GL_INVALID_VALUE</constant> is generated if <parameter>program</parameter> is
340 not the name of an existing program object.
341 </para>
342 <para>
343 <constant>GL_INVALID_VALUE</constant> is generated if <parameter>propCount</parameter> is
344 zero.
345 </para>
346 <para>
347 <constant>GL_INVALID_ENUM</constant> is generated if <parameter>programInterface</parameter>
348 is not one of the accepted interface types.
349 </para>
350 <para>
351 <constant>GL_INVLALID_ENUM</constant> is generated if any value in <parameter>props</parameter>
352 is not one of the accepted tokens for the interface <parameter>programInterface</parameter>
353 </para>
354 </refsect1>
355 <refsect1 id="seealso"><title>See Also</title>
356 <para>
357 <citerefentry><refentrytitle>glGetProgramResourceName</refentrytitle></citerefentry>,
358 <citerefentry><refentrytitle>glGetGetProgramResourceIndex</refentrytitle></citerefentry>,
359 <citerefentry><refentrytitle>glGetProgramResourceLocation</refentrytitle></citerefentry>,
360 <citerefentry><refentrytitle>glGetProgramResourceLocationIndex</refentrytitle></citerefentry>.
361 </para>
362 </refsect1>
363 <refsect1 id="Copyright"><title>Copyright</title>
364 <para>
365 Copyright <trademark class="copyright"></trademark> 2012 Khronos Group.
366 This material may be distributed subject to the terms and conditions set forth in
367 the Open Publication License, v 1.0, 8 June 1999.
368 <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
369 </para>
370 </refsect1>
371 </refentry>