mosaic.h File Reference

SNES Mosaic Effects. More...

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

Go to the source code of this file.

Macros
#define	MOSAIC_BG_ALL   0x0F
#define	MOSAIC_MAX   15
#define	MOSAIC_MIN   0

Functions
void	mosaicDisable (void)
	Disable mosaic effect for all backgrounds.
void	mosaicFadeIn (u8 speed)
	Animate mosaic fade in (pixelated -> clear).
void	mosaicFadeOut (u8 speed)
	Animate mosaic fade out (clear -> pixelated).
u8	mosaicGetSize (void)
	Get current mosaic size.
void	mosaicInit (void)
	Initialize mosaic system.
void	mosaicSetLayers (u8 bgMask)
	Set the backgrounds the mosaic applies to — REPLACES the previous set.
void	mosaicSetSize (u8 size)
	Set mosaic pixel block size.

Detailed Description

SNES Mosaic Effects.

Mosaic is a PPU effect that pixelates backgrounds, commonly used for:

• Screen transitions (fade to mosaic, then change scene)
• Damage/death effects
• Retro visual styles

Hardware: Register $2106 (MOSAIC)

• Bits 7-4: Mosaic size (0-15, block size = value + 1 pixels)
• Bit 3: Enable mosaic for BG4
• Bit 2: Enable mosaic for BG3
• Bit 1: Enable mosaic for BG2
• Bit 0: Enable mosaic for BG1

Author

OpenSNES Team

Copyright

MIT License

Macro Definition Documentation

MOSAIC_BG_ALL

#define MOSAIC_BG_ALL   0x0F

Enable mosaic for all backgrounds

MOSAIC_MAX

#define MOSAIC_MAX   15

Maximum mosaic (16x16 pixel blocks)

MOSAIC_MIN

#define MOSAIC_MIN   0

Minimum mosaic (1x1, no visible effect)

Function Documentation

mosaicDisable()

void mosaicDisable

(

void

)

Disable mosaic effect for all backgrounds.

mosaicFadeIn()

void mosaicFadeIn

(

u8

speed

)

Animate mosaic fade in (pixelated -> clear).

Smoothly decreases mosaic from current level to 0. Blocks until animation completes.

Parameters

speed

Frames to wait between steps (1 = fast, higher = slower)

Example:

mosaicSetSize(MOSAIC_MAX);
mosaicSetLayers(LAYER_BG1 | LAYER_BG2 | LAYER_BG3 | LAYER_BG4);
mosaicFadeIn(2);  // Reveal screen over ~30 frames

mosaicFadeOut()

void mosaicFadeOut

(

u8

speed

)

Animate mosaic fade out (clear -> pixelated).

Smoothly increases mosaic from current level to maximum. Blocks until animation completes.

Parameters

speed

Frames to wait between steps (1 = fast, higher = slower)

Example:

mosaicSetLayers(LAYER_BG1 | LAYER_BG2 | LAYER_BG3 | LAYER_BG4);
mosaicFadeOut(2);  // Pixelate screen over ~30 frames
loadNewLevel();
mosaicFadeIn(2);   // Reveal new content

mosaicGetSize()

u8 mosaicGetSize

(

void

)

Get current mosaic size.

Returns

Current mosaic size (0-15)

mosaicInit()

void mosaicInit

(

void

)

Initialize mosaic system.

Disables all mosaic effects. Call this once during setup.

mosaicSetLayers()

void mosaicSetLayers

(

u8

bgMask

)

Set the backgrounds the mosaic applies to — REPLACES the previous set.

mosaicSetLayers(LAYER_BG1) after mosaicSetLayers(LAYER_BG2) leaves only BG1 pixelated. This is the function the removed mosaicEnable() was (renamed 2026-09-22, removed 2026-10-05) because "Enable" reads as additive — windowEnable() IS additive — and the old name silently undid the previous call.

Parameters

bgMask

Bitmask of backgrounds (LAYER_BG1 | LAYER_BG2 | ...; 0 disables, like mosaicDisable())

Example:

mosaicSetLayers(LAYER_BG1 | LAYER_BG2);  // BG1 and BG2, nothing else
mosaicSetLayers(MOSAIC_BG_ALL);            // every background

mosaicSetSize()

void mosaicSetSize

(

u8

size

)

Set mosaic pixel block size.

Parameters

size	Mosaic level (0-15) 0 = 1x1 pixels (no visible effect) 15 = 16x16 pixel blocks (maximum pixelation)

Note: a background must be selected with mosaicSetLayers() to see the effect.