.TH gDPSet*Color 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gDPSetPrimColor, gsDPSetPrimColor,
gDPSetEnvColor, gsDPSetEnvColor,
gDPSetFogColor, gsDPSetFogColor,
gDPSetBlendColor, gsDPSetBlendColor
\- set environment, primitive, blend, fog and fill color in RDP.
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

gDPSetPrimColor(Gfx *gdl,
			unsigned int m,
			unsigned int l,
			unsigned int r,
			unsigned int g,
			unsigned int b,
			unsigned int a)

gsDPSetPrimColor(unsigned int m,
			unsigned int l,
			unsigned int r,
			unsigned int g,
			unsigned int b,
			unsigned int a)

gDPSetEnvColor(Gfx *gdl,
			unsigned int r,
			unsigned int g,
			unsigned int b,
			unsigned int a)

gsDPSetEnvColor(unsigned int r,
			unsigned int g,
			unsigned int b,
			unsigned int a)

gDPSetFogColor(Gfx *gdl,
			unsigned int r,
			unsigned int g,
			unsigned int b,
			unsigned int a)

gsDPSetFogColor(unsigned int r,
			unsigned int g,
			unsigned int b,
			unsigned int a)

gDPSetBlendColor(Gfx *gdl,
			unsigned int r,
			unsigned int g,
			unsigned int b,
			unsigned int a)

gsDPSetBlendColor(unsigned int r,
			unsigned int g,
			unsigned int b,
			unsigned int a)

GPACK_RGBA5551(r, g, b, a)
GPACK_ZDZ(z, dz)

gDPSetFillColor(Gfx *gdl, unsigned int c)

gsDPSetFillColor(unsigned int c)

\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I c
32 bit color value.
.TP
.I r, g, b, a
RGBA color component. 8 bits of precision each.
.TP
.I m
minimum value clamp for LOD < 1.0. In .8 format.
When LOD < 1.0, it is used to modulate between highest resolution map and the detail texture if enabled.
m sets a clamp to prevent the detailed texture from completely overtaking the original face texture.
.TP
.I l
LOD fraction. In .8 format.
.SH DESCRIPTION
These commands set RDP internal color registers.
The environment and primitive color are in the color combiner.
The fog and blend color are in the blender.
The fill color is in the memory interface.
.PP
The primitive color is a general-purpose color register in the CC.
For example, it can be used to represent a constant flatshaded face
color applied to a primitive. The primitive color register is also
used in rendering a specular highlight. The texture map for a specular
highlight determines the highlight intensity and the content of the
primitive color register determines the highlight color.
.PP
The fog color is a color register in the BL.  The Nintendo64 does fog by
Gouraud shading the fog decay coefficient in the alpha channel of the
RDP pipeline, with the BL using the decay to modulate the pipeline
pixel color against an ambient fog color.  Since the RDP pipeline's
alpha channel is used for Gouraud shading fog decay coefficients, it is
not possible to Gouraud shade the normal alpha values.  This means
that you cannot do variable transparency within a single triangle
while using fog.  You can still do constant transparency within a
triangle by configuring the BL to use
.I gDPSetBlendColor.
Also keep in mind that Gouraud shading of fog decay coefficient over a
large screen pixel distance will result in unrealistic fog.  This is
because fog decays exponentially, not linearly.  You can fix this by
breaking up large geometry into piecewise linear sections to approximate
exponential decay.
.PP
The environment color is a general-purpose color register in the CC.
For example, it could be used to represent the ambient color of your
scene. In an additional use, the LOD fraction could be used to modulate
between texel color and environment color. This can keep the RDP pipeline
in 1 cycle mode and does a cheap 2 map mipmap, working well with any low
frequency textures where the middle maps in a mipmap might not be so useful.
The environment color register is also used in rendering a second
specular highlight. The texture map for a specular highlight determines
the highlight intensity and the content of the environment color
register determines the color of the second highlight.
.PP
The 32 bit fill color is used only in fill mode.  Since the hardware
writes 64 bits per clock in fill mode, the 32 bit color data
represents 2 pixels, which are replicated to be a block of 4 pixels.
The details of how 32 bits fill into 4 18 bit pixels are described in
the "RDP State Machine" chapter of the
.I NU64 Programming Manual.
(Note that composing the 32 bit fill
color out of two different 16 bit pixels could be used for 'special
effects').
.PP
There are two macros that help pack colors for color or zbuffer fill.
\fBGPACK_RGBA5551(r, g, b, a)\fP and \fBGPACK_ZDZ(z, dz)\fP pack a 16 bit color for clearing these two buffers respectively.
The maximum zbuffer value is \fBG_MAXFBZ\fP.
Keep in mind these macros return 16 bits and must be duplicated for the 32 bit fill color.
.PP
The blend color is a general-purpose color register in the BL.  For
example, it could be used to set the alpha component for constant
transparency of an object while using fog.  The alpha component is
also used as a threshhold value for conditional writes to the
framebuffer.
.PP
.I gDPSetFillColor
can be used to clear color and zbuffers.  Clearing Z requires that the
color buffer pointer is set to equal to z buffer pointer prior to
issuing the gDPSetFillColor command.
.SH NOTE
To do fog, the RSP graphics microcode must generate fog decay coefficients in the alpha channel. See
.IR gSPSetGeometryMode (3P)
.
.SH SEE ALSO
.IR gDPFillRectangle (3P)
.IR gDPSetCycleType (3P)
.IR gDPSetCombineMode (3P)
.IR gDPSetRenderMode (3P)
.IR gDPSetAlphaCompare (3P)