gSPLight.3p
2.67 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
.TH gSPLight 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gSPLight, gsSPLight
\- load a light into the RSP.
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"
typedef struct {
unsigned char col[3]; /* diffuse light value (rgba) */
char pad1;
unsigned char colc[3]; /* copy of diffuse light value (rgba) */
char pad2;
signed char dir[3]; /* direction TOWARDS the light source */
char pad3; /* This does not need to be normalized */
} Light_t; /* but should have a large magnitude (~127) */
typedef union {
Light_t l;
long int force_structure_alignment[4];
} Light;
gSPLight(Gfx *gdl, Light *l, int n)
gsSPLight(Light *l, int n)
.fi
\fP
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I l
light pointer.
.TP
.I n
number of the light to replace, 1-8.
.TP
.SH DESCRIPTION
The
.I gSPLight (3P)
command loads a single light structure into the numbered position in the light
buffer.
.PP
Use the
.I gSPNumLights (3P)
command to specify which lights should be used in the lighting calculation.
If
.I gSPNumLights (3P)
specifies that N lights will be used, then the 1st N lights (1-N) will be used as
directional lights (color and direction) and the N+1st will be used as an ambient
light (color only).
.PP
The colors in the light structure combine the color of the light with
the color of the material. Although this convention may seem awkward
at first, this optimization provides significant speedup in the RSP
geometry engine.
.PP
After the light is set (with a
.I gSPLight (3P)
command) and then used (with any
.I gSPVertex (3P)
command) then that light's color may be changed for vertices in future
.I gSPVertex (3P)
calls by calling
.I gSPLight (3P)
again. This method of changing the light color is performance-efficient (note
that this is also the method to use for changing the material color).
However, if the light's direction must be changed, then the light
must be resent with a
.I gSPLight (3P)
command AND the number of lights must be reset (even if it has not changed)
with a
.I gSPNumLights (3P)
command.
.PP
The best way to define static lights is to use the
.I gdSPDefLights (3P)
command followed by the
.I gSPSetLights (3P)
command (instead of using
.I gSPLight(3P)
and
.I gSPNumLights(3P)
explicitly).
.PP
.SH NOTE
Requiring a copy of the diffuse light value in the structure is
an optimization for the RSP geometry engine; lighting calculations
for vertices are processed two at a time. This optimization could
be exploited for 'special effects'.
.SH SEE ALSO
.IR gSPGeometryMode (3P)
.IR gSPSetLights (3P)
.IR gdSPDefLights (3P)
.IR gSPNumLights (3P)
.IR gSPLightColor (3P)