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

Jo Engine 3D basics. More...

Go to the source code of this file.

Data Structures

struct  jo_3d_polygon
 Polygon (quadrilateral, a triangle repeats the last vertex). More...
struct  jo_3d_polygon_attribute
 Polygon attribute. More...
struct  jo_3d_polygon_data
 Polygon data (3D model). More...
struct  jo_3d_polygon_range
 Range of polygons of a mesh (see jo_3d_mesh_draw_ranges()). More...
struct  jo_camera
 Camera structure. More...
struct  __jo_may_alias
 Quadrilateral shape structure. More...
struct  jo_3d_mesh
 Mesh structure. More...
struct  jo_3d_part
 Points of a mesh transformed by their own matrix (see __jo_3d_draw_parts()). More...
struct  jo_3d_rect
 A rectangle of the screen (pixels, the edges are in it). More...
struct  jo_3d_ray_plane
 Plane of a polygon for the rays (see jo_3d_mesh_create_ray_planes()): the normal and its distance, without the vertices (the models are in the slow work RAM). More...

Macros

#define JO_3D_PLANE_VERTICES(SIZE)
 Plane vertice table.
#define JO_3D_TRIANGLE_VERTICES(SIZE)
 Triangle vertice table.
#define JO_3D_CUBE_VERTICES(SIZE)
 Cube vertice table.
#define JO_3D_QUAD_VERTEX_COUNT
 Vertex count of a quad (jo_3d_create_mesh_from_vertices() takes 4 vertices for each quad).
#define JO_3D_DEFAULT_PERSPECTIVE_ANGLE
 Default perspective angle in degree (see jo_3d_perspective_angle()).
#define JO_3D_DEFAULT_DISPLAY_LEVEL
 Default display level (see jo_3d_display_level()).
#define JO_3D_SORT_PREVIOUS
 Polygon sort: same depth as the previous polygon.
#define JO_3D_SORT_MIN
 Polygon sort: depth of the nearest vertex.
#define JO_3D_SORT_MAX
 Polygon sort: depth of the farthest vertex.
#define JO_3D_SORT_CENTER
 Polygon sort: average depth of the 4 vertices.
#define JO_3D_SORT_MASK
 Polygon sort mask.
#define JO_3D_SINGLE_PLANE
 Polygon hidden when seen from the back.
#define JO_3D_DUAL_PLANE
 Polygon always displayed.
#define JO_3D_NO_OPTION
 Polygon option: no option.
#define JO_3D_USE_TEXTURE
 Polygon option: textured polygon.
#define JO_3D_USE_LIGHT
 Polygon option: lighting (see jo_3d_light()).
#define JO_3D_USE_PALETTE
 Polygon option: the color is a palette (no lighting).
#define JO_3D_NO_TEXTURE
 No texture.
#define JO_3D_ATTRIBUTE(PLANE, SORT, TEXTURE, COLOR, GOURAUD, DRAW_MODE, DIRECTION, OPTIONS)
 Polygon attribute initializer.
#define JO_3D_NORMAL(X, Y, Z)
 Polygon normal initializer.
#define JO_3D_VERTICES(A, B, C, D)
 Polygon vertices initializer.
#define JO_3D_AXIS_X
 X axis for __jo_3d_rotate().
#define JO_3D_AXIS_Y
 Y axis for __jo_3d_rotate().
#define JO_3D_AXIS_Z
 Z axis for __jo_3d_rotate().
#define JO_3D_NEAR_WINDOW
 Near window (default) for jo_3d_select_window().
#define JO_3D_FAR_WINDOW
 Far window for jo_3d_select_window().
#define JO_3D_FAR_WINDOW_2
 Second far window for jo_3d_select_window() (a second mirror).
#define JO_3D_LAYER_WINDOW
 Window of the transparency layer (see jo/transparency.h): selected by jo_3d_transparency_begin().
#define JO_3D_MAX_GUARD_BAND
 Biggest guard band around the screen (pixels): the coordinates of the VDP1 are limited.
#define JO_3D_DEFAULT_GUARD_BAND
 Default guard band around the screen (pixels, see jo_3d_set_guard_band()): only the polygons that go very far outside of the screen are clipped by the CPU.
#define JO_3D_FADE_LEVELS
 Levels of the fade (the color calculation ratios 1 to 3 of the sprites, see jo_vdp2_set_sprite_blend_ratios()).
#define JO_3D_FADE_LEVEL_SHIFT
 Bit of the level in the color code of a sprite (sprite type 3: its color calculation bits 12 and 11).

Typedefs

typedef jo_pos3D jo_vertice
 Vertice structure.
typedef struct __jo_may_alias jo_3d_quad
 Quadrilateral shape structure.

Functions

static __jo_force_inline void jo_3d_set_quad_vertices (jo_vertice *const vertices, const jo_vertice *const center, const jo_vertice *const right, const jo_vertice *const down)
 Fill the 4 vertices of a quad (a parallelogram) from its center and 2 half edges, in the order of JO_3D_PLANE_VERTICES(): center - right - down, center + right - down, center + right + down, center - right + down.
bool jo_3d_create_sprite_quad (const int sprite_id)
void __jo_3d_look_at (const jo_fixed *const camera, const jo_fixed *const target, const jo_angle angle)
 Multiply the current matrix by a camera matrix (Internal usage).
void __jo_3d_translate (const jo_fixed x, const jo_fixed y, const jo_fixed z)
 Translate the current matrix (Internal usage).
void __jo_3d_scale (const jo_fixed x, const jo_fixed y, const jo_fixed z)
 Scale the current matrix (Internal usage).
void __jo_3d_rotate (const int axis, const jo_angle angle)
 Rotate the current matrix around an axis (Internal usage).
void __jo_3d_light (const jo_pos3D_fixed *const light)
 Set light direction (Internal usage).
void __jo_3d_set_perspective (const jo_angle angle)
 Set perspective angle (Internal usage).
void jo_3d_set_front_layer (const int shift)
 The next 3D polygons (of the master CPU) are a front layer: drawn after (over) all the other polygons, sorted among themselves with the depth divided by 2^shift (a rear-view mirror: its content is far away, but in front of the view of the camera; draw a background first).
bool __jo_3d_draw_ranges_from (const jo_3d_polygon_data *const pdata, const unsigned int first_point, const unsigned int point_count, const jo_3d_polygon_range *const ranges, const int range_count)
 Draw polygons using the current matrix (Internal usage).
bool __jo_3d_draw_ranges (const jo_3d_polygon_data *const pdata, const unsigned int point_count, const jo_3d_polygon_range *const ranges, const int range_count)
static __jo_force_inline bool __jo_3d_draw (const jo_3d_polygon_data *const pdata)
 Draw polygons using the current matrix (Internal usage).
static __jo_force_inline void jo_3d_camera_set_viewpoint (jo_camera *const cam, const int x, const int y, const int z)
 Set the viewpoint of the camera (where the cameraman is).
static __jo_force_inline void jo_3d_camera_set_target (jo_camera *const cam, const int x, const int y, const int z)
 Set the target of the camera (where the scene is located).
static __jo_force_inline void jo_3d_camera_set_z_angle (jo_camera *const cam, const int angle)
 Set the angle of the camera.
static __jo_force_inline void jo_3d_camera_init (jo_camera *const cam)
 Initialize the camera with default values.
static __jo_force_inline void jo_3d_camera_look_at (jo_camera *const cam)
 look at the camera
static __jo_force_inline unsigned int jo_3d_get_polygon_count (void)
 Get polygon count (visible and not visible).
static __jo_force_inline unsigned int jo_3d_get_vertices_count (void)
 Get vertice count.
static __jo_force_inline unsigned int jo_3d_get_displayed_polygon_count (void)
 Get displayed polygon count.
jo_3d_mesh * jo_3d_create_mesh_from_vertices_and_normals (const unsigned int quad_count, jo_vertice *const vertices, jo_vector *const normals)
 Create a mesh programmatically from vertices.
static __jo_force_inline jo_3d_mesh * jo_3d_create_mesh_from_vertices (const unsigned int quad_count, jo_vertice *const vertices)
 Create a mesh programmatically from vertices.
static __jo_force_inline jo_3d_mesh * jo_3d_create_mesh (const unsigned int quad_count)
 Create a mesh programmatically from vertices.
jo_3d_mesh * jo_3d_create_sphere (const int radius, const unsigned int slices, const unsigned int stacks)
 Create a sphere (UV sphere).
void jo_3d_free_mesh (const jo_3d_mesh *const mesh)
 Free a mesh created with jo_3d_create_mesh().
void jo_3d_create_plane (jo_3d_quad *const quad, jo_vertice *const vertices)
 Create a four vertices polygon (Quadrilateral shape).
void jo_3d_create_cube (jo_3d_quad *array, jo_vertice *const vertices)
 Create a cube.
void jo_3d_create_triangle (jo_3d_quad *const quad, jo_vertice *const vertices)
 Create a triangle.
static __jo_force_inline jo_3d_quad * jo_3d_get_sprite_quad (const int sprite_id)
 Get sprite quad.
void jo_3d_free_sprite_quad (const int sprite_id)
 Delete sprite quad.
void jo_3d_set_mesh_polygon_texture (jo_3d_mesh *const mesh, const int sprite_id, const unsigned int index)
 Set a texture on one polygon on the mesh.
void jo_3d_set_mesh_polygon_texture_bank (jo_3d_mesh *const mesh, const int sprite_id, const jo_palette *const palette, const int bank, const unsigned int index)
 Set a texture of 16 colors on one polygon, its colors taken in a bank of 16 colors of a palette (in place of its color lookup table): a polygon of the palette lighting (see jo_3d_set_palette_light()), or opaque over the half transparent water (the MSB of the colors of the palette cleared), or the same texture in other colors.
void jo_3d_set_mesh_polygon_texture_palette (jo_3d_mesh *const mesh, const int sprite_id, const jo_palette *const palette, const unsigned int index)
 Set a texture of 256 colors on one polygon, its colors taken in a palette (its pixel value n: the color n of the palette): opaque over a see-through bottom where the MSB of the colors is cleared, see jo_vdp2_blend_rgb_sprites_only().
void jo_3d_set_mesh_texture (jo_3d_mesh *const mesh, const int sprite_id)
 Set a texture on the mesh.
static __jo_force_inline void jo_3d_set_texture (jo_3d_quad *const quad, const int sprite_id)
 Set a texture on the quadrilateral.
void jo_3d_set_mesh_polygon_wireframe (jo_3d_mesh *const mesh, const unsigned int index, bool wireframe)
 Set wireframe mode on the mesh.
static __jo_force_inline void jo_3d_set_mesh_polygon_palette (jo_3d_mesh *const mesh, const int palette_id, const unsigned int index)
 Set a palette on the mesh.
static __jo_force_inline void jo_3d_set_mesh_palette (jo_3d_mesh *const mesh, const int palette_id)
 Set a palette on one polygon on the mesh.
static __jo_force_inline void jo_3d_set_palette (jo_3d_quad *const quad, const int palette_id)
 Set a palette on the quadrilateral.
static __jo_force_inline bool jo_3d_set_sprite_palette (const int sprite_id, const int palette_id)
 Set a palette on a sprite (3D).
void jo_3d_set_mesh_polygon_high_speed_shrink (jo_3d_mesh *const mesh, const bool enabled, const unsigned int index)
 Enable/Disable High Speed Shrink on one polygon on the mesh.
void jo_3d_set_mesh_high_speed_shrink (jo_3d_mesh *const mesh, const bool enabled)
 Enable/Disable High Speed Shrink on the mesh.
void jo_3d_set_high_speed_shrink (const bool enabled)
 High speed shrink for every textured polygon drawn from now on (models, meshes, levels), whatever their own setting (default: on); can be changed at any time (a scene, a view).
static __jo_force_inline void jo_3d_set_mesh_vertice (jo_3d_mesh *const mesh, const jo_fixed x, const jo_fixed y, const jo_fixed z, const unsigned int index)
 Set vertice position in mesh.
static __jo_force_inline void jo_3d_set_mesh_normal (jo_3d_mesh *const mesh, const jo_fixed x, const jo_fixed y, const jo_fixed z, const unsigned int index)
 Set quad normal in mesh.
static __jo_force_inline void jo_3d_light (const int x, const int y, const int z)
 Use a light source.
static __jo_force_inline void jo_3d_light_fixed (const jo_fixed x, const jo_fixed y, const jo_fixed z)
 Use a light source: its direction as a unit vector.
void jo_3d_set_palette_light (const int levels, const int stride)
 Palette lighting (the light of jo_3d_light() without the RGB colors: the only lighting of the 640 and 704 pixels modes): a lit polygon of a palette color (or a texture of 16 colors with a color bank) takes the shade of its light, its color code + shade * stride (shade 0 = the darkest).
void jo_3d_set_mesh_polygon_light (jo_3d_mesh *const mesh, const bool enabled, const unsigned int index)
 Enable/Disable light on one polygon on the mesh.
void jo_3d_set_mesh_light (jo_3d_mesh *const mesh, const bool enabled)
 Enable/Disable light on the mesh.
static __jo_force_inline void jo_3d_set_light (jo_3d_quad *const quad, const bool enabled)
 Enable/Disable light on the quad.
void jo_3d_set_mesh_polygon_transparency (jo_3d_mesh *const mesh, const bool enabled, const unsigned int index)
 Enable/Disable transparency on one polygon on the mesh.
void jo_3d_set_mesh_transparency (jo_3d_mesh *const mesh, const bool enabled)
 Enable/Disable transparency on the mesh.
static __jo_force_inline void jo_3d_set_transparency (jo_3d_quad *const quad, const bool enabled)
 Enable/Disable transparency on the quadrilateral.
void jo_3d_set_mesh_polygon_screen_doors (jo_3d_mesh *const mesh, const bool enabled, const unsigned int index)
 Enable/Disable screen doors transparency on one polygon on the mesh.
void jo_3d_set_mesh_screen_doors (jo_3d_mesh *const mesh, const bool enabled)
 Enable/Disable screen doors transparency on the mesh.
static __jo_force_inline void jo_3d_set_screen_doors (jo_3d_quad *const quad, const bool enabled)
 Enable/Disable screen doors transparency on the quad.
void jo_3d_set_mesh_polygon_gouraud (jo_3d_mesh *const mesh, const unsigned short table, const unsigned int index)
 Give a gouraud table to one polygon of the mesh (the color of each of its 4 vertices is added to its color).
unsigned short jo_3d_set_mesh_gouraud (jo_3d_mesh *const mesh, const jo_color *const tables)
 Gouraud shading of the whole mesh: one table of 4 colors per polygon (a color per vertex, in the order of the vertices of the polygon), added to the VRAM (see jo_3d_add_gouraud_tables()).
void jo_3d_set_mesh_polygon_color_ex (jo_3d_mesh *const mesh, const jo_color color, const unsigned int index, bool wireframe)
 Set the color on one polygon on the mesh with wireframe option.
static __jo_force_inline void jo_3d_set_mesh_polygon_color (jo_3d_mesh *const mesh, const jo_color color, const unsigned int index)
 Set the color on one polygon on the mesh.
void jo_3d_set_mesh_color (jo_3d_mesh *const mesh, const jo_color color)
 Set the color on the mesh.
void jo_3d_set_mesh_color_ex (jo_3d_mesh *const mesh, const jo_color color, bool wireframe)
 Set the color on the mesh.
static __jo_force_inline void jo_3d_set_color (jo_3d_quad *const quad, const jo_color color)
 Set the color on the quadrilateral.
void jo_3d_push_matrix (void)
 Push 3D matrix.
void jo_3d_pop_matrix (void)
 Pop 3D matrix.
static __jo_force_inline void jo_3d_rotate_matrix (short x, short y, short z)
 Rotate 3D matrix using degree.
static __jo_force_inline void jo_3d_rotate_matrix_x (short x)
 Rotate 3D matrix using degree (X axis).
static __jo_force_inline void jo_3d_rotate_matrix_y (short y)
 Rotate 3D matrix using degree (Y axis).
static __jo_force_inline void jo_3d_rotate_matrix_z (short z)
 Rotate 3D matrix using degree (Z axis).
static __jo_force_inline void jo_3d_rotate_matrix_rad (float x, float y, float z)
 Rotate 3D matrix using radian.
static __jo_force_inline void jo_3d_rotate_matrix_rad_x (float x)
 Rotate 3D matrix using radian (X axis).
static __jo_force_inline void jo_3d_rotate_matrix_rad_y (float y)
 Rotate 3D matrix using radian (Y axis).
static __jo_force_inline void jo_3d_rotate_matrix_rad_z (float z)
 Rotate 3D matrix using radian (Z axis).
static __jo_force_inline void jo_3d_rotate_matrix_angle (const jo_angle x, const jo_angle y, const jo_angle z)
 Rotate 3D matrix using jo_angle (0x10000 = 360 degrees: a fraction of degree, no float).
static __jo_force_inline void jo_3d_rotate_matrix_angle_x (const jo_angle x)
 Rotate 3D matrix using jo_angle (X axis).
static __jo_force_inline void jo_3d_rotate_matrix_angle_y (const jo_angle y)
 Rotate 3D matrix using jo_angle (Y axis).
static __jo_force_inline void jo_3d_rotate_matrix_angle_z (const jo_angle z)
 Rotate 3D matrix using jo_angle (Z axis).
static __jo_force_inline void jo_3d_translate_matrixf (float x, float y, float z)
 Translate 3D matrix (using floating numbers).
static __jo_force_inline void jo_3d_translate_matrix_fixed (jo_fixed x, jo_fixed y, jo_fixed z)
 Translate 3D matrix.
static __jo_force_inline void jo_3d_translate_matrix (int x, int y, int z)
 Translate 3D matrix.
static __jo_force_inline void jo_3d_translate_matrix_x (int x)
 Translate 3D matrix (X axis).
static __jo_force_inline void jo_3d_translate_matrix_y (int y)
 Translate 3D matrix (Y axis).
static __jo_force_inline void jo_3d_translate_matrix_z (int z)
 Translate 3D matrix (Z axis).
static __jo_force_inline void jo_3d_draw (jo_3d_quad *const quad)
 Draw a quadrilateral.
static __jo_force_inline void jo_3d_mesh_draw (jo_3d_mesh *const mesh)
 Draw a mesh.
static __jo_force_inline bool jo_3d_mesh_draw_ranges (const jo_3d_mesh *const mesh, const unsigned int point_count, const jo_3d_polygon_range *const ranges, const int range_count)
 Draw some ranges of polygons of a mesh, without copying them (the points are transformed once).
static __jo_force_inline void jo_3d_add_polygon_range (jo_3d_polygon_range *const ranges, int *const range_count, const int first, const int count)
 Add polygons to a list of ranges (see jo_3d_mesh_draw_ranges()): joined to the last range when they follow it.
static __jo_force_inline unsigned int jo_3d_get_mesh_polygon_count (jo_3d_mesh *const mesh)
 Get polygon count on the mesh.
static __jo_force_inline void __jo_poylgon_draw_iterator (jo_node *node)
 Internal usage for polygon display.
static __jo_force_inline void jo_3d_draw_list (jo_list *const list)
 Draw a list of quadrilateral.
static __jo_force_inline void jo_3d_draw_array (jo_3d_quad *const array, int array_size)
 Draw an array of quadrilateral.
static __jo_force_inline bool jo_3d_draw_sprite (const int sprite_id)
 Draw a sprite.
static __jo_force_inline void jo_3d_draw_sprite_at (const int sprite_id, const int x, const int y, const int z)
 Draw a sprite.
static __jo_force_inline void jo_3d_draw_billboard (const int sprite_id, const int x, const int y, const int z)
 Draw billboard.
static __jo_force_inline void jo_3d_draw_scaled_billboard (const int sprite_id, const int x, const int y, const int z, const int scale)
 Draw billboard with a specific scale.
static __jo_force_inline void jo_3d_set_scalef (const float x, const float y, const float z)
 Change scale using floating number.
static __jo_force_inline void jo_3d_set_scale (const int x, const int y, const int z)
 Change scale.
static __jo_force_inline void jo_3d_set_scale_fixed (const jo_fixed x, const jo_fixed y, const jo_fixed z)
 Change scale using fixed number.
static __jo_force_inline void jo_3d_restore_scale (void)
 Scale of 1 (nothing changes): the scale of jo_3d_set_scale() is in the current matrix, jo_3d_pop_matrix() restores the matrix before it (jo_3d_push_matrix(), jo_3d_set_scale(), draw, jo_3d_pop_matrix()).
static __jo_force_inline bool jo_3d_window (const int left, const int top, const int right, const int bottom, const int z_limit, const int center_x, const int center_y)
 Sets up a window region on the projection surface.
static __jo_force_inline void jo_3d_window_clip (const bool clip)
 The 3D polygons drawn in the current window are clipped by the VDP1 to its rectangle (user clipping: a mirror, a rear-view mirror, a view of a split screen), or not (default: the whole screen).
static __jo_force_inline void jo_3d_select_window (const int window)
 Select the window used by jo_3d_window() and by the next drawings.
static __jo_force_inline void jo_3d_set_windows_apart (const bool apart)
 The windows do not overlap (a split screen: a view per player in its window): the commands of each window are drawn together, window after window (window 0 first), sorted by depth in their window; else (default) the commands of all the windows are sorted together by depth (a mirror in the view: its window over the other one).
static __jo_force_inline void jo_3d_perspective_angle (const int angle)
 Set the perspective angle.
static __jo_force_inline void jo_3d_set_perspective (const jo_angle angle)
 Set the perspective angle using jo_angle (a fraction of degree, as slPerspective() of the SGL).
static __jo_force_inline void jo_3d_display_level (const unsigned short level)
 Set the display level of the viewing volume.
void jo_3d_enable_dsp (const bool slave_cpu)
 Transform the vertices with the SCU DSP (the third processor of the Saturn).
void jo_3d_disable_dsp (void)
 Stop using the SCU DSP to transform the vertices (see jo_3d_enable_dsp()).
static __jo_force_inline void jo_3d_set_guard_band (const int pixels)
 Set the guard band around the screen used by the clipping of the polygons drawn after this call.
static __jo_force_inline void jo_3d_set_wireframe (const bool enabled)
 Wireframe mode: the polygons and the standing sprites (distorted sprites) are drawn as their outline, in one color; the normal and scaled sprites (a HUD for instance) are drawn as they are.
static __jo_force_inline bool jo_3d_is_wireframe (void)
 Check the wireframe mode (see jo_3d_set_wireframe()).
static __jo_force_inline void jo_3d_set_depth_bias (const int bias)
 Set a depth added to the polygons and sprites drawn after this call, to sort them (the farthest are drawn first).
static __jo_force_inline int jo_3d_get_depth_bias (void)
 Get the depth added to the polygons and sprites (see jo_3d_set_depth_bias()).
void jo_3d_transform_point (const jo_pos3D_fixed *const in, jo_pos3D_fixed *out)
 Transform a point by the current matrix (for instance a world position into the view space, after jo_3d_camera_look_at() or the rotations and translations of the camera).
void jo_3d_transform_point_by (const jo_fixed(*const m)[3], const jo_pos3D_fixed *const in, jo_pos3D_fixed *const out)
 Transform a point by a matrix (see jo_3d_transform_point(): the same result with the current matrix).
void jo_3d_slave_select_window (const int window)
 Select the window of the next drawings of the slave CPU (call it on the slave CPU; jo_3d_slave_begin() selects the window of the master CPU, see jo_3d_select_window()).
void jo_3d_get_matrix (jo_fixed *m)
 Copy the current matrix.
void jo_3d_reflect_matrix (const jo_pos3D_fixed *const normal, const jo_fixed distance)
 Multiply the current matrix by a reflection through a plane (a mirror: the camera matrix of the reflected view).
void jo_3d_set_mirror (const bool mirror)
 The next polygons of the master CPU are seen in a mirror: their front faces are counterclockwise on the screen.
static __jo_force_inline jo_fixed jo_3d_get_projection_distance (void)
 Get the projection distance (distance of the projection plane, in pixels).
bool jo_3d_is_sphere_visible (const jo_pos3D_fixed *const center, const jo_fixed radius, const jo_fixed max_distance)
 Check if a sphere (in the view space) can be seen (view frustum of the screen).
bool jo_3d_slave_is_sphere_visible (const jo_pos3D_fixed *const center, const jo_fixed radius, const jo_fixed max_distance)
 jo_3d_is_sphere_visible() for the slave CPU: with the rectangle of jo_3d_set_view_rect() as it was at jo_3d_slave_begin() (the master CPU can change it while the slave CPU draws)
void jo_3d_set_view_rect (const jo_3d_rect *const rect)
 The objects are seen only in a rectangle of the screen: jo_3d_is_sphere_visible() is false for the spheres outside of it (the camera is in a building: the outside is seen only through its door, see jo_cells_outside_view()).
bool jo_3d_get_view_rect (jo_3d_rect *const rect)
 The rectangle of jo_3d_set_view_rect().
int jo_3d_mesh_get_bounding_sphere (const jo_3d_mesh *const mesh, jo_pos3D_fixed *const center)
 Bounding sphere of the points of a mesh (the sphere around their bounding box).
bool jo_3d_mesh_ray_hit (const jo_3d_mesh *const mesh, const jo_pos3D_fixed *const origin, const jo_pos3D_fixed *const dir, jo_fixed *const best, jo_pos3D_fixed *const normal)
 First polygon of a mesh hit by a ray (the bullets: the walls of a building, the rooms of a level...).
jo_3d_ray_plane * jo_3d_mesh_create_ray_planes (const jo_3d_mesh *const mesh)
 The planes of the polygons of a mesh for jo_3d_mesh_ray_hit_with_planes() (the rays are faster: the most polygons are rejected by their plane).
bool jo_3d_mesh_ray_hit_with_planes (const jo_3d_mesh *const mesh, const jo_3d_ray_plane *const planes, const jo_pos3D_fixed *const origin, const jo_pos3D_fixed *const dir, jo_fixed *const best, jo_pos3D_fixed *const normal)
 jo_3d_mesh_ray_hit() with the planes of the polygons of the mesh (the same result, faster)
bool jo_3d_draw_standing_sprite (const int sprite_id, const jo_pos3D_fixed *const foot, const jo_fixed width, const jo_fixed height, const jo_fixed sway, const bool flip)
 Draw a sprite standing on the ground and facing the camera (trees, grass, characters far away...).
bool jo_3d_set_sprite_fade (const int sprite_id, const jo_palette *const palette, const int bank)
 A standing sprite that fades with the distance (see jo_3d_set_fade_distances()): its 16 colors copied in a bank of a palette, used beyond the start of the fade.
void jo_3d_set_fade_distances (const jo_fixed start, const jo_fixed end)
 The distances of the fade of the standing sprites (see jo_3d_set_sprite_fade()): opaque up to start, then JO_3D_FADE_LEVELS levels more and more transparent up to end (beyond: the most transparent; don't draw them).
jo_3d_mesh * jo_3d_create_indexed_mesh (const unsigned int point_count, const unsigned int polygon_count)
 Create an empty mesh made of shared points and polygons (indexes of the points).
bool jo_3d_set_texture_subdivision (const int sprite_id)
 Draw the polygons that use a texture in parts when they are near the camera (2 x 2 or 4 x 4 parts, each part with its tile of the texture).
bool jo_3d_set_texture_subdivision_fine (const int sprite_id)
 Add finer tiles to the tiles of a texture (see jo_3d_set_texture_subdivision()): 8 x 8 and 16 x 16 tiles, for the parts of its polygons cut in 4 x 4 parts that cross the near plane, go very far outside of the screen, are big and partly out of the screen, or still distorted by the perspective. The last tile of a part through the near plane, or with its lines pulled in to the screen (VDP1 time), is drawn whole on what is seen of it (the VDP1 can't start a texture at any column): its texture is squeezed by up to a tile, 8 texels of a 32 x 32 texture with the 4 x 4 tiles, 2 with the 16 x 16 tiles. For a texture magnified near the camera (texels of more than about 10 pixels: a texture of a few texels on a big wall, a big floor).
bool jo_3d_set_texture_subdivision_near_only (const int sprite_id)
 Like jo_3d_set_texture_subdivision(), but only the polygons that cross the near plane (or go very far outside of the screen) are drawn in parts: a model already cut in small quads when it was made keeps its quads as they are, the parts of a quad next to a whole quad overlapped it.
void jo_3d_set_texture_subdivision_depth (const int sprite_id, const jo_fixed depth)
 Draw in parts (see jo_3d_set_texture_subdivision()) only the polygons of a texture whose nearest vertex is nearer than a depth: the ground next to the camera, where its texture slides the most (farther, the parts cost CPU time for little).
void jo_3d_set_texture_subdivision_error (const int sprite_id, const int pixels)
 Distortion of a texture over which its polygons are drawn in parts (see jo_3d_set_texture_subdivision()): a pattern with straight lines (a tiled floor) shows the distortion more, the lines bend where a part meets a whole polygon.
void jo_3d_set_fewer_parts (const bool enabled)
 Draw the polygons in parts only where it is needed to draw them at all (see jo_3d_set_texture_subdivision()): the polygons that cross the near plane, and those beyond the guard band in 2 x 2 parts only (see jo_3d_set_guard_band(); a bigger guard band keeps them few); not for the perspective of their texture, nor the big ones mostly out of the screen (the VDP1 draws their pixels out of the screen too).
bool jo_3d_set_texture_mipmaps (const int sprite_id)
 Create smaller copies of a texture (half and quarter size, "mipmaps") used when the texture is drawn small.
bool jo_3d_set_texture_mipmap_copies (const int sprite_id, const int half_id, const int levels)
 Give a texture its smaller copies made beforehand (see jo_3d_set_texture_mipmaps()): for the textures it can't reduce itself (256 colors: their palette is chosen per polygon), or reduced better by a tool (the averages in the colors of the palette, a mean color searched among 255 at the loading took seconds).
void jo_3d_slave_begin (void)
 Prepare the 3D drawing of the slave CPU (call it on the master CPU, before jo_core_exec_on_slave()).
void jo_3d_slave_set_depth_bias (const int bias)
 Change the depth bias of the objects drawn by the slave CPU (call it on the slave CPU).
void jo_3d_slave_set_guard_band (const int pixels)
 Change the guard band of the objects drawn by the slave CPU (call it on the slave CPU, see jo_3d_set_guard_band()).
void jo_3d_slave_transform_point (const jo_pos3D_fixed *const in, jo_pos3D_fixed *out)
 Transform a point by the matrix of the slave CPU (call it on the slave CPU, see jo_3d_transform_point()).
bool jo_3d_slave_push_matrix (void)
 Push the matrix of the slave CPU (call it on the slave CPU, see jo_3d_push_matrix()).
void jo_3d_slave_pop_matrix (void)
 Pop the matrix of the slave CPU (call it on the slave CPU, see jo_3d_pop_matrix()).
void jo_3d_slave_translate_matrix_fixed (const jo_fixed x, const jo_fixed y, const jo_fixed z)
 Translate the matrix of the slave CPU (call it on the slave CPU, see jo_3d_translate_matrix_fixed()).
void jo_3d_slave_rotate_matrix (const int x, const int y, const int z)
 Rotate the matrix of the slave CPU (call it on the slave CPU, see jo_3d_rotate_matrix()).
void jo_3d_slave_rotate (const int axis, const jo_angle angle)
 Rotate the matrix of the slave CPU around an axis by a precise angle (call it on the slave CPU): a slow turn (a big wheel, a fan) moves by less than a degree per frame.
void jo_3d_slave_set_scale_fixed (const jo_fixed x, const jo_fixed y, const jo_fixed z)
 Scale the matrix of the slave CPU (call it on the slave CPU, see jo_3d_set_scale_fixed()).
bool jo_3d_slave_mesh_draw_ranges (const jo_3d_mesh *const mesh, const unsigned int point_count, const jo_3d_polygon_range *const ranges, const int range_count)
 Draw some ranges of polygons of a mesh on the slave CPU, without copying them (see jo_3d_mesh_draw_ranges()).
bool __jo_3d_slave_draw_ranges_from (const jo_3d_mesh *const mesh, const unsigned int first_point, const unsigned int point_count, const jo_3d_polygon_range *const ranges, const int range_count)
 jo_3d_slave_mesh_draw_ranges() with the points of the ranges known (see __jo_3d_draw_ranges_from())
static __jo_force_inline bool jo_3d_slave_mesh_draw (const jo_3d_mesh *const mesh)
 Draw a mesh on the slave CPU (call it on the slave CPU, between jo_3d_slave_begin() and jo_3d_slave_end()).
int jo_3d_slave_get_command_count (void)
 VDP1 commands used by the slave CPU in the last frame (see jo_3d_slave_end()).
bool jo_3d_slave_draw_standing_sprite (const int sprite_id, const jo_pos3D_fixed *const foot, const jo_fixed width, const jo_fixed height, const jo_fixed sway, const bool flip)
 Draw a sprite standing on the ground and facing the camera on the slave CPU (see jo_3d_draw_standing_sprite()).
void jo_3d_slave_set_fade_distances (const jo_fixed start, const jo_fixed end)
 The distances of the fade of the standing sprites of the slave CPU (see jo_3d_set_fade_distances()), until the next jo_3d_slave_begin() (call it on the slave CPU).
int jo_3d_slave_get_current_command_count (void)
 Commands drawn by the slave CPU since jo_3d_slave_begin() (0 after jo_3d_slave_end()).
int jo_3d_slave_get_max_commands (void)
 Commands the slave CPU can draw in a frame (the others are dropped, jo_3d_slave_mesh_draw() returns false).
int jo_3d_slave_get_max_vertices (void)
 Points of the biggest object the slave CPU can draw (a bigger object is not drawn).
void jo_3d_slave_end (void)
 Add the polygons drawn by the slave CPU to the frame (call it on the master CPU, after jo_core_wait_for_slave()).
void jo_3d_slave_set_kept_commands (const int count)
 VDP1 commands kept for what is drawn after jo_3d_slave_end() (the weapon, the HUD): the polygons of the slave CPU don't take them. Without it, a frame full of polygons left no room for the HUD (and JO_DEBUG stopped the game: "Too many VDP1 commands in a frame").
unsigned short jo_3d_add_gouraud_tables (const jo_color *const tables, const unsigned int count)
 Add gouraud tables in the VDP1 VRAM (4 colors per table, one per vertex of a polygon).
void jo_3d_free_gouraud_tables (const unsigned short adr, const unsigned int count)
 Give back gouraud tables of jo_3d_add_gouraud_tables() (jo_3d_free_model() gives back the tables of a model).
void jo_3d_set_tint (const int r, const int g, const int b)
 Tint the next meshes drawn by the master CPU: added to the colors of their gouraud tables (the light of a lamp on a character, see jo_3d_point_lights_sample()), jo_3d_set_tint(0, 0, 0) to stop.
unsigned short jo_3d_get_tint (void)
 The tint of the master CPU, packed (see jo_3d_set_tint()): 5 bits per component (signed, steps of 2), 0: none.
void jo_3d_set_packed_tint (const unsigned short tint)
 Tint the next meshes drawn by the master CPU (see jo_3d_set_tint()).
void jo_3d_slave_set_tint (const unsigned short tint)
 Tint the next meshes drawn by the slave CPU (call it on the slave CPU).
void jo_3d_prepare_tint (const jo_3d_mesh *const mesh)
 Make the tinted copy of the gouraud tables of a mesh for the current tint of the master CPU (see jo_3d_set_tint()), for the slave CPU to draw it with this tint (jo_3d_slave_set_tint()).
bool jo_3d_set_mesh_environment (jo_3d_mesh *const mesh, const int sprite_id, const int tiles)
 Environment map of a mesh (a reflection, like the paint of a car): its polygons set by jo_3d_set_mesh_polygon_environment() show a tile of a picture of the surroundings, the tile of the direction of their normal in the view. The picture is cut in tiles x tiles tiles: the tile (i, j) is for the normals that point to the left (i = 0) or to the right (i = tiles - 1), up (j = 0) or down (j = tiles - 1): a sphere seen from the front (a "matcap"). The reflection moves on the object when the camera or the object turns.
bool jo_3d_set_mesh_polygon_environment (jo_3d_mesh *const mesh, const unsigned int index)
 A polygon shows the environment map of its mesh (see jo_3d_set_mesh_environment()): its gouraud table tints the reflection (16: the picture as it is).

Variables

jo_3d_quad ** __jo_sprite_quad
 Sprite quads (internal engine usage): a quad per sprite, the table allocated with the first quad (JO_NULL: none).
unsigned short __jo_3d_polygon_count
 Polygon count of the current frame (Internal usage).
unsigned short __jo_3d_vertice_count
 Vertice count of the current frame (Internal usage).
unsigned short __jo_3d_displayed_polygon_count
 Displayed polygon count of the current frame (Internal usage).
int __jo_3d_guard_band
 Guard band (internal engine usage, see jo_3d_set_guard_band()).

Detailed Description

Jo Engine 3D basics.

Author
Johannes Fetz
Bug
No known bugs.

Data Structure Documentation

◆ jo_3d_polygon

struct jo_3d_polygon

Polygon (quadrilateral, a triangle repeats the last vertex).

Data Fields
jo_pos3D_fixed normal
unsigned short vertices[4]

◆ jo_3d_polygon_attribute

struct jo_3d_polygon_attribute

Polygon attribute.

Data Fields
unsigned short color
unsigned short direction
unsigned short draw_mode
unsigned short gouraud_table
unsigned char plane
unsigned char sort
unsigned short texture_id

◆ jo_3d_polygon_data

struct jo_3d_polygon_data

Polygon data (3D model).

Data Fields
jo_3d_polygon_attribute * attributes
unsigned int point_count
jo_pos3D_fixed * points
unsigned int polygon_count
jo_3d_polygon * polygons

◆ jo_3d_polygon_range

struct jo_3d_polygon_range

Range of polygons of a mesh (see jo_3d_mesh_draw_ranges()).

Data Fields
unsigned short count
unsigned short first

◆ __jo_may_alias

struct __jo_may_alias

Quadrilateral shape structure.

Keyboard data.

Light gun data (Internal usage, see jo_get_input_gun_position()).

Pointing peripheral data (mouse).

Analog peripheral data (racing wheel, mission stick, 3D pad).

Remarks
Accessed as jo_3d_mesh (may alias)
Inherits from jo_peripheral (cast friendly)
Data Fields
jo_3d_polygon_attribute attribute
unsigned char code
unsigned char condition
jo_3d_polygon_data data
unsigned short data
unsigned char id
unsigned char light
unsigned char modifiers
unsigned short pull
unsigned short push
unsigned int reserved[3]
unsigned char reserved1[3]
unsigned int reserved2[2]
unsigned char size
unsigned char w
short x
unsigned char x
short y
unsigned char y
unsigned char z

◆ jo_3d_mesh

struct jo_3d_mesh

Mesh structure.

Data Fields
jo_3d_polygon_data data

◆ jo_3d_part

struct jo_3d_part

Points of a mesh transformed by their own matrix (see __jo_3d_draw_parts()).

Data Fields
unsigned short count
unsigned short first
jo_fixed(* matrix)[3]

◆ jo_3d_rect

struct jo_3d_rect

A rectangle of the screen (pixels, the edges are in it).

Data Fields
short bottom
short left
short right
short top

◆ jo_3d_ray_plane

struct jo_3d_ray_plane

Plane of a polygon for the rays (see jo_3d_mesh_create_ray_planes()): the normal and its distance, without the vertices (the models are in the slow work RAM).

Data Fields
short box[6]
int d
short nx
short ny
short nz
short unused

Macro Definition Documentation

◆ JO_3D_ATTRIBUTE

#define JO_3D_ATTRIBUTE ( PLANE,
SORT,
TEXTURE,
COLOR,
GOURAUD,
DRAW_MODE,
DIRECTION,
OPTIONS )

Polygon attribute initializer.

Parameters
PLANEJO_3D_SINGLE_PLANE or JO_3D_DUAL_PLANE
SORTJO_3D_SORT_xxx
TEXTURESprite id (JO_3D_NO_TEXTURE)
COLORRGB color or palette
GOURAUDGouraud table address / 8 (JO_VDP1_NO_GOURAUD)
DRAW_MODEJO_VDP1_COLOR_MODE_xxx | JO_VDP1_COLOR_CALC_xxx | ...
DIRECTIONJO_VDP1_SPRITE_NO_FLIP, JO_VDP1_POLYGON, etc
OPTIONSJO_3D_USE_xxx (JO_3D_NO_OPTION)

◆ JO_3D_AXIS_X

#define JO_3D_AXIS_X

X axis for __jo_3d_rotate().

◆ JO_3D_AXIS_Y

#define JO_3D_AXIS_Y

Y axis for __jo_3d_rotate().

◆ JO_3D_AXIS_Z

#define JO_3D_AXIS_Z

Z axis for __jo_3d_rotate().

◆ JO_3D_CUBE_VERTICES

#define JO_3D_CUBE_VERTICES ( SIZE)

Cube vertice table.

◆ JO_3D_DEFAULT_DISPLAY_LEVEL

#define JO_3D_DEFAULT_DISPLAY_LEVEL

Default display level (see jo_3d_display_level()).

◆ JO_3D_DEFAULT_GUARD_BAND

#define JO_3D_DEFAULT_GUARD_BAND

Default guard band around the screen (pixels, see jo_3d_set_guard_band()): only the polygons that go very far outside of the screen are clipped by the CPU.

◆ JO_3D_DEFAULT_PERSPECTIVE_ANGLE

#define JO_3D_DEFAULT_PERSPECTIVE_ANGLE

Default perspective angle in degree (see jo_3d_perspective_angle()).

◆ JO_3D_DUAL_PLANE

#define JO_3D_DUAL_PLANE

Polygon always displayed.

◆ JO_3D_FADE_LEVEL_SHIFT

#define JO_3D_FADE_LEVEL_SHIFT

Bit of the level in the color code of a sprite (sprite type 3: its color calculation bits 12 and 11).

◆ JO_3D_FADE_LEVELS

#define JO_3D_FADE_LEVELS

Levels of the fade (the color calculation ratios 1 to 3 of the sprites, see jo_vdp2_set_sprite_blend_ratios()).

◆ JO_3D_FAR_WINDOW

#define JO_3D_FAR_WINDOW

Far window for jo_3d_select_window().

◆ JO_3D_FAR_WINDOW_2

#define JO_3D_FAR_WINDOW_2

Second far window for jo_3d_select_window() (a second mirror).

◆ JO_3D_LAYER_WINDOW

#define JO_3D_LAYER_WINDOW

Window of the transparency layer (see jo/transparency.h): selected by jo_3d_transparency_begin().

◆ JO_3D_MAX_GUARD_BAND

#define JO_3D_MAX_GUARD_BAND

Biggest guard band around the screen (pixels): the coordinates of the VDP1 are limited.

◆ JO_3D_NEAR_WINDOW

#define JO_3D_NEAR_WINDOW

Near window (default) for jo_3d_select_window().

◆ JO_3D_NO_OPTION

#define JO_3D_NO_OPTION

Polygon option: no option.

◆ JO_3D_NO_TEXTURE

#define JO_3D_NO_TEXTURE

No texture.

◆ JO_3D_NORMAL

#define JO_3D_NORMAL ( X,
Y,
Z )

Polygon normal initializer.

Parameters
XNormal X (float)
YNormal Y (float)
ZNormal Z (float)

◆ JO_3D_PLANE_VERTICES

#define JO_3D_PLANE_VERTICES ( SIZE)

Plane vertice table.

◆ JO_3D_QUAD_VERTEX_COUNT

#define JO_3D_QUAD_VERTEX_COUNT

Vertex count of a quad (jo_3d_create_mesh_from_vertices() takes 4 vertices for each quad).

◆ JO_3D_SINGLE_PLANE

#define JO_3D_SINGLE_PLANE

Polygon hidden when seen from the back.

◆ JO_3D_SORT_CENTER

#define JO_3D_SORT_CENTER

Polygon sort: average depth of the 4 vertices.

◆ JO_3D_SORT_MASK

#define JO_3D_SORT_MASK

Polygon sort mask.

◆ JO_3D_SORT_MAX

#define JO_3D_SORT_MAX

Polygon sort: depth of the farthest vertex.

◆ JO_3D_SORT_MIN

#define JO_3D_SORT_MIN

Polygon sort: depth of the nearest vertex.

◆ JO_3D_SORT_PREVIOUS

#define JO_3D_SORT_PREVIOUS

Polygon sort: same depth as the previous polygon.

◆ JO_3D_TRIANGLE_VERTICES

#define JO_3D_TRIANGLE_VERTICES ( SIZE)

Triangle vertice table.

◆ JO_3D_USE_LIGHT

#define JO_3D_USE_LIGHT

Polygon option: lighting (see jo_3d_light()).

◆ JO_3D_USE_PALETTE

#define JO_3D_USE_PALETTE

Polygon option: the color is a palette (no lighting).

◆ JO_3D_USE_TEXTURE

#define JO_3D_USE_TEXTURE

Polygon option: textured polygon.

◆ JO_3D_VERTICES

#define JO_3D_VERTICES ( A,
B,
C,
D )

Polygon vertices initializer.

Parameters
AFirst vertex index
BSecond vertex index
CThird vertex index
DFourth vertex index (same as C for a triangle)

Typedef Documentation

◆ jo_3d_quad

typedef struct __jo_may_alias jo_3d_quad

Quadrilateral shape structure.

Remarks
Accessed as jo_3d_mesh (may alias)

◆ jo_vertice

Vertice structure.

Function Documentation

◆ __jo_3d_draw()

__jo_force_inline bool __jo_3d_draw ( const jo_3d_polygon_data *const pdata)
static

Draw polygons using the current matrix (Internal usage).

Parameters
pdataPolygon data (vertices, polygons and attributes)
Returns
false if the VDP1 command table is full

◆ __jo_3d_draw_ranges()

bool __jo_3d_draw_ranges ( const jo_3d_polygon_data *const pdata,
const unsigned int point_count,
const jo_3d_polygon_range *const ranges,
const int range_count )

◆ __jo_3d_draw_ranges_from()

bool __jo_3d_draw_ranges_from ( const jo_3d_polygon_data *const pdata,
const unsigned int first_point,
const unsigned int point_count,
const jo_3d_polygon_range *const ranges,
const int range_count )

Draw polygons using the current matrix (Internal usage).

Parameters
pdataPolygon data (vertices, polygons and attributes)
point_countNumber of points transformed (the first ones of pdata)
rangesRanges of polygons drawn (JO_NULL: all the polygons)
range_countNumber of ranges
Returns
false if the VDP1 command table is full
Remarks
Hidden polygons (behind the camera, outside the window or seen from the back) are skipped

Draw some ranges of polygons whose points are known: only the points from first_point to point_count - 1 are transformed (see jo_3d_mesh_draw_ranges(); the chunks of the cells)

Parameters
first_pointFirst point used by the polygons of the ranges (none before it)

◆ __jo_3d_light()

void __jo_3d_light ( const jo_pos3D_fixed *const light)

Set light direction (Internal usage).

Parameters
lightLight direction (unit vector) in the current matrix space
Remarks
The vector is transformed by the current matrix, so call it after jo_3d_camera_look_at()

◆ __jo_3d_look_at()

void __jo_3d_look_at ( const jo_fixed *const camera,
const jo_fixed *const target,
const jo_angle angle )

Multiply the current matrix by a camera matrix (Internal usage).

Parameters
cameraCamera position (x, y, z)
targetPoint looked at by the camera (x, y, z)
angleRotation around the view axis
Remarks
Y axis goes down, so the world "up" vector is -Y

◆ __jo_3d_rotate()

void __jo_3d_rotate ( const int axis,
const jo_angle angle )

Rotate the current matrix around an axis (Internal usage).

Parameters
axisJO_3D_AXIS_X, JO_3D_AXIS_Y or JO_3D_AXIS_Z
angleRotation angle (0x10000 = 360 degrees)

◆ __jo_3d_scale()

void __jo_3d_scale ( const jo_fixed x,
const jo_fixed y,
const jo_fixed z )

Scale the current matrix (Internal usage).

Parameters
xHorizontal scale (JO_FIXED_1 = no scale)
yVertical scale (JO_FIXED_1 = no scale)
zDepth scale (JO_FIXED_1 = no scale)

◆ __jo_3d_set_perspective()

void __jo_3d_set_perspective ( const jo_angle angle)

Set perspective angle (Internal usage).

Parameters
angleHorizontal field of view (0x4000 = 90 degrees)
Remarks
Changes the projection distance used by 3D polygons, 3D sprites and the rotation scroll screen

◆ __jo_3d_slave_draw_ranges_from()

bool __jo_3d_slave_draw_ranges_from ( const jo_3d_mesh *const mesh,
const unsigned int first_point,
const unsigned int point_count,
const jo_3d_polygon_range *const ranges,
const int range_count )

jo_3d_slave_mesh_draw_ranges() with the points of the ranges known (see __jo_3d_draw_ranges_from())

◆ __jo_3d_translate()

void __jo_3d_translate ( const jo_fixed x,
const jo_fixed y,
const jo_fixed z )

Translate the current matrix (Internal usage).

Parameters
xHorizontal translation
yVertical translation
zDepth translation

◆ __jo_poylgon_draw_iterator()

__jo_force_inline void __jo_poylgon_draw_iterator ( jo_node * node)
static

Internal usage for polygon display.

Warning
Don't use it

◆ jo_3d_add_gouraud_tables()

unsigned short jo_3d_add_gouraud_tables ( const jo_color *const tables,
const unsigned int count )

Add gouraud tables in the VDP1 VRAM (4 colors per table, one per vertex of a polygon).

Parameters
tablesColors (4 per table), or JO_NULL to only reserve the memory (black)
countTable count
Returns
Address / 8 of the first table (gouraud_table of a polygon attribute, the next table is + 1), 0 if out of memory
Remarks
The tables use the memory of the sprites (2 tables per line of a sprite of 8 pixels wide). A color of a table is added to the color of the polygon: 16 for each component (JO_COLOR_SATURN_RGB(16, 16, 16)) doesn't change it

◆ jo_3d_add_polygon_range()

__jo_force_inline void jo_3d_add_polygon_range ( jo_3d_polygon_range *const ranges,
int *const range_count,
const int first,
const int count )
static

Add polygons to a list of ranges (see jo_3d_mesh_draw_ranges()): joined to the last range when they follow it.

Parameters
rangesRanges (room for one more)
range_countNumber of ranges (updated)
firstFirst polygon
countNumber of polygons (0 or less: nothing added)

◆ jo_3d_camera_init()

__jo_force_inline void jo_3d_camera_init ( jo_camera *const cam)
static

Initialize the camera with default values.

Parameters
camPointer to a camera struct

◆ jo_3d_camera_look_at()

__jo_force_inline void jo_3d_camera_look_at ( jo_camera *const cam)
static

look at the camera

Parameters
camPointer to a camera struct

◆ jo_3d_camera_set_target()

__jo_force_inline void jo_3d_camera_set_target ( jo_camera *const cam,
const int x,
const int y,
const int z )
static

Set the target of the camera (where the scene is located).

Parameters
camPointer to a camera struct
xX coord
yY coord
zZ coord

◆ jo_3d_camera_set_viewpoint()

__jo_force_inline void jo_3d_camera_set_viewpoint ( jo_camera *const cam,
const int x,
const int y,
const int z )
static

Set the viewpoint of the camera (where the cameraman is).

Parameters
camPointer to a camera struct
xX coord
yY coord
zZ coord

◆ jo_3d_camera_set_z_angle()

__jo_force_inline void jo_3d_camera_set_z_angle ( jo_camera *const cam,
const int angle )
static

Set the angle of the camera.

Parameters
camPointer to a camera struct
angleZ-angle in degree

◆ jo_3d_create_cube()

void jo_3d_create_cube ( jo_3d_quad * array,
jo_vertice *const vertices )

Create a cube.

Parameters
arrayAddress to a 6 jo_3d_quad allocated struct
verticesVertices coords (table of 24 (6x4) jo_vertice)

◆ jo_3d_create_indexed_mesh()

jo_3d_mesh * jo_3d_create_indexed_mesh ( const unsigned int point_count,
const unsigned int polygon_count )

Create an empty mesh made of shared points and polygons (indexes of the points).

Parameters
point_countPoint count
polygon_countPolygon count
Returns
The mesh (points, polygons and attributes cleared) or JO_NULL if out of memory
Remarks
Set the points, the vertices of the polygons and their attributes (see jo_3d_set_mesh_polygon_texture()). Free the mesh with jo_3d_free_mesh()

◆ jo_3d_create_mesh()

__jo_force_inline jo_3d_mesh * jo_3d_create_mesh ( const unsigned int quad_count)
static

Create a mesh programmatically from vertices.

Parameters
quad_countQuad count (Quad count == Polygon count)
Returns
The mesh
Remarks
The return type can be casted to (jo_3d_mesh *)

◆ jo_3d_create_mesh_from_vertices()

__jo_force_inline jo_3d_mesh * jo_3d_create_mesh_from_vertices ( const unsigned int quad_count,
jo_vertice *const vertices )
static

Create a mesh programmatically from vertices.

Parameters
quad_countQuad count (Quad count == Polygon count)
verticesAn array of jo_vertice (4 * quad_count)
Returns
The mesh
Remarks
The return type can be casted to (jo_3d_mesh *)

◆ jo_3d_create_mesh_from_vertices_and_normals()

jo_3d_mesh * jo_3d_create_mesh_from_vertices_and_normals ( const unsigned int quad_count,
jo_vertice *const vertices,
jo_vector *const normals )

Create a mesh programmatically from vertices.

Parameters
quad_countQuad count (Quad count == Polygon count)
verticesAn array of jo_vertice (4 * quad_count)
normalsAn array of jo_vector (quad_count)
Returns
The mesh
Remarks
The return type can be casted to (jo_3d_mesh *)
Returns JO_NULL if out of memory. The polygons are white by default

◆ jo_3d_create_plane()

void jo_3d_create_plane ( jo_3d_quad *const quad,
jo_vertice *const vertices )

Create a four vertices polygon (Quadrilateral shape).

Parameters
quadAddress to a jo_3d_quad allocated struct
verticesVertices coords (table of 4 jo_vertice)

◆ jo_3d_create_sphere()

jo_3d_mesh * jo_3d_create_sphere ( const int radius,
const unsigned int slices,
const unsigned int stacks )

Create a sphere (UV sphere).

Parameters
radiusRadius
slicesNumber of vertical slices (around the Y axis, 3 minimum)
stacksNumber of horizontal stacks (from the top to the bottom, 2 minimum)
Returns
The mesh (slices * stacks polygons) or JO_NULL if out of memory
Remarks
The polygons are white (see jo_3d_set_mesh_color(), jo_3d_set_mesh_texture(), jo_3d_set_mesh_light(), etc)
The normals are computed, so the lighting works (see jo_3d_set_mesh_light())
The polygons near the poles are triangles. The back faces are not drawn (single plane polygons)
Free the mesh with jo_3d_free_mesh()
Warning
The VDP1 draws polygons and not pixels, so keep slices * stacks low (for instance 12 * 8 = 96 polygons)

◆ jo_3d_create_sprite_quad()

bool jo_3d_create_sprite_quad ( const int sprite_id)

◆ jo_3d_create_triangle()

void jo_3d_create_triangle ( jo_3d_quad *const quad,
jo_vertice *const vertices )

Create a triangle.

Parameters
quadAddress to a jo_3d_quad allocated struct
verticesVertices coords (table of 3 jo_vertice)

◆ jo_3d_disable_dsp()

void jo_3d_disable_dsp ( void )

Stop using the SCU DSP to transform the vertices (see jo_3d_enable_dsp()).

◆ jo_3d_display_level()

__jo_force_inline void jo_3d_display_level ( const unsigned short level)
static

Set the display level of the viewing volume.

Parameters
levelDistance from the viewpoint and the projection surface

◆ jo_3d_draw()

__jo_force_inline void jo_3d_draw ( jo_3d_quad *const quad)
static

Draw a quadrilateral.

Parameters
quadAddress to a jo_3d_quad allocated struct

◆ jo_3d_draw_array()

__jo_force_inline void jo_3d_draw_array ( jo_3d_quad *const array,
int array_size )
static

Draw an array of quadrilateral.

Parameters
arrayArray of quadrilateral
array_sizeSize of the array

◆ jo_3d_draw_billboard()

__jo_force_inline void jo_3d_draw_billboard ( const int sprite_id,
const int x,
const int y,
const int z )
static

Draw billboard.

Parameters
sprite_idSprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()
xX coordinate
yY coordinate
zZ coordinate

◆ jo_3d_draw_list()

__jo_force_inline void jo_3d_draw_list ( jo_list *const list)
static

Draw a list of quadrilateral.

Parameters
listList of quadrilateral

◆ jo_3d_draw_scaled_billboard()

__jo_force_inline void jo_3d_draw_scaled_billboard ( const int sprite_id,
const int x,
const int y,
const int z,
const int scale )
static

Draw billboard with a specific scale.

Parameters
sprite_idSprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()
xX coordinate
yY coordinate
zZ coordinate
scaleScale

◆ jo_3d_draw_sprite()

__jo_force_inline bool jo_3d_draw_sprite ( const int sprite_id)
static

Draw a sprite.

Parameters
sprite_idSprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()
Returns
true if succeeded otherwise false

◆ jo_3d_draw_sprite_at()

__jo_force_inline void jo_3d_draw_sprite_at ( const int sprite_id,
const int x,
const int y,
const int z )
static

Draw a sprite.

Parameters
sprite_idSprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()
xX coordinate
yY coordinate
zZ coordinate

◆ jo_3d_draw_standing_sprite()

bool jo_3d_draw_standing_sprite ( const int sprite_id,
const jo_pos3D_fixed *const foot,
const jo_fixed width,
const jo_fixed height,
const jo_fixed sway,
const bool flip )

Draw a sprite standing on the ground and facing the camera (trees, grass, characters far away...).

Parameters
sprite_idSprite Id returned by jo_sprite_add(), jo_sprite_add_tga(), jo_sprite_add_bin(), etc
footPosition of the bottom center of the sprite (world space, Q16.16)
widthWidth (world units, Q16.16)
heightHeight (world units, Q16.16)
swayHorizontal offset of the top of the sprite (world units, Q16.16): wind
flipHorizontal flip
Returns
true if it is drawn (false: behind the camera, outside of the screen or too near)
Remarks
The sprite is sorted with the depth of its foot (see jo_3d_set_depth_bias())

◆ jo_3d_enable_dsp()

void jo_3d_enable_dsp ( const bool slave_cpu)

Transform the vertices with the SCU DSP (the third processor of the Saturn).

Parameters
slave_cpufalse: for the objects drawn by the master CPU (jo_3d_mesh_draw(), etc), true: for the objects drawn by the slave CPU (jo_3d_slave_mesh_draw())
Remarks
The DSP computes the rotation of the vertices of a batch while the CPU projects the previous batch: the CPU time of the vertices is about 2 times smaller (the results are the same)
Only for the vertices in the high work RAM (the DSP can't read the low work RAM) and the objects of 12 vertices or more
The DSP is used by one CPU only. The program of the DSP is loaded by this function: call it again after using the DSP for something else (see dsp.h)

◆ jo_3d_free_gouraud_tables()

void jo_3d_free_gouraud_tables ( const unsigned short adr,
const unsigned int count )

Give back gouraud tables of jo_3d_add_gouraud_tables() (jo_3d_free_model() gives back the tables of a model).

Parameters
adrAddress / 8 returned by jo_3d_add_gouraud_tables()
countTable count given to jo_3d_add_gouraud_tables()
Remarks
The memory is given back for the last set of the shared sprite of the small sets, or for a set in its own sprite when it is the last sprite: free the sets in the reverse order of their adding. Else it stays used (jo_sprite_free_from() of an earlier sprite gives it back)

◆ jo_3d_free_mesh()

void jo_3d_free_mesh ( const jo_3d_mesh *const mesh)

Free a mesh created with jo_3d_create_mesh().

Parameters
meshThe mesh to free
Remarks
The mesh itself is also freed, so don't use it anymore

◆ jo_3d_free_sprite_quad()

void jo_3d_free_sprite_quad ( const int sprite_id)

Delete sprite quad.

Parameters
sprite_idSprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()

◆ jo_3d_get_depth_bias()

__jo_force_inline int jo_3d_get_depth_bias ( void )
static

Get the depth added to the polygons and sprites (see jo_3d_set_depth_bias()).

Returns
Depth (units)

◆ jo_3d_get_displayed_polygon_count()

__jo_force_inline unsigned int jo_3d_get_displayed_polygon_count ( void )
static

Get displayed polygon count.

Warning
This function must be called after display polygons
Returns
polygon count

◆ jo_3d_get_matrix()

void jo_3d_get_matrix ( jo_fixed * m)

Copy the current matrix.

Parameters
mOutput: 12 values, 4 rows of 3 values. Rows 0 to 2: the rotation (m[2], m[5], m[8] is the direction of the view in the world when the matrix only has the rotations of the camera), row 3: the translation

◆ jo_3d_get_mesh_polygon_count()

__jo_force_inline unsigned int jo_3d_get_mesh_polygon_count ( jo_3d_mesh *const mesh)
static

Get polygon count on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
Returns
polygon count

◆ jo_3d_get_polygon_count()

__jo_force_inline unsigned int jo_3d_get_polygon_count ( void )
static

Get polygon count (visible and not visible).

Warning
This function must be called after display polygons
Returns
polygon count

◆ jo_3d_get_projection_distance()

__jo_force_inline jo_fixed jo_3d_get_projection_distance ( void )
static

Get the projection distance (distance of the projection plane, in pixels).

Returns
Q16.16 distance: a point of the view space (x, y, z) is drawn at (x * distance / z, y * distance / z)
Remarks
See jo_3d_perspective_angle()

◆ jo_3d_get_sprite_quad()

__jo_force_inline jo_3d_quad * jo_3d_get_sprite_quad ( const int sprite_id)
static

Get sprite quad.

Parameters
sprite_idSprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()
Returns
Sprite quad

◆ jo_3d_get_tint()

unsigned short jo_3d_get_tint ( void )

The tint of the master CPU, packed (see jo_3d_set_tint()): 5 bits per component (signed, steps of 2), 0: none.

Remarks
For jo_3d_set_packed_tint() and jo_3d_slave_set_tint(): the tint of an object sampled by the master CPU (jo_3d_point_lights_sample()), drawn by the slave CPU

◆ jo_3d_get_vertices_count()

__jo_force_inline unsigned int jo_3d_get_vertices_count ( void )
static

Get vertice count.

Warning
This function must be called after display polygons
Returns
vertice count

◆ jo_3d_get_view_rect()

bool jo_3d_get_view_rect ( jo_3d_rect *const rect)

The rectangle of jo_3d_set_view_rect().

Parameters
rectThe rectangle (output)
Returns
false if there is none (the whole screen)

◆ jo_3d_is_sphere_visible()

bool jo_3d_is_sphere_visible ( const jo_pos3D_fixed *const center,
const jo_fixed radius,
const jo_fixed max_distance )

Check if a sphere (in the view space) can be seen (view frustum of the screen).

Parameters
centerCenter of the sphere in the view space (see jo_3d_transform_point())
radiusRadius (Q16.16)
max_distanceFarthest distance (Q16.16)
Returns
true if a part of the sphere may be in the view (the test is conservative)

◆ jo_3d_is_wireframe()

__jo_force_inline bool jo_3d_is_wireframe ( void )
static

Check the wireframe mode (see jo_3d_set_wireframe()).

Returns
true: wireframe

◆ jo_3d_light()

__jo_force_inline void jo_3d_light ( const int x,
const int y,
const int z )
static

Use a light source.

Parameters
xX position of the light source
yY position of the light source
zZ position of the light source

◆ jo_3d_light_fixed()

__jo_force_inline void jo_3d_light_fixed ( const jo_fixed x,
const jo_fixed y,
const jo_fixed z )
static

Use a light source: its direction as a unit vector.

Parameters
xX of the direction (Q16.16)
yY of the direction (Q16.16)
zZ of the direction (Q16.16)
Remarks
The vector is transformed by the current matrix, so call it after jo_3d_camera_look_at()

◆ jo_3d_mesh_create_ray_planes()

jo_3d_ray_plane * jo_3d_mesh_create_ray_planes ( const jo_3d_mesh *const mesh)

The planes of the polygons of a mesh for jo_3d_mesh_ray_hit_with_planes() (the rays are faster: the most polygons are rejected by their plane).

Parameters
meshMesh (its polygons don't change)
Returns
The planes (jo_free() them before the mesh), JO_NULL if the memory is full

◆ jo_3d_mesh_draw()

__jo_force_inline void jo_3d_mesh_draw ( jo_3d_mesh *const mesh)
static

Draw a mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct

◆ jo_3d_mesh_draw_ranges()

__jo_force_inline bool jo_3d_mesh_draw_ranges ( const jo_3d_mesh *const mesh,
const unsigned int point_count,
const jo_3d_polygon_range *const ranges,
const int range_count )
static

Draw some ranges of polygons of a mesh, without copying them (the points are transformed once).

Parameters
meshMesh
point_countNumber of points used by these polygons (the first points of the mesh are transformed). With all the points of the mesh, the points used by a few polygons are searched (only these ones are transformed); with fewer points, they are all transformed (the caller knows the points of its ranges)
rangesRanges of polygons
range_countNumber of ranges
Returns
false if the VDP1 command table is full or a polygon uses a point after point_count

◆ jo_3d_mesh_get_bounding_sphere()

int jo_3d_mesh_get_bounding_sphere ( const jo_3d_mesh *const mesh,
jo_pos3D_fixed *const center )

Bounding sphere of the points of a mesh (the sphere around their bounding box).

Parameters
meshMesh
centerCenter of the sphere (output, in the space of the mesh, whole units)
Returns
Radius (whole units: 2 more than the half diagonal of the box, the points are rounded to whole units)
Remarks
Computed once (when the mesh is loaded), then used with jo_3d_is_sphere_visible() to skip the meshes outside of the view

◆ jo_3d_mesh_ray_hit()

bool jo_3d_mesh_ray_hit ( const jo_3d_mesh *const mesh,
const jo_pos3D_fixed *const origin,
const jo_pos3D_fixed *const dir,
jo_fixed *const best,
jo_pos3D_fixed *const normal )

First polygon of a mesh hit by a ray (the bullets: the walls of a building, the rooms of a level...).

Parameters
meshMesh
originOrigin (in the space of the mesh)
dirDirection (unit vector, in the space of the mesh)
bestDistance of the nearest hit (Q16.16): give the length of the ray, updated when a nearer polygon is hit
normalNormal of the polygon hit (in the space of the mesh): updated
Returns
true if a nearer polygon was hit
Remarks
Only the front faces are hit. 32 bits integers (whole units, polygons up to 4000 units): the 64 bits operations are slow on the SH-2

◆ jo_3d_mesh_ray_hit_with_planes()

bool jo_3d_mesh_ray_hit_with_planes ( const jo_3d_mesh *const mesh,
const jo_3d_ray_plane *const planes,
const jo_pos3D_fixed *const origin,
const jo_pos3D_fixed *const dir,
jo_fixed *const best,
jo_pos3D_fixed *const normal )

jo_3d_mesh_ray_hit() with the planes of the polygons of the mesh (the same result, faster)

Parameters
meshMesh
planesThe planes of the mesh (see jo_3d_mesh_create_ray_planes()), JO_NULL: without them
originOrigin (in the space of the mesh)
dirDirection (unit vector, in the space of the mesh)
bestDistance of the nearest hit (Q16.16): give the length of the ray, updated when a nearer polygon is hit
normalNormal of the polygon hit (in the space of the mesh): updated
Returns
true if a nearer polygon was hit

◆ jo_3d_perspective_angle()

__jo_force_inline void jo_3d_perspective_angle ( const int angle)
static

Set the perspective angle.

Parameters
angleAngle in degree (from 10 to 160)

◆ jo_3d_pop_matrix()

void jo_3d_pop_matrix ( void )

Pop 3D matrix.

◆ jo_3d_prepare_tint()

void jo_3d_prepare_tint ( const jo_3d_mesh *const mesh)

Make the tinted copy of the gouraud tables of a mesh for the current tint of the master CPU (see jo_3d_set_tint()), for the slave CPU to draw it with this tint (jo_3d_slave_set_tint()).

Parameters
meshMesh

◆ jo_3d_push_matrix()

void jo_3d_push_matrix ( void )

Push 3D matrix.

◆ jo_3d_reflect_matrix()

void jo_3d_reflect_matrix ( const jo_pos3D_fixed *const normal,
const jo_fixed distance )

Multiply the current matrix by a reflection through a plane (a mirror: the camera matrix of the reflected view).

Parameters
normalNormal of the plane (unit vector, world space)
distanceThe plane is n.p = distance (world units, Q16.16)
Remarks
The winding of the polygons is reversed in the reflected view: see jo_3d_set_mirror()

◆ jo_3d_restore_scale()

__jo_force_inline void jo_3d_restore_scale ( void )
static

Scale of 1 (nothing changes): the scale of jo_3d_set_scale() is in the current matrix, jo_3d_pop_matrix() restores the matrix before it (jo_3d_push_matrix(), jo_3d_set_scale(), draw, jo_3d_pop_matrix()).

◆ jo_3d_rotate_matrix()

__jo_force_inline void jo_3d_rotate_matrix ( short x,
short y,
short z )
static

Rotate 3D matrix using degree.

Parameters
xX Angle in degree
yY Angle in degree
zZ Angle in degree

◆ jo_3d_rotate_matrix_angle()

__jo_force_inline void jo_3d_rotate_matrix_angle ( const jo_angle x,
const jo_angle y,
const jo_angle z )
static

Rotate 3D matrix using jo_angle (0x10000 = 360 degrees: a fraction of degree, no float).

Parameters
xX Angle
yY Angle
zZ Angle
Remarks
Same order as jo_3d_rotate_matrix(): X, then Y, then Z

◆ jo_3d_rotate_matrix_angle_x()

__jo_force_inline void jo_3d_rotate_matrix_angle_x ( const jo_angle x)
static

Rotate 3D matrix using jo_angle (X axis).

Parameters
xX Angle (0x10000 = 360 degrees)

◆ jo_3d_rotate_matrix_angle_y()

__jo_force_inline void jo_3d_rotate_matrix_angle_y ( const jo_angle y)
static

Rotate 3D matrix using jo_angle (Y axis).

Parameters
yY Angle (0x10000 = 360 degrees)

◆ jo_3d_rotate_matrix_angle_z()

__jo_force_inline void jo_3d_rotate_matrix_angle_z ( const jo_angle z)
static

Rotate 3D matrix using jo_angle (Z axis).

Parameters
zZ Angle (0x10000 = 360 degrees)

◆ jo_3d_rotate_matrix_rad()

__jo_force_inline void jo_3d_rotate_matrix_rad ( float x,
float y,
float z )
static

Rotate 3D matrix using radian.

Parameters
xX Angle in radian
yY Angle in radian
zZ Angle in radian

◆ jo_3d_rotate_matrix_rad_x()

__jo_force_inline void jo_3d_rotate_matrix_rad_x ( float x)
static

Rotate 3D matrix using radian (X axis).

Parameters
xX Angle in radian

◆ jo_3d_rotate_matrix_rad_y()

__jo_force_inline void jo_3d_rotate_matrix_rad_y ( float y)
static

Rotate 3D matrix using radian (Y axis).

Parameters
yY Angle in radian

◆ jo_3d_rotate_matrix_rad_z()

__jo_force_inline void jo_3d_rotate_matrix_rad_z ( float z)
static

Rotate 3D matrix using radian (Z axis).

Parameters
zZ Angle in radian

◆ jo_3d_rotate_matrix_x()

__jo_force_inline void jo_3d_rotate_matrix_x ( short x)
static

Rotate 3D matrix using degree (X axis).

Parameters
xX Angle in degree

◆ jo_3d_rotate_matrix_y()

__jo_force_inline void jo_3d_rotate_matrix_y ( short y)
static

Rotate 3D matrix using degree (Y axis).

Parameters
yY Angle in degree

◆ jo_3d_rotate_matrix_z()

__jo_force_inline void jo_3d_rotate_matrix_z ( short z)
static

Rotate 3D matrix using degree (Z axis).

Parameters
zZ Angle in degree

◆ jo_3d_select_window()

__jo_force_inline void jo_3d_select_window ( const int window)
static

Select the window used by jo_3d_window() and by the next drawings.

Parameters
windowJO_3D_NEAR_WINDOW, JO_3D_FAR_WINDOW, JO_3D_FAR_WINDOW_2 or JO_3D_LAYER_WINDOW

◆ jo_3d_set_color()

__jo_force_inline void jo_3d_set_color ( jo_3d_quad *const quad,
const jo_color color )
static

Set the color on the quadrilateral.

Parameters
quadAddress to a jo_3d_quad allocated struct
colorColor

◆ jo_3d_set_depth_bias()

__jo_force_inline void jo_3d_set_depth_bias ( const int bias)
static

Set a depth added to the polygons and sprites drawn after this call, to sort them (the farthest are drawn first).

Parameters
biasDepth (units). For instance, in a first person game the world is drawn with a positive bias and the weapon without bias: the weapon is always over the world, even when a wall is nearer than the weapon
Remarks
The depth used to sort is limited to 0 to 65535: the depth plus the bias must stay in this range
The bias isn't reset at the end of the frame

◆ jo_3d_set_fade_distances()

void jo_3d_set_fade_distances ( const jo_fixed start,
const jo_fixed end )

The distances of the fade of the standing sprites (see jo_3d_set_sprite_fade()): opaque up to start, then JO_3D_FADE_LEVELS levels more and more transparent up to end (beyond: the most transparent; don't draw them).

Parameters
startDepth of the start (world units, Q16.16)
endDepth of the end (world units, Q16.16); end <= start: no fade (the default)
Remarks
The slave CPU takes them at jo_3d_slave_begin() (see jo_3d_slave_set_fade_distances())

◆ jo_3d_set_fewer_parts()

void jo_3d_set_fewer_parts ( const bool enabled)

Draw the polygons in parts only where it is needed to draw them at all (see jo_3d_set_texture_subdivision()): the polygons that cross the near plane, and those beyond the guard band in 2 x 2 parts only (see jo_3d_set_guard_band(); a bigger guard band keeps them few); not for the perspective of their texture, nor the big ones mostly out of the screen (the VDP1 draws their pixels out of the screen too).

Parameters
enabledtrue: fewer parts (the CPU time of the parts saved), false: the default
Remarks
For both CPUs. A split screen (2 views per frame, each one half as high: the texture slides less, the VDP1 has time to spare): about 10 % of the time of the CPUs (Mednafen emulated a split screen of a 3D game 10 % faster)

◆ jo_3d_set_front_layer()

void jo_3d_set_front_layer ( const int shift)

The next 3D polygons (of the master CPU) are a front layer: drawn after (over) all the other polygons, sorted among themselves with the depth divided by 2^shift (a rear-view mirror: its content is far away, but in front of the view of the camera; draw a background first).

Parameters
shiftThe depth is divided by 2^shift (the sort keys of the layer stay small: 1 + z / 2^shift), -1: the normal sort again
Remarks
The sort keys of the other polygons must stay bigger: their depth bias (see jo_3d_set_depth_bias())

◆ jo_3d_set_guard_band()

__jo_force_inline void jo_3d_set_guard_band ( const int pixels)
static

Set the guard band around the screen used by the clipping of the polygons drawn after this call.

Parameters
pixelsDistance outside of the screen (0 to JO_3D_MAX_GUARD_BAND pixels). A polygon that goes further is clipped by the CPU (at the edges of the screen), a polygon that stays inside is drawn by the VDP1 as it is
Remarks
The VDP1 also spends time on the pixels outside of the screen: a small guard band (64 pixels for instance) saves VDP1 time, a big one saves CPU time. A big guard band is useful for big polygons near the camera that always go a little outside of the screen (the weapon of a first person game for instance)
Warning
The VDP1 maps the whole texture on each part of a clipped polygon: the texture of a clipped polygon is distorted. A small guard band is fine for detail textures (ground, grass) but not for a texture with lines (a grid for instance)
Remarks
The default is JO_3D_DEFAULT_GUARD_BAND (only the polygons too big for the VDP1 are clipped). The guard band isn't reset at the end of the frame

◆ jo_3d_set_high_speed_shrink()

void jo_3d_set_high_speed_shrink ( const bool enabled)

High speed shrink for every textured polygon drawn from now on (models, meshes, levels), whatever their own setting (default: on); can be changed at any time (a scene, a view).

Parameters
enabledtrue: all of them, false: back to their own setting (jo_3d_set_mesh_high_speed_shrink(), the materials JO_3D_MATERIAL_HIGH_SPEED_SHRINK): a texture whose details of one texel must stay sharp far away (a small text)
Remarks
A texture drawn smaller than it is on a line (far away, seen at an angle): the VDP1 reads every other texel (the even ones) instead of all of them, the line takes about half the time on a console (any shrink, even a small one). No change for the textures drawn at their size or bigger. The cost: a little less sharp far away, a detail of one texel (a thin line, a small text) can flicker or vanish between two copies of the mipmaps (jo_3d_set_texture_mipmaps())
Mednafen draws the picture of the high speed shrink but not its gain: measure on a console

◆ jo_3d_set_light()

__jo_force_inline void jo_3d_set_light ( jo_3d_quad *const quad,
const bool enabled )
static

Enable/Disable light on the quad.

Parameters
quadAddress to a jo_3d_quad allocated struct
enabledtrue to enable light support

◆ jo_3d_set_mesh_color()

void jo_3d_set_mesh_color ( jo_3d_mesh *const mesh,
const jo_color color )

Set the color on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
colorColor

◆ jo_3d_set_mesh_color_ex()

void jo_3d_set_mesh_color_ex ( jo_3d_mesh *const mesh,
const jo_color color,
bool wireframe )

Set the color on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
colorColor
wireframeTrue to enable wireframe mode

◆ jo_3d_set_mesh_environment()

bool jo_3d_set_mesh_environment ( jo_3d_mesh *const mesh,
const int sprite_id,
const int tiles )

Environment map of a mesh (a reflection, like the paint of a car): its polygons set by jo_3d_set_mesh_polygon_environment() show a tile of a picture of the surroundings, the tile of the direction of their normal in the view. The picture is cut in tiles x tiles tiles: the tile (i, j) is for the normals that point to the left (i = 0) or to the right (i = tiles - 1), up (j = 0) or down (j = tiles - 1): a sphere seen from the front (a "matcap"). The reflection moves on the object when the camera or the object turns.

Parameters
meshMesh (the normals of its polygons are computed)
sprite_idThe picture (RGB, its width / tiles a multiple of 8 pixels)
tilesTiles on a side (4 to 8: more tiles, a smoother reflection on round objects)
Returns
false if the picture can't be cut, or too many meshes have a reflection (8)
Remarks
The polygons of the mesh are drawn by the C loop of the master CPU (the matrix of the object: not the bones of a pose)

◆ jo_3d_set_mesh_gouraud()

unsigned short jo_3d_set_mesh_gouraud ( jo_3d_mesh *const mesh,
const jo_color *const tables )

Gouraud shading of the whole mesh: one table of 4 colors per polygon (a color per vertex, in the order of the vertices of the polygon), added to the VRAM (see jo_3d_add_gouraud_tables()).

Parameters
meshAddress to a jo_3d_mesh allocated struct
tablesColors: 4 per polygon (JO_COLOR_SATURN_RGB(16, 16, 16): the color of the polygon unchanged; the gouraud shading doesn't saturate: a component over 31 wraps around to the dark)
Returns
Address / 8 of the first table (the table of the polygon i: + i, to change its colors later), 0 if out of memory

◆ jo_3d_set_mesh_high_speed_shrink()

void jo_3d_set_mesh_high_speed_shrink ( jo_3d_mesh *const mesh,
const bool enabled )

Enable/Disable High Speed Shrink on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
enabledtrue to enable High Speed Shrink

◆ jo_3d_set_mesh_light()

void jo_3d_set_mesh_light ( jo_3d_mesh *const mesh,
const bool enabled )

Enable/Disable light on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
enabledtrue to enable light support

◆ jo_3d_set_mesh_normal()

__jo_force_inline void jo_3d_set_mesh_normal ( jo_3d_mesh *const mesh,
const jo_fixed x,
const jo_fixed y,
const jo_fixed z,
const unsigned int index )
static

Set quad normal in mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
xX position
yY position
zZ position
indexquad index on the mesh

◆ jo_3d_set_mesh_palette()

__jo_force_inline void jo_3d_set_mesh_palette ( jo_3d_mesh *const mesh,
const int palette_id )
static

Set a palette on one polygon on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
palette_idPalette id from jo_create_palette()

◆ jo_3d_set_mesh_polygon_color()

__jo_force_inline void jo_3d_set_mesh_polygon_color ( jo_3d_mesh *const mesh,
const jo_color color,
const unsigned int index )
static

Set the color on one polygon on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
colorColor
indexpolygon index on the mesh

◆ jo_3d_set_mesh_polygon_color_ex()

void jo_3d_set_mesh_polygon_color_ex ( jo_3d_mesh *const mesh,
const jo_color color,
const unsigned int index,
bool wireframe )

Set the color on one polygon on the mesh with wireframe option.

Parameters
meshAddress to a jo_3d_mesh allocated struct
colorColor
indexpolygon index on the mesh
wireframeTrue to display only the edge of polygons

◆ jo_3d_set_mesh_polygon_environment()

bool jo_3d_set_mesh_polygon_environment ( jo_3d_mesh *const mesh,
const unsigned int index )

A polygon shows the environment map of its mesh (see jo_3d_set_mesh_environment()): its gouraud table tints the reflection (16: the picture as it is).

Parameters
meshMesh
indexPolygon
Returns
false if the mesh has no environment map

◆ jo_3d_set_mesh_polygon_gouraud()

void jo_3d_set_mesh_polygon_gouraud ( jo_3d_mesh *const mesh,
const unsigned short table,
const unsigned int index )

Give a gouraud table to one polygon of the mesh (the color of each of its 4 vertices is added to its color).

Parameters
meshAddress to a jo_3d_mesh allocated struct
tableAddress / 8 of the table (see jo_3d_add_gouraud_tables()), JO_VDP1_NO_GOURAUD: no gouraud shading
indexpolygon index on the mesh
Remarks
The light of the mesh (jo_3d_set_mesh_light()) writes its own tables: don't use both on a polygon

◆ jo_3d_set_mesh_polygon_high_speed_shrink()

void jo_3d_set_mesh_polygon_high_speed_shrink ( jo_3d_mesh *const mesh,
const bool enabled,
const unsigned int index )

Enable/Disable High Speed Shrink on one polygon on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
enabledtrue to enable High Speed Shrink
indexpolygon index on the mesh

◆ jo_3d_set_mesh_polygon_light()

void jo_3d_set_mesh_polygon_light ( jo_3d_mesh *const mesh,
const bool enabled,
const unsigned int index )

Enable/Disable light on one polygon on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
enabledtrue to enable light support
indexpolygon index on the mesh

◆ jo_3d_set_mesh_polygon_palette()

__jo_force_inline void jo_3d_set_mesh_polygon_palette ( jo_3d_mesh *const mesh,
const int palette_id,
const unsigned int index )
static

Set a palette on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
indexpolygon index on the mesh
palette_idPalette id from jo_create_palette()

◆ jo_3d_set_mesh_polygon_screen_doors()

void jo_3d_set_mesh_polygon_screen_doors ( jo_3d_mesh *const mesh,
const bool enabled,
const unsigned int index )

Enable/Disable screen doors transparency on one polygon on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
enabledtrue to enable screen doors transparency
indexpolygon index on the mesh

◆ jo_3d_set_mesh_polygon_texture()

void jo_3d_set_mesh_polygon_texture ( jo_3d_mesh *const mesh,
const int sprite_id,
const unsigned int index )

Set a texture on one polygon on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
sprite_idSprite ID
indexpolygon index on the mesh

◆ jo_3d_set_mesh_polygon_texture_bank()

void jo_3d_set_mesh_polygon_texture_bank ( jo_3d_mesh *const mesh,
const int sprite_id,
const jo_palette *const palette,
const int bank,
const unsigned int index )

Set a texture of 16 colors on one polygon, its colors taken in a bank of 16 colors of a palette (in place of its color lookup table): a polygon of the palette lighting (see jo_3d_set_palette_light()), or opaque over the half transparent water (the MSB of the colors of the palette cleared), or the same texture in other colors.

Parameters
meshAddress to a jo_3d_mesh allocated struct
sprite_idSprite ID (16 colors: jo_sprite_add_4bits_lut(), jo_sprite_add_image_4bits_lut())
palettePalette (jo_create_palette())
bankBank of 16 colors in the palette: 0 to 15 (the pixel of index i: the color bank * 16 + i of the palette)
indexpolygon index on the mesh

◆ jo_3d_set_mesh_polygon_texture_palette()

void jo_3d_set_mesh_polygon_texture_palette ( jo_3d_mesh *const mesh,
const int sprite_id,
const jo_palette *const palette,
const unsigned int index )

Set a texture of 256 colors on one polygon, its colors taken in a palette (its pixel value n: the color n of the palette): opaque over a see-through bottom where the MSB of the colors is cleared, see jo_vdp2_blend_rgb_sprites_only().

Parameters
meshAddress to a jo_3d_mesh allocated struct
sprite_idSprite ID (256 colors: jo_sprite_add_8bits_image(), jo_level_add_textures8())
palettePalette (jo_create_palette(), see jo_level_set_textures8_palette())
indexpolygon index on the mesh

◆ jo_3d_set_mesh_polygon_transparency()

void jo_3d_set_mesh_polygon_transparency ( jo_3d_mesh *const mesh,
const bool enabled,
const unsigned int index )

Enable/Disable transparency on one polygon on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
enabledtrue to enable transparency
indexpolygon index on the mesh

◆ jo_3d_set_mesh_polygon_wireframe()

void jo_3d_set_mesh_polygon_wireframe ( jo_3d_mesh *const mesh,
const unsigned int index,
bool wireframe )

Set wireframe mode on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
indexpolygon index on the mesh
wireframeTrue to enable wireframe mode

◆ jo_3d_set_mesh_screen_doors()

void jo_3d_set_mesh_screen_doors ( jo_3d_mesh *const mesh,
const bool enabled )

Enable/Disable screen doors transparency on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
enabledtrue to enable screen doors transparency

◆ jo_3d_set_mesh_texture()

void jo_3d_set_mesh_texture ( jo_3d_mesh *const mesh,
const int sprite_id )

Set a texture on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
sprite_idSprite ID

◆ jo_3d_set_mesh_transparency()

void jo_3d_set_mesh_transparency ( jo_3d_mesh *const mesh,
const bool enabled )

Enable/Disable transparency on the mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
enabledtrue to enable transparency

◆ jo_3d_set_mesh_vertice()

__jo_force_inline void jo_3d_set_mesh_vertice ( jo_3d_mesh *const mesh,
const jo_fixed x,
const jo_fixed y,
const jo_fixed z,
const unsigned int index )
static

Set vertice position in mesh.

Parameters
meshAddress to a jo_3d_mesh allocated struct
xX position
yY position
zZ position
indexvertice index on the mesh (4 vertices for each quad)

◆ jo_3d_set_mirror()

void jo_3d_set_mirror ( const bool mirror)

The next polygons of the master CPU are seen in a mirror: their front faces are counterclockwise on the screen.

Parameters
mirrortrue in a reflected view (see jo_3d_reflect_matrix()), false after it

◆ jo_3d_set_packed_tint()

void jo_3d_set_packed_tint ( const unsigned short tint)

Tint the next meshes drawn by the master CPU (see jo_3d_set_tint()).

Parameters
tintPacked tint (see jo_3d_get_tint()), 0: none

◆ jo_3d_set_palette()

__jo_force_inline void jo_3d_set_palette ( jo_3d_quad *const quad,
const int palette_id )
static

Set a palette on the quadrilateral.

Parameters
quadAddress to a jo_3d_quad allocated struct
palette_idPalette id from jo_create_palette()

◆ jo_3d_set_palette_light()

void jo_3d_set_palette_light ( const int levels,
const int stride )

Palette lighting (the light of jo_3d_light() without the RGB colors: the only lighting of the 640 and 704 pixels modes): a lit polygon of a palette color (or a texture of 16 colors with a color bank) takes the shade of its light, its color code + shade * stride (shade 0 = the darkest).

Parameters
levelsShades of each color (2 to 32; 0 = off, the default)
strideColor codes between 2 shades of a color (the count of jo_palette_set_light_shades(): the same for all the lit palette polygons)
Remarks
In the 640 and 704 pixels modes, the polygons of the RGB textures are not lit (their gouraud shading needs an RGB frame buffer)

◆ jo_3d_set_perspective()

__jo_force_inline void jo_3d_set_perspective ( const jo_angle angle)
static

Set the perspective angle using jo_angle (a fraction of degree, as slPerspective() of the SGL).

Parameters
angleAngle (0x10000 = 360 degrees) from JO_DEG_TO_ANGLE(10) to JO_DEG_TO_ANGLE(160)
Remarks
Same as jo_3d_perspective_angle() for a whole degree

◆ jo_3d_set_quad_vertices()

__jo_force_inline void jo_3d_set_quad_vertices ( jo_vertice *const vertices,
const jo_vertice *const center,
const jo_vertice *const right,
const jo_vertice *const down )
static

Fill the 4 vertices of a quad (a parallelogram) from its center and 2 half edges, in the order of JO_3D_PLANE_VERTICES(): center - right - down, center + right - down, center + right + down, center - right + down.

Parameters
verticesThe 4 vertices to fill (for instance a part of the table given to jo_3d_create_mesh_from_vertices())
centerCenter of the quad
rightHalf of the edge from the first vertex to the second one (the top edge of the texture, left to right)
downHalf of the edge from the first vertex to the fourth one (the left edge of the texture, top to bottom)
Remarks
The front face is the side opposite to the cross product right x down: seen from there, the vertices turn clockwise (Y down). For instance right = (S, 0, 0) and down = (0, S, 0) give JO_3D_PLANE_VERTICES(S), facing -Z; right = (S, 0, 0) and down = (0, 0, -S) give a floor tile facing up (-Y) with the top of its texture toward +Z

◆ jo_3d_set_scale()

__jo_force_inline void jo_3d_set_scale ( const int x,
const int y,
const int z )
static

Change scale.

Parameters
xX Scale
yY Scale
zZ Scale

◆ jo_3d_set_scale_fixed()

__jo_force_inline void jo_3d_set_scale_fixed ( const jo_fixed x,
const jo_fixed y,
const jo_fixed z )
static

Change scale using fixed number.

Parameters
xX Scale
yY Scale
zZ Scale

◆ jo_3d_set_scalef()

__jo_force_inline void jo_3d_set_scalef ( const float x,
const float y,
const float z )
static

Change scale using floating number.

Parameters
xX Scale
yY Scale
zZ Scale

◆ jo_3d_set_screen_doors()

__jo_force_inline void jo_3d_set_screen_doors ( jo_3d_quad *const quad,
const bool enabled )
static

Enable/Disable screen doors transparency on the quad.

Parameters
quadAddress to a jo_3d_quad allocated struct
enabledtrue to enable screen doors transparency

◆ jo_3d_set_sprite_fade()

bool jo_3d_set_sprite_fade ( const int sprite_id,
const jo_palette *const palette,
const int bank )

A standing sprite that fades with the distance (see jo_3d_set_fade_distances()): its 16 colors copied in a bank of a palette, used beyond the start of the fade.

Parameters
sprite_idA 16 colors texture with its color lookup table (jo_sprite_add_image_4bits_lut()); its smaller copies too
palettePalette of the bank (jo_create_palette()); JO_NULL: the sprite no longer fades
bankBank of 16 colors in the palette: 1 to 15 (its colors bank * 16 + 1 to bank * 16 + 15 of the palette)
Returns
false if the sprite is not a 16 colors texture with its table, or if 16 sprites already fade
Remarks
Freed sprites are forgotten (jo_sprite_free_from()). A palette pixel is not shaded (gouraud) by the VDP1
The color calculation mode is the same for all the screens: not with the additive sprites (jo_enable_additive_sprites()) or the glows (jo/glow.h) at the same time, stop the fade then (jo_3d_set_fade_distances(0, 0))
Not in the 640 and 704 pixels modes

◆ jo_3d_set_sprite_palette()

__jo_force_inline bool jo_3d_set_sprite_palette ( const int sprite_id,
const int palette_id )
static

Set a palette on a sprite (3D).

Parameters
sprite_idSprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()
palette_idPalette id from jo_create_palette()
Returns
true if succeeded otherwise false

◆ jo_3d_set_texture()

__jo_force_inline void jo_3d_set_texture ( jo_3d_quad *const quad,
const int sprite_id )
static

Set a texture on the quadrilateral.

Parameters
quadAddress to a jo_3d_quad allocated struct
sprite_idSprite ID

◆ jo_3d_set_texture_mipmap_copies()

bool jo_3d_set_texture_mipmap_copies ( const int sprite_id,
const int half_id,
const int levels )

Give a texture its smaller copies made beforehand (see jo_3d_set_texture_mipmaps()): for the textures it can't reduce itself (256 colors: their palette is chosen per polygon), or reduced better by a tool (the averages in the colors of the palette, a mean color searched among 255 at the loading took seconds).

Parameters
sprite_idTexture
half_idThe copy of half size (width and height), added after the texture; the copy of quarter size: the sprite after it
levels1: the half size only, 2: the half and quarter sizes
Returns
false if the copies are not of the color mode of the texture, not of its half and quarter sizes, or if it has copies already
Remarks
Drawn with the bank of the polygon (a 256 colors copy: its palette). A thin polygon far away is not drawn of the mean color of these textures (see jo_3d_set_texture_mipmaps(): no mean color is known)

◆ jo_3d_set_texture_mipmaps()

bool jo_3d_set_texture_mipmaps ( const int sprite_id)

Create smaller copies of a texture (half and quarter size, "mipmaps") used when the texture is drawn small.

Parameters
sprite_idTexture (RGB sprite, width multiple of 16: half size, of 32: quarter size too)
Returns
true if the copies were created
Remarks
The VDP1 reads all the texels of a texture, even when it is drawn small: a polygon far away costs as much as its texture. The smallest copy that has at least as many texels as pixels on the screen is used: the polygons and the standing sprites (jo_3d_draw_standing_sprite()) far away cost less VDP1 time, and their texture flickers less
The copies are new sprites (a third of the VRAM of the texture). Call it once, after the texture was added
A polygon with the texture seen as a thin line of the screen (the ground at a grazing angle, 64 pixels long at least and 4 pixels wide at most) is drawn as a polygon of the mean color of the texture, as thin as it: the VDP1 drew its lines along the whole polygon (about the square of its length in pixels, 10 to 20 % of a frame on a hilly ground)

◆ jo_3d_set_texture_subdivision()

bool jo_3d_set_texture_subdivision ( const int sprite_id)

Draw the polygons that use a texture in parts when they are near the camera (2 x 2 or 4 x 4 parts, each part with its tile of the texture).

Parameters
sprite_idTexture (RGB, 256 colors or 16 colors sprite, width multiple of 16: 2 x 2 tiles, of 32: 4 x 4 tiles too; a 256 colors tile is drawn with the bank of the polygon: its palette)
Returns
true if the tiles were created
Remarks
The VDP1 maps a texture without perspective: a big polygon near the camera (a wall, the ground) is distorted, and the parts of a polygon clipped by the near plane get the whole texture. In parts, each part keeps its piece of the texture, the distortion stays small and the parts are sorted with their own depth (fewer sorting errors near the camera). A polygon is drawn in parts when its farthest vertex is 1.5 times (2 x 2) or 3 times (4 x 4) farther than its nearest vertex, or when it crosses the near plane
The tiles are new sprites (copies of the texture: about twice the VRAM of the texture). Call it once, after the texture was added (jo_sprite_add(), jo_sprite_add_bin(), etc)
A texture magnified near the camera (a few texels on a big quad): see jo_3d_set_texture_subdivision_fine()

◆ jo_3d_set_texture_subdivision_depth()

void jo_3d_set_texture_subdivision_depth ( const int sprite_id,
const jo_fixed depth )

Draw in parts (see jo_3d_set_texture_subdivision()) only the polygons of a texture whose nearest vertex is nearer than a depth: the ground next to the camera, where its texture slides the most (farther, the parts cost CPU time for little).

Parameters
sprite_idTexture (see jo_3d_set_texture_subdivision())
depthDepth in the view space (fixed), 0: all the polygons (default)

◆ jo_3d_set_texture_subdivision_error()

void jo_3d_set_texture_subdivision_error ( const int sprite_id,
const int pixels )

Distortion of a texture over which its polygons are drawn in parts (see jo_3d_set_texture_subdivision()): a pattern with straight lines (a tiled floor) shows the distortion more, the lines bend where a part meets a whole polygon.

Parameters
sprite_idTexture (see jo_3d_set_texture_subdivision())
pixelsDistortion (pixels on the screen, 1 to 255), 0: the default (8). 4: the lines of a tiled floor stay straight; about 1 ms more for each CPU in a room of a level (more polygons drawn in parts)

◆ jo_3d_set_texture_subdivision_fine()

bool jo_3d_set_texture_subdivision_fine ( const int sprite_id)

Add finer tiles to the tiles of a texture (see jo_3d_set_texture_subdivision()): 8 x 8 and 16 x 16 tiles, for the parts of its polygons cut in 4 x 4 parts that cross the near plane, go very far outside of the screen, are big and partly out of the screen, or still distorted by the perspective. The last tile of a part through the near plane, or with its lines pulled in to the screen (VDP1 time), is drawn whole on what is seen of it (the VDP1 can't start a texture at any column): its texture is squeezed by up to a tile, 8 texels of a 32 x 32 texture with the 4 x 4 tiles, 2 with the 16 x 16 tiles. For a texture magnified near the camera (texels of more than about 10 pixels: a texture of a few texels on a big wall, a big floor).

Parameters
sprite_idTexture (RGB, 256 colors or 16 colors sprite, width and height multiples of 16)
Returns
true if the tiles were created (with the 2 x 2 and 4 x 4 tiles if they were not)
Remarks
One more sprite, the tiles one under the other, 1/8 of the width of the texture and at least 8 pixels wide (16 for 16 colors: a narrower tile has its texels repeated): 3 times the VRAM of the texture (64 pixels wide and more, RGB and 256 colors; 128, 16 colors), 6 times for a 32 x 32 RGB texture. More parts near the camera (CPU time, VDP1 commands)

◆ jo_3d_set_texture_subdivision_near_only()

bool jo_3d_set_texture_subdivision_near_only ( const int sprite_id)

Like jo_3d_set_texture_subdivision(), but only the polygons that cross the near plane (or go very far outside of the screen) are drawn in parts: a model already cut in small quads when it was made keeps its quads as they are, the parts of a quad next to a whole quad overlapped it.

Parameters
sprite_idTexture (see jo_3d_set_texture_subdivision())
Returns
true if the tiles were created

◆ jo_3d_set_tint()

void jo_3d_set_tint ( const int r,
const int g,
const int b )

Tint the next meshes drawn by the master CPU: added to the colors of their gouraud tables (the light of a lamp on a character, see jo_3d_point_lights_sample()), jo_3d_set_tint(0, 0, 0) to stop.

Parameters
rRed added (gouraud units, -31 to 31, steps of 2)
gGreen added
bBlue added
Remarks
Only the polygons with a gouraud table. Each mesh keeps a few tinted copies of its tables in the VDP1 VRAM (a copy is written when a new tint is needed; a copy used in the frame is kept for it: the slave CPU draws with the copies, see jo_3d_slave_set_tint(). All the copies used in the frame: the nearest one, within 3 units, else no tint)

◆ jo_3d_set_transparency()

__jo_force_inline void jo_3d_set_transparency ( jo_3d_quad *const quad,
const bool enabled )
static

Enable/Disable transparency on the quadrilateral.

Parameters
quadAddress to a jo_3d_quad allocated struct
enabledtrue to enable transparency

◆ jo_3d_set_view_rect()

void jo_3d_set_view_rect ( const jo_3d_rect *const rect)

The objects are seen only in a rectangle of the screen: jo_3d_is_sphere_visible() is false for the spheres outside of it (the camera is in a building: the outside is seen only through its door, see jo_cells_outside_view()).

Parameters
rectRectangle (left > right: nothing is seen, but the spheres around the camera), JO_NULL: the whole screen
Remarks
Used by both CPUs: set it before jo_core_exec_on_slave()

◆ jo_3d_set_windows_apart()

__jo_force_inline void jo_3d_set_windows_apart ( const bool apart)
static

The windows do not overlap (a split screen: a view per player in its window): the commands of each window are drawn together, window after window (window 0 first), sorted by depth in their window; else (default) the commands of all the windows are sorted together by depth (a mirror in the view: its window over the other one).

Parameters
aparttrue: the windows drawn one after the other
Remarks
From the next frame (applied when the commands of a frame are sorted). Mixed by depth, the commands of 2 windows side by side change the window hundreds of times per frame: each change costs a header of 3 commands in the VRAM

◆ jo_3d_set_wireframe()

__jo_force_inline void jo_3d_set_wireframe ( const bool enabled)
static

Wireframe mode: the polygons and the standing sprites (distorted sprites) are drawn as their outline, in one color; the normal and scaled sprites (a HUD for instance) are drawn as they are.

Parameters
enabledtrue: wireframe, false: normal drawing
Remarks
From the next frame (applied when the commands of a frame are copied into the VRAM)

◆ jo_3d_slave_begin()

void jo_3d_slave_begin ( void )

Prepare the 3D drawing of the slave CPU (call it on the master CPU, before jo_core_exec_on_slave()).

Remarks
The slave CPU uses a copy of the current matrix, the current depth bias and the current window
A second drawing of the slave CPU in a frame (a split screen): after jo_core_wait_for_slave() of the first one (this function replaces the matrix and the counters that the slave CPU uses while it draws)

◆ jo_3d_slave_draw_standing_sprite()

bool jo_3d_slave_draw_standing_sprite ( const int sprite_id,
const jo_pos3D_fixed *const foot,
const jo_fixed width,
const jo_fixed height,
const jo_fixed sway,
const bool flip )

Draw a sprite standing on the ground and facing the camera on the slave CPU (see jo_3d_draw_standing_sprite()).

Parameters
sprite_idSprite Id
footPosition of the bottom center of the sprite (world space, Q16.16)
widthWidth (world units, Q16.16)
heightHeight (world units, Q16.16)
swayHorizontal offset of the top of the sprite (world units, Q16.16): wind
flipHorizontal flip
Returns
true if it is drawn (false: behind the camera, outside of the screen, too near, or the commands of the slave CPU are used up)
Remarks
The sprite attributes are the ones of the master CPU at jo_3d_slave_begin(), the depth bias the one of the slave CPU (jo_3d_slave_set_depth_bias())

◆ jo_3d_slave_end()

void jo_3d_slave_end ( void )

Add the polygons drawn by the slave CPU to the frame (call it on the master CPU, after jo_core_wait_for_slave()).

Remarks
The commands kept for what is drawn after it are not used (see jo_3d_slave_set_kept_commands()): the last polygons of the slave CPU are dropped when there is no room left

◆ jo_3d_slave_get_command_count()

int jo_3d_slave_get_command_count ( void )

VDP1 commands used by the slave CPU in the last frame (see jo_3d_slave_end()).

Returns
Command count (polygons and their parts)
Remarks
With jo_3d_slave_get_max_commands(): the room left for more objects on the slave CPU

◆ jo_3d_slave_get_current_command_count()

int jo_3d_slave_get_current_command_count ( void )

Commands drawn by the slave CPU since jo_3d_slave_begin() (0 after jo_3d_slave_end()).

Returns
Command count
Remarks
Called by the master CPU while the slave CPU draws: the count at this moment

◆ jo_3d_slave_get_max_commands()

int jo_3d_slave_get_max_commands ( void )

Commands the slave CPU can draw in a frame (the others are dropped, jo_3d_slave_mesh_draw() returns false).

Returns
Command count

◆ jo_3d_slave_get_max_vertices()

int jo_3d_slave_get_max_vertices ( void )

Points of the biggest object the slave CPU can draw (a bigger object is not drawn).

Returns
Point count

◆ jo_3d_slave_is_sphere_visible()

bool jo_3d_slave_is_sphere_visible ( const jo_pos3D_fixed *const center,
const jo_fixed radius,
const jo_fixed max_distance )

jo_3d_is_sphere_visible() for the slave CPU: with the rectangle of jo_3d_set_view_rect() as it was at jo_3d_slave_begin() (the master CPU can change it while the slave CPU draws)

Parameters
centerCenter of the sphere in the view space (see jo_3d_slave_transform_point())
radiusRadius (Q16.16)
max_distanceFarthest distance (Q16.16)
Returns
true if a part of the sphere may be in the view (the test is conservative)

◆ jo_3d_slave_mesh_draw()

__jo_force_inline bool jo_3d_slave_mesh_draw ( const jo_3d_mesh *const mesh)
static

Draw a mesh on the slave CPU (call it on the slave CPU, between jo_3d_slave_begin() and jo_3d_slave_end()).

Parameters
meshMesh (1024 points at most, JO_3D_SLAVE_MAX_VERTICES)
Returns
false if the command table of the slave CPU is full (960 commands)

◆ jo_3d_slave_mesh_draw_ranges()

bool jo_3d_slave_mesh_draw_ranges ( const jo_3d_mesh *const mesh,
const unsigned int point_count,
const jo_3d_polygon_range *const ranges,
const int range_count )

Draw some ranges of polygons of a mesh on the slave CPU, without copying them (see jo_3d_mesh_draw_ranges()).

Parameters
meshMesh
point_countNumber of points used by these polygons (1024 at most)
rangesRanges of polygons
range_countNumber of ranges
Returns
false if the command table of the slave CPU is full (960 commands) or a polygon uses a point after point_count

◆ jo_3d_slave_pop_matrix()

void jo_3d_slave_pop_matrix ( void )

Pop the matrix of the slave CPU (call it on the slave CPU, see jo_3d_pop_matrix()).

◆ jo_3d_slave_push_matrix()

bool jo_3d_slave_push_matrix ( void )

Push the matrix of the slave CPU (call it on the slave CPU, see jo_3d_push_matrix()).

Returns
false if the stack of the slave CPU is full (4 matrices)

◆ jo_3d_slave_rotate()

void jo_3d_slave_rotate ( const int axis,
const jo_angle angle )

Rotate the matrix of the slave CPU around an axis by a precise angle (call it on the slave CPU): a slow turn (a big wheel, a fan) moves by less than a degree per frame.

Parameters
axisJO_3D_AXIS_X, JO_3D_AXIS_Y or JO_3D_AXIS_Z
angleAngle (jo_angle: 65536 = 360 degrees)

◆ jo_3d_slave_rotate_matrix()

void jo_3d_slave_rotate_matrix ( const int x,
const int y,
const int z )

Rotate the matrix of the slave CPU (call it on the slave CPU, see jo_3d_rotate_matrix()).

Parameters
xX angle (degrees)
yY angle (degrees)
zZ angle (degrees)

◆ jo_3d_slave_select_window()

void jo_3d_slave_select_window ( const int window)

Select the window of the next drawings of the slave CPU (call it on the slave CPU; jo_3d_slave_begin() selects the window of the master CPU, see jo_3d_select_window()).

Parameters
windowJO_3D_NEAR_WINDOW, JO_3D_FAR_WINDOW, JO_3D_FAR_WINDOW_2 or JO_3D_LAYER_WINDOW

◆ jo_3d_slave_set_depth_bias()

void jo_3d_slave_set_depth_bias ( const int bias)

Change the depth bias of the objects drawn by the slave CPU (call it on the slave CPU).

Parameters
biasDepth (see jo_3d_set_depth_bias())

◆ jo_3d_slave_set_fade_distances()

void jo_3d_slave_set_fade_distances ( const jo_fixed start,
const jo_fixed end )

The distances of the fade of the standing sprites of the slave CPU (see jo_3d_set_fade_distances()), until the next jo_3d_slave_begin() (call it on the slave CPU).

Parameters
startDepth of the start (world units, Q16.16)
endDepth of the end (world units, Q16.16); end <= start: no fade

◆ jo_3d_slave_set_guard_band()

void jo_3d_slave_set_guard_band ( const int pixels)

Change the guard band of the objects drawn by the slave CPU (call it on the slave CPU, see jo_3d_set_guard_band()).

Parameters
pixelsDistance outside of the screen (0 to JO_3D_MAX_GUARD_BAND)
Remarks
jo_3d_slave_begin() copies the guard band of the master CPU: the change lasts until the next frame

◆ jo_3d_slave_set_kept_commands()

void jo_3d_slave_set_kept_commands ( const int count)

VDP1 commands kept for what is drawn after jo_3d_slave_end() (the weapon, the HUD): the polygons of the slave CPU don't take them. Without it, a frame full of polygons left no room for the HUD (and JO_DEBUG stopped the game: "Too many VDP1 commands in a frame").

Parameters
countCommands (0 by default)

◆ jo_3d_slave_set_scale_fixed()

void jo_3d_slave_set_scale_fixed ( const jo_fixed x,
const jo_fixed y,
const jo_fixed z )

Scale the matrix of the slave CPU (call it on the slave CPU, see jo_3d_set_scale_fixed()).

Parameters
xX scale (Q16.16)
yY scale (Q16.16)
zZ scale (Q16.16)

◆ jo_3d_slave_set_tint()

void jo_3d_slave_set_tint ( const unsigned short tint)

Tint the next meshes drawn by the slave CPU (call it on the slave CPU).

Parameters
tintPacked tint (see jo_3d_get_tint()), 0: none
Remarks
The slave CPU writes no copy of the tables: it uses the nearest copy made by the master CPU (within 3 units), else no tint. The master CPU makes the copy of a tint before the job of the slave CPU with jo_3d_prepare_tint()

◆ jo_3d_slave_transform_point()

void jo_3d_slave_transform_point ( const jo_pos3D_fixed *const in,
jo_pos3D_fixed * out )

Transform a point by the matrix of the slave CPU (call it on the slave CPU, see jo_3d_transform_point()).

Parameters
inPoint
outTransformed point (output)

◆ jo_3d_slave_translate_matrix_fixed()

void jo_3d_slave_translate_matrix_fixed ( const jo_fixed x,
const jo_fixed y,
const jo_fixed z )

Translate the matrix of the slave CPU (call it on the slave CPU, see jo_3d_translate_matrix_fixed()).

Parameters
xX (Q16.16)
yY (Q16.16)
zZ (Q16.16)

◆ jo_3d_transform_point()

void jo_3d_transform_point ( const jo_pos3D_fixed *const in,
jo_pos3D_fixed * out )

Transform a point by the current matrix (for instance a world position into the view space, after jo_3d_camera_look_at() or the rotations and translations of the camera).

Parameters
inPoint
outTransformed point (output)

◆ jo_3d_transform_point_by()

void jo_3d_transform_point_by ( const jo_fixed(*) m[3],
const jo_pos3D_fixed *const in,
jo_pos3D_fixed *const out )

Transform a point by a matrix (see jo_3d_transform_point(): the same result with the current matrix).

Parameters
mMatrix: 4 rows of 3 (the 3 axes, then the translation), for instance the matrix of a bone (see jo_3d_bone_callback)
inPoint
outTransformed point (output)

◆ jo_3d_translate_matrix()

__jo_force_inline void jo_3d_translate_matrix ( int x,
int y,
int z )
static

Translate 3D matrix.

Parameters
xX Position
yY Position
zZ Position

◆ jo_3d_translate_matrix_fixed()

__jo_force_inline void jo_3d_translate_matrix_fixed ( jo_fixed x,
jo_fixed y,
jo_fixed z )
static

Translate 3D matrix.

Parameters
xX Position
yY Position
zZ Position

◆ jo_3d_translate_matrix_x()

__jo_force_inline void jo_3d_translate_matrix_x ( int x)
static

Translate 3D matrix (X axis).

Parameters
xX Position

◆ jo_3d_translate_matrix_y()

__jo_force_inline void jo_3d_translate_matrix_y ( int y)
static

Translate 3D matrix (Y axis).

Parameters
yY Position

◆ jo_3d_translate_matrix_z()

__jo_force_inline void jo_3d_translate_matrix_z ( int z)
static

Translate 3D matrix (Z axis).

Parameters
zZ Position

◆ jo_3d_translate_matrixf()

__jo_force_inline void jo_3d_translate_matrixf ( float x,
float y,
float z )
static

Translate 3D matrix (using floating numbers).

Parameters
xX Position
yY Position
zZ Position

◆ jo_3d_window()

__jo_force_inline bool jo_3d_window ( const int left,
const int top,
const int right,
const int bottom,
const int z_limit,
const int center_x,
const int center_y )
static

Sets up a window region on the projection surface.

Parameters
left
top
right
bottom
z_limit
center_x
center_y
Returns
false if Failed

◆ jo_3d_window_clip()

__jo_force_inline void jo_3d_window_clip ( const bool clip)
static

The 3D polygons drawn in the current window are clipped by the VDP1 to its rectangle (user clipping: a mirror, a rear-view mirror, a view of a split screen), or not (default: the whole screen).

Parameters
cliptrue: clipped to the rectangle of jo_3d_window()
Remarks
With windows apart (jo_3d_set_windows_apart(), set before), a clipped window is a screen of its own: the polygons are culled, cut and drawn in parts against its rectangle, not against the whole screen (its commands are relative to its top left corner: the local coordinates of the VDP1, written at the end of the frame: the window must not change during the frame). Else the polygons are only clipped by the VDP1 to the rectangle of the window at the end of the frame (a mirror)

Variable Documentation

◆ __jo_3d_displayed_polygon_count

unsigned short __jo_3d_displayed_polygon_count
extern

Displayed polygon count of the current frame (Internal usage).

◆ __jo_3d_guard_band

int __jo_3d_guard_band
extern

Guard band (internal engine usage, see jo_3d_set_guard_band()).

◆ __jo_3d_polygon_count

unsigned short __jo_3d_polygon_count
extern

Polygon count of the current frame (Internal usage).

◆ __jo_3d_vertice_count

unsigned short __jo_3d_vertice_count
extern

Vertice count of the current frame (Internal usage).

◆ __jo_sprite_quad

jo_3d_quad** __jo_sprite_quad
extern

Sprite quads (internal engine usage): a quad per sprite, the table allocated with the first quad (JO_NULL: none).

Warning
MC Hammer: don't touch this