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

3D models (.JOM files): meshes made with a 3D software, converted by Compiler/COMMON/jo_model.py More...

Go to the source code of this file.

Data Structures

struct  jo_3d_material
 Material of a model (the same layout as the file: 32 bytes). More...
struct  jo_3d_model_group
 Group of a model: OBJ o or g (the same layout as the file: 24 bytes). More...
struct  jo_3d_bone
 Bone of a rigid skeleton (the same layout as the file: 32 bytes). More...
struct  jo_3d_animation
 Animation of a skeleton (the same layout as the file: 28 bytes). More...
struct  jo_3d_morph
 Vertex animation (morph targets: the position of each point at each frame, the same layout as the file: 28 bytes). Unlike a skeleton, the surface bends (a knee, a cloth, a face): see jo_3d_model_draw_morph(). More...
struct  jo_3d_skin_point
 A point of a skeleton that follows 2 bones (the same layout as the file: 8 bytes): drawn by the bone of its group, moved toward where the other bone puts it (the knee between the thigh and the shin). More...
struct  jo_3d_pose
 Pose of a skeleton: the angles of the bones (see jo_3d_model_get_pose() and jo_3d_model_draw_pose()). More...
struct  jo_3d_model
 3D model loaded from a JOM file More...
struct  jo_3d_model_pool
 Models read one after the other from a file (the parts of a level) into big memory blocks, used in place (jo_3d_create_model_in_place()): no copy, no small memory blocks for each model. Measured (a 3D game, about 1000 models): the copies of jo_3d_create_model_from_memory() took 11 s (about 12 memory blocks each, every block allocated after a search among the ones before). More...

Macros

#define JO_3D_MODEL_VERSION
 Version of the JOM files read by this engine.
#define JO_3D_MATERIAL_DUAL_PLANE
 Material: drawn on both sides (JO_3D_DUAL_PLANE).
#define JO_3D_MATERIAL_SORT_MIN
 Material: sorted with the nearest point (JO_3D_SORT_MIN).
#define JO_3D_MATERIAL_SORT_MAX
 Material: sorted with the farthest point (JO_3D_SORT_MAX).
#define JO_3D_MATERIAL_SORT_PREVIOUS
 Material: sorted with the depth of the previous polygon of the model (JO_3D_SORT_PREVIOUS): a decal drawn over the face before it (a grille, a sign), whatever their nearest points.
#define JO_3D_MATERIAL_GOURAUD
 Material: gouraud shading with the vertex colors ("GOUR" chunk).
#define JO_3D_MATERIAL_HALF_TRANSPARENT
 Material: half transparent.
#define JO_3D_MATERIAL_SCREEN_DOORS
 Material: screen doors (mesh).
#define JO_3D_MATERIAL_LIGHT
 Material: lit by the light of the engine (jo_3d_light()).
#define JO_3D_MATERIAL_FLIP_H
 Material: texture flipped horizontally.
#define JO_3D_MATERIAL_FLIP_V
 Material: texture flipped vertically.
#define JO_3D_MATERIAL_END_CODES
 Material: the texture stops each line after its last visible pixel (jo_sprite_add_end_codes()).
#define JO_3D_MATERIAL_MIPMAPS
 Material: smaller copies of the texture far away (jo_3d_set_texture_mipmaps()).
#define JO_3D_MATERIAL_SUBDIVISION
 Material: the polygons near the camera are drawn in parts (jo_3d_set_texture_subdivision()).
#define JO_3D_MATERIAL_SUBDIVISION_NEAR
 Material: only the polygons that cross the near plane are drawn in parts (jo_3d_set_texture_subdivision_near_only(), MTL: jo_subdivision 2).
#define JO_3D_MATERIAL_HIGH_SPEED_SHRINK
 Material: the VDP1 reads every other texel of a texture drawn smaller than it is (JO_VDP1_HIGH_SPEED_SHRINK, MTL: jo_high_speed_shrink 1; all the textures: jo_3d_set_high_speed_shrink()).
#define JO_3D_MATERIAL_USER(N)
 First flag of the program (bits 16 to 31, MTL: jo_user).
#define JO_3D_MAX_BONES
 Bones of a model at most (jo_3d_pose).
#define JO_3D_BONE_NO_GROUP
 jo_3d_bone.group: the bone has no polygons
#define JO_3D_ANIMATION_LOOP
 jo_3d_animation.flags: the last key goes back to the first one
#define JO_3D_ANIMATION_TICKS_PER_SECOND
 Ticks of the animations per second (the time of jo_3d_model_get_pose()).
#define JO_3D_MORPH_LOOP
 jo_3d_morph.flags: the last frame goes back to the first one
#define JO_3D_MORPH_NORMALS
 Directions of the normals of the vertex animations (see jo_3d_morph_normal()).
#define JO_3D_SKIN_ONE
 jo_3d_skin_point.weight: 1.0
#define JO_3D_MODEL_POOL_MAX_BLOCKS
 Maximum of memory blocks of a pool of models.

Typedefs

typedef void(*) jo_3d_bone_callback(const int bone, void *const param, const jo_fixed(*const matrix)[3])
 Called by jo_3d_model_draw_pose() after each bone is drawn, with the matrix of the bone (the program draws a weapon in a hand, a muzzle flash...).

Functions

jo_3d_model * jo_3d_create_model_from_memory (const unsigned char *const data, const unsigned int size)
 Create a model from the content of a JOM file.
jo_3d_model * jo_3d_create_model_in_place (const unsigned char *const data, const unsigned int size)
 Create a model that uses the content of a JOM file in place (like jo_3d_load_model(): the points, the polygons, the materials are not copied): much faster than jo_3d_create_model_from_memory() for many models (a level read in one block: 4 memory blocks per model instead of about 12), and smaller.
const unsigned char * jo_3d_model_find_chunk (const void *const data, const char *const tag, unsigned int *const size)
 Find a chunk in the content of a JOM file (a chunk of the program too: the loader skips the chunks it doesn't know).
const unsigned short * jo_3d_model_file_gouraud_colors (const void *const data, const unsigned int polygon_count)
 The gouraud colors of the polygons in the content of a JOM file ("GOUR" chunk).
static __jo_force_inline const unsigned short * jo_3d_model_gouraud_colors (const jo_3d_model *const model)
 The gouraud colors of a model as they were loaded: a game that writes its gouraud tables again (a light on a car) starts from them (its tables in the VRAM may not be written yet).
bool jo_3d_model_set_environment (jo_3d_model *const model, const int sprite_id, const int tiles, const unsigned int material_flags)
 Environment map on the polygons of a model whose material has a flag (the paint and the glass of a car, see jo_3d_set_mesh_environment()).
void jo_3d_model_pool_init (jo_3d_model_pool *const pool, const unsigned int block_size, const unsigned int bytes)
 Start a pool of models.
jo_3d_model * jo_3d_model_pool_read (jo_3d_model_pool *const pool, jo_file *const file, const unsigned int size)
 Read the next model of a file (the content of a JOM file, see jo_3d_create_model_in_place()) into a pool.
void jo_3d_model_pool_free (jo_3d_model_pool *const pool)
 Free the memory blocks of a pool (after its models: jo_3d_free_model()).
jo_3d_model * jo_3d_load_model (const char *const filename)
 Load a model (JOM file) from the current directory of the CD.
void jo_3d_set_unique_gouraud_tables (const bool unique)
 The next models created or loaded get a gouraud table per polygon, in the order of the polygons (default: the polygons with the same 4 colors share a table): for a model whose tables the game writes again polygon by polygon (the light on a car).
void jo_3d_set_neutral_gouraud_skipped (const bool skipped)
 The next models created or loaded draw without gouraud only the polygons whose 4 gouraud colors leave the texels as they are (16, 16, 16 each): the same picture (see jo_3d_set_uniform_gouraud_skipped(), on by default, that does it too).
void jo_3d_set_uniform_gouraud_skipped (const bool skipped)
 The next models created or loaded draw without gouraud the polygons whose 4 gouraud colors are the same (a flat light), the light put in their color: the same picture, the VDP1 draws them faster (default: on).
int jo_3d_model_texture (const char *const filename)
 Get the sprite id of a texture of the models (loaded the first time: a texture shared by several models, or by the program, is loaded once).
int jo_3d_model_loaded_texture (const char *const name)
 Get the sprite id of a texture already loaded by the models (embedded in a model, or loaded by jo_3d_model_texture()), without loading it.
void jo_3d_free_model (jo_3d_model *const model)
 Free a model (the textures stay loaded).
void jo_3d_model_free_textures_from (const int sprite_id)
 Free the sprites added since a sprite (the textures of the models loaded since, their tiles and smaller copies, their gouraud tables, the sprites added by the program): the VRAM of the VDP1 is given back.
const jo_3d_model_group * jo_3d_model_find_group (const jo_3d_model *const model, const char *const name)
 Find a group of a model.
int jo_3d_model_find_bone (const jo_3d_model *const model, const char *const name)
 Find a bone of a model.
int jo_3d_model_find_animation (const jo_3d_model *const model, const char *const name)
 Find an animation of a model.
bool jo_3d_model_is_animation (const jo_3d_model *const model, const int animation, const char *const name)
 Check if an animation is the one jo_3d_model_find_animation() finds for a name (faster: the name of this one is compared, the ones before it only when it matches).
int jo_3d_model_animation_duration (const jo_3d_model *const model, const int animation)
 Duration of an animation.
void jo_3d_model_get_pose (const jo_3d_model *const model, const int animation, int time, jo_3d_pose *const pose)
 Pose of a skeleton at a time of an animation (the keys are interpolated).
void jo_3d_pose_blend (const jo_3d_model *const model, jo_3d_pose *const pose, const jo_3d_pose *const other, const int weight)
 Blend 2 poses (a smooth change of animation).
void jo_3d_model_draw_pose (const jo_3d_model *const model, const jo_3d_pose *const pose, const jo_3d_bone_callback callback, void *const param)
 Draw a model with a skeleton with the current matrix.
void jo_3d_slave_model_draw_pose (const jo_3d_model *const model, const jo_3d_pose *const pose, const jo_3d_bone_callback callback, void *const param, const unsigned int hidden_bones)
 Draw a model with a skeleton in a pose on the slave CPU (call it on the slave CPU, see jo_3d_model_draw_pose()).
void jo_3d_model_set_hidden_bones (const unsigned int mask)
 Bones not drawn by the next jo_3d_model_draw_pose() (a hat shot off the head of a character: its bone hidden, the hat drawn alone where it falls: the other bones hidden).
int jo_3d_model_find_morph (const jo_3d_model *const model, const char *const name)
 Find a vertex animation of a model.
int jo_3d_model_morph_duration (const jo_3d_model *const model, const int morph)
 Duration of a vertex animation.
void jo_3d_model_draw_morph (const jo_3d_model *const model, const int morph, const int time)
 Draw a model with the current matrix, its points at a time of a vertex animation (the 2 frames around it are interpolated).
bool jo_3d_slave_model_draw_morph (const jo_3d_model *const model, const int morph, const int time)
 jo_3d_model_draw_morph() on the slave CPU (call it on the slave CPU: its own buffer, the master CPU can draw the same model at the same time)
void jo_3d_morph_normal (const int index, jo_pos3D_fixed *const normal)
 Direction of a normal of the vertex animations (the frames give the normal of each polygon as one byte).
bool jo_3d_model_use_fast_memory (jo_3d_model *const model)
 Move what the drawing of a model reads for each vertex, polygon and bone (its points, its polygons, their attributes, its bones and their groups) to the high work RAM, when it is in a slower memory (the low work RAM, a RAM cartridge).
static __jo_force_inline void jo_3d_model_draw (const jo_3d_model *const model)
 Draw a model with the current matrix.

Detailed Description

3D models (.JOM files): meshes made with a 3D software, converted by Compiler/COMMON/jo_model.py

Author
Johannes Fetz
Remarks
The converter reads Wavefront OBJ files (and their MTL materials, see jo_model.py for the options of the materials) and writes a JOM file. The data of a JOM file are in the memory format of the Saturn (big endian, 16.16 fixed point): the points and the polygons are copied as they are, nothing is converted when it is loaded

JOM file (all the values are big endian, the chunks are aligned on 4 bytes):

Header (24 bytes)
char[4] "JOM1"
u16 version (1)
u16 reserved (0)
fixed[3] center of the bounding sphere (16.16)
fixed radius of the bounding sphere
Chunks, until the "END " chunk. A chunk: char[4] tag, u32 size of the data (multiple of 4), data.
The loader skips the unknown chunks (newer versions of the converter)
"TIMG" (optional, first chunk) u32 count, then count x (char[16] name, u16 width, u16 height, u16 format,
u16 reserved, then the pixels, 4 bytes aligned): embedded textures. Format 0 (RGB 555): width x height u16
pixels, 0 is transparent. Format 1 (16 colors, jo_lut in the MTL): 16 u16 colors (RGB 555, the color 0 is
transparent), then 2 pixels per byte (the left pixel in the high bits), see jo_sprite_add_4bits_lut()
(jo_model.py --embed-textures). jo_3d_load_model() reads them one at a time and copies them in the VRAM
(a texture already loaded by another model is skipped), they don't stay in the work RAM
"PNTS" u32 count, then count x (fixed x, fixed y, fixed z) Points (Saturn axes: Y down)
"QUAD" u32 count, then count x (fixed nx, ny, nz, u16 v0, v1, v2, v3) Polygons (jo_3d_polygon): normal and
4 point indexes (a triangle: v3 = v2)
"QMAT" u32 count, then count x u16 (+ u16 pad if count is odd) Material of each polygon
"MATL" u32 count, then count x jo_3d_material (32 bytes) Materials
"TEXT" u32 count, then count x char[16] Textures: names (the embedded textures, or
the files on the CD: .BIN or .TGA)
"NTAB" u32 count, then count x (fixed x, fixed y, fixed z) Normals (OBJ vn)
"CNRM" u32 count (4 x polygons), then count x u16 (+ pad) Normal of each corner of each polygon
"VCOL" u32 count (points), then count x (fixed r, fixed g, fixed b) Vertex colors (OBJ v x y z r g b), 1.0 = 0x10000
"GOUR" u32 count (4 x polygons), then count x u16 (+ pad) Gouraud colors of the corners (RGB 555 of
the vertex colors: 16 = texture unchanged)
"GRUP" u32 count, then count x jo_3d_model_group (24 bytes) Groups (OBJ o and g): names, ranges of
polygons and of the points used only by
the group (for animations)
"BONE" u32 count, then count x jo_3d_bone (32 bytes) Rigid skeleton: each bone moves a group
(its polygons use only its points), a
parent is before its children
"ANIM" u32 count, then count x jo_3d_animation (28 bytes), then the keys Animations. The keys of an animation
(at offset from the count): key_count x
(fixed root x, y, z, then bones x
(s16 angle x, y, z), + s16 pad if odd)
"MRPH" u32 count, u16 shift, u16 flags, then count x jo_3d_morph Vertex animations (morph targets): the
(28 bytes), then the frames points of each frame. The frames of an
animation (at offset from the count):
frame_count x (points x (s16 x, y, z) of
the points: value x 2^shift = 16.16 fixed;
then, with the flag 1, polygons x u8:
the normal of each polygon, an index in
jo_3d_morph_normal(); 4 bytes aligned)
"SKIN" u32 count, then count x jo_3d_skin_point (8 bytes) The points of a skeleton that follow 2
bones (a skin that bends at the joints):
the bone of their group and another one,
weighted (see jo_3d_model_draw_pose())
"END " 0
Polygon (quadrilateral, a triangle repeats the last vertex).
Definition 3d.h:158
jo_pos3D_fixed center
Definition entity.h:13
int radius
Definition entity.h:3
void * data
Definition entity.h:19
const char * name
Definition entity.h:9
unsigned int flags
Definition entity.h:1
int height
Definition entity.h:4
void jo_3d_model_draw_pose(const jo_3d_model *const model, const jo_3d_pose *const pose, const jo_3d_bone_callback callback, void *const param)
Draw a model with a skeleton with the current matrix.
void jo_3d_morph_normal(const int index, jo_pos3D_fixed *const normal)
Direction of a normal of the vertex animations (the frames give the normal of each polygon as one byt...
jo_3d_model * jo_3d_load_model(const char *const filename)
Load a model (JOM file) from the current directory of the CD.
Animation of a skeleton (the same layout as the file: 28 bytes).
Definition model.h:182
Bone of a rigid skeleton (the same layout as the file: 32 bytes).
Definition model.h:173
Material of a model (the same layout as the file: 32 bytes).
Definition model.h:139
Group of a model: OBJ o or g (the same layout as the file: 24 bytes).
Definition model.h:154
Vertex animation (morph targets: the position of each point at each frame, the same layout as the fil...
Definition model.h:200
A point of a skeleton that follows 2 bones (the same layout as the file: 8 bytes): drawn by the bone ...
Definition model.h:216
int jo_sprite_add_4bits_lut(const unsigned char *const pixels, const unsigned short width, const unsigned short height, const jo_color *const lut)
Add a 16 colors texture with its color lookup table: 4 bits per pixel (4 times less VRAM than an RGB ...

Data Structure Documentation

◆ jo_3d_material

struct jo_3d_material

Material of a model (the same layout as the file: 32 bytes).

Data Fields
unsigned char b
unsigned int flags
unsigned char g
char name[16]
unsigned char r
unsigned char shine
unsigned short subdivision_error
short texture
unsigned int user

◆ jo_3d_model_group

struct jo_3d_model_group

Group of a model: OBJ o or g (the same layout as the file: 24 bytes).

Data Fields
unsigned short first_point
unsigned short first_polygon
char name[16]
unsigned short point_count
unsigned short polygon_count

◆ jo_3d_bone

struct jo_3d_bone

Bone of a rigid skeleton (the same layout as the file: 32 bytes).

Data Fields
unsigned short group
char name[16]
short parent
jo_pos3D_fixed pivot

◆ jo_3d_animation

struct jo_3d_animation

Animation of a skeleton (the same layout as the file: 28 bytes).

Data Fields
unsigned short duplicate
unsigned short flags
unsigned short key_count
unsigned short key_ticks
char name[16]
unsigned int offset

◆ jo_3d_morph

struct jo_3d_morph

Vertex animation (morph targets: the position of each point at each frame, the same layout as the file: 28 bytes). Unlike a skeleton, the surface bends (a knee, a cloth, a face): see jo_3d_model_draw_morph().

Data Fields
unsigned short duplicate
unsigned short flags
unsigned short frame_count
unsigned short frame_ticks
char name[16]
unsigned int offset

◆ jo_3d_skin_point

struct jo_3d_skin_point

A point of a skeleton that follows 2 bones (the same layout as the file: 8 bytes): drawn by the bone of its group, moved toward where the other bone puts it (the knee between the thigh and the shin).

Data Fields
unsigned char bone
unsigned char other
unsigned short point
unsigned short reserved
unsigned short weight

◆ jo_3d_pose

struct jo_3d_pose

Pose of a skeleton: the angles of the bones (see jo_3d_model_get_pose() and jo_3d_model_draw_pose()).

Data Fields
jo_angle angles[(32)][3]
jo_pos3D_fixed root

◆ jo_3d_model

struct jo_3d_model

3D model loaded from a JOM file

Data Fields
unsigned int animation_count
const unsigned char * animation_data
jo_3d_animation * animations
signed char * bone_children
unsigned int bone_count
jo_3d_bone * bones
jo_pos3D_fixed center
unsigned short * corner_normals
void * fast_block
void * file
bool file_not_owned
unsigned short gouraud_table_count
unsigned short gouraud_tables
unsigned int group_count
jo_3d_model_group * groups
unsigned int material_count
jo_3d_material * materials
jo_3d_mesh * mesh
unsigned int morph_count
const unsigned char * morph_data
jo_3d_polygon_data * morph_draw[2]
unsigned int morph_frame_size
bool morph_normals
unsigned short morph_shift
jo_3d_morph * morphs
unsigned int normal_count
jo_pos3D_fixed * normals
unsigned short * polygon_materials
jo_fixed radius
bool single_block
const jo_3d_skin_point * skin
unsigned int skin_count
unsigned int texture_count
int * textures
jo_pos3D_fixed * vertex_colors

◆ jo_3d_model_pool

struct jo_3d_model_pool

Models read one after the other from a file (the parts of a level) into big memory blocks, used in place (jo_3d_create_model_in_place()): no copy, no small memory blocks for each model. Measured (a 3D game, about 1000 models): the copies of jo_3d_create_model_from_memory() took 11 s (about 12 memory blocks each, every block allocated after a search among the ones before).

Data Fields
unsigned char * block
int block_count
unsigned int block_size
unsigned char * blocks[(256)]
unsigned int bytes_left
unsigned int left

Macro Definition Documentation

◆ JO_3D_ANIMATION_LOOP

#define JO_3D_ANIMATION_LOOP

jo_3d_animation.flags: the last key goes back to the first one

◆ JO_3D_ANIMATION_TICKS_PER_SECOND

#define JO_3D_ANIMATION_TICKS_PER_SECOND

Ticks of the animations per second (the time of jo_3d_model_get_pose()).

◆ JO_3D_BONE_NO_GROUP

#define JO_3D_BONE_NO_GROUP

jo_3d_bone.group: the bone has no polygons

◆ JO_3D_MATERIAL_DUAL_PLANE

#define JO_3D_MATERIAL_DUAL_PLANE

Material: drawn on both sides (JO_3D_DUAL_PLANE).

◆ JO_3D_MATERIAL_END_CODES

#define JO_3D_MATERIAL_END_CODES

Material: the texture stops each line after its last visible pixel (jo_sprite_add_end_codes()).

◆ JO_3D_MATERIAL_FLIP_H

#define JO_3D_MATERIAL_FLIP_H

Material: texture flipped horizontally.

◆ JO_3D_MATERIAL_FLIP_V

#define JO_3D_MATERIAL_FLIP_V

Material: texture flipped vertically.

◆ JO_3D_MATERIAL_GOURAUD

#define JO_3D_MATERIAL_GOURAUD

Material: gouraud shading with the vertex colors ("GOUR" chunk).

◆ JO_3D_MATERIAL_HALF_TRANSPARENT

#define JO_3D_MATERIAL_HALF_TRANSPARENT

Material: half transparent.

◆ JO_3D_MATERIAL_HIGH_SPEED_SHRINK

#define JO_3D_MATERIAL_HIGH_SPEED_SHRINK

Material: the VDP1 reads every other texel of a texture drawn smaller than it is (JO_VDP1_HIGH_SPEED_SHRINK, MTL: jo_high_speed_shrink 1; all the textures: jo_3d_set_high_speed_shrink()).

◆ JO_3D_MATERIAL_LIGHT

#define JO_3D_MATERIAL_LIGHT

Material: lit by the light of the engine (jo_3d_light()).

◆ JO_3D_MATERIAL_MIPMAPS

#define JO_3D_MATERIAL_MIPMAPS

Material: smaller copies of the texture far away (jo_3d_set_texture_mipmaps()).

◆ JO_3D_MATERIAL_SCREEN_DOORS

#define JO_3D_MATERIAL_SCREEN_DOORS

Material: screen doors (mesh).

◆ JO_3D_MATERIAL_SORT_MAX

#define JO_3D_MATERIAL_SORT_MAX

Material: sorted with the farthest point (JO_3D_SORT_MAX).

◆ JO_3D_MATERIAL_SORT_MIN

#define JO_3D_MATERIAL_SORT_MIN

Material: sorted with the nearest point (JO_3D_SORT_MIN).

◆ JO_3D_MATERIAL_SORT_PREVIOUS

#define JO_3D_MATERIAL_SORT_PREVIOUS

Material: sorted with the depth of the previous polygon of the model (JO_3D_SORT_PREVIOUS): a decal drawn over the face before it (a grille, a sign), whatever their nearest points.

◆ JO_3D_MATERIAL_SUBDIVISION

#define JO_3D_MATERIAL_SUBDIVISION

Material: the polygons near the camera are drawn in parts (jo_3d_set_texture_subdivision()).

◆ JO_3D_MATERIAL_SUBDIVISION_NEAR

#define JO_3D_MATERIAL_SUBDIVISION_NEAR

Material: only the polygons that cross the near plane are drawn in parts (jo_3d_set_texture_subdivision_near_only(), MTL: jo_subdivision 2).

◆ JO_3D_MATERIAL_USER

#define JO_3D_MATERIAL_USER ( N)

First flag of the program (bits 16 to 31, MTL: jo_user).

◆ JO_3D_MAX_BONES

#define JO_3D_MAX_BONES

Bones of a model at most (jo_3d_pose).

◆ JO_3D_MODEL_POOL_MAX_BLOCKS

#define JO_3D_MODEL_POOL_MAX_BLOCKS

Maximum of memory blocks of a pool of models.

◆ JO_3D_MODEL_VERSION

#define JO_3D_MODEL_VERSION

Version of the JOM files read by this engine.

◆ JO_3D_MORPH_LOOP

#define JO_3D_MORPH_LOOP

jo_3d_morph.flags: the last frame goes back to the first one

◆ JO_3D_MORPH_NORMALS

#define JO_3D_MORPH_NORMALS

Directions of the normals of the vertex animations (see jo_3d_morph_normal()).

◆ JO_3D_SKIN_ONE

#define JO_3D_SKIN_ONE

Typedef Documentation

◆ jo_3d_bone_callback

typedef void(*) jo_3d_bone_callback(const int bone, void *const param, const jo_fixed(*const matrix)[3])

Called by jo_3d_model_draw_pose() after each bone is drawn, with the matrix of the bone (the program draws a weapon in a hand, a muzzle flash...).

Parameters
boneIndex of the bone
paramParameter of jo_3d_model_draw_pose()
matrixMatrix of the bone (4 rows of 3, see jo_3d_transform_point_by()); the current matrix is not the one of the bone

Function Documentation

◆ jo_3d_create_model_from_memory()

jo_3d_model * jo_3d_create_model_from_memory ( const unsigned char *const data,
const unsigned int size )

Create a model from the content of a JOM file.

Parameters
dataContent of the file (4 bytes aligned)
sizeSize in bytes
Returns
The model, JO_NULL if the file is wrong or if out of memory
Remarks
The embedded textures ("TIMG" chunk) are copied to the VRAM, the other textures are loaded from the CD (see jo_3d_model_texture()). The data can be freed after the call

◆ jo_3d_create_model_in_place()

jo_3d_model * jo_3d_create_model_in_place ( const unsigned char *const data,
const unsigned int size )

Create a model that uses the content of a JOM file in place (like jo_3d_load_model(): the points, the polygons, the materials are not copied): much faster than jo_3d_create_model_from_memory() for many models (a level read in one block: 4 memory blocks per model instead of about 12), and smaller.

Parameters
dataContent of the file (4 bytes aligned), kept by the caller as long as the model exists
sizeSize in bytes
Returns
The model, JO_NULL if the file is wrong or if out of memory
Remarks
jo_3d_free_model() does not free the data

◆ jo_3d_free_model()

void jo_3d_free_model ( jo_3d_model *const model)

Free a model (the textures stay loaded).

Parameters
modelModel

◆ jo_3d_load_model()

jo_3d_model * jo_3d_load_model ( const char *const filename)

Load a model (JOM file) from the current directory of the CD.

Parameters
filenameFile name (example: "MODEL.JOM")
Returns
The model, JO_NULL if the file is not found, wrong or if out of memory
Remarks
Free it with jo_3d_free_model()
The model uses the data of the file (one memory block: the points and the polygons are not copied)
Embedded textures (jo_model.py –embed-textures): read one at a time and copied to the VRAM, they don't stay in the work RAM

◆ jo_3d_model_animation_duration()

int jo_3d_model_animation_duration ( const jo_3d_model *const model,
const int animation )

Duration of an animation.

Parameters
modelModel
animationIndex of the animation
Returns
Ticks (1/60 s): a loop goes back to its first key at this time, the other animations stay on their last key

◆ jo_3d_model_draw()

__jo_force_inline void jo_3d_model_draw ( const jo_3d_model *const model)
static

Draw a model with the current matrix.

Parameters
modelModel
Remarks
A model with a skeleton is drawn in the pose of the OBJ (see jo_3d_model_draw_pose())

◆ jo_3d_model_draw_morph()

void jo_3d_model_draw_morph ( const jo_3d_model *const model,
const int morph,
const int time )

Draw a model with the current matrix, its points at a time of a vertex animation (the 2 frames around it are interpolated).

Parameters
modelModel
morphIndex of the vertex animation (see jo_3d_model_find_morph()), -1 or wrong: the points of the OBJ
timeTicks (1/60 s) from the start of the animation
Remarks
The points are interpolated in a buffer of the model, not in the model: several characters drawn with the same model at different times. Cost: 3 multiplications per point, beside their transformation
The lit polygons (jo_light in the MTL, see jo_3d_light()) get the normal of the nearest frame (one of 256 directions). The point lights (jo_3d_point_lights_xxx) and the corner normals ("CNRM") are not animated
Drawn with the polygon data of the model for this CPU (model->morph_draw): the tint (jo_3d_set_tint()) is applied, the environment map of the mesh (jo_3d_model_set_environment()) is not

◆ jo_3d_model_draw_pose()

void jo_3d_model_draw_pose ( const jo_3d_model *const model,
const jo_3d_pose *const pose,
const jo_3d_bone_callback callback,
void *const param )

Draw a model with a skeleton with the current matrix.

Parameters
modelModel
posePose (JO_NULL: the pose of the OBJ)
callbackCalled after each bone is drawn, with the matrix of the bone (JO_NULL: none)
paramParameter of the callback
Remarks
With a skin ("SKIN", jo_model.py by default when polygons join 2 bones): the points near a joint follow both bones (computed for each draw in a buffer of the model, see model->morph_draw), the skin bends instead of folding like rigid parts

◆ jo_3d_model_file_gouraud_colors()

const unsigned short * jo_3d_model_file_gouraud_colors ( const void *const data,
const unsigned int polygon_count )

The gouraud colors of the polygons in the content of a JOM file ("GOUR" chunk).

Parameters
dataContent of the file (4 bytes aligned)
polygon_countPolygons of the model
Returns
polygon_count x 4 colors (RGB 555, 16: the texture unchanged), JO_NULL if the file has none for these polygons

◆ jo_3d_model_find_animation()

int jo_3d_model_find_animation ( const jo_3d_model *const model,
const char *const name )

Find an animation of a model.

Parameters
modelModel
nameName of the animation
Returns
Index of the animation, -1 if not found

◆ jo_3d_model_find_bone()

int jo_3d_model_find_bone ( const jo_3d_model *const model,
const char *const name )

Find a bone of a model.

Parameters
modelModel
nameName of the bone
Returns
Index of the bone, -1 if not found

◆ jo_3d_model_find_chunk()

const unsigned char * jo_3d_model_find_chunk ( const void *const data,
const char *const tag,
unsigned int *const size )

Find a chunk in the content of a JOM file (a chunk of the program too: the loader skips the chunks it doesn't know).

Parameters
dataContent of the file (4 bytes aligned): model->file of a model that keeps it (jo_3d_load_model(), jo_3d_create_model_in_place())
tagTag of the chunk (4 characters, example: "GOUR")
sizeSize of the data of the chunk (output, JO_NULL: not wanted)
Returns
The data of the chunk (after its tag and its size), JO_NULL if the file has no such chunk

◆ jo_3d_model_find_group()

const jo_3d_model_group * jo_3d_model_find_group ( const jo_3d_model *const model,
const char *const name )

Find a group of a model.

Parameters
modelModel
nameName of the group (OBJ o or g)
Returns
The group, JO_NULL if not found

◆ jo_3d_model_find_morph()

int jo_3d_model_find_morph ( const jo_3d_model *const model,
const char *const name )

Find a vertex animation of a model.

Parameters
modelModel
nameName of the vertex animation (case insensitive)
Returns
Index of the vertex animation, -1 if not found

◆ jo_3d_model_free_textures_from()

void jo_3d_model_free_textures_from ( const int sprite_id)

Free the sprites added since a sprite (the textures of the models loaded since, their tiles and smaller copies, their gouraud tables, the sprites added by the program): the VRAM of the VDP1 is given back.

Parameters
sprite_idFirst sprite to free (jo_sprite_count() before the models were loaded)
Remarks
Call it after the models were freed (jo_3d_free_model()): a level loaded and freed again and again, with its models, would use up the VRAM otherwise (the gouraud tables of a model are new sprites at each load)

◆ jo_3d_model_get_pose()

void jo_3d_model_get_pose ( const jo_3d_model *const model,
const int animation,
int time,
jo_3d_pose *const pose )

Pose of a skeleton at a time of an animation (the keys are interpolated).

Parameters
modelModel
animationIndex of the animation, -1: the bones don't turn (the pose of the OBJ)
timeTicks (1/60 s) from the start of the animation
posePose

◆ jo_3d_model_gouraud_colors()

__jo_force_inline const unsigned short * jo_3d_model_gouraud_colors ( const jo_3d_model *const model)
static

The gouraud colors of a model as they were loaded: a game that writes its gouraud tables again (a light on a car) starts from them (its tables in the VRAM may not be written yet).

Parameters
modelModel that keeps the content of its file (jo_3d_load_model(), jo_3d_create_model_in_place())
Returns
polygons x 4 colors, JO_NULL if the model has no gouraud colors or keeps no file (jo_3d_create_model_from_memory())

◆ jo_3d_model_is_animation()

bool jo_3d_model_is_animation ( const jo_3d_model *const model,
const int animation,
const char *const name )

Check if an animation is the one jo_3d_model_find_animation() finds for a name (faster: the name of this one is compared, the ones before it only when it matches).

Parameters
modelModel
animationIndex of the animation
nameName (case insensitive)
Returns
true if jo_3d_model_find_animation(model, name) == animation

◆ jo_3d_model_loaded_texture()

int jo_3d_model_loaded_texture ( const char *const name)

Get the sprite id of a texture already loaded by the models (embedded in a model, or loaded by jo_3d_model_texture()), without loading it.

Parameters
nameName of the texture (its file name, or its name in the model)
Returns
Sprite id, -1 if no model has this texture

◆ jo_3d_model_morph_duration()

int jo_3d_model_morph_duration ( const jo_3d_model *const model,
const int morph )

Duration of a vertex animation.

Parameters
modelModel
morphIndex of the vertex animation
Returns
Ticks (1/60 s): a loop goes back to its first frame at this time, the other ones stay on their last frame

◆ jo_3d_model_pool_free()

void jo_3d_model_pool_free ( jo_3d_model_pool *const pool)

Free the memory blocks of a pool (after its models: jo_3d_free_model()).

Parameters
poolPool (empty after the call)

◆ jo_3d_model_pool_init()

void jo_3d_model_pool_init ( jo_3d_model_pool *const pool,
const unsigned int block_size,
const unsigned int bytes )

Start a pool of models.

Parameters
poolPool
block_sizeSize of its memory blocks (64 KB for example: a bigger model has a block of its size)
bytesBytes of all the models it will read, each one rounded up to 4 bytes: the last block is no bigger than the models left (0: unknown)

◆ jo_3d_model_pool_read()

jo_3d_model * jo_3d_model_pool_read ( jo_3d_model_pool *const pool,
jo_file *const file,
const unsigned int size )

Read the next model of a file (the content of a JOM file, see jo_3d_create_model_in_place()) into a pool.

Parameters
poolPool
fileFile open at the model (many small models: a bigger read buffer, see jo_fs_set_read_sector_count())
sizeSize of the model in the file (the next one starts after it, rounded up to 4 bytes)
Returns
The model (free it with jo_3d_free_model()), JO_NULL if size is 0, the read failed, the model is wrong or out of memory
Remarks
The chunks used only while the model is created, when they are the last ones of the file ("TIMG", "TEXT", "GOUR": the textures and the gouraud tables are in the VRAM now), are given back: the next model is read over them (jo_3d_model_gouraud_colors() gives JO_NULL for such a model)

◆ jo_3d_model_set_environment()

bool jo_3d_model_set_environment ( jo_3d_model *const model,
const int sprite_id,
const int tiles,
const unsigned int material_flags )

Environment map on the polygons of a model whose material has a flag (the paint and the glass of a car, see jo_3d_set_mesh_environment()).

Parameters
modelModel
sprite_idThe picture of the surroundings (RGB)
tilesTiles on a side (4 to 8)
material_flagsFlags of the materials (jo_3d_material.flags, example: JO_3D_MATERIAL_USER(0)): the polygons of a material with one of them show the environment map
Returns
false if the model is JO_NULL, the sprite -1, or if the mesh can't have this environment map (see jo_3d_set_mesh_environment())

◆ jo_3d_model_set_hidden_bones()

void jo_3d_model_set_hidden_bones ( const unsigned int mask)

Bones not drawn by the next jo_3d_model_draw_pose() (a hat shot off the head of a character: its bone hidden, the hat drawn alone where it falls: the other bones hidden).

Parameters
maskBit k: the polygons of the bone k hidden (its children are drawn), 0: all drawn

◆ jo_3d_model_texture()

int jo_3d_model_texture ( const char *const filename)

Get the sprite id of a texture of the models (loaded the first time: a texture shared by several models, or by the program, is loaded once).

Parameters
filenameFile name on the CD (.BIN: jo_sprite_add_bin(), .TGA: jo_sprite_add_tga())
Returns
Sprite id, -1 if not loaded
Remarks
The transparent color is JO_COLOR_Transparent

◆ jo_3d_model_use_fast_memory()

bool jo_3d_model_use_fast_memory ( jo_3d_model *const model)

Move what the drawing of a model reads for each vertex, polygon and bone (its points, its polygons, their attributes, its bones and their groups) to the high work RAM, when it is in a slower memory (the low work RAM, a RAM cartridge).

Parameters
modelModel loaded by jo_3d_load_model() (its data in the file: the copies replace them, the file stays)
Returns
true if the model reads them in the high work RAM now (moved, or already there), false: not enough free high work RAM (the model is unchanged)
Remarks
For the models drawn in many copies at each frame (the characters of a crowd): the high work RAM is full after the rooms of a level, the characters loaded after them are read in the low work RAM. Measured (FPS demo, 9 scientists in front of the camera): the slave CPU drew them in 23.8 ms, 20.7 ms with their models in the high work RAM
jo_malloc() takes the high work RAM first: it is often full after the loading of a level. Keep some for this (jo_malloc() a block before the loading, jo_free() it just before this call)
The animations stay in the file (only 2 keys are read per pose)

◆ jo_3d_morph_normal()

void jo_3d_morph_normal ( const int index,
jo_pos3D_fixed *const normal )

Direction of a normal of the vertex animations (the frames give the normal of each polygon as one byte).

Parameters
index0 to JO_3D_MORPH_NORMALS - 1 (directions spread evenly on the sphere: a golden angle spiral, the same as jo_model.py)
normalUnit vector (16.16 fixed)

◆ jo_3d_pose_blend()

void jo_3d_pose_blend ( const jo_3d_model *const model,
jo_3d_pose *const pose,
const jo_3d_pose *const other,
const int weight )

Blend 2 poses (a smooth change of animation).

Parameters
modelModel
poseFirst pose, the result
otherSecond pose
weightWeight of the second pose (0 to 256)

◆ jo_3d_set_neutral_gouraud_skipped()

void jo_3d_set_neutral_gouraud_skipped ( const bool skipped)

The next models created or loaded draw without gouraud only the polygons whose 4 gouraud colors leave the texels as they are (16, 16, 16 each): the same picture (see jo_3d_set_uniform_gouraud_skipped(), on by default, that does it too).

Parameters
skippedtrue: only those polygons without gouraud; false: all the polygons keep their gouraud table
Remarks
Not for a model whose tables the game writes again (a light, a tint): those polygons have no table any more. Not with jo_3d_set_unique_gouraud_tables()

◆ jo_3d_set_uniform_gouraud_skipped()

void jo_3d_set_uniform_gouraud_skipped ( const bool skipped)

The next models created or loaded draw without gouraud the polygons whose 4 gouraud colors are the same (a flat light), the light put in their color: the same picture, the VDP1 draws them faster (default: on).

Parameters
skippedtrue: those polygons without gouraud (the neutral ones too, see jo_3d_set_neutral_gouraud_skipped()); false: all the polygons keep their gouraud table (the models that the game tints or lights by their tables, see below). Both: the copies of the color lookup tables made until then are not shared with the next models any more
Remarks
An untextured polygon: its RGB color + the light. A texture of 16 colors (color lookup table): a copy of the table with the light (32 bytes of the VRAM with the gouraud tables of the model, shared by the next models until sprites are freed or until this function is called). The other textures (RGB, palette) and the lit polygons (JO_3D_MATERIAL_LIGHT) keep their gouraud, the models of the entities (a tint) and of the cells (the point lights) too
Load between jo_3d_set_uniform_gouraud_skipped(false) and (true) a model that the game tints (jo_3d_set_tint()), adds to the point lights (jo_3d_point_lights_add_mesh()), whose gouraud tables or polygon colors it writes again: the polygons without gouraud would not get the tint or the light, a color changed would lose the light put in it. Not with jo_3d_set_unique_gouraud_tables() (those models keep all their tables)

◆ jo_3d_set_unique_gouraud_tables()

void jo_3d_set_unique_gouraud_tables ( const bool unique)

The next models created or loaded get a gouraud table per polygon, in the order of the polygons (default: the polygons with the same 4 colors share a table): for a model whose tables the game writes again polygon by polygon (the light on a car).

Parameters
uniquetrue: a table per polygon
Remarks
Shared, the tables of a model are fewer than its polygons: a game that wrote a table per polygon from the first one wrote over the tables (and the color lookup tables of the textures) that follow them in the VRAM

◆ jo_3d_slave_model_draw_morph()

bool jo_3d_slave_model_draw_morph ( const jo_3d_model *const model,
const int morph,
const int time )

jo_3d_model_draw_morph() on the slave CPU (call it on the slave CPU: its own buffer, the master CPU can draw the same model at the same time)

Parameters
modelModel
morphIndex of the vertex animation
timeTicks (1/60 s) from the start of the animation
Returns
false if the slave CPU can't draw more commands in this frame (see jo_3d_slave_mesh_draw())
Remarks
The tint of the slave CPU (jo_3d_slave_set_tint()) is not applied (its copies of the gouraud tables are the ones the master CPU prepared for the meshes it drew)

◆ jo_3d_slave_model_draw_pose()

void jo_3d_slave_model_draw_pose ( const jo_3d_model *const model,
const jo_3d_pose *const pose,
const jo_3d_bone_callback callback,
void *const param,
const unsigned int hidden_bones )

Draw a model with a skeleton in a pose on the slave CPU (call it on the slave CPU, see jo_3d_model_draw_pose()).

Parameters
modelModel
posePose (JO_NULL: the pose of the OBJ)
callbackCalled after each bone (JO_NULL: none; on the slave CPU: what it writes is read by the master CPU without its cache)
paramParameter of the callback
hidden_bonesBones not drawn (bits, see jo_3d_model_set_hidden_bones())
Remarks
The tint of the slave CPU (see jo_3d_slave_set_tint())