upstream-man-pages/man2/xhtml/glGetLight.xml

   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>glGetLight</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glGetLight"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glGetLight — return light source parameter values</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">glGetLightfv</b>(</code></td><td>GLenum  </td><td><var class="pdparam">light</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">pname</var>, </td></tr><tr><td> </td><td>GLfloat *  </td><td><var class="pdparam">params</var><code>)</code>;</td></tr></table></div><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glGetLightiv</b>(</code></td><td>GLenum  </td><td><var class="pdparam">light</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">pname</var>, </td></tr><tr><td> </td><td>GLint *  </td><td><var class="pdparam">params</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>light</code></em></span></dt><dd><p>
   4                     Specifies a light source.
   5                     The number of possible lights depends on the implementation,
   6                     but at least eight lights are supported.
   7                     They are identified by symbolic names of the form <code class="constant">GL_LIGHT</code>
   8                     <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>
   9                     where
  10                     <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>
  11                     ranges from 0 to the value of <code class="constant">GL_MAX_LIGHTS</code> - 1.
  12                 </p></dd><dt><span class="term"><em class="parameter"><code>pname</code></em></span></dt><dd><p>
  13                     Specifies a light source parameter for <em class="parameter"><code>light</code></em>.
  14                     Accepted symbolic names are
  15                     <code class="constant">GL_AMBIENT</code>,
  16                     <code class="constant">GL_DIFFUSE</code>,
  17                     <code class="constant">GL_SPECULAR</code>,
  18                     <code class="constant">GL_POSITION</code>,
  19                     <code class="constant">GL_SPOT_DIRECTION</code>,
  20                     <code class="constant">GL_SPOT_EXPONENT</code>,
  21                     <code class="constant">GL_SPOT_CUTOFF</code>,
  22                     <code class="constant">GL_CONSTANT_ATTENUATION</code>,
  23                     <code class="constant">GL_LINEAR_ATTENUATION</code>, and
  24                     <code class="constant">GL_QUADRATIC_ATTENUATION</code>.
  25                 </p></dd><dt><span class="term"><em class="parameter"><code>params</code></em></span></dt><dd><p>
  26                     Returns the requested data.
  27                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  28             <code class="function">glGetLight</code> returns in <em class="parameter"><code>params</code></em> the value or values of a light source parameter.
  29             <em class="parameter"><code>light</code></em> names the light and is a symbolic name of the form <code class="constant">GL_LIGHT</code>
  30             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>
  31             where i ranges from 0 to the value of <code class="constant">GL_MAX_LIGHTS</code> - 1.
  32             <code class="constant">GL_MAX_LIGHTS</code> is an implementation dependent constant that is
  33             greater than or equal to eight.
  34             <em class="parameter"><code>pname</code></em> specifies one of ten light source parameters,
  35             again by symbolic name.
  36         </p><p>
  37             The following parameters are defined:
  38         </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GL_AMBIENT</code></span></dt><dd><p>
  39                         <em class="parameter"><code>params</code></em> returns four integer or floating-point values representing the
  40                         ambient intensity of the light source.
  41                         Integer values,
  42                         when requested,
  43                         are linearly mapped from the internal floating-point representation
  44                         such that 1.0 maps to the most positive representable integer value,
  45                         and
  46                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  47
  48                             <mml:mn>-1.0</mml:mn>
  49                         </mml:math>
  50                         maps to the most negative representable integer value.
  51                         If the internal value is outside the range
  52                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  53
  54                             <mml:mfenced open="[" close="]">
  55                                 <mml:mn>-1</mml:mn>
  56                                 <mml:mn>1</mml:mn>
  57                             </mml:mfenced>
  58                         </mml:math>,
  59                         the corresponding integer return value is undefined. The initial value is
  60                         (0, 0, 0, 1).
  61                     </p></dd><dt><span class="term"><code class="constant">GL_DIFFUSE</code></span></dt><dd><p>
  62                         <em class="parameter"><code>params</code></em> returns four integer or floating-point values representing the
  63                         diffuse intensity of the light source.
  64                         Integer values,
  65                         when requested,
  66                         are linearly mapped from the internal floating-point representation
  67                         such that 1.0 maps to the most positive representable integer value,
  68                         and
  69                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  70
  71                             <mml:mn>-1.0</mml:mn>
  72                         </mml:math>
  73                         maps to the most negative representable integer value.
  74                         If the internal value is outside the range
  75                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  76
  77                             <mml:mfenced open="[" close="]">
  78                                 <mml:mn>-1</mml:mn>
  79                                 <mml:mn>1</mml:mn>
  80                             </mml:mfenced>
  81                         </mml:math>,
  82                         the corresponding integer return value is undefined. The initial value
  83                         for <code class="constant">GL_LIGHT0</code> is (1, 1, 1, 1); for other lights, the
  84                         initial value is (0, 0, 0, 0).
  85                     </p></dd><dt><span class="term"><code class="constant">GL_SPECULAR</code></span></dt><dd><p>
  86                         <em class="parameter"><code>params</code></em> returns four integer or floating-point values representing the
  87                         specular intensity of the light source.
  88                         Integer values,
  89                         when requested,
  90                         are linearly mapped from the internal floating-point representation
  91                         such that 1.0 maps to the most positive representable integer value,
  92                         and
  93                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  94
  95                             <mml:mn>-1.0</mml:mn>
  96                         </mml:math>
  97                         maps to the most negative representable integer value.
  98                         If the internal value is outside the range
  99                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 100
 101                             <mml:mfenced open="[" close="]">
 102                                 <mml:mn>-1</mml:mn>
 103                                 <mml:mn>1</mml:mn>
 104                             </mml:mfenced>
 105                         </mml:math>,
 106                         the corresponding integer return value is undefined. The initial value
 107                         for <code class="constant">GL_LIGHT0</code> is (1, 1, 1, 1); for other lights, the
 108                         initial value is (0, 0, 0, 0).
 109                     </p></dd><dt><span class="term"><code class="constant">GL_POSITION</code></span></dt><dd><p>
 110                         <em class="parameter"><code>params</code></em> returns four integer or floating-point values representing the
 111                         position of the light source.
 112                         Integer values,
 113                         when requested,
 114                         are computed by rounding the internal floating-point values to the
 115                         nearest integer value.
 116                         The returned values are those maintained in eye coordinates.
 117                         They will not be equal to the values specified using <a class="citerefentry" href="glLight.xml"><span class="citerefentry"><span class="refentrytitle">glLight</span></span></a>,
 118                         unless the modelview matrix was identity at the time <a class="citerefentry" href="glLight.xml"><span class="citerefentry"><span class="refentrytitle">glLight</span></span></a> was
 119                         called. The initial value is (0, 0, 1, 0).
 120                     </p></dd><dt><span class="term"><code class="constant">GL_SPOT_DIRECTION</code></span></dt><dd><p>
 121                         <em class="parameter"><code>params</code></em> returns three integer or floating-point values representing the
 122                         direction of the light source.
 123                         Integer values,
 124                         when requested,
 125                         are computed by rounding the internal floating-point values to the
 126                         nearest integer value.
 127                         The returned values are those maintained in eye coordinates.
 128                         They will not be equal to the values specified using <a class="citerefentry" href="glLight.xml"><span class="citerefentry"><span class="refentrytitle">glLight</span></span></a>,
 129                         unless the modelview matrix was identity at the time <a class="citerefentry" href="glLight.xml"><span class="citerefentry"><span class="refentrytitle">glLight</span></span></a> was called.
 130                         Although spot direction is normalized before being used in the lighting
 131                         equation,
 132                         the returned values are the transformed versions of the specified values
 133                         prior to normalization. The initial value is
 134                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 135
 136                             <mml:mfenced open="(" close=")">
 137                                 <mml:mn>0</mml:mn>
 138                                 <mml:mn>0</mml:mn>
 139                                 <mml:mn>-1</mml:mn>
 140                             </mml:mfenced>
 141                         </mml:math>.
 142                     </p></dd><dt><span class="term"><code class="constant">GL_SPOT_EXPONENT</code></span></dt><dd><p>
 143                         <em class="parameter"><code>params</code></em> returns a single integer or floating-point value representing the
 144                         spot exponent of the light.
 145                         An integer value,
 146                         when requested,
 147                         is computed by rounding the internal floating-point representation to
 148                         the nearest integer. The initial value is 0.
 149                     </p></dd><dt><span class="term"><code class="constant">GL_SPOT_CUTOFF</code></span></dt><dd><p>
 150                         <em class="parameter"><code>params</code></em> returns a single integer or floating-point value representing the
 151                         spot cutoff angle of the light.
 152                         An integer value,
 153                         when requested,
 154                         is computed by rounding the internal floating-point representation to
 155                         the nearest integer. The initial value is 180.
 156                     </p></dd><dt><span class="term"><code class="constant">GL_CONSTANT_ATTENUATION</code></span></dt><dd><p>
 157                         <em class="parameter"><code>params</code></em> returns a single integer or floating-point value representing the
 158                         constant (not distance-related) attenuation of the light.
 159                         An integer value,
 160                         when requested,
 161                         is computed by rounding the internal floating-point representation to
 162                         the nearest integer. The initial value is 1.
 163                     </p></dd><dt><span class="term"><code class="constant">GL_LINEAR_ATTENUATION</code></span></dt><dd><p>
 164                         <em class="parameter"><code>params</code></em> returns a single integer or floating-point value representing the
 165                         linear attenuation of the light.
 166                         An integer value,
 167                         when requested,
 168                         is computed by rounding the internal floating-point representation to
 169                         the nearest integer. The initial value is 0.
 170                     </p></dd><dt><span class="term"><code class="constant">GL_QUADRATIC_ATTENUATION</code></span></dt><dd><p>
 171                         <em class="parameter"><code>params</code></em> returns a single integer or floating-point value representing the
 172                         quadratic attenuation of the light.
 173                         An integer value,
 174                         when requested,
 175                         is computed by rounding the internal floating-point representation to
 176                         the nearest integer. The initial value is 0.
 177                     </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 178             It is always the case that <code class="constant">GL_LIGHT</code>
 179             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>
 180             = <code class="constant">GL_LIGHT0</code> +
 181             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>.
 182         </p><p>
 183             If an error is generated,
 184             no change is made to the contents of <em class="parameter"><code>params</code></em>.
 185         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 186             <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>light</code></em> or <em class="parameter"><code>pname</code></em> is not an
 187             accepted value.
 188         </p><p>
 189             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glGetLight</code>
 190             is executed between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
 191             and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 192         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 193             <a class="citerefentry" href="glLight.xml"><span class="citerefentry"><span class="refentrytitle">glLight</span></span></a>
 194         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 195             Copyright <span class="trademark"></span>© 1991-2006
 196             Silicon Graphics, Inc. This document is licensed under the SGI
 197             Free Software B License. For details, see
 198             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 199         </p></div></div></body></html>