# ccbl

Copyright (C) 1999, Nintendo of America Inc.
Copyright (C) 1998, NINTENDO Co,Ltd.

Copyright (C) 1998, MONEGI CORPORATION.

## Contents

Overview

Operation

Menu Descriptions

RSP
GEO_MODE
LIGHT_COL
FOG_POS

RDP
CYCLE_TYPE
TEX_FILTER

VI
SPECIAL FEATURES

MISC
MODEL
TEXTURE
BG_COLOR
BG_MODEL

Example Settings

Primitive Color
Texture Decal
Writing
Reflection Mapping
Specular Highlighting
Fog
Trilinear MIP Mapping
Antialiasing
Transparent Surface
Texture Edge Mode
Decal Surface
Interpenetration Modes
Particle Effects

Miscellaneous Items

Menu Rendering Mode
Near/Far-plane Clipping Values
Unsupported Combine Modes
Performance Meter
Parameters that ccbl Cannot Set

## Overview

This program was created as a means of easily learning about the Nintendo 64 RDP feature block, particularly the ColorCombiner and Blender features.

ccbl is typically started by the Windows application dptest. Work performed in ccbl cannot be saved or loaded. However, ccbl can be run by downloading it to the debugging target as a normal N64 application. It also can be run by writing it to a flash ROM Pak.

## Operation

Although two Controllers are normally used, the program can be operated with only one Controller if necessary.

Camera Operations (Controller 1)
Control Stick | Rotates model.
Z Button+Control Stick UP/DOWN | Changes camera position.

Menu Operations (Controller 1)
R Button | Turns menu ON/OFF.
Control Pad | Moves cursor.
A Button | Opens next window. Determines menu.
B Button | Closes window.
C Buttons
| Change parameters.

Changing Parameters (Controller 1)
Hexadecimal Display Parameters (e.g. changing *_COLOR )
C | Decreases value by 1.
C | Increases value by 1.
C | Decreases value by 0x10.
C | Increases value by 0x10.
L+C | Sets to minimum value.
L+C | Sets to maximum value.
Decimal Display Parameters (change FogPosition)
C | Decreases by the specified number of decimal places.
C | Increases by the specified number of decimal places.
Changing the ON/OFF parameter
C | Changes the ON/OFF (/~) Parameter.

Menu Screen Dump (Controller 2)
L Button* | Processes menu screen dump with osSyncPrintf().

Toggling Cover Value Visualization (Controller 2)
R Button | Uses RM_VISCVG to visualize cover values. See> Programming Manual, section 15.7.11.

GBI Macro Output (Controller 2)
A Button* | Processes settings parameters in GBI format (gSP*,gDP*) with osSyncPrintf().
B Button* | Processes settings parameters in GBI format (gsSP*,gsDP*) with osSyncPrintf().

* | Not supported in programs created using make DPTEST=1 and make FINAL=1.

## Menu Descriptions

RSP | Changes RSP parameters.

GEO_MODE
Changes the geometry mode and enables reflection mapping.

Related GBI functions: | g*SPSetGeometryMode()

LIGHT_COL
Changes the light color. ccbl uses all 8 of the lights that can be used in N64. ON/OFF can be implemented by setting the light color to (RGB=[0,0,0]), although RSP processing speed will vary slightly. The position of a light cannot be changed. The position and direction of the lights are as follows:

DIF1 | from camera position toward (0,0,0)
DIF2 | from (0,1,0) toward (0,0,0)
DIF3 | from (1,0,0) toward (0,0,0)
DIF4 | from (0,-1,0) toward (0,0,0)
DIF5 | from (-1,0,0) toward (0,0,0)
DIF6 | from (-1,1,1) toward (0,0,0)
DIF7 | toward (0,0,0) while describing a circular orbit that has (0,0,0) on the X-Z plane as its center
AMB | ambient light; illuminates the entire model

Related GBI functions: | g*SPLightColor()
| g*SPLight()
| g*SPSetLights()

FOG_POS
Changes the Fog position. A restriction of g*SPFogPosition() is that min must be less than max. Thus min cannot be set to a value greater than max nor max to a value less than min (min != max is OK).

Related GBI functions: | g*SPFogPosition()

RDP | Changes RDP parameters.

CYCLE_TYPE
Changes the RDP cycle type.

Related GBI functions: | g*DPSetCycleType()

CL_COMBINER->COMBINE_MD
Changes the Color Combiner setting. When the cycle type is G_CYC_1CYCLE, the parameter for the second cycle cannot be changed. The fields in the bottom two lines of the Configuration menu were provided to enable quick selection of the same settings as those of the Combine mode macros defined in gbi.h.

Related GBI functions: | g*DPSetCombineMode()
| g*DPSetCombineLERP() |

Note: | Setting the parameter to the typical setting causes the macro settings display to indicate **** NO MACRO ****. This is a ccbl specification designed to serve as a warning that the typical setting may differ from the macro setting.

CL_COMBINER->ENV_COLOR
Changes the ambient color used as an input source for the Color Combiner.

Related GBI functions: | g*DPSetEnvColor()

CL_COMBINER->PRIM_COLOR
Changes the Primitive color used as an input source for the Color Combiner.

Related GBI functions: | g*DPSetPrimColor()

BLENDER->RENDER_MODE
Changes the Render mode setting. As with COMBINE_MD, when the cycle type is G_CYC_1CYCLE, the parameter for the second cycle cannot be changed. The fields in the bottom two lines of the Configuration menu enable quick selection of the same settings as those of the Render mode macros defined in gbi.h.

Related GBI functions: | g*DPSetRenderMode()

Note: | Setting the parameter to the typical setting causes the macro settings display to indicate **** NO MACRO ****. This is a ccbl specification designed to serve as a warning that the typical setting may differ from the macro setting. Similarly, according to the ccbl specifications, the alpha comparison cannot be set with RENDER MODE when the RM_G_*_PCL_SURFACTANT setting is in effect.

For more information, see the Particle Effects example in Setting Examples.

BLENDER->BL_COLOR
Changes the Blend Color used as an input source for Blender.

Related GBI functions: | g*DPSetBlendColor()

BLENDER->FOG_COLOR
Changes the Fog Color used as an input source for Blender.

Related GBI functions: | g*DPSetFogColor()

BLENDER->CD AD AC
Changes the settings for color dithering, alpha dithering, and alpha comparison.

Related GBI functions: | g*DPSetColorDither()
| g*DPSetAlphaDither()
| g*DPSetAlphaCompare()

TEX_FILTER
Changes the texture filter settings.

Related GBI functions: | g*DPSetTextureFilter()

VI | Changes the VI parameters.

SPECIAL FEATURES
Changes the settings for VI gamma correction, gamma dithering, divot filtering, and dither filtering. Although these parameters are not directly related to the Color Combiner or Blender, they do play a large role in the N64 screen display. Thus ccbl was designed to also enable changes in these parameters.

VI does not operate completely independently. N64 does not display the original pixel values that Blender writes to the frame buffer. Rather, VI creates and displays the final colors based on the original color and cover values. Thus, where display is concerned, VI cannot be ignored.

Related GBI functions: | osViSetSpecialFeatures()

MISC | Sets the other settings.

MODEL
Changes the display model.

Model Descriptions
TETRA | A regular tetrahedron (triangular pyramid) |
CUBE | A cube |
SPHERE | A sphere |
XY-YZ | Combination of X-Y and Y-Z planes |
MOUNTAIN | Terrain |
TRIANGLE | A single triangle |
A | The letter A |
MIZO | Terrain with a ditch |
TORUS2 | A combination of two doughnuts |

TEXTURE
Changes the texture applied to the model.

Texture Descriptions
RGBA16 MARIO | The file mario.rgb located in $(ROOT)/usr/src/PR/demos/Texture/. Alpha of 1.
RGBA16 TREE | Has an alpha that allows elimination. Masked using an alpha value a bit smaller than that of the RGB image.
RGBA16 BRICK | The file brick.rgb in $(ROOT)/usr/src/PR/demos/Texture/.
RGBA16 CHECKER | Has an elimination alpha. An alpha of 1 is assigned to the white portion of the RGB image and an alpha of 0 to the black portion.
RGBA16 BRICK_MM | Designed for MIP mapping, this has a total of 6 levels of MIP mapping textures. Other textures do not allow trilinear MIP mapping to be properly represented.
RGBA32 GRADIENT | A texture with an 8-bit alpha channel.
IA16 GRADIENT | A texture for which both the intensity and alpha are 8 bits. *Garbage* in the central region.
RGBA16 REFLECT | Texture that simulates a specular map; used mainly for reflection mapping. Note that the alpha is 0 for the entire texture.
I8 HIGHLIGHT | Texture with an effect like specular highlighting. Although ccbl does not support specular highlighting, *quasi-specular highlighting* can always be displayed using reflection mapping.

Except for BRICK_MM, all textures are 3232 pixel images. gDPTextureLoadblock() transfers them to texture memory and sets tiling to 0. Texture wrapping is set by specifying st with G_TX_WRAP (wrapping).

Except in the case of BRICK_MM, gSPTexture() is given the following arguments.

gSPTexture(glistp++,0x8000, 0x8000, 0, G_TX_RENDERTILE, G_ON);

When BRICK_MM is specified,

gSPTexture(glistp++,0x8000, 0x8000, 5, G_TX_RENDERTILE, G_ON);

is used.

However, when reflection mapping is enabled, gSPTexture() is forcibly set to

gSPTexture(glistp++,(32<<6),(32 <<6), 0, G_TX_RENDERTILE, G_ON);

BG_COLOR
Changes the background color. Actually writes the specified color when the frame buffer is cleared. When IMAGE1,2 is specified, a 16-bit RGBA-format image is copied to clear the frame buffer rather than a color value.

BG_MODEL
Displays the model, unaffected by the ccbl parameters. Render mode uses G_RM_AA_ZB_OPA_SURF.

Model Descriptions
DISABLE | Disables display of the BG model.
PLANE | A simple plane. Used mainly when displaying G_RM_*_DECAL or G_RM_*_INTER.
STARS | 9 star-shaped models are distributed. Used to show the stacking relation with the display model.

## Example Settings

Cycle mode is set to 1 cycle unless otherwise indicated.

Default parameter values are used unless otherwise indicated.

The * symbol indicates settings that are required to view the effect with ccbl.

Primitive color
Displays an object using the primitive color. Set the Combine mode to PRIMITIVE.* [RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: PRIMITIVE Try changing the primitive color and see the results. [RDP]->CL_COMBINE->PRIM_COLOR

Texture Decal
Applies a texel color unchanged. Sets Combine mode to DECALRGB. * [RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: DECALRGB

Writing
Sets to a display with writing. Set the Geometry mode. Settings for [RSP]->GEO_MODE are as follows.

    +[GEO_MODE]---------+
    | G_SHADE         :O|*
    | G_LIGHTING      :O|*
    | G_SHADING_SMOOTH:O|*
    | G_ZBUFFER       :O|*
    | G_TEXTURE_GEN   :x|
    | G_TEXTURE_GEN_L :x|
    |>G_CULL_FRONT    <x|
    | G_CULL_BACK     :O|
    | G_FOG           :x|
    |- - - - - - - - - -|
    |  REFLECTION EN  :x|
    +-------------------+

Settings for Combine mode are as follows.*

[RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: SHADE

Try changing the light color and see the results.

[RSP]->LIGHT_COL

Using MODULATERGB for Combine mode enables a light to be applied to a textured object.

Reflection Map
Performs reflection mapping. Set the Geometry mode. [RSP]->The GEO_MODE setting is as follows.

    +[GEO_MODE]---------+
    | G_SHADE         :O|*
    | G_LIGHTING      :O|*
    | G_SHADING_SMOOTH:O|*
    | G_ZBUFFER       :O|*
    | G_TEXTURE_GEN   :O|*
    | G_TEXTURE_GEN_L :x|
    | G_CULL_FRONT    :x|
    | G_CULL_BACK     :O|
    | G_FOG           :x|
    |- - - - - - - - - -|
    |> REFLECTION EN  <O|*
    +-------------------+

The Combine mode setting is as follows.*

[RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: DECALRGB

Note: If reflection mapping is enabled without performing only the ccbl settings, the settings performed internally will be insufficient.

Specular Highlight
Uses reflection mapping to simulate specular highlighting. TORUS2 is used as the model so that the effect is readily seen. Select IA8 HIGHLIGHT for the texture. The Geometry mode settings used are the same as for reflection mapping.* Because reflection mapping is used, the light is assumed be located at the viewpoint. Thus, only DIF1 is used.

Light color settings are as follows.*

    +[LIGHT COLOR]--+
    |      R  G  B  |
    |DIF1: 50 50>00<|
    |DIF2: 00 00 00 |
    |DIF3: 00 00 00 |
    |DIF4: 00 00 00 |
    |DIF5: 00 00 00 |
    |DIF6: 00 00 00 |
    |DIF7: 00 00 00 |
    |AMB : 00 00 00 |
    +---------------+

The Combine mode setting is as follows.*

[RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: HILIGHTRGB

The primitive color is set to the same color as the light color.*

    +[PRIM COL]-+
    | RED  : FF |
    | GREEN: FF |
    | BLUE : 00 |
    |>ALPHA< 80 |
    |- - - - - -|
    | MIN  : 80 |
    | LOD  : 80 |
    +-----------+

The primitive color becomes the light color.

Note: | Specular highlighting can always be simulated using reflection mapping. For examples of the correct settings, see the Programming Manual.

Fog
Uses Fog. Set the Geometry mode. [RSP]->GEO_MODE settings are as follows.

    +[GEO_MODE]---------+
    | G_SHADE         :O|(*)
    | G_LIGHTING      :O|(*)
    | G_SHADING_SMOOTH:O|
    | G_ZBUFFER       :O|(*)
    | G_TEXTURE_GEN   :x|
    | G_TEXTURE_GEN_L :x|
    | G_CULL_FRONT    :x|
    | G_CULL_BACK     :x|
    | G_FOG           :O|(*)
    |- - - - - - - - - -|
    |> REFLECTION EN  <x|
    +-------------------+

The cycle type is set to 2 cycles.*

[RDP]->CYCLE_TYPE->G_CYC_2CYCLE

To make the effect readily visible, select DECALRGB as the Combine mode, CUBE as the model, and BRICK as the texture. In addition, specify the following Combine mode settings.

[RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: DECALRGB
[RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: PASS2

Set the Rendering mode.*

[RDP]->BLENDER->RENDER_MODE->CYCLE1: FOG_SHADE_A
[RDP]->BLENDER->RENDER_MODE->CYCLE2: AA_ZB_OPA_SURF2

Select the Fog color.*

[RDP]->BLENDER->FOG_COLOR settings are as follows.

    +[FOG COL]--+
    |<RED  > 80 |
    | GREEN: 80 |
    | BLUE : 80 |
    | ALPHA: 80 |
    +-----------+

Set the BG color to a color close to that of the Fog.

[MISC]->BG_COLOR->GRAY

The positions of the Fog threshold and Fog color saturation can be changed by changing the Fog position ([RSP]->FOG_POS).

Trilinear MIP Mapping
Set the cycle type to 2 cycles.* [RDP]->CYCLE_TYPE->G_CYC_2CYCLE Set the Combine mode.* [RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: TRILERP [RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: DECALRGB2

Set the Rendering mode.*

[RDP]->BLENDER->RENDER_MODE->CYCLE1: PASS
[RDP]->BLENDER->RENDER_MODE->CYCLE2: AA_ZB_OPA_SURF2

Set the texture.*

[MISC]->TEXTURE->RGBA16 BRICK_MM

Note: | ccbl specifies texture tiling internally when BRICK_MM is used as the texture.

Antialiasing
Antialiasing in N64 is ultimately performed by VI. Blender writes the antialiasing data (cover values) to the frame buffer when it writes the pixel values to that buffer. Using the G_RM_VISCVG, ccbl enables cover values to be visualized. Try changing the Blender settings and using this feature to see the types of cover values generated. The result will likely be many very interesting discoveries.

Transparent Surface
Combine mode is set as follows.* [RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: PRIM Blender mode is set as follows.* [RDP]->BLENDER->RENDER_MODE->CYCLE1: AA_ZB_XLU_SURF Change BG_COLOR so that the effect is easily seen.

[MISC]->BG_COLOR->IMAGE2

Try changing the alpha for the primitive color and see the results.

[RDP]->CL_COMBINER->PRIM_COLOR->ALPHA

Texture Edge Mode
The model and texture are set as follows. [MISC]->MODEL->CUBE [MISC]->TEXTURE->RGBA16 TREE Combine mode is set as follows.* [RDP]->CL_COMBINE->COMBINE_MODE->CYCLE1: DECALRGBA

Rendering mode is set as follows.*

[RDP]->BLENDER->RENDER_MODE->CYCLE1: AA_ZB_TEX_EDGE

Decal surface
The model is set as follows.* [MISC]->MODEL->TRIANGLE Rendering mode is set as follows.* [RDP]->BLENDER->RENDER_MODE->CYCLE1: AA_ZB_OPA_DECAL The BG model is set as follows.*

[MISC]->BG_MODEL->PLANE

Interpenetration Mode
The model is set as follows.* [MISC]->MODEL->TETRA Rendering mode is set as follows.* [RDP]->BLENDER->RENDER_MODE->CYCLE1: AA_ZB_OPA_INTER The BG model is set as follows.*

[MISC]->BG_MODEL->PLANE

Try visualizing the cover values and see how they change when the Rendering mode is AA_ZB_OPA_SURF.

Particle Effects
Rendering mode is set as follows.* [RDP]->BLENDER->RENDER_MODE->CYCLE1: AA_ZB_PCL_SURF Alpha comparison is set as follows.* [RDP]->BLENDER->CD AD AC->G_AC_DITHER

Note: | With the macros in PR/gbi.h, the alpha comparison is set automatically when the G_RM_*_PCL_SURF setting is specified. Under the ccbl specifications, the alpha comparison cannot be set while in a RENDER_MODE, so be sure to specify the alpha comparison here.

A common bug is to set the alpha comparison after the rendering mode, so that even if G_RM_*_PCL_SURF is specified as the rendering mode, it is subsequently overwritten with the alpha comparison setting.

## Miscellaneous Items

Menu Rendering Mode
The menu rendering mode used is G_RM_XLU_SURF. Because this mode uses the CVG_DIST_FULL setting, it may corrupt the cover values for the display model. For a proper display, turn off the menu display.

Near/Far-Plane Clipping Values
ccbl sets the near-plane clipping value to 500 and the far-plane clipping value to 20,000. These are not necessarily recommended values. Values that are appopriate for the application should be selected.

Unsupported Combine Modes
The Combine mode macro settings shown below are not supported. In addition, parameters for these settings have been omitted. The Color Combiner parameters can be set directly.

G_CC_TEMPLERP
G_CC_1CYUV2RGB
G_CC_YUV2RGB
G_CC_CHROMA_KEY2

Performance Meter
The nuDebTaskPerfBar1() function of NuSystem is used as the performance meter. For information on the performance meter, see the NuSysytem documentation. The performance meter includes not only the model display time but also latencies such as the time for frame buffer clearing and menu display.

Parameters that ccbl Cannot Set
ccbl cannot be used to set items that are not closely related to Color Combiner and Blender. In developing an actual application, setting only those parameters that can be set by ccbl will not produce a proper display. Please use the documentation and sample source code available as references.