console.h File Reference

SNES Console Initialization and Core Functions. More...

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

Go to the source code of this file.

Functions
void	consoleInit (void)
	Initialize SNES hardware.
void	consoleInitEx (u16 options)
	Initialize console with options.
void	fadeIn (u8 speed)
	Fade the screen from black (0) up to full brightness (15).
void	fadeOut (u8 speed)
	Fade the screen from full brightness (15) down to black (0).
u8	getBrightness (void)
u16	getFrameCount (void)
	Get frame counter.
u8	getRegion (void)
	Get system region.
u8	isInVBlank (void)
	Check if currently in VBlank.
u8	isPAL (void)
	Check if PAL system.
u16	rand (void)
	Get random 16-bit number.
void	resetFrameCount (void)
	Reset frame counter.
void	setBrightness (u8 brightness)
	Set screen brightness.
void	setScreenOff (void)
void	setScreenOn (void)
	Enable screen display.
void	srand (u16 seed)
	Seed random number generator.
void	WaitForVBlank (void)
	Wait for next VBlank period.

Variables
u8	current_brightness
	Get current brightness.
u8	force_blanked
	Disable screen display (blank).

Detailed Description

SNES Console Initialization and Core Functions.

Provides functions for initializing SNES hardware and core functionality like VBlank synchronization.

Basic Usage

#include <snes.h>
 
int main(void) {
    // Initialize hardware
    consoleInit();
 
    // Set up your game...
 
    // Main game loop
    while (1) {
        // Wait for VBlank (required for stable graphics)
        WaitForVBlank();
 
        // Update game logic
        // Handle input
        // Update sprites/backgrounds
    }
}

Attribution

Originally from: PVSnesLib (https://github.com/alekmaul/pvsneslib) Author: Alekmaul License: zlib (compatible with MIT) Modifications:

• Renamed functions for clarity
• Added comprehensive documentation

Author

OpenSNES Team

Copyright

MIT License

Function Documentation

consoleInit()

void consoleInit

(

void

)

Initialize SNES hardware.

Must be called at the start of your program. Performs:

• PPU initialization (screen blank, registers cleared)
• CPU register setup
• Work RAM clearing
• Default palette loading
• VBlank interrupt setup

After calling, screen is blanked (black). Call setScreenOn() to enable display after you've set up your graphics.

int main(void) {
    consoleInit();
 
    // Load graphics...
    // Set up sprites...
 
    setScreenOn();  // Now show the screen
 
    while (1) {
        WaitForVBlank();
    }
}

consoleInitEx()

void consoleInitEx

(

u16

options

)

Initialize console with options.

Advanced initialization with configuration options.

Parameters

options

Initialization flags (reserved for future use)

Note

For most games, use consoleInit() instead.

fadeIn()

void fadeIn

(

u8

speed

)

Fade the screen from black (0) up to full brightness (15).

Symmetric counterpart to fadeOut. Steps INIDISP brightness from 0 → 15, waiting speed VBlank frames between each step.

Parameters

speed

VBlank frames to wait between steps (see fadeOut for the wall-clock cost at common values).

fadeOut()

void fadeOut

(

u8

speed

)

Fade the screen from full brightness (15) down to black (0).

Steps INIDISP brightness from 15 → 0, waiting speed VBlank frames between each step. Final state: setBrightness(0) (visually black, screen still rendering). Combine with setScreenOff() afterwards if you want to also enter force-blank for safe VRAM updates.

At 60 fps (NTSC):

• speed=1 → 16 frames (~0.27 s, fast/snappy)
• speed=3 → 48 frames (~0.80 s, cinematic)
• speed=6 → 96 frames (~1.60 s, dramatic)

Parameters

speed

VBlank frames to wait between each brightness step. speed=0 falls through with no inter-step delay (visible flash, ~16 frames if every step still hits VBlank via loop overhead — not typically useful).

fadeOut(3);              // ~0.8 s cinematic fade
setScreenOff();          // force-blank for VRAM swap
dmaCopyVram(new_tiles, 0, ...);
setScreenOn();
fadeIn(3);

getBrightness()

u8 getBrightness ( void )

inline

getFrameCount()

u16 getFrameCount ( void )

inline

Get frame counter.

Returns the number of VBlanks since initialization. Wraps at 65535.

Inlined for zero-call-overhead access (just a 16-bit load).

Returns

Frame count

// Simple animation timing
u8 anim_frame = (getFrameCount() / 8) % 4;

getRegion()

u8 getRegion

(

void

)

Get system region.

Returns

0 = NTSC, 1 = PAL

isInVBlank()

u8 isInVBlank

(

void

)

Check if currently in VBlank.

Returns

TRUE if in VBlank, FALSE if in active display

isPAL()

u8 isPAL

(

void

)

Check if PAL system.

Returns

TRUE if PAL (50Hz), FALSE if NTSC (60Hz)

if (isPAL()) {
    // Adjust game speed for 50Hz
}

rand()

u16 rand

(

void

)

Get random 16-bit number.

Returns a pseudo-random number using a linear feedback shift register.

Returns

Random value 0-65535

u16 enemy_x = rand() % 256;

resetFrameCount()

void resetFrameCount

(

void

)

Reset frame counter.

Sets frame counter to 0. Useful for timing game events.

setBrightness()

void setBrightness

(

u8

brightness

)

Set screen brightness.

Parameters

brightness

Brightness level (0-15, 0=black, 15=full)

Warning

setBrightness(0) is NOT forced blank. It makes the screen black, but the PPU keeps fetching, so VRAM and CGRAM writes are still rejected. Only setScreenOff() (INIDISP bit 7) opens the write window outside VBlank.

The mistake survives testing: a small transfer written this way lands inside VBlank and is correct every time, while a multi-KB one has its tail dropped during active display. Use setScreenOff() / setScreenOn() around any upload that is not comfortably inside the VBlank budget — see dmaCopyVram().

// Fade in effect
for (u8 i = 0; i <= 15; i++) {
    setBrightness(i);
    WaitForVBlank();
}

setScreenOff()

void setScreenOff ( void )

inline

setScreenOn()

void setScreenOn ( void )

inline

Enable screen display.

Turns on the display after initialization or a screen blank. Sets full brightness (15).

Inlined for zero-call-overhead access (saves ~28 cycles per call). Shares the same force_blanked and current_brightness shadows as setScreenOff(); both are declared extern below.

consoleInit();
// ... load graphics ...
setScreenOn();  // Display is now visible

srand()

void srand

(

u16

seed

)

Seed random number generator.

Parameters

seed	Initial seed value

// Seed from player input timing for variety
srand(getFrameCount());

WaitForVBlank()

void WaitForVBlank

(

void

)

Wait for next VBlank period.

Blocks until the PPU enters Vertical Blank. This is essential for:

• Stable graphics (prevents tearing)
• Safe VRAM/OAM/CGRAM updates
• Consistent game timing

Call once per frame in your main loop.

while (1) {
    // Update game logic (can happen during active display)
    updatePlayer();
    checkCollisions();
 
    // Wait for VBlank
    WaitForVBlank();
 
    // Now safe to update graphics
    updateOAM();
    scrollBackground();
}

Note

VBlank occurs ~60 times/second (NTSC) or ~50 times/second (PAL)

Variable Documentation

current_brightness

u8 current_brightness

extern

Get current brightness.

Inlined for zero-call-overhead access. The standalone definition is still available (force-emitted in console.c) for fn-pointer callers.

Returns

Current brightness level (0-15)

force_blanked

u8 force_blanked

extern

Disable screen display (blank).

Turns off the display. Use during major VRAM updates that can't complete during VBlank.

Inlined for zero-call-overhead access (saves ~28 cycles per call). The standalone definition in console.c is still emitted (via the extern inline declaration there) for ABI compatibility — direct call sites collapse to two stores.

setScreenOff();
// ... massive VRAM update ...
setScreenOn();