Jo Engine 2026.11.6
Jo Sega Saturn Engine
Loading...
Searching...
No Matches
core.h
Go to the documentation of this file.
1/*
2** Jo Sega Saturn Engine
3** Copyright (c) 2012-2026, Johannes Fetz (johannesfetz@gmail.com)
4** All rights reserved.
5**
6** Redistribution and use in source and binary forms, with or without
7** modification, are permitted provided that the following conditions are met:
8** * Redistributions of source code must retain the above copyright
9** notice, this list of conditions and the following disclaimer.
10** * Redistributions in binary form must reproduce the above copyright
11** notice, this list of conditions and the following disclaimer in the
12** documentation and/or other materials provided with the distribution.
13** * Neither the name of the Johannes Fetz nor the
14** names of its contributors may be used to endorse or promote products
15** derived from this software without specific prior written permission.
16**
17** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
18** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19** WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20** DISCLAIMED. IN NO EVENT SHALL Johannes Fetz BE LIABLE FOR ANY
21** DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22** (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23** LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24** ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26** SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27*/
34
35#ifndef __JO_CORE_H__
36# define __JO_CORE_H__
37
38#ifdef JO_DEBUG
39
46void __jo_core_errorf(const char *function, const char *format, ...) __attribute__((cold, noinline));
47# define jo_core_error(...) __jo_core_errorf(__FUNCTION__, __VA_ARGS__)
48
55# define __JO_INDEX_IS_WRONG(INDEX, COUNT, WHAT) \
56 ((unsigned int)(INDEX) >= (unsigned int)(COUNT) && \
57 (jo_core_error("Wrong %s: %d (max=%d)", (WHAT), (int)(INDEX), (int)(COUNT) - 1), true))
58
59#endif
60
62# define JO_ENGINE_VERSION (2025.1)
63
64/*
65** TYPEDEFS
66*/
68typedef void (*jo_event_callback)(void);
69
71typedef void (*jo_interrupt_handler)(void);
72
73#ifdef JO_COMPILE_WITH_DUAL_CPU_SUPPORT
74
76typedef void (*jo_slave_callback)(void);
77
78#endif
79
87void jo_core_init(const jo_color back_color);
88
92void jo_core_run(void);
93
99
103void jo_core_remove_vblank_callback(const int vblank_event_id);
104
111
115void jo_core_remove_callback(const int event_id);
116
117#ifdef JO_COMPILE_WITH_DUAL_CPU_SUPPORT
118
125
131void jo_core_remove_slave_callback(const int event_id);
132
133#endif
134
140
146
150
151#ifdef JO_COMPILE_WITH_DUAL_CPU_SUPPORT
152
161
166
173
180
182typedef void (*jo_slave_job_function)(void *argument);
183
184#endif
185
194
201
204void jo_core_tv_off(void);
205
208void jo_core_tv_on(void);
209
230
233
248bool jo_core_set_screen_resolution(const int width, const int height);
249
255void jo_core_set_screen_single_interlace(const bool enabled);
256
261{
262 return (__jo_screen.width);
263}
264
269{
270 return (__jo_screen.height);
271}
272
278void jo_core_set_screen_palette(const int palette_id);
279
285{
286 return ((JO_VDP2_TVSTAT & JO_VDP2_TVSTAT_PAL) ? 50 : 60);
287}
288
294{
295 // (the NULL pointer trap of JO_DEBUG off: the Boot ROM reads its own data, see jo_core_init())
296 *(volatile unsigned short *)0xFFFFFF48 = 0;
297 (**(void(**)(void))0x600026C)();
298}
299
304{
305 // (after the INTBACK of the frame: a command sent during an INTBACK is lost)
307}
308
314#define jo_core_set_screens_order(screen1, args...) __jo_core_set_screens_order(screen1, ## args, ~0);
315
316#ifdef JO_DEBUG
317
321
326typedef void (*jo_core_error_handler)(const char *message, const char *function);
327
334
339{
340 return (__jo_last_error);
341}
342
346
350
351#else
352
356static __jo_force_inline char * jo_get_last_error(void)
357{
358 return ("");
359}
360
361#endif
362
367
368/*
369** Internal usage
370*/
371
373extern volatile unsigned int __jo_core_vblank_count;
374
380{
381 return (__jo_core_vblank_count);
382}
383
385extern int __jo_core_fps;
386
388extern unsigned int __jo_core_late_frames;
389
395{
396 return (__jo_core_fps);
397}
398
407{
408 return (__jo_core_late_frames);
409}
410
411#endif /* !__JO_CORE_H__ */
412
413/*
414** END OF FILE
415*/
#define JO_PRINTF_BUF_SIZE
Max character in available in jo_printf().
Definition conf.h:146
void jo_core_suspend(void)
Stop the execution until someone press Start.
void(*) jo_core_error_handler(const char *message, const char *function)
Function called by jo_core_error() (see jo_core_set_error_handler()).
Definition core.h:326
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,...
void(*) jo_interrupt_handler(void)
Function prototype for interrupt handlers (Internal usage).
Definition core.h:71
void jo_core_remove_callback(const int event_id)
Remove a callback in the game loop from on main CPU.
void jo_core_init(const jo_color back_color)
Init the engine.
void jo_core_remove_vblank_callback(const int vblank_event_id)
Remove a callback during VBLANK interruption.
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 ...
void(*) jo_event_callback(void)
Function prototype for jo_core_add_callback().
Definition core.h:68
void(*) jo_slave_job_function(void *argument)
Function of a job of the slave CPU (Internal usage).
Definition core.h:182
static __jo_force_inline int jo_core_get_fps(void)
Get the frames per second really shown, measured over the last 2 seconds.
Definition core.h:394
bool hires
640 or 704 pixels: the frame buffer of the VDP1 has 8 bits per pixel
Definition core.h:222
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_add_vblank_callback(const jo_event_callback callback)
Add a callback during VBLANK interruption.
void jo_core_remove_slave_callback(const int event_id)
Remove a callback in the game loop from on slave CPU.
__jo_screen_mode __jo_screen
The screen now (Internal usage).
void jo_core_set_cd_tray_open_callback(const jo_event_callback callback)
Add a callback when the tray of the CD is opened.
short background_height
Definition core.h:220
void jo_goto_boot_menu(void)
Return to the boot menu.
static __jo_force_inline int jo_core_get_refresh_rate(void)
Get the refresh rate of the console.
Definition core.h:284
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().
unsigned int __jo_core_late_frames
Count of late frames (Internal usage, see jo_core_get_late_frame_count()).
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.
void noinline
Definition core.h:46
short width_2
Definition core.h:215
bool interlace
448 to 512 lines: double density interlace
Definition core.h:224
int __jo_core_fps
Frames per second shown (Internal usage, see jo_core_get_fps()).
void jo_core_exec_on_slave(jo_slave_callback callback)
Execute a callback on the slave CPU.
static __jo_force_inline void jo_core_exit_to_multiplayer(void)
Exit program and return to the Saturn multiplayer (CD player) screen.
Definition core.h:293
bool single_interlace
Single density interlace (see jo_core_set_screen_single_interlace()).
Definition core.h:228
void jo_core_tv_off(void)
Turn OFF scroll drawing processing in the monitor.
static __jo_force_inline void jo_core_disable_reset(void)
Disable reset button.
Definition core.h:190
void jo_core_run(void)
Run the game.
short height_2
Definition core.h:216
char __jo_last_error[JO_PRINTF_BUF_SIZE]
Error handling (Internal usage).
static __jo_force_inline void jo_core_enable_reset(void)
Enable reset button (see jo_core_disable_reset()).
Definition core.h:197
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...
volatile unsigned int __jo_core_vblank_count
Number of VBLANK since startup (Internal usage).
void(*) jo_slave_callback(void)
Function prototype for jo_core_exec_on_slave().
Definition core.h:76
static __jo_force_inline void jo_core_restart_saturn(void)
Restart the Saturn.
Definition core.h:303
short width
Definition core.h:213
void jo_dump_vdp2_registers(void)
Dump VDP2 registers.
int jo_core_add_callback(const jo_event_callback callback)
Add a callback in the game loop on main CPU.
short background_width
The size of the screen in pixels of NBG0 and NBG1 (jo_printf(), the NBG1 bitmap): they are zoomed 2 t...
Definition core.h:219
static __jo_force_inline int jo_core_get_screen_width(void)
Get the width of the screen.
Definition core.h:260
void jo_core_wait_for_slave(void)
Wait until all the callbacks given to jo_core_exec_on_slave() are completed.
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.
bool clock_352
352 or 704 pixels: the system clock is 28.6 MHz (26.8 MHz otherwise)
Definition core.h:226
void __jo_core_set_screens_order(jo_scroll_screen screen1,...)
Screen order (Internal usage).
void jo_dump_vdp1_registers(void)
Dump VDP1 registers.
static __jo_force_inline unsigned int jo_core_get_late_frame_count(void)
Get the count of the late frames since startup.
Definition core.h:406
int jo_core_add_slave_callback(const jo_event_callback callback)
Add a callback in the game loop on slave CPU.
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 j...
short height
Definition core.h:214
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).
Definition core.h:379
static __jo_force_inline int jo_core_get_screen_height(void)
Get the height of the screen.
Definition core.h:268
static __jo_force_inline char * jo_get_last_error(void)
Get last error.
Definition core.h:338
The screen now (Internal usage, see jo_core_set_screen_resolution()).
Definition core.h:212
typedef __attribute__
16 bits word of any memory (see __jo_uint32_alias)
Definition types.h:50
int height
Definition entity.h:4
#define JO_VDP2_TVSTAT
Definition sega_saturn.h:175
#define JO_VDP2_TVSTAT_PAL
TVSTAT: PAL console (50 Hz).
Definition sega_saturn.h:177
void __jo_smpc_set_reset_button(const bool enabled)
Enable or disable the reset button, nested calls (Internal usage, see jo_core_disable_reset()).
@ SystemReset
Resets the System.
Definition smpc.h:62
void __jo_smpc_command(const jo_smpc_command command)
Send a command to the SMPC and wait for the end of the command (Internal usage).
#define __jo_force_inline
force inline attribute (and prevent Doxygen prototype parsing bug)
Definition types.h:39
unsigned short jo_color
15 bits color type
Definition types.h:53
jo_scroll_screen
Sega Saturn Scroll Screen Ids.
Definition types.h:340