mirror of
https://github.com/Ryujinx/Opentk.git
synced 2024-12-26 13:35:27 +00:00
445 lines
22 KiB
XML
445 lines
22 KiB
XML
<?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>
|