video.h File Reference

SNES Video / PPU Functions. More...

#include <snes/types.h>

Go to the source code of this file.

Macros
#define	BG3_MODE1_PRIORITY_HIGH   0x08
#define	BG_MODE0   0
#define	BG_MODE1   1
#define	BG_MODE2   2
#define	BG_MODE3   3
#define	BG_MODE4   4
#define	BG_MODE5   5
#define	BG_MODE6   6
#define	BG_MODE7   7
#define	LAYER_BG1   0x01
#define	LAYER_BG2   0x02
#define	LAYER_BG3   0x04
#define	LAYER_BG4   0x08
#define	LAYER_OBJ   0x10
#define	RGB(r, g, b)
	Create RGB color value.
#define	RGB24(r, g, b)
	Convert 24-bit RGB to SNES format.
#define	SCREEN_HEIGHT   224
	Visible screen height in pixels (NTSC, 224 lines).
#define	SCREEN_WIDTH   256
	Visible screen width in pixels.
#define	setColor(index, color)
	Set a single CGRAM color.
#define	setMainScreen(layers)
	Enable layers on the main screen.
#define	setSubScreen(layers)
	Enable layers on the sub screen.

Functions
void	setMode (u8 mode, u8 flags)
	Set background mode.
void	videoSetInterlace (u8 on)
	Enable/disable screen interlace (SETINI bit 0).
void	videoSetObjInterlace (u8 on)
	Enable/disable sprite interlace (SETINI bit 1).
void	videoSetOverscan (u8 on)
	Enable/disable overscan (SETINI bit 2).
void	videoSetPseudoHires (u8 on)
	Enable/disable pseudo-hires (SETINI bit 3).

Detailed Description

SNES Video / PPU Functions.

Low-level video functions for PPU control, palette management, and screen modes.

Author

OpenSNES Team

Copyright

MIT License

Macro Definition Documentation

RGB

#define RGB	(		r,
			g,
			b )

Value:

((((b) & 31) << 10) | (((g) & 31) << 5) | ((r) & 31))

Create RGB color value.

Parameters

r	Red (0-31; masked to 5 bits)
g	Green (0-31; masked to 5 bits)
b	Blue (0-31; masked to 5 bits)

Returns

15-bit BGR color

Note

Operands are masked to 5 bits so an out-of-range component can't bleed into the neighbouring channel. With constant arguments (every call site in the SDK) the masks fold away at compile time — zero cost.

RGB24

#define RGB24	(		r,
			g,
			b )

Value:

RGB((r) >> 3, (g) >> 3, (b) >> 3)

Convert 24-bit RGB to SNES format.

Parameters

r	Red (0-255)
g	Green (0-255)
b	Blue (0-255)

Returns

15-bit BGR color

SCREEN_HEIGHT

#define SCREEN_HEIGHT   224

Visible screen height in pixels (NTSC, 224 lines).

SCREEN_WIDTH

#define SCREEN_WIDTH   256

Visible screen width in pixels.

setColor

#define setColor	(		index,
			color )

Value:

    do { \
    REG_CGADD = (u8)(index); \
    REG_CGDATA = (u8)((color) & 0xFF); \
    REG_CGDATA = (u8)(((color) >> 8) & 0xFF); \
} while(0)

Set a single CGRAM color.

Writes a 15-bit BGR color to the specified palette index. Works during VBlank or force blank only.

Parameters

index	Color index (0-255)
color	15-bit BGR color (use RGB() or RGB24() macros)

setColor(0, RGB(0, 0, 0));        // Color 0 = black
setColor(1, RGB(31, 31, 31));     // Color 1 = white
setColor(128, RGB(31, 0, 0));     // Sprite palette 0, color 0 = red

setMainScreen

#define setMainScreen

(

layers

)

Value:

(REG_TM = (u8)(layers))

Enable layers on the main screen.

Sets which layers are visible on the main screen (REG_TM $212C). Forgetting to call this (or set REG_TM directly) is the #1 cause of blank screens after consoleInit().

Parameters

layers

OR'd combination of LAYER_BG1..LAYER_OBJ

setMainScreen(LAYER_BG1 | LAYER_OBJ);   // Show BG1 + sprites
setMainScreen(LAYER_BG1 | LAYER_BG2);   // Show BG1 + BG2

setSubScreen

#define setSubScreen

(

layers

)

Value:

(REG_TS = (u8)(layers))

Enable layers on the sub screen.

Sets which layers are visible on the sub screen (REG_TS $212D). The sub screen is used as the second operand for color math.

Parameters

layers

OR'd combination of LAYER_BG1..LAYER_OBJ

setSubScreen(LAYER_BG2);  // BG2 as color math source

Function Documentation

setMode()

void setMode	(	u8	mode,
		u8	flags )

Set background mode.

Parameters

mode	Background mode (BG_MODE0-BG_MODE7), optionally OR'd with priority flags

Mode overview:

• 0: 4 BG layers, 4 colors each
• 1: 2 BG 16-color, 1 BG 4-color (most common)
• 7: Mode 7 rotation/scaling

Note

consoleInit() sets BG1 tilemap at VRAM $0400 and tile data at $0000. Use bgSetMapPtr() and bgSetGfxPtr() to customize after setMode().

// Mode 1 with BG3 having high priority (for HUD overlay)
setMode(BG_MODE1, BG3_MODE1_PRIORITY_HIGH);

videoSetInterlace()

void videoSetInterlace

(

u8

on

)

Enable/disable screen interlace (SETINI bit 0).

With BG Mode 5/6 this doubles the vertical resolution to 448 visible lines (the PPU alternates odd/even fields). Modes 5/6 also render 512 pixels horizontally and use 16x8 tiles.

Warning

Hi-res/interlace content displays through BOTH screens: enable the layer on the MAIN and SUB screen (setMainScreen(LAYER_BG1); setSubScreen(LAYER_BG1);) or the odd columns/fields stay blank — the classic Mode 5 trap.

Parameters

on	1 to enable, 0 to disable

videoSetObjInterlace()

void videoSetObjInterlace

(

u8

on

)

Enable/disable sprite interlace (SETINI bit 1).

In interlace mode, sprites are halved vertically and rendered per field — doubles apparent sprite vertical resolution.

Parameters

on	1 to enable, 0 to disable

videoSetOverscan()

void videoSetOverscan

(

u8

on

)

Enable/disable overscan (SETINI bit 2).

Extends the visible frame from 224 to 239 lines (PAL-style height on NTSC). VBlank starts at line 240 instead of 225 — the VBlank budget for DMA shrinks by ~15 lines.

Warning

The SDK's NMI handler assumes the standard 224-line frame for its DMA budget guidance; with overscan on, heavy per-frame VRAM transfers may no longer fit VBlank. The lib does not adjust anything automatically.

Parameters

on	1 to enable, 0 to disable

videoSetPseudoHires()

void videoSetPseudoHires

(

u8

on

)

Enable/disable pseudo-hires (SETINI bit 3).

Renders 512 horizontal pixels in ANY BG mode by alternating main and sub screen pixels — the poor man's Mode 5 (used for cross-fade blend effects). Configure the sub screen layers before enabling.

Parameters

on	1 to enable, 0 to disable