upstream-doc/man2/xhtml/glLight.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>glLight</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glLight"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glLight — set light source parameters</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">glLightf</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">param</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">glLighti</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">param</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.
   5                     The number of 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 i ranges from 0 to the value of <code class="constant">GL_MAX_LIGHTS</code> - 1.
  10                 </p></dd><dt><span class="term"><em class="parameter"><code>pname</code></em></span></dt><dd><p>
  11                     Specifies a single-valued light source parameter for <em class="parameter"><code>light</code></em>.
  12                     <code class="constant">GL_SPOT_EXPONENT</code>,
  13                     <code class="constant">GL_SPOT_CUTOFF</code>,
  14                     <code class="constant">GL_CONSTANT_ATTENUATION</code>,
  15                     <code class="constant">GL_LINEAR_ATTENUATION</code>, and
  16                     <code class="constant">GL_QUADRATIC_ATTENUATION</code> are accepted.
  17                 </p></dd><dt><span class="term"><em class="parameter"><code>param</code></em></span></dt><dd><p>
  18                     Specifies the value that parameter <em class="parameter"><code>pname</code></em> of light source <em class="parameter"><code>light</code></em>
  19                     will be set to.
  20                 </p></dd></dl></div></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">glLightfv</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>const 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">glLightiv</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>const 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="parameters2"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>light</code></em></span></dt><dd><p>
  21                     Specifies a light.
  22                     The number of lights depends on the implementation, but
  23                     at least eight lights are supported.
  24                     They are identified by symbolic names of the form <code class="constant">GL_LIGHT</code>
  25                     <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>,
  26                     where i ranges from 0 to the value of <code class="constant">GL_MAX_LIGHTS</code> - 1.
  27                 </p></dd><dt><span class="term"><em class="parameter"><code>pname</code></em></span></dt><dd><p>
  28                     Specifies a light source parameter for <em class="parameter"><code>light</code></em>.
  29                     <code class="constant">GL_AMBIENT</code>,
  30                     <code class="constant">GL_DIFFUSE</code>,
  31                     <code class="constant">GL_SPECULAR</code>,
  32                     <code class="constant">GL_POSITION</code>,
  33                     <code class="constant">GL_SPOT_CUTOFF</code>,
  34                     <code class="constant">GL_SPOT_DIRECTION</code>,
  35                     <code class="constant">GL_SPOT_EXPONENT</code>,
  36                     <code class="constant">GL_CONSTANT_ATTENUATION</code>,
  37                     <code class="constant">GL_LINEAR_ATTENUATION</code>, and
  38                     <code class="constant">GL_QUADRATIC_ATTENUATION</code> are accepted.
  39                 </p></dd><dt><span class="term"><em class="parameter"><code>params</code></em></span></dt><dd><p>
  40                     Specifies a pointer to the value or values that parameter <em class="parameter"><code>pname</code></em>
  41                     of light source <em class="parameter"><code>light</code></em> will be set to.
  42                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  43             <code class="function">glLight</code> sets the values of individual light source parameters.
  44             <em class="parameter"><code>light</code></em> names the light and is a symbolic name of the form <code class="constant">GL_LIGHT</code>
  45             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>,
  46             where i ranges from 0 to the value of <code class="constant">GL_MAX_LIGHTS</code> - 1.
  47             <em class="parameter"><code>pname</code></em> specifies one of ten light source parameters,
  48             again by symbolic name.
  49             <em class="parameter"><code>params</code></em> is either a single value or a pointer to an array that contains
  50             the new values.
  51         </p><p>
  52             To enable and disable lighting calculation, call <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a>
  53             and <a class="citerefentry" href="glDisable.xml"><span class="citerefentry"><span class="refentrytitle">glDisable</span></span></a> with argument <code class="constant">GL_LIGHTING</code>. Lighting is
  54             initially disabled.
  55             When it is enabled,
  56             light sources that are enabled contribute to the lighting calculation.
  57             Light source
  58             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>
  59             is enabled and disabled using <a class="citerefentry" href="glEnable.xml"><span class="citerefentry"><span class="refentrytitle">glEnable</span></span></a> and
  60             <a class="citerefentry" href="glDisable.xml"><span class="citerefentry"><span class="refentrytitle">glDisable</span></span></a> with argument <code class="constant">GL_LIGHT</code>
  61             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>.
  62         </p><p>
  63             The ten light parameters are as follows:
  64         </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GL_AMBIENT</code></span></dt><dd><p>
  65                         <em class="parameter"><code>params</code></em> contains four integer or floating-point values that specify
  66                         the ambient RGBA intensity of the light.
  67                         Integer values are mapped linearly such that the most positive representable
  68                         value maps to 1.0,
  69                         and the most negative representable value maps to
  70                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  71
  72                             <mml:mn>-1.0</mml:mn>
  73                         </mml:math>.
  74                         Floating-point values are mapped directly.
  75                         Neither integer nor floating-point values are clamped.
  76                         The initial ambient light intensity is (0, 0, 0, 1).
  77                     </p></dd><dt><span class="term"><code class="constant">GL_DIFFUSE</code></span></dt><dd><p>
  78                         <em class="parameter"><code>params</code></em> contains four integer or floating-point values that specify
  79                         the diffuse RGBA intensity of the light.
  80                         Integer values are mapped linearly such that the most positive representable
  81                         value maps to 1.0,
  82                         and the most negative representable value maps to
  83                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  84
  85                             <mml:mn>-1.0</mml:mn>
  86                         </mml:math>.
  87                         Floating-point values are mapped directly.
  88                         Neither integer nor floating-point values are clamped.
  89                         The initial value
  90                         for <code class="constant">GL_LIGHT0</code> is (1, 1, 1, 1); for other lights, the
  91                         initial value is (0, 0, 0, 1).
  92                     </p></dd><dt><span class="term"><code class="constant">GL_SPECULAR</code></span></dt><dd><p>
  93                         <em class="parameter"><code>params</code></em> contains four integer or floating-point values that specify
  94                         the specular RGBA intensity of the light.
  95                         Integer values are mapped linearly such that the most positive representable
  96                         value maps to 1.0,
  97                         and the most negative representable value maps to
  98                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
  99
 100                             <mml:mn>-1.0</mml:mn>
 101                         </mml:math>.
 102                         Floating-point values are mapped directly.
 103                         Neither integer nor floating-point values are clamped.
 104                         The initial value
 105                         for <code class="constant">GL_LIGHT0</code> is (1, 1, 1, 1); for other lights, the
 106                         initial value is (0, 0, 0, 1).
 107                     </p></dd><dt><span class="term"><code class="constant">GL_POSITION</code></span></dt><dd><p>
 108                         <em class="parameter"><code>params</code></em> contains four integer or floating-point values that specify
 109                         the position of the light in homogeneous object coordinates.
 110                         Both integer and floating-point values are mapped directly.
 111                         Neither integer nor floating-point values are clamped.
 112                     </p><p>
 113                         The position is transformed by the modelview matrix when
 114                         <code class="function">glLight</code> is called (just as if it were a point),
 115                         and it is stored in eye coordinates.
 116                         If the
 117                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">w</mml:mi></mml:math>
 118                         component of the position is 0,
 119                         the light is treated as a directional source.
 120                         Diffuse and specular lighting calculations take the light's direction,
 121                         but not its actual position,
 122                         into account,
 123                         and attenuation is disabled.
 124                         Otherwise,
 125                         diffuse and specular lighting calculations are based on the actual location
 126                         of the light in eye coordinates,
 127                         and attenuation is enabled.
 128                         The initial position is (0, 0, 1, 0);
 129                         thus, the initial light source is directional,
 130                         parallel to, and in the direction of the
 131                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 132
 133                             <mml:mrow>
 134                                 <mml:mo>-</mml:mo>
 135                                 <mml:mi mathvariant="italic">z</mml:mi>
 136                             </mml:mrow>
 137                         </mml:math>
 138                         axis.
 139                     </p></dd><dt><span class="term"><code class="constant">GL_SPOT_DIRECTION</code></span></dt><dd><p>
 140                         <em class="parameter"><code>params</code></em> contains three integer or floating-point values that specify
 141                         the direction of the light in homogeneous object coordinates.
 142                         Both integer and floating-point values are mapped directly.
 143                         Neither integer nor floating-point values are clamped.
 144                     </p><p>
 145                         The spot direction is transformed by the upper 3x3 of the modelview matrix when
 146                         <code class="function">glLight</code> is called,
 147                         and it is stored in eye coordinates.
 148                         It is significant only when <code class="constant">GL_SPOT_CUTOFF</code> is not 180,
 149                         which it is initially.
 150                         The initial direction is
 151                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 152
 153                             <mml:mfenced open="(" close=")">
 154                                 <mml:mn>0</mml:mn>
 155                                 <mml:mn>0</mml:mn>
 156                                 <mml:mn>-1</mml:mn>
 157                             </mml:mfenced>
 158                         </mml:math>.
 159                     </p></dd><dt><span class="term"><code class="constant">GL_SPOT_EXPONENT</code></span></dt><dd><p>
 160                         <em class="parameter"><code>params</code></em> is a single integer or floating-point value that specifies
 161                         the intensity distribution of the light.
 162                         Integer and floating-point values are mapped directly.
 163                         Only values in the range
 164                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 165
 166                             <mml:mfenced open="[" close="]">
 167                                 <mml:mn>0</mml:mn>
 168                                 <mml:mn>128</mml:mn>
 169                             </mml:mfenced>
 170                         </mml:math>
 171                         are accepted.
 172                     </p><p>
 173                         Effective light intensity is attenuated by the cosine of the angle between
 174                         the direction of the light and the direction from the light to the vertex
 175                         being lighted,
 176                         raised to the power of the spot exponent.
 177                         Thus, higher spot exponents result in a more focused light source,
 178                         regardless of the spot cutoff angle (see <code class="constant">GL_SPOT_CUTOFF</code>, next paragraph).
 179                         The initial spot exponent is 0,
 180                         resulting in uniform light distribution.
 181                     </p></dd><dt><span class="term"><code class="constant">GL_SPOT_CUTOFF</code></span></dt><dd><p>
 182                         <em class="parameter"><code>params</code></em> is a single integer or floating-point value that specifies
 183                         the maximum spread angle of a light source.
 184                         Integer and floating-point values are mapped directly.
 185                         Only values in the range
 186                         <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 187
 188                             <mml:mfenced open="[" close="]">
 189                                 <mml:mn>0</mml:mn>
 190                                 <mml:mn>90</mml:mn>
 191                             </mml:mfenced>
 192                         </mml:math>
 193                         and the special value 180
 194                         are accepted.
 195                         If the angle between the direction of the light and the direction from the
 196                         light to the vertex being lighted is greater than the spot cutoff angle,
 197                         the light is completely masked.
 198                         Otherwise, its intensity is controlled by the spot exponent and the
 199                         attenuation factors.
 200                         The initial spot cutoff is 180,
 201                         resulting in uniform light distribution.
 202                     </p></dd><dt><span class="term"><code class="constant">GL_CONSTANT_ATTENUATION</code></span></dt><dd></dd><dt><span class="term"><code class="constant">GL_LINEAR_ATTENUATION</code></span></dt><dd></dd><dt><span class="term"><code class="constant">GL_QUADRATIC_ATTENUATION</code></span></dt><dd><p>
 203                         <em class="parameter"><code>params</code></em> is a single integer or floating-point value that specifies
 204                         one of the three light attenuation factors.
 205                         Integer and floating-point values are mapped directly.
 206                         Only nonnegative values are accepted.
 207                         If the light is positional,
 208                         rather than directional,
 209                         its intensity is attenuated by the reciprocal of the sum of the constant
 210                         factor, the linear factor times the distance between the light
 211                         and the vertex being lighted,
 212                         and the quadratic factor times the square of the same distance.
 213                         The initial attenuation factors are (1, 0, 0),
 214                         resulting in no attenuation.
 215                     </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 216             It is always the case that <code class="constant">GL_LIGHT</code>
 217             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>
 218             = <code class="constant">GL_LIGHT0</code> +
 219             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">i</mml:mi></mml:math>.
 220         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 221             <code class="constant">GL_INVALID_ENUM</code> is generated if either <em class="parameter"><code>light</code></em> or <em class="parameter"><code>pname</code></em>
 222             is not an accepted value.
 223         </p><p>
 224             <code class="constant">GL_INVALID_VALUE</code> is generated if a spot exponent value is specified
 225             outside the range
 226             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 227
 228                 <mml:mfenced open="[" close="]">
 229                     <mml:mn>0</mml:mn>
 230                     <mml:mn>128</mml:mn>
 231                 </mml:mfenced>
 232             </mml:math>,
 233             or if spot cutoff is specified outside the range
 234             <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll">
 235
 236                 <mml:mfenced open="[" close="]">
 237                     <mml:mn>0</mml:mn>
 238                     <mml:mn>90</mml:mn>
 239                 </mml:mfenced>
 240             </mml:math>
 241             (except for the
 242             special value 180),
 243             or if a negative attenuation factor is specified.
 244         </p><p>
 245             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glLight</code> is executed between
 246             the execution of
 247             <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a> and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
 248         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
 249             <a class="citerefentry" href="glGetLight.xml"><span class="citerefentry"><span class="refentrytitle">glGetLight</span></span></a>
 250         </p><p>
 251             <a class="citerefentry" href="glIsEnabled.xml"><span class="citerefentry"><span class="refentrytitle">glIsEnabled</span></span></a> with argument <code class="constant">GL_LIGHTING</code>
 252         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 253             <a class="citerefentry" href="glColorMaterial.xml"><span class="citerefentry"><span class="refentrytitle">glColorMaterial</span></span></a>,
 254             <a class="citerefentry" href="glLightModel.xml"><span class="citerefentry"><span class="refentrytitle">glLightModel</span></span></a>,
 255             <a class="citerefentry" href="glMaterial.xml"><span class="citerefentry"><span class="refentrytitle">glMaterial</span></span></a>
 256         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 257             Copyright <span class="trademark"></span>© 1991-2006
 258             Silicon Graphics, Inc. This document is licensed under the SGI
 259             Free Software B License. For details, see
 260             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 261         </p></div></div></body></html>