![]() |
Jo Engine 2026.11.6
Jo Sega Saturn Engine
|
Cells and portals: the rooms of an inside level (sections CELL and PRTL, see Documentation/level_format.md). More...
Go to the source code of this file.
Data Structures | |
| struct | jo_cell |
| A cell. More... | |
| struct | jo_cell_portal |
| A portal: an opening of a cell toward another cell. More... | |
Macros | |
| #define | JO_CELL_MAX |
| Cells at most. | |
| #define | JO_CELL_MAX_PORTALS |
| Portals at most. | |
| #define | JO_CELL_MAX_DRAWN |
| Cells drawn in a frame at most. | |
| #define | JO_CELLS_DEFAULT_SHARE |
| Share of the polygons of the cells drawn by the master CPU at the start (0 to 1024, see jo_cells_draw_prepared_on_both_cpus()). | |
| #define | JO_CELLS_DEFAULT_MAX_SHARE |
| Highest share of the master CPU by default (all the cells: the slave CPU may draw the entities). | |
Functions | |
| int | jo_cells_load (jo_level *const level) |
| Create the cells of a level (sections CELL and PRTL): the previous ones are freed. | |
| void | jo_cells_free (void) |
| Free the cells (and their models). | |
| int | jo_cells_count (void) |
| Number of cells. | |
| bool | jo_cells_have_exits (void) |
| Check if a cell has a door or a window to the outside (the level is not an inside level: there is a world around the cells). | |
| const jo_cell * | jo_cells_get (const int index) |
| A cell. | |
| int | jo_cells_outside_view (jo_3d_rect *const rect) |
| Rectangle of the screen where the outside is seen (after jo_cells_prepare()): the portals of the cells seen that go to the outside (PRTL.cell NO_INDEX: the door of a building on a terrain). Give it to jo_3d_set_view_rect(): only the objects of the outside seen through the doors are drawn. | |
| int | jo_cell_floor (const jo_cell *const cell, const int x, const int z) |
| Floor of a cell at a position (its slope). | |
| int | jo_cells_find (const jo_fixed x, const jo_fixed y, const jo_fixed z, const int step) |
| Cell of a position: its box has the position, its floor is under it (the highest one). | |
| bool | jo_cells_floor (const jo_fixed x, const jo_fixed y, const jo_fixed z, const int step, int *const floor) |
| Floor under a position. | |
| bool | jo_cells_is_walkable (const jo_fixed x, const jo_fixed y, const jo_fixed z, const int radius, const int step) |
| Check if the player can stand at a position: a circle around it is in the box of a cell, the floor of the cell is under the feet (or a step over them). | |
| int | jo_cells_draw (const jo_pos3D_fixed *const camera) |
| Draw the cells seen from the camera (the camera matrix is the current matrix, see jo_3d_set_depth_bias()). | |
| int | jo_cells_prepare (const jo_pos3D_fixed *const camera) |
| Find the cells seen from the camera (the camera matrix is the current matrix): jo_cells_draw() in 2 parts, to draw them on the slave CPU (the master CPU finds them, the slave CPU draws them while the master CPU draws the rest). | |
| void | jo_cells_draw_prepared (const bool slave) |
| Draw the cells found by jo_cells_prepare(). | |
| void | jo_cells_draw_prepared_part (const bool slave, const int part, const int handicap) |
| Draw a part of the cells found by jo_cells_prepare(): the 2 CPUs draw them together (the meshes split in 2 parts with about as many polygons, the same split on both CPUs). | |
| void | jo_cells_draw_prepared_share (const bool slave, const int part, const int share) |
| Draw a part of the cells found by jo_cells_prepare(): the 2 CPUs draw them together, the polygons split at a share (a mesh can be split: the CPUs can be balanced at each frame, see jo_core_slave_idle_time()). | |
| int | jo_cells_prepared_polygon_count (void) |
| Polygons of the cells found by jo_cells_prepare() (the polygons of the chunks seen of the meshes seen: the share of each CPU is cut in them, see jo_cells_draw_prepared_share()). | |
| void | jo_cells_draw_prepared_on_both_cpus (void(*const slave_before)(void), const int slave_polygons) |
| Draw the cells found by jo_cells_prepare() on the 2 CPUs: the slave CPU draws its part (a job, see jo_core_exec_on_slave()) while the master CPU draws the other part. The share of each CPU: half of the polygons of the frame to each one (the cells and what else the slave CPU draws), plus a correction that follows the load of the last frames (see jo_cells_balance_share()). | |
| void | jo_cells_balance_share (void) |
| Balance the share of the CPUs for the next frame (see jo_cells_draw_prepared_on_both_cpus()): more polygons to the slave CPU when it waited in the last frame, fewer when the master CPU waited for it (or when its command table is nearly full: its last polygons would be lost). | |
| void | jo_cells_set_share_limits (const int min, const int max) |
| Limits of the share of the master CPU (see jo_cells_draw_prepared_on_both_cpus()). | |
| int | jo_cells_get_share (void) |
| Share of the polygons of the cells drawn by the master CPU in the next frame (0 to 1024). | |
| bool | jo_cells_draw_mirror (void(*draw_more)(void)) |
| Draw the mirror seen by the camera (in the cell of the camera or in a cell seen through a door), when jo_cells_prepare() found one (a portal MIRROR): its cell is drawn again with the camera reflected by the plane of the mirror, in a far window (JO_3D_FAR_WINDOW, then JO_3D_FAR_WINDOW_2 for a second mirror: a polished floor and a mirror on a wall seen together) clipped by the VDP1 to the rectangle of the mirror on the screen. On the master CPU, the camera matrix is the current matrix. | |
| bool | jo_cells_mirror_is_floor (void) |
| The mirror drawn now (in draw_more of jo_cells_draw_mirror()) is a polished floor (a horizontal portal MIRROR under a half transparent floor), not a mirror on a wall (in draw_more of jo_cells_draw_mirror(): the player does not see his own body under him). | |
| void | jo_cells_set_window_distance (const int distance) |
| Distance from the outside under which a cell is seen through its windows (portals JO_LEVEL_PORTAL_WINDOW to the outside): farther, the cell is not drawn through them (a window is small on the screen, its cell would cost a lot of CPU time for a few pixels: the model outside can show something dark in the window instead). | |
| bool | jo_cells_view_rect_at (const jo_pos3D_fixed *const position, jo_3d_rect *const rect) |
| The rectangle of the screen where a point is seen (the cell of the point seen through the doors, see jo_cells_prepare(): after it). For an effect drawn over the 3D view that the walls don't hide (a glow, see jo_3d_glows_set_clip()): it is seen only in this rectangle. | |
| bool | jo_cells_seen_through (const int index, jo_3d_rect *const rect) |
| The rectangle of the screen where a cell is seen from the outside (through its doors and its near windows, see jo_cells_set_window_distance()), after jo_cells_prepare(): the program can draw what is in the cell in a window clipped to this rectangle (jo_3d_window(), jo_3d_window_clip()): the polygons outside of it are not drawn. | |
| bool | jo_cells_seen_through_window (const int index) |
| Check if a cell is seen from the outside through one of its windows in this frame (see jo_cells_set_window_distance(); or from its doorway: the whole screen). | |
| bool | jo_cells_is_drawn (const int index) |
| Check if a cell was drawn in the last call of jo_cells_draw() or jo_cells_prepare() (the objects in the other cells are hidden). The camera outside of the cells: a cell with doors to the outside is drawn when one of them is seen. | |
| int | jo_cells_close_portals (const jo_fixed x, const jo_fixed z, const int radius, const bool closed) |
| Close the portals of a door (JO_LEVEL_PORTAL_DOOR) whose middle is near a point: the cells behind them are not drawn through them (a closed door: its panel hides the room behind it), or open them again. | |
| int | jo_cells_depth_bias_at (const jo_fixed x, const jo_fixed y, const jo_fixed z) |
| Depth bias of an object in the cells (see jo_cells_draw()): the cells seen through more portals are drawn behind, the objects in them too (else they are seen through the walls of the nearer cells). | |
| int | jo_cells_object_cell (const jo_fixed x, const jo_fixed y, const jo_fixed z) |
| Cell of an object (see jo_cells_depth_bias_at()). | |
| void | jo_cells_set_portal_clipping (const bool enabled) |
| The cells seen through the portals are drawn in the far window (JO_3D_FAR_WINDOW), clipped by the VDP1 to the union of the rectangles of the portals on the screen (default: on). A room seen through a door was drawn whole: the VDP1 spent its time on the walls around the door (up to 50 ms in a frame). Not in a frame with a mirror (it draws in the far window). The objects of these cells go in the far window too: jo_cells_window_of(). | |
| void | jo_cells_set_occluders (const bool enabled) |
| A polygon of the cell of the camera that covers the whole screen (the camera near a wall, facing it, or a bench against it) hides everything behind it: the polygons behind it are not drawn (the depth limit of the near window, see jo_3d_set_depth_limit(), set by jo_cells_prepare() in a frame where the cell of the camera is seen alone: nothing seen through a door). Default: on. Against a wall, the VDP1 drew the whole room behind it (up to 50 ms). A polygon with holes in its texture is taken as opaque: nothing is seen through the holes. | |
| int | jo_cells_window_of (const int bias) |
| The window of an object drawn with a depth bias of the cells (see jo_cells_depth_bias_at(), jo_cells_set_portal_clipping()): select it with jo_3d_select_window() (jo_3d_slave_select_window() on the slave CPU) before the object is drawn, and the near window after. | |
| int | jo_cells_depth_bias_of (const int cell) |
| Depth bias of an object in a cell (see jo_cells_depth_bias_at()). | |
| unsigned short | jo_cells_generation (void) |
| Generation of the cells: it changes when cells are loaded or freed (the cells found before are then stale). | |
| bool | jo_cells_ray_hit (const jo_pos3D_fixed *const origin, const jo_pos3D_fixed *const dir, const jo_fixed max_t, jo_fixed *const t, jo_pos3D_fixed *const normal) |
| First wall (polygon of a cell) hit by a ray (the bullets). | |
| int | jo_cells_add_point_light_meshes (const bool shadows) |
| The models of the cells are lit by the point lights (see jo/light.h): their meshes are added, and with shadows the walls of the cells stop the light (it goes through the doors). | |
Cells and portals: the rooms of an inside level (sections CELL and PRTL, see Documentation/level_format.md).
| struct jo_cell |
A cell.
| Data Fields | ||
|---|---|---|
| jo_pos3D_fixed | center | |
| jo_fixed | cos | |
| unsigned short | first_portal | |
| int | floor0 | |
| int | floor1 | |
| jo_3d_mesh * | mesh | |
| unsigned short | portal_count | |
| int | radius | |
| jo_3d_mesh * | reflection | |
| jo_fixed | sin | |
| unsigned short | slope | |
| int | x0 | |
| int | x1 | |
| short | yaw | |
| int | z0 | |
| int | z1 | |
| struct jo_cell_portal |
A portal: an opening of a cell toward another cell.
| Data Fields | ||
|---|---|---|
| unsigned short | cell | |
| unsigned short | kind | |
| jo_pos3D_fixed | points[4] | |
| #define JO_CELL_MAX |
Cells at most.
| #define JO_CELL_MAX_DRAWN |
Cells drawn in a frame at most.
| #define JO_CELL_MAX_PORTALS |
Portals at most.
| #define JO_CELLS_DEFAULT_MAX_SHARE |
Highest share of the master CPU by default (all the cells: the slave CPU may draw the entities).
| #define JO_CELLS_DEFAULT_SHARE |
Share of the polygons of the cells drawn by the master CPU at the start (0 to 1024, see jo_cells_draw_prepared_on_both_cpus()).
| int jo_cell_floor | ( | const jo_cell *const | cell, |
| const int | x, | ||
| const int | z ) |
Floor of a cell at a position (its slope).
| cell | Cell |
| x | Position (world) |
| z | Position (world) |
| int jo_cells_add_point_light_meshes | ( | const bool | shadows | ) |
The models of the cells are lit by the point lights (see jo/light.h): their meshes are added, and with shadows the walls of the cells stop the light (it goes through the doors).
| shadows | true: the walls stop the light (a ray for each corner near a light, at the loading) |
| void jo_cells_balance_share | ( | void | ) |
Balance the share of the CPUs for the next frame (see jo_cells_draw_prepared_on_both_cpus()): more polygons to the slave CPU when it waited in the last frame, fewer when the master CPU waited for it (or when its command table is nearly full: its last polygons would be lost).
| int jo_cells_close_portals | ( | const jo_fixed | x, |
| const jo_fixed | z, | ||
| const int | radius, | ||
| const bool | closed ) |
Close the portals of a door (JO_LEVEL_PORTAL_DOOR) whose middle is near a point: the cells behind them are not drawn through them (a closed door: its panel hides the room behind it), or open them again.
| x | Point (world space) |
| z | Point |
| radius | Distance on X and on Z (world units) |
| closed | true: closed |
| int jo_cells_count | ( | void | ) |
Number of cells.
Depth bias of an object in the cells (see jo_cells_draw()): the cells seen through more portals are drawn behind, the objects in them too (else they are seen through the walls of the nearer cells).
| x | Position of the object |
| y | Position of the object (its feet) |
| z | Position of the object |
| int jo_cells_depth_bias_of | ( | const int | cell | ) |
Depth bias of an object in a cell (see jo_cells_depth_bias_at()).
| cell | Cell of the object (jo_cells_object_cell()), -1: outside of the cells |
| int jo_cells_draw | ( | const jo_pos3D_fixed *const | camera | ) |
Draw the cells seen from the camera (the camera matrix is the current matrix, see jo_3d_set_depth_bias()).
| camera | Position of the camera (world) |
| bool jo_cells_draw_mirror | ( | void(* | draw_more )(void) | ) |
Draw the mirror seen by the camera (in the cell of the camera or in a cell seen through a door), when jo_cells_prepare() found one (a portal MIRROR): its cell is drawn again with the camera reflected by the plane of the mirror, in a far window (JO_3D_FAR_WINDOW, then JO_3D_FAR_WINDOW_2 for a second mirror: a polished floor and a mirror on a wall seen together) clipped by the VDP1 to the rectangle of the mirror on the screen. On the master CPU, the camera matrix is the current matrix.
| draw_more | The game draws the other things seen in the mirror (the entities, the model of the player...) with the reflected matrix, JO_NULL: nothing |
| void jo_cells_draw_prepared | ( | const bool | slave | ) |
Draw the cells found by jo_cells_prepare().
| slave | true: on the slave CPU (between jo_3d_slave_begin() and jo_3d_slave_end(), see jo_3d_slave_mesh_draw()), false: on the master CPU (without JO_COMPILE_WITH_DUAL_CPU_MODULE: always on the master CPU) |
| void jo_cells_draw_prepared_on_both_cpus | ( | void(* | slave_before )(void), |
| const int | slave_polygons ) |
Draw the cells found by jo_cells_prepare() on the 2 CPUs: the slave CPU draws its part (a job, see jo_core_exec_on_slave()) while the master CPU draws the other part. The share of each CPU: half of the polygons of the frame to each one (the cells and what else the slave CPU draws), plus a correction that follows the load of the last frames (see jo_cells_balance_share()).
| slave_before | What the slave CPU draws before its part of the cells (in its job: the entities, jo_entities_draw_slave()), JO_NULL: nothing |
| slave_polygons | Polygons of what slave_before draws (see jo_entities_polygon_count()), 0: none |
| void jo_cells_draw_prepared_part | ( | const bool | slave, |
| const int | part, | ||
| const int | handicap ) |
Draw a part of the cells found by jo_cells_prepare(): the 2 CPUs draw them together (the meshes split in 2 parts with about as many polygons, the same split on both CPUs).
| slave | true: on the slave CPU (see jo_cells_draw_prepared()) |
| part | 0 or 1 (-1: all) |
| handicap | Polygons counted in the part 1 before the cells (the other work of its CPU: the part 1 gets fewer) |
| void jo_cells_draw_prepared_share | ( | const bool | slave, |
| const int | part, | ||
| const int | share ) |
Draw a part of the cells found by jo_cells_prepare(): the 2 CPUs draw them together, the polygons split at a share (a mesh can be split: the CPUs can be balanced at each frame, see jo_core_slave_idle_time()).
| slave | true: on the slave CPU (see jo_cells_draw_prepared()) |
| part | 0 (the polygons before the cut) or 1 (after it) |
| share | The cut: the share of the polygons in the part 0 (0 to 1024), the same on both CPUs |
Cell of a position: its box has the position, its floor is under it (the highest one).
| x | Position (world, Q16.16) |
| y | Position: the feet (Saturn Y, Q16.16) |
| z | Position (world, Q16.16) |
| step | The floor can be this much over the feet (a step of the stairs, world units) |
| bool jo_cells_floor | ( | const jo_fixed | x, |
| const jo_fixed | y, | ||
| const jo_fixed | z, | ||
| const int | step, | ||
| int *const | floor ) |
Floor under a position.
| x | Position (world, Q16.16) |
| y | Position: the feet (Saturn Y, Q16.16) |
| z | Position (world, Q16.16) |
| step | The floor can be this much over the feet (world units) |
| floor | Floor (output, Saturn Y, world units) |
| void jo_cells_free | ( | void | ) |
Free the cells (and their models).
| unsigned short jo_cells_generation | ( | void | ) |
Generation of the cells: it changes when cells are loaded or freed (the cells found before are then stale).
| const jo_cell * jo_cells_get | ( | const int | index | ) |
A cell.
| index | Index (0 to jo_cells_count() - 1) |
| int jo_cells_get_share | ( | void | ) |
Share of the polygons of the cells drawn by the master CPU in the next frame (0 to 1024).
| bool jo_cells_have_exits | ( | void | ) |
Check if a cell has a door or a window to the outside (the level is not an inside level: there is a world around the cells).
| bool jo_cells_is_drawn | ( | const int | index | ) |
Check if a cell was drawn in the last call of jo_cells_draw() or jo_cells_prepare() (the objects in the other cells are hidden). The camera outside of the cells: a cell with doors to the outside is drawn when one of them is seen.
| index | Cell (-1: true) |
| bool jo_cells_is_walkable | ( | const jo_fixed | x, |
| const jo_fixed | y, | ||
| const jo_fixed | z, | ||
| const int | radius, | ||
| const int | step ) |
Check if the player can stand at a position: a circle around it is in the box of a cell, the floor of the cell is under the feet (or a step over them).
| x | Position (world, Q16.16) |
| y | Position: the feet (Saturn Y, Q16.16) |
| z | Position (world, Q16.16) |
| radius | Radius of the player (world units) |
| step | The floor can be this much over the feet (world units) |
| int jo_cells_load | ( | jo_level *const | level | ) |
Create the cells of a level (sections CELL and PRTL): the previous ones are freed.
| level | Level (it can be freed after) |
| bool jo_cells_mirror_is_floor | ( | void | ) |
The mirror drawn now (in draw_more of jo_cells_draw_mirror()) is a polished floor (a horizontal portal MIRROR under a half transparent floor), not a mirror on a wall (in draw_more of jo_cells_draw_mirror(): the player does not see his own body under him).
Cell of an object (see jo_cells_depth_bias_at()).
| x | Position of the object |
| y | Position of the object (its feet) |
| z | Position of the object |
| int jo_cells_outside_view | ( | jo_3d_rect *const | rect | ) |
Rectangle of the screen where the outside is seen (after jo_cells_prepare()): the portals of the cells seen that go to the outside (PRTL.cell NO_INDEX: the door of a building on a terrain). Give it to jo_3d_set_view_rect(): only the objects of the outside seen through the doors are drawn.
| rect | Rectangle (output, when the result is 1) |
| int jo_cells_prepare | ( | const jo_pos3D_fixed *const | camera | ) |
Find the cells seen from the camera (the camera matrix is the current matrix): jo_cells_draw() in 2 parts, to draw them on the slave CPU (the master CPU finds them, the slave CPU draws them while the master CPU draws the rest).
| camera | Position of the camera (world) |
| int jo_cells_prepared_polygon_count | ( | void | ) |
Polygons of the cells found by jo_cells_prepare() (the polygons of the chunks seen of the meshes seen: the share of each CPU is cut in them, see jo_cells_draw_prepared_share()).
| bool jo_cells_ray_hit | ( | const jo_pos3D_fixed *const | origin, |
| const jo_pos3D_fixed *const | dir, | ||
| const jo_fixed | max_t, | ||
| jo_fixed *const | t, | ||
| jo_pos3D_fixed *const | normal ) |
First wall (polygon of a cell) hit by a ray (the bullets).
| origin | Origin (world) |
| dir | Direction (unit vector, Q16.16) |
| max_t | Length of the ray (world units, Q16.16) |
| t | Distance of the hit (output, Q16.16) |
| normal | Normal of the polygon hit (output, unit vector) |
| bool jo_cells_seen_through | ( | const int | index, |
| jo_3d_rect *const | rect ) |
The rectangle of the screen where a cell is seen from the outside (through its doors and its near windows, see jo_cells_set_window_distance()), after jo_cells_prepare(): the program can draw what is in the cell in a window clipped to this rectangle (jo_3d_window(), jo_3d_window_clip()): the polygons outside of it are not drawn.
| index | Cell |
| rect | Rectangle (output) |
| bool jo_cells_seen_through_window | ( | const int | index | ) |
Check if a cell is seen from the outside through one of its windows in this frame (see jo_cells_set_window_distance(); or from its doorway: the whole screen).
| index | Cell |
| void jo_cells_set_occluders | ( | const bool | enabled | ) |
A polygon of the cell of the camera that covers the whole screen (the camera near a wall, facing it, or a bench against it) hides everything behind it: the polygons behind it are not drawn (the depth limit of the near window, see jo_3d_set_depth_limit(), set by jo_cells_prepare() in a frame where the cell of the camera is seen alone: nothing seen through a door). Default: on. Against a wall, the VDP1 drew the whole room behind it (up to 50 ms). A polygon with holes in its texture is taken as opaque: nothing is seen through the holes.
| enabled | false: no depth limit |
| void jo_cells_set_portal_clipping | ( | const bool | enabled | ) |
The cells seen through the portals are drawn in the far window (JO_3D_FAR_WINDOW), clipped by the VDP1 to the union of the rectangles of the portals on the screen (default: on). A room seen through a door was drawn whole: the VDP1 spent its time on the walls around the door (up to 50 ms in a frame). Not in a frame with a mirror (it draws in the far window). The objects of these cells go in the far window too: jo_cells_window_of().
| enabled | false: everything in the near window |
| void jo_cells_set_share_limits | ( | const int | min, |
| const int | max ) |
Limits of the share of the master CPU (see jo_cells_draw_prepared_on_both_cpus()).
| min | Lowest share of the master CPU (0 to 1024, 0: the slave CPU can draw all the cells) |
| max | Highest share (0 to 1024, JO_CELLS_DEFAULT_MAX_SHARE by default) |
| void jo_cells_set_window_distance | ( | const int | distance | ) |
Distance from the outside under which a cell is seen through its windows (portals JO_LEVEL_PORTAL_WINDOW to the outside): farther, the cell is not drawn through them (a window is small on the screen, its cell would cost a lot of CPU time for a few pixels: the model outside can show something dark in the window instead).
| distance | Horizontal distance between the camera and the center of the window (units), 0: never (default) |
| bool jo_cells_view_rect_at | ( | const jo_pos3D_fixed *const | position, |
| jo_3d_rect *const | rect ) |
The rectangle of the screen where a point is seen (the cell of the point seen through the doors, see jo_cells_prepare(): after it). For an effect drawn over the 3D view that the walls don't hide (a glow, see jo_3d_glows_set_clip()): it is seen only in this rectangle.
| position | Point (world) |
| rect | Rectangle (output: the whole screen if the point and the camera are in the same cell, or both outside) |
| int jo_cells_window_of | ( | const int | bias | ) |
The window of an object drawn with a depth bias of the cells (see jo_cells_depth_bias_at(), jo_cells_set_portal_clipping()): select it with jo_3d_select_window() (jo_3d_slave_select_window() on the slave CPU) before the object is drawn, and the near window after.
| bias | Depth bias of the object (without the bias of the program) |