N64 Functions Reference (HTML Manual Pages) Function Page

N64^® Functions Menu

al - Audio Library Functions

gDP - DP GBI Macros

gdSP - General GBI Macros

gSP - SP GBI Macros

gt - Turbo Microcode RDP

gu - Graphics Utilities

Math - Math Functions

nuSys - NuSystem

os - N64 Operating System

sp - Sprite Library Functions

uh - Host to Target IO

64DD - N64 Disk Drive

Nintendo^® Confidential

Color-Setting Functions

Format

#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)

Arguments

gdl is the pointer to the graphics display list
c is the 32-bit color value
r, g, b, a specify the RGBA color component with 8 bits of precision each
m is the minimum value clamp for LOD < 1.0 in .8 format. When LOD is less than 1.0, it is used to modulate between the highest resolution map and the detail texture if enabled. This argument (m) sets a clamp to prevent the detailed texture from completely overtaking the original face texture
lis the LOD fraction in .8 format

What These Macros Do
These macros set the RDP internal color registers. They include the following macros:

gDPSetPrimColor
gDPSetEnvColor
gDPSetFillColor
gDPSetFogColor
gDPSetBlendColor

Each of these also has a static version:

gsDPSetPrimColor
gsDPSetEnvColor
gsDPSetFillColor
gsDPSetFogColor
gsDPSetBlendColor

The environment and primitive colors are in the color combiner (CC). The fog and blend colors are in the blender (BL). The fill color is in the memory interface.

The primitive color is a general-purpose color register in the CC. For example, it can be used to represent a constant flat-shaded 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.

The fog color is a color register in the BL. The N64 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. Because 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 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.

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 MIP map, working well with any low frequency textures where the middle maps in a MIP map 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.

The 32-bit fill color is used only in fill mode. Because the hardware writes 64 bits per clock in fill mode, the 32-bit color data represents two pixels, which are replicated to be a block of four pixels. The details of how 32 bits fill into four 18-bit pixels are described in the "RDP State Machine" chapter of the N64 Programming Manual. (Note that composing the 32-bit fill color out of two different 16-bit pixels could be used for special effects).

There are two macros that help pack colors for color or Z-Buffer fill. GPACK_RGBA5551(r, g, b, a) and GPACK_ZDZ(z, dz) pack a 16-bit color for clearing these two buffers respectively. The maximum Z-Buffer value is G_MAXFBZ. Keep in mind these macros return 16 bits and must be duplicated for the 32-bit fill color.

The blend color is a general-purpose color register in the BL. For example, you could use it to set the alpha component for constant transparency of an object while using fog. The alpha component can also be used as a threshold value for conditional writes to the framebuffer.

Use gDPSetFillColor to clear color and Z-Buffers. Clearing Z requires that the pointer to the color buffer be set to equal the pointer to the z buffer prior to calling the gDPSetFillColor macro.

Note
To do fog, the RSP graphics microcode must generate fog decay coefficients in the alpha channel. See gSPSetGeometryMode.

See Also
gDPFillRectangle
gDPSetCycleType
gDPSetCombineMode
gDPSetRenderMode
gDPSetAlphaCompare

Nintendo^® Confidential

Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility.

Copyright © 1998
Nintendo of America Inc. All rights reserved
Nintendo and N64 are registered trademarks of Nintendo
Last updated January 1998