upstream-man-pages/man2/glLight.xml

   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="glLight">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glLight</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glLight</refname>
  17         <refpurpose>set light source parameters</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glLightf</function></funcdef>
  23                 <paramdef>GLenum <parameter>light</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  25                 <paramdef>GLfloat <parameter>param</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28         <funcsynopsis>
  29             <funcprototype>
  30                 <funcdef>void <function>glLighti</function></funcdef>
  31                 <paramdef>GLenum <parameter>light</parameter></paramdef>
  32                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  33                 <paramdef>GLint <parameter>param</parameter></paramdef>
  34             </funcprototype>
  35         </funcsynopsis>
  36     </refsynopsisdiv>
  37     <!-- eqn: ignoring delim $$ -->
  38     <refsect1 id="parameters"><title>Parameters</title>
  39         <variablelist>
  40         <varlistentry>
  41             <term><parameter>light</parameter></term>
  42             <listitem>
  43                 <para>
  44                     Specifies a light.
  45                     The number of 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>,
  49                     where i ranges from 0 to the value of <constant>GL_MAX_LIGHTS</constant> - 1.
  50                 </para>
  51             </listitem>
  52         </varlistentry>
  53         <varlistentry>
  54             <term><parameter>pname</parameter></term>
  55             <listitem>
  56                 <para>
  57                     Specifies a single-valued light source parameter for <parameter>light</parameter>.
  58                     <constant>GL_SPOT_EXPONENT</constant>,
  59                     <constant>GL_SPOT_CUTOFF</constant>,
  60                     <constant>GL_CONSTANT_ATTENUATION</constant>,
  61                     <constant>GL_LINEAR_ATTENUATION</constant>, and
  62                     <constant>GL_QUADRATIC_ATTENUATION</constant> are accepted.
  63                 </para>
  64             </listitem>
  65         </varlistentry>
  66         <varlistentry>
  67             <term><parameter>param</parameter></term>
  68             <listitem>
  69                 <para>
  70                     Specifies the value that parameter <parameter>pname</parameter> of light source <parameter>light</parameter>
  71                     will be set to.
  72                 </para>
  73             </listitem>
  74         </varlistentry>
  75         </variablelist>
  76     </refsect1>
  77     <refsynopsisdiv><title>C Specification</title>
  78         <funcsynopsis>
  79             <funcprototype>
  80                 <funcdef>void <function>glLightfv</function></funcdef>
  81                 <paramdef>GLenum <parameter>light</parameter></paramdef>
  82                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  83                 <paramdef>const GLfloat * <parameter>params</parameter></paramdef>
  84             </funcprototype>
  85         </funcsynopsis>
  86         <funcsynopsis>
  87             <funcprototype>
  88                 <funcdef>void <function>glLightiv</function></funcdef>
  89                 <paramdef>GLenum <parameter>light</parameter></paramdef>
  90                 <paramdef>GLenum <parameter>pname</parameter></paramdef>
  91                 <paramdef>const GLint * <parameter>params</parameter></paramdef>
  92             </funcprototype>
  93         </funcsynopsis>
  94     </refsynopsisdiv>
  95     <refsect1 id="parameters2"><title>Parameters</title>
  96         <variablelist>
  97         <varlistentry>
  98             <term><parameter>light</parameter></term>
  99             <listitem>
 100                 <para>
 101                     Specifies a light.
 102                     The number of lights depends on the implementation, but
 103                     at least eight lights are supported.
 104                     They are identified by symbolic names of the form <constant>GL_LIGHT</constant>
 105                     <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>,
 106                     where i ranges from 0 to the value of <constant>GL_MAX_LIGHTS</constant> - 1.
 107                 </para>
 108             </listitem>
 109         </varlistentry>
 110         <varlistentry>
 111             <term><parameter>pname</parameter></term>
 112             <listitem>
 113                 <para>
 114                     Specifies a light source parameter for <parameter>light</parameter>.
 115                     <constant>GL_AMBIENT</constant>,
 116                     <constant>GL_DIFFUSE</constant>,
 117                     <constant>GL_SPECULAR</constant>,
 118                     <constant>GL_POSITION</constant>,
 119                     <constant>GL_SPOT_CUTOFF</constant>,
 120                     <constant>GL_SPOT_DIRECTION</constant>,
 121                     <constant>GL_SPOT_EXPONENT</constant>,
 122                     <constant>GL_CONSTANT_ATTENUATION</constant>,
 123                     <constant>GL_LINEAR_ATTENUATION</constant>, and
 124                     <constant>GL_QUADRATIC_ATTENUATION</constant> are accepted.
 125                 </para>
 126             </listitem>
 127         </varlistentry>
 128         <varlistentry>
 129             <term><parameter>params</parameter></term>
 130             <listitem>
 131                 <para>
 132                     Specifies a pointer to the value or values that parameter <parameter>pname</parameter>
 133                     of light source <parameter>light</parameter> will be set to.
 134                 </para>
 135             </listitem>
 136         </varlistentry>
 137         </variablelist>
 138     </refsect1>
 139     <refsect1 id="description"><title>Description</title>
 140         <para>
 141             <function>glLight</function> sets the values of individual light source parameters.
 142             <parameter>light</parameter> names the light and is a symbolic name of the form <constant>GL_LIGHT</constant>
 143             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>,
 144             where i ranges from 0 to the value of <constant>GL_MAX_LIGHTS</constant> - 1.
 145             <parameter>pname</parameter> specifies one of ten light source parameters,
 146             again by symbolic name.
 147             <parameter>params</parameter> is either a single value or a pointer to an array that contains
 148             the new values.
 149         </para>
 150         <para>
 151             To enable and disable lighting calculation, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
 152             and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_LIGHTING</constant>. Lighting is
 153             initially disabled.
 154             When it is enabled,
 155             light sources that are enabled contribute to the lighting calculation.
 156             Light source
 157             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
 158             is enabled and disabled using <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and
 159             <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_LIGHT</constant>
 160             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>.
 161         </para>
 162         <para>
 163             The ten light parameters are as follows:
 164         </para>
 165         <variablelist>
 166             <varlistentry>
 167                 <term><constant>GL_AMBIENT</constant></term>
 168                 <listitem>
 169                     <para>
 170                         <parameter>params</parameter> contains four integer or floating-point values that specify
 171                         the ambient RGBA intensity of the light.
 172                         Integer values are mapped linearly such that the most positive representable
 173                         value maps to 1.0,
 174                         and the most negative representable value maps to
 175                         <inlineequation><mml:math>
 176                             <!-- eqn: -1.0:-->
 177                             <mml:mn>-1.0</mml:mn>
 178                         </mml:math></inlineequation>.
 179                         Floating-point values are mapped directly.
 180                         Neither integer nor floating-point values are clamped.
 181                         The initial ambient light intensity is (0, 0, 0, 1).
 182                     </para>
 183                 </listitem>
 184             </varlistentry>
 185             <varlistentry>
 186                 <term><constant>GL_DIFFUSE</constant></term>
 187                 <listitem>
 188                     <para>
 189                         <parameter>params</parameter> contains four integer or floating-point values that specify
 190                         the diffuse RGBA intensity of the light.
 191                         Integer values are mapped linearly such that the most positive representable
 192                         value maps to 1.0,
 193                         and the most negative representable value maps to
 194                         <inlineequation><mml:math>
 195                             <!-- eqn: -1.0:-->
 196                             <mml:mn>-1.0</mml:mn>
 197                         </mml:math></inlineequation>.
 198                         Floating-point values are mapped directly.
 199                         Neither integer nor floating-point values are clamped.
 200                         The initial value
 201                         for <constant>GL_LIGHT0</constant> is (1, 1, 1, 1); for other lights, the
 202                         initial value is (0, 0, 0, 1).
 203                     </para>
 204                 </listitem>
 205             </varlistentry>
 206             <varlistentry>
 207                 <term><constant>GL_SPECULAR</constant></term>
 208                 <listitem>
 209                     <para>
 210                         <parameter>params</parameter> contains four integer or floating-point values that specify
 211                         the specular RGBA intensity of the light.
 212                         Integer values are mapped linearly such that the most positive representable
 213                         value maps to 1.0,
 214                         and the most negative representable value maps to
 215                         <inlineequation><mml:math>
 216                             <!-- eqn: -1.0:-->
 217                             <mml:mn>-1.0</mml:mn>
 218                         </mml:math></inlineequation>.
 219                         Floating-point values are mapped directly.
 220                         Neither integer nor floating-point values are clamped.
 221                         The initial value
 222                         for <constant>GL_LIGHT0</constant> is (1, 1, 1, 1); for other lights, the
 223                         initial value is (0, 0, 0, 1).
 224                     </para>
 225                 </listitem>
 226             </varlistentry>
 227             <varlistentry>
 228                 <term><constant>GL_POSITION</constant></term>
 229                 <listitem>
 230                     <para>
 231                         <parameter>params</parameter> contains four integer or floating-point values that specify
 232                         the position of the light in homogeneous object coordinates.
 233                         Both integer and floating-point values are mapped directly.
 234                         Neither integer nor floating-point values are clamped.
 235                     </para>
 236                     <para>
 237                         The position is transformed by the modelview matrix when
 238                         <function>glLight</function> is called (just as if it were a point),
 239                         and it is stored in eye coordinates.
 240                         If the
 241                         <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 242                         component of the position is 0,
 243                         the light is treated as a directional source.
 244                         Diffuse and specular lighting calculations take the light's direction,
 245                         but not its actual position,
 246                         into account,
 247                         and attenuation is disabled.
 248                         Otherwise,
 249                         diffuse and specular lighting calculations are based on the actual location
 250                         of the light in eye coordinates,
 251                         and attenuation is enabled.
 252                         The initial position is (0, 0, 1, 0);
 253                         thus, the initial light source is directional,
 254                         parallel to, and in the direction of the
 255                         <inlineequation><mml:math>
 256                             <!-- eqn: -z:-->
 257                             <mml:mrow>
 258                                 <mml:mo>-</mml:mo>
 259                                 <mml:mi mathvariant="italic">z</mml:mi>
 260                             </mml:mrow>
 261                         </mml:math></inlineequation>
 262                         axis.
 263                     </para>
 264                 </listitem>
 265             </varlistentry>
 266             <varlistentry>
 267                 <term><constant>GL_SPOT_DIRECTION</constant></term>
 268                 <listitem>
 269                     <para>
 270                         <parameter>params</parameter> contains three integer or floating-point values that specify
 271                         the direction of the light in homogeneous object coordinates.
 272                         Both integer and floating-point values are mapped directly.
 273                         Neither integer nor floating-point values are clamped.
 274                     </para>
 275                     <para>
 276                         The spot direction is transformed by the upper 3x3 of the modelview matrix when
 277                         <function>glLight</function> is called,
 278                         and it is stored in eye coordinates.
 279                         It is significant only when <constant>GL_SPOT_CUTOFF</constant> is not 180,
 280                         which it is initially.
 281                         The initial direction is
 282                         <inlineequation><mml:math>
 283                             <!-- eqn: (0, 0, -1):-->
 284                             <mml:mfenced open="(" close=")">
 285                                 <mml:mn>0</mml:mn>
 286                                 <mml:mn>0</mml:mn>
 287                                 <mml:mn>-1</mml:mn>
 288                             </mml:mfenced>
 289                         </mml:math></inlineequation>.
 290                     </para>
 291                 </listitem>
 292             </varlistentry>
 293             <varlistentry>
 294                 <term><constant>GL_SPOT_EXPONENT</constant></term>
 295                 <listitem>
 296                     <para>
 297                         <parameter>params</parameter> is a single integer or floating-point value that specifies
 298                         the intensity distribution of the light.
 299                         Integer and floating-point values are mapped directly.
 300                         Only values in the range
 301                         <inlineequation><mml:math>
 302                             <!-- eqn: [0,128]:-->
 303                             <mml:mfenced open="[" close="]">
 304                                 <mml:mn>0</mml:mn>
 305                                 <mml:mn>128</mml:mn>
 306                             </mml:mfenced>
 307                         </mml:math></inlineequation>
 308                         are accepted.
 309                     </para>
 310                     <para>
 311                         Effective light intensity is attenuated by the cosine of the angle between
 312                         the direction of the light and the direction from the light to the vertex
 313                         being lighted,
 314                         raised to the power of the spot exponent.
 315                         Thus, higher spot exponents result in a more focused light source,
 316                         regardless of the spot cutoff angle (see <constant>GL_SPOT_CUTOFF</constant>, next paragraph).
 317                         The initial spot exponent is 0,
 318                         resulting in uniform light distribution.
 319                     </para>
 320                 </listitem>
 321             </varlistentry>
 322             <varlistentry>
 323                 <term><constant>GL_SPOT_CUTOFF</constant></term>
 324                 <listitem>
 325                     <para>
 326                         <parameter>params</parameter> is a single integer or floating-point value that specifies
 327                         the maximum spread angle of a light source.
 328                         Integer and floating-point values are mapped directly.
 329                         Only values in the range
 330                         <inlineequation><mml:math>
 331                             <!-- eqn: [0,90]:-->
 332                             <mml:mfenced open="[" close="]">
 333                                 <mml:mn>0</mml:mn>
 334                                 <mml:mn>90</mml:mn>
 335                             </mml:mfenced>
 336                         </mml:math></inlineequation>
 337                         and the special value 180
 338                         are accepted.
 339                         If the angle between the direction of the light and the direction from the
 340                         light to the vertex being lighted is greater than the spot cutoff angle,
 341                         the light is completely masked.
 342                         Otherwise, its intensity is controlled by the spot exponent and the
 343                         attenuation factors.
 344                         The initial spot cutoff is 180,
 345                         resulting in uniform light distribution.
 346                     </para>
 347                 </listitem>
 348             </varlistentry>
 349             <varlistentry>
 350                 <term><constant>GL_CONSTANT_ATTENUATION</constant></term>
 351                 <listitem>
 352                 </listitem>
 353             </varlistentry>
 354             <varlistentry>
 355                 <term><constant>GL_LINEAR_ATTENUATION</constant></term>
 356                 <listitem>
 357                 </listitem>
 358             </varlistentry>
 359             <varlistentry>
 360                 <term><constant>GL_QUADRATIC_ATTENUATION</constant></term>
 361                 <listitem>
 362                     <para>
 363                         <parameter>params</parameter> is a single integer or floating-point value that specifies
 364                         one of the three light attenuation factors.
 365                         Integer and floating-point values are mapped directly.
 366                         Only nonnegative values are accepted.
 367                         If the light is positional,
 368                         rather than directional,
 369                         its intensity is attenuated by the reciprocal of the sum of the constant
 370                         factor, the linear factor times the distance between the light
 371                         and the vertex being lighted,
 372                         and the quadratic factor times the square of the same distance.
 373                         The initial attenuation factors are (1, 0, 0),
 374                         resulting in no attenuation.
 375                     </para>
 376                 </listitem>
 377             </varlistentry>
 378         </variablelist>
 379     </refsect1>
 380     <refsect1 id="notes"><title>Notes</title>
 381         <para>
 382             It is always the case that <constant>GL_LIGHT</constant>
 383             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
 384             = <constant>GL_LIGHT0</constant> +
 385             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>.
 386         </para>
 387     </refsect1>
 388     <refsect1 id="errors"><title>Errors</title>
 389         <para>
 390             <constant>GL_INVALID_ENUM</constant> is generated if either <parameter>light</parameter> or <parameter>pname</parameter>
 391             is not an accepted value.
 392         </para>
 393         <para>
 394             <constant>GL_INVALID_VALUE</constant> is generated if a spot exponent value is specified
 395             outside the range
 396             <inlineequation><mml:math>
 397                 <!-- eqn: [0,128]:-->
 398                 <mml:mfenced open="[" close="]">
 399                     <mml:mn>0</mml:mn>
 400                     <mml:mn>128</mml:mn>
 401                 </mml:mfenced>
 402             </mml:math></inlineequation>,
 403             or if spot cutoff is specified outside the range
 404             <inlineequation><mml:math>
 405                 <!-- eqn: [0,90]:-->
 406                 <mml:mfenced open="[" close="]">
 407                     <mml:mn>0</mml:mn>
 408                     <mml:mn>90</mml:mn>
 409                 </mml:mfenced>
 410             </mml:math></inlineequation>
 411             (except for the
 412             special value 180),
 413             or if a negative attenuation factor is specified.
 414         </para>
 415         <para>
 416             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glLight</function> is executed between
 417             the execution of
 418             <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 419         </para>
 420     </refsect1>
 421     <refsect1 id="associatedgets"><title>Associated Gets</title>
 422         <para>
 423             <citerefentry><refentrytitle>glGetLight</refentrytitle></citerefentry>
 424         </para>
 425         <para>
 426             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_LIGHTING</constant>
 427         </para>
 428     </refsect1>
 429     <refsect1 id="seealso"><title>See Also</title>
 430         <para>
 431             <citerefentry><refentrytitle>glColorMaterial</refentrytitle></citerefentry>,
 432             <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>,
 433             <citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>
 434         </para>
 435     </refsect1>
 436     <refsect1 id="Copyright"><title>Copyright</title>
 437         <para>
 438             Copyright <trademark class="copyright"></trademark> 1991-2006
 439             Silicon Graphics, Inc. This document is licensed under the SGI
 440             Free Software B License. For details, see
 441             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 442         </para>
 443     </refsect1>
 444 </refentry>