1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
<!DOCTYPE refentry [ <!ENTITY % mathent SYSTEM "math.ent"> %mathent; ]>
<!-- Converted by db4-upgrade version 1.1 -->
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="glGetUniformLocation">
<info>
<copyright>
<year>2003-2005</year>
<holder>3Dlabs Inc. Ltd.</holder>
</copyright>
<copyright>
<year>2010-2014</year>
<holder>Khronos Group</holder>
</copyright>
</info>
<refmeta>
<refentrytitle>glGetUniformLocation</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glGetUniformLocation</refname>
<refpurpose>Returns the location of a uniform variable</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>GLint <function>glGetUniformLocation</function></funcdef>
<paramdef>GLuint <parameter>program</parameter></paramdef>
<paramdef>const GLchar *<parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>program</parameter></term>
<listitem>
<para>Specifies the program object to be
queried.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>name</parameter></term>
<listitem>
<para>Points to a null terminated string containing
the name of the uniform variable whose location is
to be queried.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="description"><title>Description</title>
<para><function>glGetUniformLocation </function> returns an
integer that represents the location of a specific uniform
variable within a program object. <parameter>name</parameter>
must be a null terminated string that contains no white space.
<parameter>name</parameter> must be an active uniform variable
name in <parameter>program</parameter> that is not a structure,
an array of structures, or a subcomponent of a vector or a
matrix. This function returns -1 if <parameter>name</parameter>
does not correspond to an active uniform variable in
<parameter>program</parameter>, if <parameter>name</parameter>
starts with the reserved prefix "gl_", or if
<parameter>name</parameter> is associated with an atomic counter or
a named uniform block.</para>
<para>Uniform variables that are structures or arrays of
structures may be queried by calling
<function>glGetUniformLocation</function> for each field within
the structure. The array element operator "[]" and the
structure field operator "." may be used in
<parameter>name</parameter> in order to select elements within
an array or fields within a structure. The result of using these
operators is not allowed to be another structure, an array of
structures, or a subcomponent of a vector or a matrix. Except if
the last part of <parameter>name</parameter> indicates a uniform
variable array, the location of the first element of an array
can be retrieved by using the name of the array, or by using the
name appended by "[0]".</para>
<para>The actual locations assigned to uniform variables are not
known until the program object is linked successfully. After
linking has occurred, the command
<function>glGetUniformLocation</function> can be used to obtain
the location of a uniform variable. This location value can then
be passed to
<citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>
to set the value of the uniform variable or to
<citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>
in order to query the current value of the uniform variable.
After a program object has been linked successfully, the index
values for uniform variables remain fixed until the next link
command occurs. Uniform variable locations and values can only
be queried after a link if the link was successful.</para>
</refsect1>
<refsect1 xml:id="errors"><title>Errors</title>
<para><constant>GL_INVALID_VALUE</constant> is generated if
<parameter>program</parameter> is not a value generated by
OpenGL.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>program</parameter> is not a program object.</para>
<para><constant>GL_INVALID_OPERATION</constant> is generated if
<parameter>program</parameter> has not been successfully
linked.</para>
</refsect1>
<refsect1 xml:id="associatedgets"><title>Associated Gets</title>
<para><citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>
with arguments <parameter>program</parameter> and the index of
an active uniform variable</para>
<para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
with arguments <parameter>program</parameter> and
<constant>GL_ACTIVE_UNIFORMS</constant> or
<constant>GL_ACTIVE_UNIFORM_MAX_LENGTH</constant></para>
<para><citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>
with arguments <parameter>program</parameter> and the name of a
uniform variable</para>
<para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 xml:id="versions"><title>Version Support</title>
<informaltable>
<tgroup cols="13" align="left">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apifunchead.xml" xpointer="xpointer(/*/*)"/>
<tbody>
<row>
<entry><function>glGetUniformLocation</function></entry>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='20']/*)"/>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 xml:id="seealso"><title>See Also</title>
<para><citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry></para>
</refsect1>
<refsect1 xml:id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"/> 2003-2005 3Dlabs Inc. Ltd.
Copyright <trademark class="copyright"/> 2010-2014 Khronos Group.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://opencontent.org/openpub/">http://opencontent.org/openpub/</link>.
</para>
</refsect1>
</refentry>
|
