254 lines
8.5 KiB
Plaintext
254 lines
8.5 KiB
Plaintext
'\" te
|
|
'\"! tbl|eqn | mmdoc
|
|
'\"macro stdmacro
|
|
.ds Vn Version 1.2
|
|
.ds Dt 24 September 1999
|
|
.ds Re Release 1.2.1
|
|
.ds Dp Jan 14 18:30
|
|
.ds Dm 01 light.gl
|
|
.ds Xs 33725 10 light.gl
|
|
.TH GLLIGHT 3G
|
|
.SH NAME
|
|
.B "glLightf, glLighti, glLightfv, glLightiv
|
|
\- set light source parameters
|
|
|
|
.SH C SPECIFICATION
|
|
void \f3glLightf\fP(
|
|
GLenum \fIlight\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglLightf( 'u
|
|
GLenum \fIpname\fP,
|
|
GLfloat \fIparam\fP )
|
|
.fi
|
|
void \f3glLighti\fP(
|
|
GLenum \fIlight\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglLighti( 'u
|
|
GLenum \fIpname\fP,
|
|
GLint \fIparam\fP )
|
|
.fi
|
|
|
|
.EQ
|
|
delim $$
|
|
.EN
|
|
.SH PARAMETERS
|
|
.TP \w'\fIparams\fP\ \ 'u
|
|
\f2light\fP
|
|
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 \%\f3GL_LIGHT\fP$i$
|
|
where 0 \(<= $ i $ < \%\f3GL_MAX_LIGHTS\fP.
|
|
.TP
|
|
\f2pname\fP
|
|
Specifies a single-valued light source parameter for \f2light\fP.
|
|
\%\f3GL_SPOT_EXPONENT\fP,
|
|
\%\f3GL_SPOT_CUTOFF\fP,
|
|
\%\f3GL_CONSTANT_ATTENUATION\fP,
|
|
\%\f3GL_LINEAR_ATTENUATION\fP, and
|
|
\%\f3GL_QUADRATIC_ATTENUATION\fP are accepted.
|
|
.TP
|
|
\f2param\fP
|
|
Specifies the value that parameter \f2pname\fP of light source \f2light\fP
|
|
will be set to.
|
|
.SH C SPECIFICATION
|
|
void \f3glLightfv\fP(
|
|
GLenum \fIlight\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglLightfv( 'u
|
|
GLenum \fIpname\fP,
|
|
const GLfloat \fI*params\fP )
|
|
.fi
|
|
void \f3glLightiv\fP(
|
|
GLenum \fIlight\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglLightiv( 'u
|
|
GLenum \fIpname\fP,
|
|
const GLint \fI*params\fP )
|
|
.fi
|
|
|
|
.SH PARAMETERS
|
|
.TP
|
|
\f2light\fP
|
|
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 \%\f3GL_LIGHT\fP$i$
|
|
where 0 \(<= $ i $ < \%\f3GL_MAX_LIGHTS\fP.
|
|
.TP
|
|
\f2pname\fP
|
|
Specifies a light source parameter for \f2light\fP.
|
|
\%\f3GL_AMBIENT\fP,
|
|
\%\f3GL_DIFFUSE\fP,
|
|
\%\f3GL_SPECULAR\fP,
|
|
\%\f3GL_POSITION\fP,
|
|
\%\f3GL_SPOT_CUTOFF\fP,
|
|
\%\f3GL_SPOT_DIRECTION\fP,
|
|
\%\f3GL_SPOT_EXPONENT\fP,
|
|
\%\f3GL_CONSTANT_ATTENUATION\fP,
|
|
\%\f3GL_LINEAR_ATTENUATION\fP, and
|
|
\%\f3GL_QUADRATIC_ATTENUATION\fP are accepted.
|
|
.TP
|
|
\f2params\fP
|
|
Specifies a pointer to the value or values that parameter \f2pname\fP
|
|
of light source \f2light\fP will be set to.
|
|
.SH DESCRIPTION
|
|
\%\f3glLight\fP sets the values of individual light source parameters.
|
|
\f2light\fP names the light and is a symbolic name of the form \%\f3GL_LIGHT\fP$i$,
|
|
where 0 \(<= i < \%\f3GL_MAX_LIGHTS\fP.
|
|
\f2pname\fP specifies one of ten light source parameters,
|
|
again by symbolic name.
|
|
\f2params\fP is either a single value or a pointer to an array that contains
|
|
the new values.
|
|
.P
|
|
To enable and disable lighting calculation, call \%\f3glEnable\fP
|
|
and \%\f3glDisable\fP with argument \%\f3GL_LIGHTING\fP. Lighting is
|
|
initially disabled.
|
|
When it is enabled,
|
|
light sources that are enabled contribute to the lighting calculation.
|
|
Light source $i$ is enabled and disabled using \%\f3glEnable\fP and
|
|
\%\f3glDisable\fP with argument \%\f3GL_LIGHT\fP$i$.
|
|
.P
|
|
The ten light parameters are as follows:
|
|
.TP 20
|
|
\%\f3GL_AMBIENT\fP
|
|
\f2params\fP 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 \-1.0.
|
|
Floating-point values are mapped directly.
|
|
Neither integer nor floating-point values are clamped.
|
|
The initial ambient light intensity is (0, 0, 0, 1).
|
|
.TP
|
|
\%\f3GL_DIFFUSE\fP
|
|
\f2params\fP 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 \-1.0.
|
|
Floating-point values are mapped directly.
|
|
Neither integer nor floating-point values are clamped.
|
|
The initial value
|
|
for \%\f3GL_LIGHT0\fP is (1, 1, 1, 1); for other lights, the
|
|
initial value is (0, 0, 0, 0).
|
|
.TP
|
|
\%\f3GL_SPECULAR\fP
|
|
\f2params\fP 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 \-1.0.
|
|
Floating-point values are mapped directly.
|
|
Neither integer nor floating-point values are clamped.
|
|
The initial value
|
|
for \%\f3GL_LIGHT0\fP is (1, 1, 1, 1); for other lights, the
|
|
initial value is (0, 0, 0, 0).
|
|
.TP
|
|
\%\f3GL_POSITION\fP
|
|
\f2params\fP 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.
|
|
.IP
|
|
The position is transformed by the modelview matrix when
|
|
\%\f3glLight\fP is called (just as if it were a point),
|
|
and it is stored in eye coordinates.
|
|
If the $w$ 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 $-z$ axis.
|
|
.TP
|
|
\%\f3GL_SPOT_DIRECTION\fP
|
|
\f2params\fP 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.
|
|
.IP
|
|
The spot direction is transformed by the inverse of the modelview matrix when
|
|
\%\f3glLight\fP is called (just as if it were a normal),
|
|
and it is stored in eye coordinates.
|
|
It is significant only when \%\f3GL_SPOT_CUTOFF\fP is not 180,
|
|
which it is initially.
|
|
The initial direction is (0, 0, \-1).
|
|
.TP
|
|
\%\f3GL_SPOT_EXPONENT\fP
|
|
\f2params\fP 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 [0,128] are accepted.
|
|
.IP
|
|
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 \%\f3GL_SPOT_CUTOFF\fP, next paragraph).
|
|
The initial spot exponent is 0,
|
|
resulting in uniform light distribution.
|
|
.TP
|
|
\%\f3GL_SPOT_CUTOFF\fP
|
|
\f2params\fP 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 [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.
|
|
.BP
|
|
Otherwise, its intensity is controlled by the spot exponent and the
|
|
attenuation factors.
|
|
The initial spot cutoff is 180,
|
|
resulting in uniform light distribution.
|
|
.TP
|
|
\%\f3GL_CONSTANT_ATTENUATION\fP
|
|
.TP
|
|
\%\f3GL_LINEAR_ATTENUATION \fP
|
|
.TP
|
|
\%\f3GL_QUADRATIC_ATTENUATION\fP
|
|
\f2params\fP 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.
|
|
.SH NOTES
|
|
It is always the case that \%\f3GL_LIGHT\fP$i$ = \%\f3GL_LIGHT0\fP + $i$.
|
|
.SH ERRORS
|
|
\%\f3GL_INVALID_ENUM\fP is generated if either \f2light\fP or \f2pname\fP
|
|
is not an accepted value.
|
|
.P
|
|
\%\f3GL_INVALID_VALUE\fP 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.
|
|
.P
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glLight\fP is executed between
|
|
the execution of
|
|
\%\f3glBegin\fP and the corresponding execution of \%\f3glEnd\fP.
|
|
.SH ASSOCIATED GETS
|
|
\%\f3glGetLight\fP
|
|
.br
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_LIGHTING\fP
|
|
.SH SEE ALSO
|
|
\%\f3glColorMaterial(3G)\fP,
|
|
\%\f3glLightModel(3G)\fP,
|
|
\%\f3glMaterial(3G)\fP
|