--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
+ "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
+<refentry id="glLight">
+ <refmeta>
+ <refmetainfo>
+ <copyright>
+ <year>1991-2006</year>
+ <holder>Silicon Graphics, Inc.</holder>
+ </copyright>
+ </refmetainfo>
+ <refentrytitle>glLight</refentrytitle>
+ <manvolnum>3G</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>glLight</refname>
+ <refpurpose>set light source parameters</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv><title>C Specification</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>void <function>glLightf</function></funcdef>
+ <paramdef>GLenum <parameter>light</parameter></paramdef>
+ <paramdef>GLenum <parameter>pname</parameter></paramdef>
+ <paramdef>GLfloat <parameter>param</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>void <function>glLighti</function></funcdef>
+ <paramdef>GLenum <parameter>light</parameter></paramdef>
+ <paramdef>GLenum <parameter>pname</parameter></paramdef>
+ <paramdef>GLint <parameter>param</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+ <!-- eqn: ignoring delim $$ -->
+ <refsect1 id="parameters"><title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>light</parameter></term>
+ <listitem>
+ <para>
+ Specifies a light.
+ The number of lights depends on the implementation,
+ but at least eight lights are supported.
+ They are identified by symbolic names of the form <constant>GL_LIGHT</constant>
+ <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>,
+ where i ranges from 0 to the value of <constant>GL_MAX_LIGHTS</constant> - 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>pname</parameter></term>
+ <listitem>
+ <para>
+ Specifies a single-valued light source parameter for <parameter>light</parameter>.
+ <constant>GL_SPOT_EXPONENT</constant>,
+ <constant>GL_SPOT_CUTOFF</constant>,
+ <constant>GL_CONSTANT_ATTENUATION</constant>,
+ <constant>GL_LINEAR_ATTENUATION</constant>, and
+ <constant>GL_QUADRATIC_ATTENUATION</constant> are accepted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>param</parameter></term>
+ <listitem>
+ <para>
+ Specifies the value that parameter <parameter>pname</parameter> of light source <parameter>light</parameter>
+ will be set to.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsynopsisdiv><title>C Specification</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>void <function>glLightfv</function></funcdef>
+ <paramdef>GLenum <parameter>light</parameter></paramdef>
+ <paramdef>GLenum <parameter>pname</parameter></paramdef>
+ <paramdef>const GLfloat * <parameter>params</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>void <function>glLightiv</function></funcdef>
+ <paramdef>GLenum <parameter>light</parameter></paramdef>
+ <paramdef>GLenum <parameter>pname</parameter></paramdef>
+ <paramdef>const GLint * <parameter>params</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+ <refsect1 id="parameters2"><title>Parameters</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>light</parameter></term>
+ <listitem>
+ <para>
+ Specifies a light.
+ The number of lights depends on the implementation, but
+ at least eight lights are supported.
+ They are identified by symbolic names of the form <constant>GL_LIGHT</constant>
+ <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>,
+ where i ranges from 0 to the value of <constant>GL_MAX_LIGHTS</constant> - 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>pname</parameter></term>
+ <listitem>
+ <para>
+ Specifies a light source parameter for <parameter>light</parameter>.
+ <constant>GL_AMBIENT</constant>,
+ <constant>GL_DIFFUSE</constant>,
+ <constant>GL_SPECULAR</constant>,
+ <constant>GL_POSITION</constant>,
+ <constant>GL_SPOT_CUTOFF</constant>,
+ <constant>GL_SPOT_DIRECTION</constant>,
+ <constant>GL_SPOT_EXPONENT</constant>,
+ <constant>GL_CONSTANT_ATTENUATION</constant>,
+ <constant>GL_LINEAR_ATTENUATION</constant>, and
+ <constant>GL_QUADRATIC_ATTENUATION</constant> are accepted.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>params</parameter></term>
+ <listitem>
+ <para>
+ Specifies a pointer to the value or values that parameter <parameter>pname</parameter>
+ of light source <parameter>light</parameter> will be set to.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1 id="description"><title>Description</title>
+ <para>
+ <function>glLight</function> sets the values of individual light source parameters.
+ <parameter>light</parameter> names the light and is a symbolic name of the form <constant>GL_LIGHT</constant>
+ <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>,
+ where i ranges from 0 to the value of <constant>GL_MAX_LIGHTS</constant> - 1.
+ <parameter>pname</parameter> specifies one of ten light source parameters,
+ again by symbolic name.
+ <parameter>params</parameter> is either a single value or a pointer to an array that contains
+ the new values.
+ </para>
+ <para>
+ To enable and disable lighting calculation, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
+ and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_LIGHTING</constant>. Lighting is
+ initially disabled.
+ When it is enabled,
+ light sources that are enabled contribute to the lighting calculation.
+ Light source
+ <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
+ is enabled and disabled using <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and
+ <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_LIGHT</constant>
+ <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>.
+ </para>
+ <para>
+ The ten light parameters are as follows:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>GL_AMBIENT</constant></term>
+ <listitem>
+ <para>
+ <parameter>params</parameter> contains four integer or floating-point values that specify
+ the ambient RGBA intensity of the light.
+ Integer values are mapped linearly such that the most positive representable
+ value maps to 1.0,
+ and the most negative representable value maps to
+ <inlineequation><mml:math>
+ <!-- eqn: -1.0:-->
+ <mml:mn>-1.0</mml:mn>
+ </mml:math></inlineequation>.
+ Floating-point values are mapped directly.
+ Neither integer nor floating-point values are clamped.
+ The initial ambient light intensity is (0, 0, 0, 1).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GL_DIFFUSE</constant></term>
+ <listitem>
+ <para>
+ <parameter>params</parameter> contains four integer or floating-point values that specify
+ the diffuse RGBA intensity of the light.
+ Integer values are mapped linearly such that the most positive representable
+ value maps to 1.0,
+ and the most negative representable value maps to
+ <inlineequation><mml:math>
+ <!-- eqn: -1.0:-->
+ <mml:mn>-1.0</mml:mn>
+ </mml:math></inlineequation>.
+ Floating-point values are mapped directly.
+ Neither integer nor floating-point values are clamped.
+ The initial value
+ for <constant>GL_LIGHT0</constant> is (1, 1, 1, 1); for other lights, the
+ initial value is (0, 0, 0, 1).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GL_SPECULAR</constant></term>
+ <listitem>
+ <para>
+ <parameter>params</parameter> contains four integer or floating-point values that specify
+ the specular RGBA intensity of the light.
+ Integer values are mapped linearly such that the most positive representable
+ value maps to 1.0,
+ and the most negative representable value maps to
+ <inlineequation><mml:math>
+ <!-- eqn: -1.0:-->
+ <mml:mn>-1.0</mml:mn>
+ </mml:math></inlineequation>.
+ Floating-point values are mapped directly.
+ Neither integer nor floating-point values are clamped.
+ The initial value
+ for <constant>GL_LIGHT0</constant> is (1, 1, 1, 1); for other lights, the
+ initial value is (0, 0, 0, 1).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GL_POSITION</constant></term>
+ <listitem>
+ <para>
+ <parameter>params</parameter> contains four integer or floating-point values that specify
+ the position of the light in homogeneous object coordinates.
+ Both integer and floating-point values are mapped directly.
+ Neither integer nor floating-point values are clamped.
+ </para>
+ <para>
+ The position is transformed by the modelview matrix when
+ <function>glLight</function> is called (just as if it were a point),
+ and it is stored in eye coordinates.
+ If the
+ <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
+ component of the position is 0,
+ the light is treated as a directional source.
+ Diffuse and specular lighting calculations take the light's direction,
+ but not its actual position,
+ into account,
+ and attenuation is disabled.
+ Otherwise,
+ diffuse and specular lighting calculations are based on the actual location
+ of the light in eye coordinates,
+ and attenuation is enabled.
+ The initial position is (0, 0, 1, 0);
+ thus, the initial light source is directional,
+ parallel to, and in the direction of the
+ <inlineequation><mml:math>
+ <!-- eqn: -z:-->
+ <mml:mrow>
+ <mml:mo>-</mml:mo>
+ <mml:mi mathvariant="italic">z</mml:mi>
+ </mml:mrow>
+ </mml:math></inlineequation>
+ axis.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GL_SPOT_DIRECTION</constant></term>
+ <listitem>
+ <para>
+ <parameter>params</parameter> contains three integer or floating-point values that specify
+ the direction of the light in homogeneous object coordinates.
+ Both integer and floating-point values are mapped directly.
+ Neither integer nor floating-point values are clamped.
+ </para>
+ <para>
+ The spot direction is transformed by the upper 3x3 of the modelview matrix when
+ <function>glLight</function> is called,
+ and it is stored in eye coordinates.
+ It is significant only when <constant>GL_SPOT_CUTOFF</constant> is not 180,
+ which it is initially.
+ The initial direction is
+ <inlineequation><mml:math>
+ <!-- eqn: (0, 0, -1):-->
+ <mml:mfenced open="(" close=")">
+ <mml:mn>0</mml:mn>
+ <mml:mn>0</mml:mn>
+ <mml:mn>-1</mml:mn>
+ </mml:mfenced>
+ </mml:math></inlineequation>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GL_SPOT_EXPONENT</constant></term>
+ <listitem>
+ <para>
+ <parameter>params</parameter> is a single integer or floating-point value that specifies
+ the intensity distribution of the light.
+ Integer and floating-point values are mapped directly.
+ Only values in the range
+ <inlineequation><mml:math>
+ <!-- eqn: [0,128]:-->
+ <mml:mfenced open="[" close="]">
+ <mml:mn>0</mml:mn>
+ <mml:mn>128</mml:mn>
+ </mml:mfenced>
+ </mml:math></inlineequation>
+ are accepted.
+ </para>
+ <para>
+ Effective light intensity is attenuated by the cosine of the angle between
+ the direction of the light and the direction from the light to the vertex
+ being lighted,
+ raised to the power of the spot exponent.
+ Thus, higher spot exponents result in a more focused light source,
+ regardless of the spot cutoff angle (see <constant>GL_SPOT_CUTOFF</constant>, next paragraph).
+ The initial spot exponent is 0,
+ resulting in uniform light distribution.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GL_SPOT_CUTOFF</constant></term>
+ <listitem>
+ <para>
+ <parameter>params</parameter> is a single integer or floating-point value that specifies
+ the maximum spread angle of a light source.
+ Integer and floating-point values are mapped directly.
+ Only values in the range
+ <inlineequation><mml:math>
+ <!-- eqn: [0,90]:-->
+ <mml:mfenced open="[" close="]">
+ <mml:mn>0</mml:mn>
+ <mml:mn>90</mml:mn>
+ </mml:mfenced>
+ </mml:math></inlineequation>
+ and the special value 180
+ are accepted.
+ If the angle between the direction of the light and the direction from the
+ light to the vertex being lighted is greater than the spot cutoff angle,
+ the light is completely masked.
+ Otherwise, its intensity is controlled by the spot exponent and the
+ attenuation factors.
+ The initial spot cutoff is 180,
+ resulting in uniform light distribution.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GL_CONSTANT_ATTENUATION</constant></term>
+ <listitem>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GL_LINEAR_ATTENUATION</constant></term>
+ <listitem>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>GL_QUADRATIC_ATTENUATION</constant></term>
+ <listitem>
+ <para>
+ <parameter>params</parameter> is a single integer or floating-point value that specifies
+ one of the three light attenuation factors.
+ Integer and floating-point values are mapped directly.
+ Only nonnegative values are accepted.
+ If the light is positional,
+ rather than directional,
+ its intensity is attenuated by the reciprocal of the sum of the constant
+ factor, the linear factor times the distance between the light
+ and the vertex being lighted,
+ and the quadratic factor times the square of the same distance.
+ The initial attenuation factors are (1, 0, 0),
+ resulting in no attenuation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1 id="notes"><title>Notes</title>
+ <para>
+ It is always the case that <constant>GL_LIGHT</constant>
+ <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
+ = <constant>GL_LIGHT0</constant> +
+ <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>.
+ </para>
+ </refsect1>
+ <refsect1 id="errors"><title>Errors</title>
+ <para>
+ <constant>GL_INVALID_ENUM</constant> is generated if either <parameter>light</parameter> or <parameter>pname</parameter>
+ is not an accepted value.
+ </para>
+ <para>
+ <constant>GL_INVALID_VALUE</constant> is generated if a spot exponent value is specified
+ outside the range
+ <inlineequation><mml:math>
+ <!-- eqn: [0,128]:-->
+ <mml:mfenced open="[" close="]">
+ <mml:mn>0</mml:mn>
+ <mml:mn>128</mml:mn>
+ </mml:mfenced>
+ </mml:math></inlineequation>,
+ or if spot cutoff is specified outside the range
+ <inlineequation><mml:math>
+ <!-- eqn: [0,90]:-->
+ <mml:mfenced open="[" close="]">
+ <mml:mn>0</mml:mn>
+ <mml:mn>90</mml:mn>
+ </mml:mfenced>
+ </mml:math></inlineequation>
+ (except for the
+ special value 180),
+ or if a negative attenuation factor is specified.
+ </para>
+ <para>
+ <constant>GL_INVALID_OPERATION</constant> is generated if <function>glLight</function> is executed between
+ the execution of
+ <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
+ </para>
+ </refsect1>
+ <refsect1 id="associatedgets"><title>Associated Gets</title>
+ <para>
+ <citerefentry><refentrytitle>glGetLight</refentrytitle></citerefentry>
+ </para>
+ <para>
+ <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_LIGHTING</constant>
+ </para>
+ </refsect1>
+ <refsect1 id="seealso"><title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>glColorMaterial</refentrytitle></citerefentry>,
+ <citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>,
+ <citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>
+ </para>
+ </refsect1>
+ <refsect1 id="Copyright"><title>Copyright</title>
+ <para>
+ Copyright <trademark class="copyright"></trademark> 1991-2006
+ Silicon Graphics, Inc. This document is licensed under the SGI
+ Free Software B License. For details, see
+ <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
+ </para>
+ </refsect1>
+</refentry>
HCoop / clinton / guile-figl.git / blobdiff