Commit | Line | Data |
---|---|---|
7faf1d71 AW |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd"> |
2 | <!-- saved from url=(0013)about:internet --> | |
3 | <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glGetActiveUniform</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glGetActiveUniform"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glGetActiveUniform — Returns information about an active uniform variable for the specified program object</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glGetActiveUniform</b>(</code></td><td>GLuint </td><td><var class="pdparam">program</var>, </td></tr><tr><td> </td><td>GLuint </td><td><var class="pdparam">index</var>, </td></tr><tr><td> </td><td>GLsizei </td><td><var class="pdparam">bufSize</var>, </td></tr><tr><td> </td><td>GLsizei * </td><td><var class="pdparam">length</var>, </td></tr><tr><td> </td><td>GLint * </td><td><var class="pdparam">size</var>, </td></tr><tr><td> </td><td>GLenum * </td><td><var class="pdparam">type</var>, </td></tr><tr><td> </td><td>GLchar * </td><td><var class="pdparam">name</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>program</code></em></span></dt><dd><p>Specifies the program object to be | |
4 | queried.</p></dd><dt><span class="term"><em class="parameter"><code>index</code></em></span></dt><dd><p>Specifies the index of the uniform variable to | |
5 | be queried.</p></dd><dt><span class="term"><em class="parameter"><code>bufSize</code></em></span></dt><dd><p>Specifies the maximum number of characters | |
6 | OpenGL is allowed to write in the character buffer | |
7 | indicated by <em class="parameter"><code>name</code></em>.</p></dd><dt><span class="term"><em class="parameter"><code>length</code></em></span></dt><dd><p>Returns the number of characters actually | |
8 | written by OpenGL in the string indicated by | |
9 | <em class="parameter"><code>name</code></em> (excluding the null | |
10 | terminator) if a value other than | |
11 | <code class="constant">NULL</code> is passed.</p></dd><dt><span class="term"><em class="parameter"><code>size</code></em></span></dt><dd><p>Returns the size of the uniform | |
12 | variable.</p></dd><dt><span class="term"><em class="parameter"><code>type</code></em></span></dt><dd><p>Returns the data type of the uniform | |
13 | variable.</p></dd><dt><span class="term"><em class="parameter"><code>name</code></em></span></dt><dd><p>Returns a null terminated string containing | |
14 | the name of the uniform variable.</p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p><code class="function">glGetActiveUniform</code> returns | |
15 | information about an active uniform variable in the program | |
16 | object specified by <em class="parameter"><code>program</code></em>. The number | |
17 | of active uniform variables can be obtained by calling | |
18 | <a class="citerefentry" href="glGetProgram.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgram</span></span></a> | |
19 | with the value <code class="constant">GL_ACTIVE_UNIFORMS</code>. A value | |
20 | of 0 for <em class="parameter"><code>index</code></em> selects the first active | |
21 | uniform variable. Permissible values for | |
22 | <em class="parameter"><code>index</code></em> range from 0 to the number of | |
23 | active uniform variables minus 1.</p><p>Shaders may use either built-in uniform variables, | |
24 | user-defined uniform variables, or both. Built-in uniform | |
25 | variables have a prefix of "gl_" and reference | |
26 | existing OpenGL state or values derived from such state (e.g., | |
27 | <em class="parameter"><code>gl_Fog</code></em>, | |
28 | <em class="parameter"><code>gl_ModelViewMatrix</code></em>, etc., see the OpenGL | |
29 | Shading Language specification for a complete list.) | |
30 | User-defined uniform variables have arbitrary names and obtain | |
31 | their values from the application through calls to | |
32 | <a class="citerefentry" href="glUniform.xml"><span class="citerefentry"><span class="refentrytitle">glUniform</span></span></a>. | |
33 | A uniform variable (either built-in or user-defined) is | |
34 | considered active if it is determined during the link operation | |
35 | that it may be accessed during program execution. Therefore, | |
36 | <em class="parameter"><code>program</code></em> should have previously been the | |
37 | target of a call to | |
38 | <a class="citerefentry" href="glLinkProgram.xml"><span class="citerefentry"><span class="refentrytitle">glLinkProgram</span></span></a>, | |
39 | but it is not necessary for it to have been linked | |
40 | successfully.</p><p>The size of the character buffer required to store the | |
41 | longest uniform variable name in <em class="parameter"><code>program</code></em> | |
42 | can be obtained by calling | |
43 | <a class="citerefentry" href="glGetProgram.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgram</span></span></a> | |
44 | with the value | |
45 | <code class="constant">GL_ACTIVE_UNIFORM_MAX_LENGTH</code>. This value | |
46 | should be used to allocate a buffer of sufficient size to store | |
47 | the returned uniform variable name. The size of this character | |
48 | buffer is passed in <em class="parameter"><code>bufSize</code></em>, and a | |
49 | pointer to this character buffer is passed in | |
50 | <em class="parameter"><code>name.</code></em></p><p><code class="function">glGetActiveUniform</code> returns the name | |
51 | of the uniform variable indicated by | |
52 | <em class="parameter"><code>index</code></em>, storing it in the character buffer | |
53 | specified by <em class="parameter"><code>name</code></em>. The string returned | |
54 | will be null terminated. The actual number of characters written | |
55 | into this buffer is returned in <em class="parameter"><code>length</code></em>, | |
56 | and this count does not include the null termination character. | |
57 | If the length of the returned string is not required, a value of | |
58 | <code class="constant">NULL</code> can be passed in the | |
59 | <em class="parameter"><code>length</code></em> argument.</p><p>The <em class="parameter"><code>type</code></em> | |
60 | argument will return a pointer to the uniform variable's data | |
61 | type. The symbolic constants | |
62 | <code class="constant">GL_FLOAT</code>, | |
63 | <code class="constant">GL_FLOAT_VEC2</code>, | |
64 | <code class="constant">GL_FLOAT_VEC3</code>, | |
65 | <code class="constant">GL_FLOAT_VEC4</code>, | |
66 | <code class="constant">GL_INT</code>, | |
67 | <code class="constant">GL_INT_VEC2</code>, | |
68 | <code class="constant">GL_INT_VEC3</code>, | |
69 | <code class="constant">GL_INT_VEC4</code>, | |
70 | <code class="constant">GL_BOOL</code>, | |
71 | <code class="constant">GL_BOOL_VEC2</code>, | |
72 | <code class="constant">GL_BOOL_VEC3</code>, | |
73 | <code class="constant">GL_BOOL_VEC4</code>, | |
74 | <code class="constant">GL_FLOAT_MAT2</code>, | |
75 | <code class="constant">GL_FLOAT_MAT3</code>, | |
76 | <code class="constant">GL_FLOAT_MAT4</code>, | |
77 | <code class="constant">GL_FLOAT_MAT2x3</code>, | |
78 | <code class="constant">GL_FLOAT_MAT2x4</code>, | |
79 | <code class="constant">GL_FLOAT_MAT3x2</code>, | |
80 | <code class="constant">GL_FLOAT_MAT3x4</code>, | |
81 | <code class="constant">GL_FLOAT_MAT4x2</code>, | |
82 | <code class="constant">GL_FLOAT_MAT4x3</code>, | |
83 | <code class="constant">GL_SAMPLER_1D</code>, | |
84 | <code class="constant">GL_SAMPLER_2D</code>, | |
85 | <code class="constant">GL_SAMPLER_3D</code>, | |
86 | <code class="constant">GL_SAMPLER_CUBE</code>, | |
87 | <code class="constant">GL_SAMPLER_1D_SHADOW</code>, or | |
88 | <code class="constant">GL_SAMPLER_2D_SHADOW</code> | |
89 | may be returned.</p><p>If one or more elements of an array are active, the name | |
90 | of the array is returned in <em class="parameter"><code>name</code></em>, the | |
91 | type is returned in <em class="parameter"><code>type</code></em>, and the | |
92 | <em class="parameter"><code>size</code></em> parameter returns the highest array | |
93 | element index used, plus one, as determined by the compiler | |
94 | and/or linker. Only one active uniform variable will be reported | |
95 | for a uniform array.</p><p>Uniform variables that are declared as structures or | |
96 | arrays of structures will not be returned directly by this | |
97 | function. Instead, each of these uniform variables will be | |
98 | reduced to its fundamental components containing the | |
99 | "." and "[]" operators such that each of the | |
100 | names is valid as an argument to | |
101 | <a class="citerefentry" href="glGetUniformLocation.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniformLocation</span></span></a>. | |
102 | Each of these reduced uniform variables is counted as one active | |
103 | uniform variable and is assigned an index. A valid name cannot | |
104 | be a structure, an array of structures, or a subcomponent of a | |
105 | vector or matrix.</p><p>The size of the uniform variable will be returned in | |
106 | <em class="parameter"><code>size</code></em>. Uniform variables other than arrays | |
107 | will have a size of 1. Structures and arrays of structures will | |
108 | be reduced as described earlier, such that each of the names | |
109 | returned will be a data type in the earlier list. If this | |
110 | reduction results in an array, the size returned will be as | |
111 | described for uniform arrays; otherwise, the size returned will | |
112 | be 1.</p><p>The list of active uniform variables may include both | |
113 | built-in uniform variables (which begin with the prefix | |
114 | "gl_") as well as user-defined uniform variable | |
115 | names.</p><p>This function will return as much information as it can | |
116 | about the specified active uniform variable. If no information | |
117 | is available, <em class="parameter"><code>length</code></em> will be 0, and | |
118 | <em class="parameter"><code>name</code></em> will be an empty string. This | |
119 | situation could occur if this function is called after a link | |
120 | operation that failed. If an error occurs, the return values | |
121 | <em class="parameter"><code>length</code></em>, <em class="parameter"><code>size</code></em>, | |
122 | <em class="parameter"><code>type</code></em>, and <em class="parameter"><code>name</code></em> | |
123 | will be unmodified.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p><code class="function">glGetActiveUniform</code> is available only | |
124 | if the GL version is 2.0 or greater.</p><p><code class="constant">GL_FLOAT_MAT2x3</code>, | |
125 | <code class="constant">GL_FLOAT_MAT2x4</code>, | |
126 | <code class="constant">GL_FLOAT_MAT3x2</code>, | |
127 | <code class="constant">GL_FLOAT_MAT3x4</code>, | |
128 | <code class="constant">GL_FLOAT_MAT4x2</code>, and | |
129 | <code class="constant">GL_FLOAT_MAT4x3</code> | |
130 | will only be returned as a <em class="parameter"><code>type</code></em> | |
131 | if the GL version is 2.1 or greater.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p><code class="constant">GL_INVALID_VALUE</code> is generated if | |
132 | <em class="parameter"><code>program</code></em> is not a value generated by | |
133 | OpenGL.</p><p><code class="constant">GL_INVALID_OPERATION</code> is generated if | |
134 | <em class="parameter"><code>program</code></em> is not a program object.</p><p><code class="constant">GL_INVALID_VALUE</code> is generated if | |
135 | <em class="parameter"><code>index</code></em> is greater than or equal to the | |
136 | number of active uniform variables in | |
137 | <em class="parameter"><code>program</code></em>.</p><p><code class="constant">GL_INVALID_OPERATION</code> is generated if | |
138 | <code class="function">glGetActiveUniform</code> is executed between the | |
139 | execution of | |
140 | <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a> | |
141 | and the corresponding execution of | |
142 | <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.</p><p><code class="constant">GL_INVALID_VALUE</code> is generated if | |
143 | <em class="parameter"><code>bufSize</code></em> is less than 0.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p><a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> | |
144 | with argument <code class="constant">GL_MAX_VERTEX_UNIFORM_COMPONENTS | |
145 | </code> or | |
146 | <code class="constant">GL_MAX_FRAGMENT_UNIFORM_COMPONENTS</code>.</p><p><a class="citerefentry" href="glGetProgram.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgram</span></span></a> | |
147 | with argument <code class="constant">GL_ACTIVE_UNIFORMS</code> or | |
148 | <code class="constant">GL_ACTIVE_UNIFORM_MAX_LENGTH</code>.</p><p><a class="citerefentry" href="glIsProgram.xml"><span class="citerefentry"><span class="refentrytitle">glIsProgram</span></span></a></p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p><a class="citerefentry" href="glGetUniform.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniform</span></span></a>, | |
149 | <a class="citerefentry" href="glGetUniformLocation.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniformLocation</span></span></a>, | |
150 | <a class="citerefentry" href="glLinkProgram.xml"><span class="citerefentry"><span class="refentrytitle">glLinkProgram</span></span></a>, | |
151 | <a class="citerefentry" href="glUniform.xml"><span class="citerefentry"><span class="refentrytitle">glUniform</span></span></a>, | |
152 | <a class="citerefentry" href="glUseProgram.xml"><span class="citerefentry"><span class="refentrytitle">glUseProgram</span></span></a></p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p> | |
153 | Copyright <span class="trademark"></span>© 2003-2005 3Dlabs Inc. Ltd. | |
154 | This material may be distributed subject to the terms and conditions set forth in | |
155 | the Open Publication License, v 1.0, 8 June 1999. | |
156 | <a class="ulink" href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>. | |
157 | </p></div></div></body></html> |