SNES Color Math (Blending/Transparency). More...

#include <snes/types.h>
#include <snes/registers.h>

Macros
#define	COLDATA_ALL (COLDATA_RED \| COLDATA_GREEN \| COLDATA_BLUE)
	Apply fixed color to all channels.
#define	COLDATA_BLUE 0x80
	Apply fixed color to blue channel.
#define	COLDATA_GREEN 0x40
	Apply fixed color to green channel.
#define	COLDATA_RED 0x20
	Apply fixed color to red channel.
#define	COLORMATH_ADD 0
	Add colors (brightens).
#define	COLORMATH_ALL 0x3F
	Apply color math to all layers.
#define	COLORMATH_ALWAYS 0
	Always enable color math.
#define	COLORMATH_BACKDROP BIT(5)
	Apply color math to backdrop (color 0).
#define	COLORMATH_BG1 BIT(0)
	Apply color math to BG1.
#define	COLORMATH_BG2 BIT(1)
	Apply color math to BG2.
#define	COLORMATH_BG3 BIT(2)
	Apply color math to BG3.
#define	COLORMATH_BG4 BIT(3)
	Apply color math to BG4.
#define	COLORMATH_INSIDE 1
	Enable inside window only.
#define	COLORMATH_NEVER 3
	Never enable color math.
#define	COLORMATH_OBJ BIT(4)
	Apply color math to sprites (OBJ).
#define	COLORMATH_OUTSIDE 2
	Enable outside window only.
#define	COLORMATH_SRC_FIXED 1
	Use fixed color as color source.
#define	COLORMATH_SRC_SUBSCREEN 0
	Use sub screen as color source.
#define	COLORMATH_SUB 1
	Subtract colors (darkens).

Functions
void	colorMathDisable (void)
	Disable all color math.
void	colorMathEnable (u8 layers)
	Enable color math for specified layers.
void	colorMathInit (void)
	Initialize color math to defaults.
void	colorMathSetBrightness (u8 brightness)
	Set brightness for fade effects.
void	colorMathSetChannel (u8 channel, u8 intensity)
	Set a single fixed color channel.
void	colorMathSetCondition (u8 condition)
	Set when color math is enabled (window control).
void	colorMathSetDirectColor (u8 enable)
	Enable or disable direct color mode (CGWSEL bit 0).
void	colorMathSetFixedColor (u8 r, u8 g, u8 b)
	Set fixed color for blending.
void	colorMathSetHalf (u8 enable)
	Enable or disable half mode.
void	colorMathSetOp (u8 op)
	Set color math operation (add or subtract).
void	colorMathSetSource (u8 source)
	Set color math source.
void	colorMathShadow (u8 layers, u8 intensity)
	Set up shadow/darkening effect.
void	colorMathTint (u8 layers, u8 r, u8 g, u8 b)
	Set up color tint effect.
void	colorMathTransparency50 (u8 layers)
	Set up 50% transparency for layers.

Variables
u8	cgadsub
u8	cgwsel

Detailed Description

SNES Color Math (Blending/Transparency).

Color math enables blending between the main screen and sub screen or a fixed color. This creates effects like transparency, shadows, fading, and underwater tints.

How Color Math Works

The SNES can add or subtract colors:

Add: Main screen + Sub screen (or fixed color) = brighter
Subtract: Main screen - Sub screen (or fixed color) = darker

Half mode divides the result by 2, useful for 50% transparency.

Main Screen vs Sub Screen

Main screen: Primary display (what you normally see)
Sub screen: Secondary layer used for blending

For transparency, put the background on main screen and the transparent layer on sub screen.

Usage Example

// 50% transparent BG2 over BG1
REG_TM = TM_BG1 | TM_BG2;   // Both on main screen
REG_TS = TM_BG2;            // BG2 also on sub screen
 
colorMathEnable(COLORMATH_BG2);  // Apply math to BG2
colorMathSetOp(COLORMATH_ADD);   // Add mode
colorMathSetHalf(1);              // Divide by 2 = 50%
colorMathSetSource(COLORMATH_SRC_SUBSCREEN);  // Blend with sub screen

// Fade to black
colorMathSetFixedColor(0, 0, 0);  // Black
colorMathSetSource(COLORMATH_SRC_FIXED);
colorMathSetOp(COLORMATH_SUB);    // Subtract = darken
colorMathEnable(COLORMATH_ALL);   // Apply to all layers

Author: OpenSNES Team

Copyright: MIT License

Macro Definition Documentation

◆ COLDATA_ALL

#define COLDATA_ALL (COLDATA_RED | COLDATA_GREEN | COLDATA_BLUE)

Apply fixed color to all channels.

◆ COLDATA_BLUE

#define COLDATA_BLUE 0x80

Apply fixed color to blue channel.

◆ COLDATA_GREEN

#define COLDATA_GREEN 0x40

Apply fixed color to green channel.

◆ COLDATA_RED

#define COLDATA_RED 0x20

Apply fixed color to red channel.

◆ COLORMATH_ADD

#define COLORMATH_ADD 0

Add colors (brightens).

◆ COLORMATH_ALL

#define COLORMATH_ALL 0x3F

Apply color math to all layers.

◆ COLORMATH_ALWAYS

#define COLORMATH_ALWAYS 0

Always enable color math.

◆ COLORMATH_BACKDROP

#define COLORMATH_BACKDROP BIT(5)

Apply color math to backdrop (color 0).

◆ COLORMATH_BG1

#define COLORMATH_BG1 BIT(0)

Apply color math to BG1.

◆ COLORMATH_BG2

#define COLORMATH_BG2 BIT(1)

Apply color math to BG2.

◆ COLORMATH_BG3

#define COLORMATH_BG3 BIT(2)

Apply color math to BG3.

◆ COLORMATH_BG4

#define COLORMATH_BG4 BIT(3)

Apply color math to BG4.

◆ COLORMATH_INSIDE

#define COLORMATH_INSIDE 1

Enable inside window only.

◆ COLORMATH_NEVER

#define COLORMATH_NEVER 3

Never enable color math.

◆ COLORMATH_OBJ

#define COLORMATH_OBJ BIT(4)

Apply color math to sprites (OBJ).

◆ COLORMATH_OUTSIDE

#define COLORMATH_OUTSIDE 2

Enable outside window only.

◆ COLORMATH_SRC_FIXED

#define COLORMATH_SRC_FIXED 1

Use fixed color as color source.

◆ COLORMATH_SRC_SUBSCREEN

#define COLORMATH_SRC_SUBSCREEN 0

Use sub screen as color source.

◆ COLORMATH_SUB

#define COLORMATH_SUB 1

Subtract colors (darkens).

Function Documentation

◆ colorMathDisable()

void colorMathDisable ( void )

inline

Disable all color math.

Inlined for zero-call-overhead access.

◆ colorMathEnable()

void colorMathEnable ( u8 layers )

inline

Enable color math for specified layers.

Enables color math blending for the given layers. Inlined for zero-call-overhead access (wave 4 retrofit).

Parameters

layers Layer mask (COLORMATH_BG1, COLORMATH_BG2, etc.)

◆ colorMathInit()

void colorMathInit ( void )

inline

Initialize color math to defaults.

Disables all color math effects. Inlined for zero-call-overhead.

◆ colorMathSetBrightness()

void colorMathSetBrightness ( u8 brightness )

Set brightness for fade effects.

Sets the fixed color for use in fading. Use with colorMathSetOp() to fade to white (add) or black (subtract).

Parameters

brightness Fade level (0 = no effect, 31 = full white/black)

◆ colorMathSetChannel()

void colorMathSetChannel	(	u8	channel,
		u8	intensity )

Set a single fixed color channel.

Parameters

channel	Channel mask (COLDATA_RED, COLDATA_GREEN, COLDATA_BLUE)
intensity	Intensity (0-31)

◆ colorMathSetCondition()

void colorMathSetCondition ( u8 condition )

Set when color math is enabled (window control).

Parameters

condition COLORMATH_ALWAYS, COLORMATH_INSIDE, COLORMATH_OUTSIDE, or COLORMATH_NEVER

◆ colorMathSetDirectColor()

void colorMathSetDirectColor ( u8 enable )

Enable or disable direct color mode (CGWSEL bit 0).

In direct color mode the PPU stops looking 256-color (8bpp) BG pixels up in CGRAM: the tile's pixel byte IS the color, interpreted as BBGGGRRR (2 bits blue, 3 green, 3 red) and expanded to 15-bit BGR by shifting each field left — B: bits 7-6 -> color bits 14-13, G: bits 5-3 -> 9-7, R: bits 2-0 -> 4-2. The tilemap entry's palette bits stop selecting a palette and instead supply one extra LOW bit per channel (pal bit 0 -> red bit 1, pal bit 1 -> green bit 6, pal bit 2 -> blue bit 12), for 2048 distinct colors with no CGRAM cost.

Only affects 8bpp layers: BG1 in modes 3/4 and the Mode 7 layer (EXTBG included). 2/4bpp layers and sprites keep using CGRAM, so a HUD or sprite palette coexists untouched. Worked example: examples/graphics/effects/direct_color (the same VRAM bytes drawn both ways).

Parameters

enable 1 = pixel bytes are colors, 0 = CGRAM lookup (default)

◆ colorMathSetFixedColor()

void colorMathSetFixedColor	(	u8	r,
		u8	g,
		u8	b )

Set fixed color for blending.

Sets the fixed color used when source is COLORMATH_SRC_FIXED.

Parameters

r	Red intensity (0-31)
g	Green intensity (0-31)
b	Blue intensity (0-31)

◆ colorMathSetHalf()

void colorMathSetHalf ( u8 enable )

Enable or disable half mode.

When enabled, the color math result is divided by 2. This creates 50% transparency/blending.

Parameters

enable 1 = divide by 2, 0 = full result

◆ colorMathSetOp()

void colorMathSetOp ( u8 op )

Set color math operation (add or subtract).

Parameters

op	Operation (COLORMATH_ADD or COLORMATH_SUB)

◆ colorMathSetSource()

void colorMathSetSource ( u8 source )

Set color math source.

Chooses whether to blend with the sub screen or a fixed color.

Parameters

source COLORMATH_SRC_SUBSCREEN or COLORMATH_SRC_FIXED

◆ colorMathShadow()

void colorMathShadow	(	u8	layers,
		u8	intensity )

Set up shadow/darkening effect.

Subtracts fixed color from layers to darken them.

Parameters

layers	Layers to darken
intensity	Darkness level (0-31, higher = darker)

◆ colorMathTint()

void colorMathTint	(	u8	layers,
		u8	r,
		u8	g,
		u8	b )

Set up color tint effect.

Adds a fixed color tint to layers.

Parameters

layers	Layers to tint
r	Red tint (0-31)
g	Green tint (0-31)
b	Blue tint (0-31)

◆ colorMathTransparency50()

void colorMathTransparency50 ( u8 layers )

Set up 50% transparency for layers.

Quick setup for semi-transparent layers. The transparent layers should be on both main and sub screen.

Parameters

layers Layers to make 50% transparent

Note: You must also set REG_TS to include the transparent layers

Variable Documentation

◆ cgadsub

u8 cgadsub

extern

◆ cgwsel

u8 cgwsel

extern

Macros

Functions

Variables

Detailed Description

How Color Math Works

Main Screen vs Sub Screen

Usage Example

Macro Definition Documentation

◆ COLDATA_ALL

◆ COLDATA_BLUE

◆ COLDATA_GREEN

◆ COLDATA_RED

◆ COLORMATH_ADD

◆ COLORMATH_ALL

◆ COLORMATH_ALWAYS

◆ COLORMATH_BACKDROP

◆ COLORMATH_BG1

◆ COLORMATH_BG2

◆ COLORMATH_BG3

◆ COLORMATH_BG4

◆ COLORMATH_INSIDE

◆ COLORMATH_NEVER

◆ COLORMATH_OBJ

◆ COLORMATH_OUTSIDE

◆ COLORMATH_SRC_FIXED

◆ COLORMATH_SRC_SUBSCREEN

◆ COLORMATH_SUB

Function Documentation

◆ colorMathDisable()

◆ colorMathEnable()

◆ colorMathInit()

◆ colorMathSetBrightness()

◆ colorMathSetChannel()

◆ colorMathSetCondition()

◆ colorMathSetDirectColor()

◆ colorMathSetFixedColor()

◆ colorMathSetHalf()

◆ colorMathSetOp()

◆ colorMathSetSource()

◆ colorMathShadow()

◆ colorMathTint()

◆ colorMathTransparency50()

Variable Documentation

◆ cgadsub

◆ cgwsel