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_3d_quad
	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_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_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.

Typedefs
typedef jo_pos3D	jo_vertice
	Vertice structure.

Functions
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_parts (const jo_3d_polygon_data *const pdata, const jo_3d_part *const parts, const int part_count)
	Draw polygons whose points are in parts, each one transformed by its own matrix: the bones of a skeleton (one draw for the whole model, see jo_3d_model_draw_pose()) (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)
	Draw polygons using the current matrix (Internal usage).
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_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.
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.
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_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_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 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)
	Restore default scale for every 3d model displayed after this call.
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), 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_perspective_angle (const int angle)
	Set the perspective angle.
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_bone_matrix (jo_fixed(*const out)[3], const jo_fixed(*const parent)[3], const jo_pos3D_fixed *const pivot, const jo_angle *const angles)
	The matrix of a bone (Internal usage, see jo_3d_model_draw_pose()): the matrix of its parent turned around its joint (the same operations as jo_3d_translate_matrix_fixed() and __jo_3d_rotate() on the current matrix).
jo_fixed(*	__jo_3d_current_matrix (void))[3]
	The current matrix (Internal usage): 4 rows of 3.
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...).
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_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.
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.
void	__jo_3d_forget_sprites_from (const int sprite_id)
	Forget the tiles and the smaller copies of the textures freed from a sprite (Internal usage, see jo_3d_model_free_textures_from()).
void	__jo_3d_forget_tint (const jo_3d_polygon_data *const pdata)
	Forget the tinted copies of the gouraud tables of a mesh: its polygons got other tables (Internal usage, see jo_3d_point_lights_add_mesh()).
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()).
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()).
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_gouraud_pool_freed (const int sprite_id)
	Sprites freed from a sprite (see jo_sprite_free_from()): the shared sprite of the gouraud tables is dropped if it is among them.
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.
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 [JO_MAX_SPRITE]
	Sprite quads (internal engine usage).
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_3d_quad

struct jo_3d_quad

Quadrilateral shape structure.

Data Fields
jo_3d_polygon_attribute	attribute
jo_3d_polygon_data	data

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

PLANE	JO_3D_SINGLE_PLANE or JO_3D_DUAL_PLANE
SORT	JO_3D_SORT_xxx
TEXTURE	Sprite id (JO_3D_NO_TEXTURE)
COLOR	RGB color or palette
GOURAUD	Gouraud table address / 8 (JO_VDP1_NO_GOURAUD)
DRAW_MODE	JO_VDP1_COLOR_MODE_xxx | JO_VDP1_COLOR_CALC_xxx | ...
DIRECTION	JO_VDP1_SPRITE_NO_FLIP, JO_VDP1_POLYGON, etc
OPTIONS	JO_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_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_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

X	Normal X (float)
Y	Normal Y (float)
Z	Normal Z (float)

JO_3D_PLANE_VERTICES

#define JO_3D_PLANE_VERTICES

(

SIZE

)

Plane vertice table.

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

A	First vertex index
B	Second vertex index
C	Third vertex index
D	Fourth vertex index (same as C for a triangle)

Typedef Documentation

jo_vertice

typedef jo_pos3D jo_vertice

Vertice structure.

Function Documentation

__jo_3d_bone_matrix()

void __jo_3d_bone_matrix	(	jo_fixed(*)	out[3],
		const jo_fixed(*)	parent[3],
		const jo_pos3D_fixed *const	pivot,
		const jo_angle *const	angles )

The matrix of a bone (Internal usage, see jo_3d_model_draw_pose()): the matrix of its parent turned around its joint (the same operations as jo_3d_translate_matrix_fixed() and __jo_3d_rotate() on the current matrix).

Parameters

out	Matrix of the bone (output)
parent	Matrix of its parent
pivot	Joint
angles	Around X, Y and Z

__jo_3d_current_matrix()

jo_fixed(* __jo_3d_current_matrix

(

void

)

)[3]

The current matrix (Internal usage): 4 rows of 3.

__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

pdata

Polygon data (vertices, polygons and attributes)

Returns

false if the VDP1 command table is full

__jo_3d_draw_parts()

bool __jo_3d_draw_parts	(	const jo_3d_polygon_data *const	pdata,
		const jo_3d_part *const	parts,
		const int	part_count )

Draw polygons whose points are in parts, each one transformed by its own matrix: the bones of a skeleton (one draw for the whole model, see jo_3d_model_draw_pose()) (Internal usage).

Parameters

pdata	Polygon data (vertices, polygons and attributes)
parts	Parts (the points not in a part are not transformed: the polygons must not use them)
part_count	Number of parts

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 )

Draw polygons using the current matrix (Internal usage).

Parameters

pdata	Polygon data (vertices, polygons and attributes)
point_count	Number of points transformed (the first ones of pdata)
ranges	Ranges of polygons drawn (JO_NULL: all the polygons)
range_count	Number 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

__jo_3d_forget_sprites_from()

void __jo_3d_forget_sprites_from

(

const int

sprite_id

)

Forget the tiles and the smaller copies of the textures freed from a sprite (Internal usage, see jo_3d_model_free_textures_from()).

Parameters

sprite_id

First sprite freed

__jo_3d_forget_tint()

void __jo_3d_forget_tint

(

const jo_3d_polygon_data *const

pdata

)

Forget the tinted copies of the gouraud tables of a mesh: its polygons got other tables (Internal usage, see jo_3d_point_lights_add_mesh()).

Parameters

pdata

Polygons of the mesh

__jo_3d_gouraud_pool_freed()

void __jo_3d_gouraud_pool_freed

(

const int

sprite_id

)

Sprites freed from a sprite (see jo_sprite_free_from()): the shared sprite of the gouraud tables is dropped if it is among them.

Parameters

sprite_id

First sprite freed

__jo_3d_light()

void __jo_3d_light

(

const jo_pos3D_fixed *const

light

)

Set light direction (Internal usage).

Parameters

light

Light 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

camera	Camera position (x, y, z)
target	Point looked at by the camera (x, y, z)
angle	Rotation 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

axis	JO_3D_AXIS_X, JO_3D_AXIS_Y or JO_3D_AXIS_Z
angle	Rotation 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

x	Horizontal scale (JO_FIXED_1 = no scale)
y	Vertical scale (JO_FIXED_1 = no scale)
z	Depth 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

angle

Horizontal field of view (0x4000 = 90 degrees)

Remarks

Changes the projection distance used by 3D polygons, 3D sprites and the rotation scroll screen

__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

x	Horizontal translation
y	Vertical translation
z	Depth 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

tables	Colors (4 per table), or JO_NULL to only reserve the memory (black)
count	Table 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_camera_init()

__jo_force_inline void jo_3d_camera_init ( jo_camera *const cam )

static

Initialize the camera with default values.

Parameters

cam	Pointer 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

cam	Pointer 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

cam	Pointer to a camera struct
x	X coord
y	Y coord
z	Z 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

cam	Pointer to a camera struct
x	X coord
y	Y coord
z	Z 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

cam	Pointer to a camera struct
angle	Z-angle in degree

jo_3d_create_cube()

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

Create a cube.

Parameters

array	Address to a 6 jo_3d_quad allocated struct
vertices	Vertices 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_count	Point count
polygon_count	Polygon 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_count

Quad 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_count	Quad count (Quad count == Polygon count)
vertices	An 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_count	Quad count (Quad count == Polygon count)
vertices	An array of jo_vertice (4 * quad_count)
normals	An 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

quad	Address to a jo_3d_quad allocated struct
vertices	Vertices 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

radius	Radius
slices	Number of vertical slices (around the Y axis, 3 minimum)
stacks	Number 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

quad	Address to a jo_3d_quad allocated struct
vertices	Vertices 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

level

Distance 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

quad	Address 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

array	Array of quadrilateral
array_size	Size 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_id	Sprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()
x	X coordinate
y	Y coordinate
z	Z coordinate

jo_3d_draw_list()

__jo_force_inline void jo_3d_draw_list ( jo_list *const list )

static

Draw a list of quadrilateral.

Parameters

list	List 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_id	Sprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()
x	X coordinate
y	Y coordinate
z	Z coordinate
scale	Scale

jo_3d_draw_sprite()

__jo_force_inline bool jo_3d_draw_sprite ( const int sprite_id )

static

Draw a sprite.

Parameters

sprite_id

Sprite 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_id	Sprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()
x	X coordinate
y	Y coordinate
z	Z 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_id	Sprite Id returned by jo_sprite_add(), jo_sprite_add_tga(), jo_sprite_add_bin(), etc
foot	Position of the bottom center of the sprite (world space, Q16.16)
width	Width (world units, Q16.16)
height	Height (world units, Q16.16)
sway	Horizontal offset of the top of the sprite (world units, Q16.16): wind
flip	Horizontal 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_cpu

false: 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_mesh()

void jo_3d_free_mesh

(

const jo_3d_mesh *const

mesh

)

Free a mesh created with jo_3d_create_mesh().

Parameters

mesh	The 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_id

Sprite 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

m	Output: 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

mesh	Address 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_id

Sprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()

Returns

Sprite quad

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

rect	The 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

center	Center of the sphere in the view space (see jo_3d_transform_point())
radius	Radius (Q16.16)
max_distance	Farthest 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

x	X position of the light source
y	Y position of the light source
z	Z position of the light source

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

mesh	Mesh (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

mesh	Address 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

mesh	Mesh
point_count	Number 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)
ranges	Ranges of polygons
range_count	Number 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

mesh	Mesh
center	Center 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

mesh	Mesh
origin	Origin (in the space of the mesh)
dir	Direction (unit vector, in the space of the mesh)
best	Distance of the nearest hit (Q16.16): give the length of the ray, updated when a nearer polygon is hit
normal	Normal 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

mesh	Mesh
planes	The planes of the mesh (see jo_3d_mesh_create_ray_planes()), JO_NULL: without them
origin	Origin (in the space of the mesh)
dir	Direction (unit vector, in the space of the mesh)
best	Distance of the nearest hit (Q16.16): give the length of the ray, updated when a nearer polygon is hit
normal	Normal 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

angle

Angle in degree (from 21 to 159)

jo_3d_pop_matrix()

void jo_3d_pop_matrix

(

void

)

Pop 3D matrix.

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

normal	Normal of the plane (unit vector, world space)
distance	The 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

Restore default scale for every 3d model displayed after this call.

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

x	X Angle in degree
y	Y Angle in degree
z	Z Angle in degree

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

x	X Angle in radian
y	Y Angle in radian
z	Z 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

x	X 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

y	Y 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

z	Z 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

x	X 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

y	Y 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

z	Z 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

window

JO_3D_NEAR_WINDOW, JO_3D_FAR_WINDOW or JO_3D_FAR_WINDOW_2

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

quad	Address to a jo_3d_quad allocated struct
color	Color

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

bias	Depth (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_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

shift

The 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

pixels

Distance 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_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

quad	Address to a jo_3d_quad allocated struct
enabled	true 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

mesh	Address to a jo_3d_mesh allocated struct
color	Color

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

mesh	Address to a jo_3d_mesh allocated struct
color	Color
wireframe	True 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

mesh	Mesh (the normals of its polygons are computed)
sprite_id	The picture (RGB, its width / tiles a multiple of 8 pixels)
tiles	Tiles 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_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

mesh	Address to a jo_3d_mesh allocated struct
enabled	true 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

mesh	Address to a jo_3d_mesh allocated struct
enabled	true 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

mesh	Address to a jo_3d_mesh allocated struct
x	X position
y	Y position
z	Z position
index	quad 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

mesh	Address to a jo_3d_mesh allocated struct
palette_id	Palette 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

mesh	Address to a jo_3d_mesh allocated struct
color	Color
index	polygon 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

mesh	Address to a jo_3d_mesh allocated struct
color	Color
index	polygon index on the mesh
wireframe	True 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

mesh	Mesh
index	Polygon

Returns

false if the mesh has no environment map

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

mesh	Address to a jo_3d_mesh allocated struct
enabled	true to enable High Speed Shrink
index	polygon 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

mesh	Address to a jo_3d_mesh allocated struct
enabled	true to enable light support
index	polygon 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

mesh	Address to a jo_3d_mesh allocated struct
index	polygon index on the mesh
palette_id	Palette 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

mesh	Address to a jo_3d_mesh allocated struct
enabled	true to enable screen doors transparency
index	polygon 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

mesh	Address to a jo_3d_mesh allocated struct
sprite_id	Sprite ID
index	polygon 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

mesh	Address to a jo_3d_mesh allocated struct
enabled	true to enable transparency
index	polygon 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

mesh	Address to a jo_3d_mesh allocated struct
index	polygon index on the mesh
wireframe	True 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

mesh	Address to a jo_3d_mesh allocated struct
enabled	true 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

mesh	Address to a jo_3d_mesh allocated struct
sprite_id	Sprite 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

mesh	Address to a jo_3d_mesh allocated struct
enabled	true 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

mesh	Address to a jo_3d_mesh allocated struct
x	X position
y	Y position
z	Z position
index	vertice 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

mirror

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

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

quad	Address to a jo_3d_quad allocated struct
palette_id	Palette id from jo_create_palette()

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

x	X Scale
y	Y Scale
z	Z 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

x	X Scale
y	Y Scale
z	Z 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

x	X Scale
y	Y Scale
z	Z 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

quad	Address to a jo_3d_quad allocated struct
enabled	true to enable screen doors transparency

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_id	Sprite Id returned by jo_sprite_add(), jo_sprite_add_tga() or jo_sprite_add_image_pack()
palette_id	Palette 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

quad	Address to a jo_3d_quad allocated struct
sprite_id	Sprite ID

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_id

Texture (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

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_id

Texture (RGB sprite, width multiple of 16: 2 x 2 tiles, of 32: 4 x 4 tiles too)

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)

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_id	Texture (see jo_3d_set_texture_subdivision())
depth	Depth 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_id	Texture (see jo_3d_set_texture_subdivision())
pixels	Distortion (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_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_id

Texture (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

r	Red added (gouraud units, -31 to 31, steps of 2)
g	Green added
b	Blue 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 tint that changes at each frame costs a copy at each frame). The polygons tinted are drawn by the C loop (not the assembly loop)

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

quad	Address to a jo_3d_quad allocated struct
enabled	true 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

rect	Rectangle (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_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

enabled

true: 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

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_id	Sprite Id
foot	Position of the bottom center of the sprite (world space, Q16.16)
width	Width (world units, Q16.16)
height	Height (world units, Q16.16)
sway	Horizontal offset of the top of the sprite (world units, Q16.16): wind
flip	Horizontal 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

center	Center of the sphere in the view space (see jo_3d_slave_transform_point())
radius	Radius (Q16.16)
max_distance	Farthest 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

mesh	Mesh (512 points at most)

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

mesh	Mesh
point_count	Number of points used by these polygons (512 at most)
ranges	Ranges of polygons
range_count	Number 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

axis	JO_3D_AXIS_X, JO_3D_AXIS_Y or JO_3D_AXIS_Z
angle	Angle (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

x	X angle (degrees)
y	Y angle (degrees)
z	Z angle (degrees)

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

bias	Depth (see jo_3d_set_depth_bias())

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

pixels

Distance 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

count

Commands (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

x	X scale (Q16.16)
y	Y scale (Q16.16)
z	Z scale (Q16.16)

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

in	Point
out	Transformed 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

x	X (Q16.16)
y	Y (Q16.16)
z	Z (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

in	Point
out	Transformed 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

m	Matrix: 4 rows of 3 (the 3 axes, then the translation), for instance the matrix of a bone (see jo_3d_bone_callback)
in	Point
out	Transformed 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

x	X Position
y	Y Position
z	Z 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

x	X Position
y	Y Position
z	Z Position

jo_3d_translate_matrix_x()

__jo_force_inline void jo_3d_translate_matrix_x ( int x )

static

Translate 3D matrix (X axis).

Parameters

x	X Position

jo_3d_translate_matrix_y()

__jo_force_inline void jo_3d_translate_matrix_y ( int y )

static

Translate 3D matrix (Y axis).

Parameters

y	Y Position

jo_3d_translate_matrix_z()

__jo_force_inline void jo_3d_translate_matrix_z ( int z )

static

Translate 3D matrix (Z axis).

Parameters

z	Z 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

x	X Position
y	Y Position
z	Z 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), or not (default: the whole screen).

Parameters

clip	true: clipped to the rectangle of jo_3d_window()

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[JO_MAX_SPRITE]

extern

Sprite quads (internal engine usage).

Warning

MC Hammer: don't touch this