<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "DTD/docbook/docbookx.dtd">
<!--
License Applicability. Except to the extent portions of this file are
made subject to an alternative license as permitted in the SGI Free
Software License B, Version 1.1 (the "License"), the contents of this
file are subject only to the provisions of the License. You may not use
this file except in compliance with the License. You may obtain a copy
of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:
http://oss.sgi.com/projects/FreeB
Note that, as provided in the License, the Software is distributed on an
"AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
Original Code. The Original Code is: OpenGL ES Reference Manual,
Version 1.0, released September 2003, developed by Silicon Graphics,
Inc. The Original Code is Copyright (c) 2003 Silicon Graphics, Inc.
Copyright in any portions created by third parties is as indicated
elsewhere herein. All Rights Reserved.
-->
<refentry id="glLight">
<refmeta>
<refentrytitle>glLight</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refdescriptor>glLight</refdescriptor>
<refname>glLightf</refname>
<refname>glLightx</refname>
<refname>glLightfv</refname>
<refname>glLightxv</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>
<funcprototype>
<funcdef>void <function>glLightx</function></funcdef>
<paramdef>GLenum <parameter>light</parameter></paramdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>GLfixed <parameter>param</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<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><replaceable>i</replaceable>
where
<inlineequation><math>
<mn>0</mn>
<mo><=</mo>
<mi>i</mi>
<mo><</mo>
<mi>GL_MAX_LIGHTS</mi>
</math></inlineequation>.
</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>
<funcprototype>
<funcdef>void <function>glLightxv</function></funcdef>
<paramdef>GLenum <parameter>light</parameter></paramdef>
<paramdef>GLenum <parameter>pname</parameter></paramdef>
<paramdef>const GLfixed * <parameter>params</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<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><replaceable>i</replaceable>
where
<inlineequation><math>
<mn>0</mn>
<mo><=</mo>
<mi>i</mi>
<mo><</mo>
<mi>GL_MAX_LIGHTS</mi>
</math></inlineequation>.
</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>
<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><replaceable>i</replaceable>,
where
<inlineequation><math>
<mn>0</mn>
<mo><=</mo>
<mi>i</mi>
<mo><</mo>
<mi>GL_MAX_LIGHTS</mi>
</math></inlineequation>.
<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 <replaceable>i</replaceable>
is enabled and disabled using
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry>
with argument <constant>GL_LIGHT</constant><replaceable>i</replaceable>.
</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 fixed-point or floating-point values that
specify the ambient RGBA intensity of the light. Both
fixed-point and floating-point values are mapped
directly. Neither fixed-point 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 fixed-point or floating-point values that
specify the diffuse RGBA intensity of the light. Both
fixed-point and floating-point values are mapped
directly. Neither fixed-point 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, 0).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_SPECULAR</constant>
</term>
<listitem>
<para><parameter>params</parameter>
contains four fixed-point or floating-point values that
specify the specular RGBA intensity of the light. Both
fixed-point and floating-point values are mapped
directly. Neither fixed-point 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, 0).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_POSITION</constant>
</term>
<listitem>
<para><parameter>params</parameter>
contains four fixed-point or floating-point values that
specify the position of the light in homogeneous object
coordinates. Both fixed-point and floating-point values
are mapped directly. Neither fixed-point 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 <replaceable>w</replaceable>
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
-<replaceable>z</replaceable> axis.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_SPOT_DIRECTION</constant>
</term>
<listitem>
<para><parameter>params</parameter>
contains three fixed-point or floating-point values that
specify the direction of the light in homogeneous object
coordinates. Both fixed-point and floating-point values
are mapped directly. Neither fixed-point nor
floating-point values are clamped.</para>
<para>The spot direction is transformed by the inverse of the
modelview matrix when <function>glLight</function>
is called (just as if it were a normal), 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 (0,
0, -1).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>GL_SPOT_EXPONENT</constant>
</term>
<listitem>
<para><parameter>params</parameter>
is a single fixed-point or floating-point value that
specifies the intensity distribution of the light.
Fixed-point and floating-point values are mapped
directly. Only values in the range [0, 128] 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 fixed-point or floating-point value that
specifies the maximum spread angle of a light source.
Fixed-point and floating-point values are mapped
directly. Only values in the range [0, 90] 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>,
<constant>GL_LINEAR_ATTENUATION</constant>,
<constant>GL_QUADRATIC_ATTENUATION</constant>
</term>
<listitem>
<para><parameter>params</parameter>
is a single fixed-point or floating-point value that
specifies one of the three light attenuation factors.
Fixed-point 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>
<title>Notes</title>
<para>It is always the case that
<inlineequation><math>
<mi>GL_LIGHT</mi><mi>i</mi> <mo>=</mo>
<mi>GL_LIGHT0</mi><mo>+</mo><mi>i</mi>
</math></inlineequation>.
</para>
</refsect1>
<refsect1>
<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 [0, 128], or if spot cutoff is specified outside the range
[0, 90] (except for the special value 180), or if a negative
attenuation factor is specified.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glLightModel</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMaterial</refentrytitle></citerefentry>
</para>
</refsect1>
</refentry>
![[BACK]](/icons/back.gif){kind=icon}
Return to glLight.xml CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [Development] / projects / ogl-sample / main / doc / gles / xml