window.h File Reference

SNES Window/Masking System. More...

#include <snes/types.h>

Go to the source code of this file.

Macros
#define	WINDOW_1   0
	Window 1.
#define	WINDOW_2   1
	Window 2.
#define	WINDOW_ALL   0x1F
	All layers including sprites.
#define	WINDOW_ALL_BG   0x0F
	All background layers.
#define	WINDOW_LOGIC_AND   1
	AND: mask if inside window 1 AND window 2.
#define	WINDOW_LOGIC_OR   0
	OR: mask if inside window 1 OR window 2.
#define	WINDOW_LOGIC_XNOR   3
	XNOR: mask if inside both or neither window.
#define	WINDOW_LOGIC_XOR   2
	XOR: mask if inside exactly one window.
#define	WINDOW_MAIN_SCREEN   0
	Apply window to main screen.
#define	WINDOW_MASK_INSIDE   0
	invert = 0: the layer is HIDDEN inside the window, shown outside
#define	WINDOW_MASK_OUTSIDE   1
	invert = 1: the layer is HIDDEN outside the window, shown inside
#define	WINDOW_MATH   BIT(5)
	Color math (affects color blending) — the window's own bit.
#define	WINDOW_SUB_SCREEN   1
	Apply window to sub screen.

Functions
void	windowCentered (u8 window, u8 width)
	Create a centered rectangular window.
void	windowDisable (u8 window, u8 layers)
	Disable window for specified layers.
void	windowDisableAll (void)
	Disable all windows.
void	windowEnable (u8 window, u8 layers)
	Enable window for specified layers.
void	windowInit (void)
	Initialize window system.
void	windowSetInvert (u8 window, u8 layers, u8 invert)
	Set window inversion for layers.
void	windowSetLogic (u8 layer, u8 logic)
	Set logic operation for combining windows.
void	windowSetMainMask (u8 layers)
	Set main screen window masking.
void	windowSetPos (u8 window, u8 left, u8 right)
	Set window boundaries.
void	windowSetSubMask (u8 layers)
	Set sub screen window masking.
void	windowSplit (u8 splitX)
	Create a vertical split at the specified X position.

Detailed Description

SNES Window/Masking System.

Windows are rectangular regions that can mask (hide or show) portions of background layers and sprites. The SNES has two windows that can be combined using logic operations.

How Windows Work

Each window has left and right boundaries (0-255 pixel positions). Pixels inside the window are treated differently than pixels outside. Windows can be enabled independently for each layer (BG1-4, OBJ).

Window Logic

When both windows affect a layer, they can be combined:

• OR: Either window masks the pixel
• AND: Both windows must overlap to mask
• XOR: Exactly one window masks the pixel
• XNOR: Both or neither window masks the pixel

Usage Example

// Create a spotlight effect - show BG1 only inside the window
windowSetPos(WINDOW_1, 80, 176);          // Window from x=80 to x=176
windowEnable(WINDOW_1, LAYER_BG1);       // Window 1 applies to BG1
windowSetInvert(WINDOW_1, LAYER_BG1, 1); // mask OUTSIDE it = show inside
windowSetMainMask(LAYER_BG1);            // ...and let it mask the main screen

The last call is the one that makes anything happen: windowEnable() only selects which window applies to which layer; the main- / sub-screen mask (TMW / TSW) is what hides pixels. This example called a windowSetMask() that has never existed, until 2026-09-20.

Author

OpenSNES Team

Copyright

MIT License

Macro Definition Documentation

WINDOW_1

#define WINDOW_1   0

Window 1.

WINDOW_2

#define WINDOW_2   1

Window 2.

WINDOW_ALL

#define WINDOW_ALL   0x1F

All layers including sprites.

WINDOW_ALL_BG

#define WINDOW_ALL_BG   0x0F

All background layers.

WINDOW_LOGIC_AND

#define WINDOW_LOGIC_AND   1

AND: mask if inside window 1 AND window 2.

WINDOW_LOGIC_OR

#define WINDOW_LOGIC_OR   0

OR: mask if inside window 1 OR window 2.

WINDOW_LOGIC_XNOR

#define WINDOW_LOGIC_XNOR   3

XNOR: mask if inside both or neither window.

WINDOW_LOGIC_XOR

#define WINDOW_LOGIC_XOR   2

XOR: mask if inside exactly one window.

WINDOW_MAIN_SCREEN

#define WINDOW_MAIN_SCREEN   0

Apply window to main screen.

WINDOW_MASK_INSIDE

#define WINDOW_MASK_INSIDE   0

invert = 0: the layer is HIDDEN inside the window, shown outside

WINDOW_MASK_OUTSIDE

#define WINDOW_MASK_OUTSIDE   1

invert = 1: the layer is HIDDEN outside the window, shown inside

WINDOW_MATH

#define WINDOW_MATH   BIT(5)

Color math (affects color blending) — the window's own bit.

WINDOW_SUB_SCREEN

#define WINDOW_SUB_SCREEN   1

Apply window to sub screen.

Function Documentation

windowCentered()

void windowCentered	(	u8	window,
		u8	width )

Create a centered rectangular window.

Convenience function to set up a window centered on screen.

Parameters

window	Window number
width	Width in pixels (1-256)

windowDisable()

void windowDisable	(	u8	window,
		u8	layers )

Disable window for specified layers.

Parameters

window	Window number (WINDOW_1 or WINDOW_2)
layers	Layer mask

windowDisableAll()

void windowDisableAll

(

void

)

Disable all windows.

Convenience function to turn off all window effects.

windowEnable()

void windowEnable	(	u8	window,
		u8	layers )

Enable window for specified layers.

Enables a window to affect the specified layers. The window's masking behavior depends on the invert setting (see windowSetInvert).

Parameters

window	Window number (WINDOW_1 or WINDOW_2)
layers	Layer mask (LAYER_BG1, LAYER_BG2, etc.)

windowEnable(WINDOW_1, LAYER_BG1 | LAYER_OBJ);  // Affect BG1 and sprites

windowInit()

void windowInit

(

void

)

Initialize window system.

Resets all window settings to defaults (windows disabled, full screen).

windowSetInvert()

void windowSetInvert	(	u8	window,
		u8	layers,
		u8	invert )

Set window inversion for layers.

Controls whether pixels inside the window are shown or hidden.

Parameters

window	Window number (WINDOW_1 or WINDOW_2)
layers	Layer mask
invert	0 = the layer is hidden INSIDE the window (shown outside); 1 = hidden OUTSIDE (shown inside — the spotlight / iris case). Documented the other way round until 2026-09-20; arbiter: fullsnes, "2123h W12SEL" window area Inside / Outside.

windowSetLogic()

void windowSetLogic	(	u8	layer,
		u8	logic )

Set logic operation for combining windows.

When both windows affect a layer, this sets how they combine.

Parameters

layer	Single layer (LAYER_BG1, LAYER_BG2, etc.)
logic	Logic operation (WINDOW_LOGIC_*)

windowSetMainMask()

void windowSetMainMask

(

u8

layers

)

Set main screen window masking.

Controls which layers use window masking on the main screen.

Parameters

layers

Layer mask for main screen windowing

windowSetPos()

void windowSetPos	(	u8	window,
		u8	left,
		u8	right )

Set window boundaries.

Sets the left and right pixel positions for a window. Valid range is 0-255. If left > right, window is empty.

Parameters

window	Window number (WINDOW_1 or WINDOW_2)
left	Left boundary (0-255)
right	Right boundary (0-255)

windowSetPos(WINDOW_1, 64, 192);  // Window from x=64 to x=192

windowSetSubMask()

void windowSetSubMask

(

u8

layers

)

Set sub screen window masking.

Controls which layers use window masking on the sub screen.

Parameters

layers

Layer mask for sub screen windowing

windowSplit()

void windowSplit

(

u8

splitX

)

Create a vertical split at the specified X position.

Sets up Window 1 for left side, Window 2 for right side. Useful for split-screen or scene transitions.

Parameters

splitX

X position of the split (0-255)