Jo Engine 2026.11.6
Jo Sega Saturn Engine
Loading...
Searching...
No Matches
core.h File Reference

Jo Engine core function prototypes. More...

Go to the source code of this file.

Data Structures

struct  __jo_screen_mode
 The screen now (Internal usage, see jo_core_set_screen_resolution()). More...

Macros

#define jo_core_error(...)
#define __JO_INDEX_IS_WRONG(INDEX, COUNT, WHAT)
 Check an index given to a function of the engine (Internal usage, JO_DEBUG).
#define JO_ENGINE_VERSION
 Jo Engine Version.
#define jo_core_set_screens_order(screen1, args...)
 Set scroll screen order between them.

Typedefs

typedef void(*) jo_event_callback(void)
 Function prototype for jo_core_add_callback().
typedef void(*) jo_interrupt_handler(void)
 Function prototype for interrupt handlers (Internal usage).
typedef void(*) jo_slave_callback(void)
 Function prototype for jo_core_exec_on_slave().
typedef void(*) jo_slave_job_function(void *argument)
 Function of a job of the slave CPU (Internal usage).
typedef void(*) jo_core_error_handler(const char *message, const char *function)
 Function called by jo_core_error() (see jo_core_set_error_handler()).

Functions

void __jo_core_errorf (const char *function, const char *format,...) __attribute__((cold
 The message formatted, then __jo_core_error() (Internal usage): one call at each of the hundreds of jo_core_error() (the formatting at each of them was about 4 KB of code), out of the hot code (cold).
void jo_core_init (const jo_color back_color)
 Init the engine.
void jo_core_run (void)
 Run the game.
int jo_core_add_vblank_callback (const jo_event_callback callback)
 Add a callback during VBLANK interruption.
void jo_core_remove_vblank_callback (const int vblank_event_id)
 Remove a callback during VBLANK interruption.
int jo_core_add_callback (const jo_event_callback callback)
 Add a callback in the game loop on main CPU.
void jo_core_remove_callback (const int event_id)
 Remove a callback in the game loop from on main CPU.
int jo_core_add_slave_callback (const jo_event_callback callback)
 Add a callback in the game loop on slave CPU.
void jo_core_remove_slave_callback (const int event_id)
 Remove a callback in the game loop from on slave CPU.
void jo_core_set_restart_game_callback (const jo_event_callback callback)
 Add a callback when A+B+C+Start is pressed on the first control pad (called at each frame while they are pressed).
void jo_core_set_cd_tray_open_callback (const jo_event_callback callback)
 Add a callback when the tray of the CD is opened.
void jo_goto_boot_menu (void)
 Return to the boot menu.
void jo_core_exec_on_slave (jo_slave_callback callback)
 Execute a callback on the slave CPU.
void jo_core_wait_for_slave (void)
 Wait until all the callbacks given to jo_core_exec_on_slave() are completed.
int jo_core_slave_idle_time (void)
 Balance of the CPUs in the last frame (between the 2 last calls of jo_core_wait_for_slave()).
int jo_core_master_wait_time (void)
 The time the master CPU waited for the slave CPU in the last jo_core_wait_for_slave().
static __jo_force_inline void jo_core_disable_reset (void)
 Disable reset button.
static __jo_force_inline void jo_core_enable_reset (void)
 Enable reset button (see jo_core_disable_reset()).
void jo_core_tv_off (void)
 Turn OFF scroll drawing processing in the monitor.
void jo_core_tv_on (void)
 Turn ON scroll drawing processing in the monitor.
bool jo_core_set_screen_resolution (const int width, const int height)
 Change the resolution of the screen while the game runs.
void jo_core_set_screen_single_interlace (const bool enabled)
 Single density interlace: the image of 224 to 256 lines is displayed in the 2 fields, the second one half a line lower (the look of the games that use it on a CRT: no dark lines between the lines, a slight flicker).
static __jo_force_inline int jo_core_get_screen_width (void)
 Get the width of the screen.
static __jo_force_inline int jo_core_get_screen_height (void)
 Get the height of the screen.
void jo_core_set_screen_palette (const int palette_id)
 Choose the palette of the sprites in the 640 and 704 pixels modes (the frame buffer of the VDP1 has 8 bits per pixel: one palette of 256 colors for all the sprites).
static __jo_force_inline int jo_core_get_refresh_rate (void)
 Get the refresh rate of the console.
static __jo_force_inline void jo_core_exit_to_multiplayer (void)
 Exit program and return to the Saturn multiplayer (CD player) screen.
static __jo_force_inline void jo_core_restart_saturn (void)
 Restart the Saturn.
void jo_core_suspend (void)
 Stop the execution until someone press Start.
void jo_core_set_error_handler (const jo_core_error_handler handler)
 Call a function instead of the error screen (JO_DEBUG): automated tests count the errors and go on.
static __jo_force_inline char * jo_get_last_error (void)
 Get last error.
void jo_dump_vdp1_registers (void)
 Dump VDP1 registers.
void jo_dump_vdp2_registers (void)
 Dump VDP2 registers.
void __jo_core_set_screens_order (jo_scroll_screen screen1,...)
 Screen order (Internal usage).
static __jo_force_inline unsigned int jo_core_get_vblank_count (void)
 Get the number of VBLANK since startup (60 per second in NTSC, 50 in PAL).
static __jo_force_inline int jo_core_get_fps (void)
 Get the frames per second really shown, measured over the last 2 seconds.
static __jo_force_inline unsigned int jo_core_get_late_frame_count (void)
 Get the count of the late frames since startup.

Variables

char __jo_last_error [JO_PRINTF_BUF_SIZE]
 Error handling (Internal usage).
void noinline
__jo_screen_mode __jo_screen
 The screen now (Internal usage).
volatile unsigned int __jo_core_vblank_count
 Number of VBLANK since startup (Internal usage).
int __jo_core_fps
 Frames per second shown (Internal usage, see jo_core_get_fps()).
unsigned int __jo_core_late_frames
 Count of late frames (Internal usage, see jo_core_get_late_frame_count()).

Detailed Description

Jo Engine core function prototypes.

Author
Johannes Fetz
Bug
No known bugs.

Data Structure Documentation

◆ __jo_screen_mode

struct __jo_screen_mode

The screen now (Internal usage, see jo_core_set_screen_resolution()).

Data Fields
short background_height
short background_width The size of the screen in pixels of NBG0 and NBG1 (jo_printf(), the NBG1 bitmap): they are zoomed 2 times in the hi-res and interlace modes.
bool clock_352 352 or 704 pixels: the system clock is 28.6 MHz (26.8 MHz otherwise)
short height
short height_2
bool hires 640 or 704 pixels: the frame buffer of the VDP1 has 8 bits per pixel
bool interlace 448 to 512 lines: double density interlace
bool single_interlace Single density interlace (see jo_core_set_screen_single_interlace()).
short width
short width_2

Macro Definition Documentation

◆ __JO_INDEX_IS_WRONG

#define __JO_INDEX_IS_WRONG ( INDEX,
COUNT,
WHAT )

Check an index given to a function of the engine (Internal usage, JO_DEBUG).

Parameters
INDEXIndex (int)
COUNTSize of the table: the index must be in [0, COUNT)
WHATWhat the index is (a string, in the error)
Returns
true with the error (in the function that uses it) if it is not

◆ jo_core_error

#define jo_core_error ( ...)

◆ jo_core_set_screens_order

#define jo_core_set_screens_order ( screen1,
args... )

Set scroll screen order between them.

Parameters
screen1First screen (high priority)
argsOther screens
Remarks
Default Jo Engine screen priority : NBG0 > SPR0 > SPR1 > RBG0 > NBG1 > NBG2 > NBG3

◆ JO_ENGINE_VERSION

#define JO_ENGINE_VERSION

Jo Engine Version.

Typedef Documentation

◆ jo_core_error_handler

typedef void(*) jo_core_error_handler(const char *message, const char *function)

Function called by jo_core_error() (see jo_core_set_error_handler()).

Parameters
messageThe error
functionThe function of the error

◆ jo_event_callback

typedef void(*) jo_event_callback(void)

Function prototype for jo_core_add_callback().

◆ jo_interrupt_handler

typedef void(*) jo_interrupt_handler(void)

Function prototype for interrupt handlers (Internal usage).

◆ jo_slave_callback

typedef void(*) jo_slave_callback(void)

Function prototype for jo_core_exec_on_slave().

◆ jo_slave_job_function

typedef void(*) jo_slave_job_function(void *argument)

Function of a job of the slave CPU (Internal usage).

Function Documentation

◆ __jo_core_errorf()

void __jo_core_errorf ( const char * function,
const char * format,
... )

The message formatted, then __jo_core_error() (Internal usage): one call at each of the hundreds of jo_core_error() (the formatting at each of them was about 4 KB of code), out of the hot code (cold).

◆ __jo_core_set_screens_order()

void __jo_core_set_screens_order ( jo_scroll_screen screen1,
... )

Screen order (Internal usage).

Warning
Use jo_core_set_screens_order instead

◆ jo_core_add_callback()

int jo_core_add_callback ( const jo_event_callback callback)

Add a callback in the game loop on main CPU.

Parameters
callbackFunction name with no parameters and no return value
Warning
Must be called before jo_core_run()
Returns
Event Id (usefull for jo_core_remove_callback())

◆ jo_core_add_slave_callback()

int jo_core_add_slave_callback ( const jo_event_callback callback)

Add a callback in the game loop on slave CPU.

Parameters
callbackFunction name with no parameters and no return value
Warning
Must be called before jo_core_run()
Returns
Event Id (usefull for jo_core_remove_slave_callback())

◆ jo_core_add_vblank_callback()

int jo_core_add_vblank_callback ( const jo_event_callback callback)

Add a callback during VBLANK interruption.

Parameters
callbackFunction name with no parameters and no return value
Returns
VBLANK Event Id (usefull for jo_core_remove_vblank_callback())

◆ jo_core_disable_reset()

__jo_force_inline void jo_core_disable_reset ( void )
static

Disable reset button.

Remarks
The calls are nested: the reset button is enabled again when each call has its jo_core_enable_reset(). The backup functions disable it while they write (a reset would corrupt the backup)

◆ jo_core_enable_reset()

__jo_force_inline void jo_core_enable_reset ( void )
static

Enable reset button (see jo_core_disable_reset()).

◆ jo_core_exec_on_slave()

void jo_core_exec_on_slave ( jo_slave_callback callback)

Execute a callback on the slave CPU.

Parameters
callbackFunction name with no parameters and no return value
Remarks
The callback is added to the jobs of the slave CPU: the master CPU doesn't wait (unless 8 jobs are waiting). The slave CPU may first finish a job of the engine (the VDP1 commands of the previous frame are sorted and copied by the slave CPU, see JO_COMPILE_WITH_DUAL_CPU_SUPPORT)
If the slave CPU didn't start, the callback is executed on the master CPU

◆ jo_core_exit_to_multiplayer()

__jo_force_inline void jo_core_exit_to_multiplayer ( void )
static

Exit program and return to the Saturn multiplayer (CD player) screen.

Remarks
Routine of the Boot ROM (SYS_EXECDMP). Called when the tray of the CD is opened and on A+B+C+Start by default (see jo_core_set_cd_tray_open_callback() and jo_core_set_restart_game_callback())

◆ jo_core_get_fps()

__jo_force_inline int jo_core_get_fps ( void )
static

Get the frames per second really shown, measured over the last 2 seconds.

Returns
Frames per second (60 / JO_FRAMERATE in NTSC when no frame is late), 0 during the first 2 seconds
Remarks
jo_printf(0, 27, "%d FPS ", jo_core_get_fps());

◆ jo_core_get_late_frame_count()

__jo_force_inline unsigned int jo_core_get_late_frame_count ( void )
static

Get the count of the late frames since startup.

Returns
Frames that took more VBLANK than JO_FRAMERATE (the game missed the end of a frame: it slows down)
Remarks
The first frame is not counted (the loading before it)
As the images of the VDP1: a frame of 1.2 field followed by a frame of 0.5 field is not late (the table of the second frame waits for its VBLANK: each image stays one field, 60 images per second). Measured: the count is the fields that showed the image before again

◆ jo_core_get_refresh_rate()

__jo_force_inline int jo_core_get_refresh_rate ( void )
static

Get the refresh rate of the console.

Returns
50 for a PAL console, 60 for a NTSC console
Remarks
This is the number of VBLANK per second (see jo_core_add_vblank_callback())

◆ jo_core_get_screen_height()

__jo_force_inline int jo_core_get_screen_height ( void )
static

Get the height of the screen.

Returns
Height in lines (JO_TV_HEIGHT at the start, see jo_core_set_screen_resolution())

◆ jo_core_get_screen_width()

__jo_force_inline int jo_core_get_screen_width ( void )
static

Get the width of the screen.

Returns
Width in pixels (JO_TV_WIDTH at the start, see jo_core_set_screen_resolution())

◆ jo_core_get_vblank_count()

__jo_force_inline unsigned int jo_core_get_vblank_count ( void )
static

Get the number of VBLANK since startup (60 per second in NTSC, 50 in PAL).

Returns
VBLANK count (it is incremented by the VBLANK interrupt)
Remarks
Measure the time of a frame or the frames per second without a timer

◆ jo_core_init()

void jo_core_init ( const jo_color back_color)

Init the engine.

Parameters
back_colorDefault background color (colors.h)
Warning
Must be the first function called in jo_main()
Remarks
With JO_DEBUG, a NULL pointer trap of the master CPU (its user break controller) stops each data access to the first 4 KB of the memory after this call: the error screen shows the PC (the instruction after the access) and the PR (return address of its function), to find in the map file. The emulators (Mednafen, Yabause) do not emulate it

◆ jo_core_master_wait_time()

int jo_core_master_wait_time ( void )

The time the master CPU waited for the slave CPU in the last jo_core_wait_for_slave().

Returns
Microseconds (0: the slave CPU was done first)
Remarks
With several jobs of the slave CPU per frame (a split screen: a view after the other), the balance of each one: jo_core_slave_idle_time() also counts the time the slave CPU waited before the job (the master CPU prepared it)

◆ jo_core_remove_callback()

void jo_core_remove_callback ( const int event_id)

Remove a callback in the game loop from on main CPU.

Parameters
event_idValue returned by jo_core_add_callback()

◆ jo_core_remove_slave_callback()

void jo_core_remove_slave_callback ( const int event_id)

Remove a callback in the game loop from on slave CPU.

Parameters
event_idValue returned by jo_core_add_slave_callback()
Remarks
Called while the slave CPU runs its callbacks (from a callback of either CPU), the callback is removed after they are done

◆ jo_core_remove_vblank_callback()

void jo_core_remove_vblank_callback ( const int vblank_event_id)

Remove a callback during VBLANK interruption.

Parameters
vblank_event_idValue returned by jo_core_add_vblank_callback()

◆ jo_core_restart_saturn()

__jo_force_inline void jo_core_restart_saturn ( void )
static

Restart the Saturn.

Warning
Doesn't work in Yabause

◆ jo_core_run()

void jo_core_run ( void )

Run the game.

Warning
Must be the last function called in jo_main()

◆ jo_core_set_cd_tray_open_callback()

void jo_core_set_cd_tray_open_callback ( const jo_event_callback callback)

Add a callback when the tray of the CD is opened.

Parameters
callbackFunction name with no parameters and no return value (JO_NULL, by default: back to the multiplayer screen of the BIOS, see jo_core_exit_to_multiplayer())

◆ jo_core_set_error_handler()

void jo_core_set_error_handler ( const jo_core_error_handler handler)

Call a function instead of the error screen (JO_DEBUG): automated tests count the errors and go on.

Parameters
handlerFunction, JO_NULL: the error screen (the default)
Remarks
An error of the slave CPU, of an interrupt (a VBLANK callback) or of code with the interrupts masked is shown (or given to the handler) by the master CPU at its next frame: the first one, with the count of the next ones

◆ jo_core_set_restart_game_callback()

void jo_core_set_restart_game_callback ( const jo_event_callback callback)

Add a callback when A+B+C+Start is pressed on the first control pad (called at each frame while they are pressed).

Parameters
callbackFunction name with no parameters and no return value (JO_NULL: back to the multiplayer screen of the BIOS, see jo_core_exit_to_multiplayer())

◆ jo_core_set_screen_palette()

void jo_core_set_screen_palette ( const int palette_id)

Choose the palette of the sprites in the 640 and 704 pixels modes (the frame buffer of the VDP1 has 8 bits per pixel: one palette of 256 colors for all the sprites).

Parameters
palette_idPalette (jo_create_palette())
Remarks
A polygon of color palette_id * 256 + k (k from 1 to 255) has the color k of the palette in all the modes

◆ jo_core_set_screen_resolution()

bool jo_core_set_screen_resolution ( const int width,
const int height )

Change the resolution of the screen while the game runs.

Parameters
width320, 352, 640 or 704 pixels
height224 or 240 lines (256 in PAL), or 448 or 480 (512 in PAL): double density interlace
Returns
true if succeed, false if the resolution is not supported
Remarks
The text (jo_printf()) and the NBG1 bitmap keep their size: they are zoomed 2 times in the 640 and 704 pixels modes and in the interlace modes. The sprites and the 3D are drawn with all the pixels of the screen
In the 640 and 704 pixels modes, the VDP1 draws 8 bits per pixel: only the palette sprites (8 bits images) and the colors of a palette (see jo_core_set_screen_palette()) are displayed, not the RGB colors
The 3D has one projection distance for the 2 axes (from the width): in the modes 640 x 224 / 240 and 320 x 448 / 480, whose pixels are not square, the 3D is stretched 2 times vertically or horizontally
320 and 640 pixels use the 26.8 MHz clock, 352 and 704 pixels the 28.6 MHz clock: the clock is chosen at the start by JO_SCREEN_WIDTH (makefile) and the width can only change inside its family (false otherwise)
The windows (jo_3d_window()) and the VDP2 windows (jo_vdp2_set_window()) are reset to the whole screen

◆ jo_core_set_screen_single_interlace()

void jo_core_set_screen_single_interlace ( const bool enabled)

Single density interlace: the image of 224 to 256 lines is displayed in the 2 fields, the second one half a line lower (the look of the games that use it on a CRT: no dark lines between the lines, a slight flicker).

Parameters
enabledtrue to enable it, false for the progressive display (default)
Remarks
Only in the modes of 224 to 256 lines: the 448 to 512 lines modes are always double density interlace

◆ jo_core_slave_idle_time()

int jo_core_slave_idle_time ( void )

Balance of the CPUs in the last frame (between the 2 last calls of jo_core_wait_for_slave()).

Returns
Microseconds the slave CPU spent waiting for a job (it can take more work), negative: microseconds the master CPU waited for the slave CPU in jo_core_wait_for_slave() (the slave CPU has too much work)
Remarks
To move the drawing of some objects from a CPU to the other: the frame takes the time of the slowest CPU

◆ jo_core_suspend()

void jo_core_suspend ( void )

Stop the execution until someone press Start.

◆ jo_core_tv_off()

void jo_core_tv_off ( void )

Turn OFF scroll drawing processing in the monitor.

◆ jo_core_tv_on()

void jo_core_tv_on ( void )

Turn ON scroll drawing processing in the monitor.

◆ jo_core_wait_for_slave()

void jo_core_wait_for_slave ( void )

Wait until all the callbacks given to jo_core_exec_on_slave() are completed.

Remarks
Then the master CPU can read the data written by the slave CPU (its cache is purged)

◆ jo_dump_vdp1_registers()

void jo_dump_vdp1_registers ( void )

Dump VDP1 registers.

◆ jo_dump_vdp2_registers()

void jo_dump_vdp2_registers ( void )

Dump VDP2 registers.

◆ jo_get_last_error()

__jo_force_inline char * jo_get_last_error ( void )
static

Get last error.

Returns
Formated error

◆ jo_goto_boot_menu()

void jo_goto_boot_menu ( void )

Return to the boot menu.

Variable Documentation

◆ __jo_core_fps

int __jo_core_fps
extern

Frames per second shown (Internal usage, see jo_core_get_fps()).

◆ __jo_core_late_frames

unsigned int __jo_core_late_frames
extern

Count of late frames (Internal usage, see jo_core_get_late_frame_count()).

◆ __jo_core_vblank_count

volatile unsigned int __jo_core_vblank_count
extern

Number of VBLANK since startup (Internal usage).

◆ __jo_last_error

char __jo_last_error[JO_PRINTF_BUF_SIZE]
extern

Error handling (Internal usage).

Warning
MC Hammer: don't touch this

◆ __jo_screen

__jo_screen_mode __jo_screen
extern

The screen now (Internal usage).

◆ noinline

void noinline