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=
"glGetLight">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glGetLight
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glGetLight
</refname>
17 <refpurpose>return light source parameter values
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glGetLightfv
</function></funcdef>
23 <paramdef>GLenum
<parameter>light
</parameter></paramdef>
24 <paramdef>GLenum
<parameter>pname
</parameter></paramdef>
25 <paramdef>GLfloat *
<parameter>params
</parameter></paramdef>
30 <funcdef>void
<function>glGetLightiv
</function></funcdef>
31 <paramdef>GLenum
<parameter>light
</parameter></paramdef>
32 <paramdef>GLenum
<parameter>pname
</parameter></paramdef>
33 <paramdef>GLint *
<parameter>params
</parameter></paramdef>
37 <!-- eqn: ignoring delim $$ -->
38 <refsect1 id=
"parameters"><title>Parameters
</title>
41 <term><parameter>light
</parameter></term>
44 Specifies a light source.
45 The number of possible lights depends on the implementation,
46 but at least eight lights are supported.
47 They are identified by symbolic names of the form
<constant>GL_LIGHT
</constant>
48 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>
50 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>
51 ranges from
0 to the value of
<constant>GL_MAX_LIGHTS
</constant> -
1.
56 <term><parameter>pname
</parameter></term>
59 Specifies a light source parameter for
<parameter>light
</parameter>.
60 Accepted symbolic names are
61 <constant>GL_AMBIENT
</constant>,
62 <constant>GL_DIFFUSE
</constant>,
63 <constant>GL_SPECULAR
</constant>,
64 <constant>GL_POSITION
</constant>,
65 <constant>GL_SPOT_DIRECTION
</constant>,
66 <constant>GL_SPOT_EXPONENT
</constant>,
67 <constant>GL_SPOT_CUTOFF
</constant>,
68 <constant>GL_CONSTANT_ATTENUATION
</constant>,
69 <constant>GL_LINEAR_ATTENUATION
</constant>, and
70 <constant>GL_QUADRATIC_ATTENUATION
</constant>.
75 <term><parameter>params
</parameter></term>
78 Returns the requested data.
84 <refsect1 id=
"description"><title>Description
</title>
86 <function>glGetLight
</function> returns in
<parameter>params
</parameter> the value or values of a light source parameter.
87 <parameter>light
</parameter> names the light and is a symbolic name of the form
<constant>GL_LIGHT
</constant>
88 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>
89 where i ranges from
0 to the value of
<constant>GL_MAX_LIGHTS
</constant> -
1.
90 <constant>GL_MAX_LIGHTS
</constant> is an implementation dependent constant that is
91 greater than or equal to eight.
92 <parameter>pname
</parameter> specifies one of ten light source parameters,
93 again by symbolic name.
96 The following parameters are defined:
100 <term><constant>GL_AMBIENT
</constant></term>
103 <parameter>params
</parameter> returns four integer or floating-point values representing the
104 ambient intensity of the light source.
107 are linearly mapped from the internal floating-point representation
108 such that
1.0 maps to the most positive representable integer value,
110 <inlineequation><mml:math>
112 <mml:mn>-
1.0</mml:mn>
113 </mml:math></inlineequation>
114 maps to the most negative representable integer value.
115 If the internal value is outside the range
116 <inlineequation><mml:math>
118 <mml:mfenced open=
"[" close=
"]">
122 </mml:math></inlineequation>,
123 the corresponding integer return value is undefined. The initial value is
129 <term><constant>GL_DIFFUSE
</constant></term>
132 <parameter>params
</parameter> returns four integer or floating-point values representing the
133 diffuse intensity of the light source.
136 are linearly mapped from the internal floating-point representation
137 such that
1.0 maps to the most positive representable integer value,
139 <inlineequation><mml:math>
141 <mml:mn>-
1.0</mml:mn>
142 </mml:math></inlineequation>
143 maps to the most negative representable integer value.
144 If the internal value is outside the range
145 <inlineequation><mml:math>
147 <mml:mfenced open=
"[" close=
"]">
151 </mml:math></inlineequation>,
152 the corresponding integer return value is undefined. The initial value
153 for
<constant>GL_LIGHT0
</constant> is (
1,
1,
1,
1); for other lights, the
154 initial value is (
0,
0,
0,
0).
159 <term><constant>GL_SPECULAR
</constant></term>
162 <parameter>params
</parameter> returns four integer or floating-point values representing the
163 specular intensity of the light source.
166 are linearly mapped from the internal floating-point representation
167 such that
1.0 maps to the most positive representable integer value,
169 <inlineequation><mml:math>
171 <mml:mn>-
1.0</mml:mn>
172 </mml:math></inlineequation>
173 maps to the most negative representable integer value.
174 If the internal value is outside the range
175 <inlineequation><mml:math>
177 <mml:mfenced open=
"[" close=
"]">
181 </mml:math></inlineequation>,
182 the corresponding integer return value is undefined. The initial value
183 for
<constant>GL_LIGHT0
</constant> is (
1,
1,
1,
1); for other lights, the
184 initial value is (
0,
0,
0,
0).
189 <term><constant>GL_POSITION
</constant></term>
192 <parameter>params
</parameter> returns four integer or floating-point values representing the
193 position of the light source.
196 are computed by rounding the internal floating-point values to the
197 nearest integer value.
198 The returned values are those maintained in eye coordinates.
199 They will not be equal to the values specified using
<citerefentry><refentrytitle>glLight
</refentrytitle></citerefentry>,
200 unless the modelview matrix was identity at the time
<citerefentry><refentrytitle>glLight
</refentrytitle></citerefentry> was
201 called. The initial value is (
0,
0,
1,
0).
206 <term><constant>GL_SPOT_DIRECTION
</constant></term>
209 <parameter>params
</parameter> returns three integer or floating-point values representing the
210 direction of the light source.
213 are computed by rounding the internal floating-point values to the
214 nearest integer value.
215 The returned values are those maintained in eye coordinates.
216 They will not be equal to the values specified using
<citerefentry><refentrytitle>glLight
</refentrytitle></citerefentry>,
217 unless the modelview matrix was identity at the time
<citerefentry><refentrytitle>glLight
</refentrytitle></citerefentry> was called.
218 Although spot direction is normalized before being used in the lighting
220 the returned values are the transformed versions of the specified values
221 prior to normalization. The initial value is
222 <inlineequation><mml:math>
223 <!-- eqn: (0, 0, -1):-->
224 <mml:mfenced open=
"(" close=
")">
229 </mml:math></inlineequation>.
234 <term><constant>GL_SPOT_EXPONENT
</constant></term>
237 <parameter>params
</parameter> returns a single integer or floating-point value representing the
238 spot exponent of the light.
241 is computed by rounding the internal floating-point representation to
242 the nearest integer. The initial value is
0.
247 <term><constant>GL_SPOT_CUTOFF
</constant></term>
250 <parameter>params
</parameter> returns a single integer or floating-point value representing the
251 spot cutoff angle of the light.
254 is computed by rounding the internal floating-point representation to
255 the nearest integer. The initial value is
180.
260 <term><constant>GL_CONSTANT_ATTENUATION
</constant></term>
263 <parameter>params
</parameter> returns a single integer or floating-point value representing the
264 constant (not distance-related) attenuation of the light.
267 is computed by rounding the internal floating-point representation to
268 the nearest integer. The initial value is
1.
273 <term><constant>GL_LINEAR_ATTENUATION
</constant></term>
276 <parameter>params
</parameter> returns a single integer or floating-point value representing the
277 linear attenuation of the light.
280 is computed by rounding the internal floating-point representation to
281 the nearest integer. The initial value is
0.
286 <term><constant>GL_QUADRATIC_ATTENUATION
</constant></term>
289 <parameter>params
</parameter> returns a single integer or floating-point value representing the
290 quadratic attenuation of the light.
293 is computed by rounding the internal floating-point representation to
294 the nearest integer. The initial value is
0.
300 <refsect1 id=
"notes"><title>Notes
</title>
302 It is always the case that
<constant>GL_LIGHT
</constant>
303 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>
304 =
<constant>GL_LIGHT0
</constant> +
305 <inlineequation><mml:math><mml:mi mathvariant=
"italic">i
</mml:mi></mml:math></inlineequation>.
308 If an error is generated,
309 no change is made to the contents of
<parameter>params
</parameter>.
312 <refsect1 id=
"errors"><title>Errors
</title>
314 <constant>GL_INVALID_ENUM
</constant> is generated if
<parameter>light
</parameter> or
<parameter>pname
</parameter> is not an
318 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glGetLight
</function>
319 is executed between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry>
320 and the corresponding execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
323 <refsect1 id=
"seealso"><title>See Also
</title>
325 <citerefentry><refentrytitle>glLight
</refentrytitle></citerefentry>
328 <refsect1 id=
"Copyright"><title>Copyright
</title>
330 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
331 Silicon Graphics, Inc. This document is licensed under the SGI
332 Free Software B License. For details, see
333 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.