Synchronization

Synchronization routines for your game. More...

Macros
#define	oslSetFrameskip(val)   (osl_frameskip = val)
	Sets the frameskipping mode.
#define	oslSetMaxFrameskip(val)   (osl_maxFrameskip = val)
	Sets the maximum frameskip value.
#define	oslSetVSync(val)   (osl_vsyncEnabled = val)
	Sets the frame synchronization flags.
#define	oslSyncFrame()   oslSyncFrameEx(osl_frameskip, osl_maxFrameskip, osl_vsyncEnabled)
	Synchronization function to be called at the end of a frame.

Functions
void	oslEndFrame ()
	Call this function when a frame has ended.
int	oslSyncFrameEx (int frameskip, int max_frameskip, int vsync)
	Synchronization function with explicit parameters.
static void	oslSetFramerate (int framerate)
	Sets the framerate for oslSyncFrame(Ex).
void	oslWaitVSync ()
	Waits for the VSync, synchronizing your game.

Variables
int	osl_quit
	Indicates whether the application should exit.
int	osl_standByUnpermitted
	Controls whether standby mode is permitted.
int(*	osl_powerCallback )(int arg1, int arg2, void *common)
	Pointer to the power callback function.
int(*	osl_exitCallback )(int arg1, int arg2, void *common)
	Pointer to the exit callback function.
int	osl_vblInterruptNumber
	The interrupt number for the VBLANK interrupt.
int	osl_maxFrameskip
	Limits consecutive skips requested by the recovery branch.
int	osl_vsyncEnabled
	Frame synchronization bitmask (default set by oslInit: 4).
int	osl_frameskip
	Current frameskip setting.
volatile int	osl_vblCount
	Count of VBLANK interrupts.
volatile int	osl_vblCallCount
	Count of VBLANK interrupt calls.
volatile int	osl_vblankCounterActive
	Indicates if the VBLANK counter is active.
volatile int	osl_skip
	Indicates whether rendering should be skipped on the next iteration.
volatile int	osl_currentFrameRate
	Current framerate setting.

Detailed Description

Synchronization routines for your game.

These functions are used to synchronize the game's frame rate and ensure smooth rendering and input handling. They include functions for managing frame skipping and VSync.

Macro Definition Documentation

oslSetFrameskip

#define oslSetFrameskip

(

val

)

(osl_frameskip = val)

Sets the frameskipping mode.

Parameters

val

0 disables frameskipping (the default set by oslInit). 1 enables automatic rendering skips when running late. For N > 1, bit 4 of osl_vsyncEnabled requests a fixed pattern of one rendered frame per N logical frames, subject to the recovery limit in osl_maxFrameskip. Without bit 4, synchronization targets osl_currentFrameRate / N frames per second (60 / N by default), with additional rendering skips when late.

oslSetMaxFrameskip

#define oslSetMaxFrameskip

(

val

)

(osl_maxFrameskip = val)

Sets the maximum frameskip value.

Parameters

val	Recovery limit; see osl_maxFrameskip. The default set by oslInit is 5.

oslSetVSync

#define oslSetVSync

(

val

)

(osl_vsyncEnabled = val)

Sets the frame synchronization flags.

Parameters

val	Bitmask documented in osl_vsyncEnabled. The default set by oslInit is 4.

oslSyncFrame

#define oslSyncFrame

(

)

oslSyncFrameEx(osl_frameskip, osl_maxFrameskip, osl_vsyncEnabled)

Synchronization function to be called at the end of a frame.

This function synchronizes the frame rate based on the current frameskip and VSync settings.

Run game logic on every loop iteration, including skipped frames. Use the return value only to decide whether to render on the next iteration:

int skip = 0;
while (!osl_quit) {
    // Read input and update game logic here, even when skip is nonzero.
    if (!skip) {
        oslStartDrawing();
        // Draw the game here.
        oslEndDrawing();
    }
    oslEndFrame();
    skip = oslSyncFrame();
}

Returns

1 to skip rendering the next frame, 0 to render it. This is not a lateness indicator: fixed skipping can return 1 when on time, and disabled frameskipping always returns 0, even when late.

Function Documentation

oslEndFrame()

void oslEndFrame ( )

extern

Call this function when a frame has ended.

This function should be called just before calling oslSyncFrame or oslWaitVSync. It handles audio synchronization and other end-of-frame tasks.

oslSyncFrameEx()

int oslSyncFrameEx ( int  frameskip, int  max_frameskip, int  vsync  )

extern

Synchronization function with explicit parameters.

This function is similar to oslSyncFrame but allows you to pass all synchronization parameters directly in one call.

Parameters

frameskip	Frameskipping mode; see oslSetFrameskip. oslInit sets the corresponding global osl_frameskip to 0.
max_frameskip	Recovery branch limit; see osl_maxFrameskip for the counter semantics and fixed-skip exception. Ignored when frameskip is 0. oslInit sets the corresponding global to 5.
vsync	Synchronization bitmask; see osl_vsyncEnabled for bits 1, 4, 8 and 16. oslInit sets the corresponding global to 4.

Returns

1 to skip rendering the next frame, 0 to render it. Always 0 when frameskip is 0; fixed skipping may return 1 even when on time. Run game logic on every iteration; see the loop example in oslSyncFrame.

oslSetFramerate()

static void oslSetFramerate ( int  framerate )

inlinestatic

Sets the framerate for oslSyncFrame(Ex).

This can be any value from 1 to 60. For example, use 50 to simulate a PAL (European) game.

Parameters

framerate

Desired framerate.

oslWaitVSync()

void oslWaitVSync ( )

extern

Waits for the VSync, synchronizing your game.

This function is a simpler and less efficient method than oslSyncFrame.

Variable Documentation

osl_quit

int osl_quit

extern

Indicates whether the application should exit.

This variable is set to 1 when the user chooses "Exit" from the HOME menu, signaling that the application should clean up resources and quit. Game loops should monitor this variable and exit gracefully when it is set to 1.

osl_standByUnpermitted

int osl_standByUnpermitted

extern

Controls whether standby mode is permitted.

This variable can be set to 1 to prevent the PSP from entering standby mode. If set to 0, standby mode is allowed.

osl_powerCallback

int(* osl_powerCallback) (int arg1, int arg2, void *common) ( int  arg1, int  arg2, void *  common  )

extern

Pointer to the power callback function.

This function is called when a power event occurs, such as low battery, power switch action, or other power-related events. The callback receives three parameters: two integers and a void pointer for user-defined data.

Parameters

arg1	First argument, typically indicating the type of power event.
arg2	Second argument, providing additional context or flags related to the event.
common	A pointer to user-defined data, typically passed when setting up the callback.

Returns

Typically returns 0, but the return value may be used to influence power event handling.

osl_exitCallback

int(* osl_exitCallback) (int arg1, int arg2, void *common) ( int  arg1, int  arg2, void *  common  )

extern

Pointer to the exit callback function.

This function is executed when the user chooses "Exit" from the HOME menu. By default, it sets osl_quit to 1. You can override this function to handle exit events in a custom way.

Parameters

arg1	First argument, usually indicating the reason for the exit request.
arg2	Second argument, providing additional context or flags related to the exit request.
common	A pointer to user-defined data, typically passed when setting up the callback.

Returns

Typically returns 0, but the return value may be used to influence exit event handling.

osl_vblInterruptNumber

int osl_vblInterruptNumber

extern

The interrupt number for the VBLANK interrupt.

This variable stores the number of the VBLANK interrupt used by OSLib. It is generally set during initialization and used to manage frame synchronization.

osl_maxFrameskip

int osl_maxFrameskip

extern

Limits consecutive skips requested by the recovery branch.

The recovery branch runs while its skip counter is less than this value minus 1. The default set by oslInit is 5, allowing up to four consecutive recovery skips. A value of 1 prevents that branch from requesting skips. Fixed skipping (frameskip > 1 with synchronization bit 4) can still request a skip outside that branch, so this is not an absolute limit on all skips. Ignored when frameskipping is disabled (osl_frameskip == 0).

osl_vsyncEnabled

int osl_vsyncEnabled

extern

Frame synchronization bitmask (default set by oslInit: 4).

Combine the following flags with bitwise OR:

• 1: With frameskipping enabled, wait for VSync before presenting a rendered frame.
• 4: With osl_frameskip > 1, request fixed rendering skips rather than reducing the logical update rate; see oslSetFrameskip.
• 8: Alternative synchronization method. With frameskipping enabled, remove the extra one-count lateness offset used by bit 1 for a rendered frame. When the recovery branch is not taken (including when its skip limit is reached), also raise the VBlank counter wait target by one when the frame was rendered. This flag does not clear bit 1 or allocate a third buffer.
• 16: Disable automatic buffer swapping; the caller must swap buffers.

With frameskipping disabled, either bit 1 or bit 4 forces at least one VBlank wait per call, even when late. With neither bit set, wait only if the VBlank counter has not advanced since the previous call. Bit 8 has no effect in this mode. A zero bitmask does not disable all synchronization waits.

osl_frameskip

int osl_frameskip

extern

Current frameskip setting.

The default set by oslInit is 0 (disabled). A value of 1 enables automatic rendering skips when late. Values N > 1 target a rendered rate of osl_currentFrameRate / N (60 / N by default); the logical update rate and skip pattern depend on synchronization bit 4 and osl_maxFrameskip. See oslSetFrameskip for the mode details.

osl_vblCount

volatile int osl_vblCount

extern

Count of VBLANK interrupts.

This volatile variable tracks the number of VBLANK interrupts that have occurred. It is used internally to synchronize rendering with the display's refresh rate.

osl_vblCallCount

volatile int osl_vblCallCount

extern

Count of VBLANK interrupt calls.

This volatile variable tracks the number of times the VBLANK interrupt has been handled. It is used to ensure that the application correctly responds to each interrupt.

osl_vblankCounterActive

volatile int osl_vblankCounterActive

extern

Indicates if the VBLANK counter is active.

This volatile variable is set to 1 when the VBLANK counter is actively tracking VBLANK interrupts. It is used internally by OSLib for frame synchronization.

osl_skip

volatile int osl_skip

extern

Indicates whether rendering should be skipped on the next iteration.

Set by oslSyncFrameEx at the end of a frame and returned to the caller for the next iteration. A value of 1 skips rendering only; game logic must still run. The default set by oslInit is 0.

osl_currentFrameRate

volatile int osl_currentFrameRate

extern

Current framerate setting.

This volatile variable stores the current target framerate, typically set to 60 for a standard PSP display. It can be modified to simulate different framerates, such as 50 for PAL games.