Jo Engine 2026.11.6
Jo Sega Saturn Engine
Loading...
Searching...
No Matches
model.h
Go to the documentation of this file.
1/*
2** Jo Sega Saturn Engine
3** Copyright (c) 2012-2026, Johannes Fetz (johannesfetz@gmail.com)
4** All rights reserved.
5**
6** Redistribution and use in source and binary forms, with or without
7** modification, are permitted provided that the following conditions are met:
8** * Redistributions of source code must retain the above copyright
9** notice, this list of conditions and the following disclaimer.
10** * Redistributions in binary form must reproduce the above copyright
11** notice, this list of conditions and the following disclaimer in the
12** documentation and/or other materials provided with the distribution.
13** * Neither the name of the Johannes Fetz nor the
14** names of its contributors may be used to endorse or promote products
15** derived from this software without specific prior written permission.
16**
17** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
18** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19** WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20** DISCLAIMED. IN NO EVENT SHALL Johannes Fetz BE LIABLE FOR ANY
21** DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22** (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23** LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24** ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26** SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27*/
89
90#ifndef __JO_MODEL_H__
91# define __JO_MODEL_H__
92
93#ifdef JO_COMPILE_WITH_3D_SUPPORT
94
96# define JO_3D_MODEL_VERSION (1)
97
98/*
99** Material flags (jo_3d_material.flags, low 16 bits: the engine, high 16 bits: free for the program, see jo_model.py)
100*/
102# define JO_3D_MATERIAL_DUAL_PLANE (1 << 0)
104# define JO_3D_MATERIAL_SORT_MIN (1 << 1)
106# define JO_3D_MATERIAL_SORT_MAX (1 << 2)
109# define JO_3D_MATERIAL_SORT_PREVIOUS (JO_3D_MATERIAL_SORT_MIN | JO_3D_MATERIAL_SORT_MAX)
111# define JO_3D_MATERIAL_GOURAUD (1 << 3)
113# define JO_3D_MATERIAL_HALF_TRANSPARENT (1 << 4)
115# define JO_3D_MATERIAL_SCREEN_DOORS (1 << 5)
117# define JO_3D_MATERIAL_LIGHT (1 << 6)
119# define JO_3D_MATERIAL_FLIP_H (1 << 7)
121# define JO_3D_MATERIAL_FLIP_V (1 << 8)
123# define JO_3D_MATERIAL_END_CODES (1 << 9)
125# define JO_3D_MATERIAL_MIPMAPS (1 << 10)
127# define JO_3D_MATERIAL_SUBDIVISION (1 << 11)
130# define JO_3D_MATERIAL_SUBDIVISION_NEAR (1 << 12)
133# define JO_3D_MATERIAL_HIGH_SPEED_SHRINK (1 << 13)
135# define JO_3D_MATERIAL_USER(N) (1 << (16 + (N)))
136
138typedef struct
139{
140 char name[16]; // MTL newmtl (truncated, ended by a zero)
141 unsigned char r; // Color (MTL Kd): the polygons without texture
142 unsigned char g;
143 unsigned char b;
144 unsigned char shine; // MTL Ns (0 to 255, for the program)
145 short texture; // Index in the textures of the model, -1: no texture
146 unsigned short subdivision_error; // MTL jo_subdivision_error (pixels, see
147 // jo_3d_set_texture_subdivision_error()), 0: the default
148 unsigned int flags; // JO_3D_MATERIAL_xxx
149 unsigned int user; // MTL jo_value (for the program)
151
153typedef struct
154{
155 char name[16];
156 unsigned short first_point;
157 unsigned short point_count; // The points used only by the group (from first_point)
158 unsigned short first_polygon;
159 unsigned short polygon_count;
161
163# define JO_3D_MAX_BONES (32)
165# define JO_3D_BONE_NO_GROUP (0xFFFF)
167# define JO_3D_ANIMATION_LOOP (1 << 0)
169# define JO_3D_ANIMATION_TICKS_PER_SECOND (60)
170
172typedef struct
173{
174 char name[16];
175 unsigned short group; // Group moved by the bone (JO_3D_BONE_NO_GROUP: none)
176 short parent; // Index of the parent bone, -1: root
177 jo_pos3D_fixed pivot; // Joint (model space): the bone turns around it
178} jo_3d_bone;
179
181typedef struct
182{
183 char name[16];
184 unsigned short key_count;
185 unsigned short key_ticks; // Time between 2 keys (1/60 s)
186 unsigned short flags; // JO_3D_ANIMATION_xxx
187 unsigned short duplicate; // 0 in the file. Set at the loading: 1 when an animation before
188 // has the same name (see jo_3d_model_is_animation())
189 unsigned int offset; // Keys: offset from the count of the "ANIM" chunk
191
193# define JO_3D_MORPH_LOOP (1 << 0)
195# define JO_3D_MORPH_NORMALS (256)
196
199typedef struct
200{
201 char name[16];
202 unsigned short frame_count;
203 unsigned short frame_ticks; // Time between 2 frames (1/60 s)
204 unsigned short flags; // JO_3D_MORPH_xxx
205 unsigned short duplicate; // 0 in the file. Set at the loading: 1 when a vertex animation
206 // before has the same name
207 unsigned int offset; // Frames: offset from the count of the "MRPH" chunk
209
211# define JO_3D_SKIN_ONE (32768)
212
215typedef struct
216{
217 unsigned short point; // Index of the point
218 unsigned char bone; // The bone of its group (the bone that draws it)
219 unsigned char other; // The other bone (its parent or a child)
220 unsigned short weight; // Weight of the other bone (JO_3D_SKIN_ONE: 1.0)
221 unsigned short reserved; // 0
223
225typedef struct
226{
227 jo_pos3D_fixed root; // Offset of the whole model
228 jo_angle angles[JO_3D_MAX_BONES][3]; // Around X, Y, Z (0x10000 = 360 degrees)
229} jo_3d_pose;
230
238typedef void (*jo_3d_bone_callback)(const int bone, void * const param, const jo_fixed (* const matrix)[3]);
239
241typedef struct
242{
243 jo_3d_mesh *mesh; // Drawn with jo_3d_mesh_draw()
244 jo_pos3D_fixed center; // Bounding sphere (see jo_3d_is_sphere_visible())
246 unsigned int material_count;
248 unsigned short *polygon_materials; // Material of each polygon
249 unsigned int texture_count;
250 int *textures; // Sprite ids
251 unsigned int normal_count; // 0: no normals
253 unsigned short *corner_normals; // 4 per polygon: index in normals (JO_NULL: none)
254 jo_pos3D_fixed *vertex_colors; // r, g, b per point, 1.0 = JO_FIXED_1 (JO_NULL: none)
255 unsigned short gouraud_tables; // First gouraud table (polygon k: + k), 0: none
256 unsigned short gouraud_table_count;
257 unsigned int group_count;
259 unsigned int bone_count; // 0: no skeleton
261 signed char *bone_children; // First child of each bone, then the next sibling of
262 // each bone (-1: none)
263 unsigned int animation_count;
265 const unsigned char *animation_data; // The "ANIM" chunk from its count
266 unsigned int morph_count; // Vertex animations (0: none)
268 const unsigned char *morph_data; // The "MRPH" chunk from its count
269 unsigned int morph_frame_size; // Bytes of a frame
270 unsigned short morph_shift; // A value of a frame x 2^shift: 16.16 fixed
271 bool morph_normals; // The frames have the normals of the polygons
272 jo_3d_polygon_data *morph_draw[2]; // What jo_3d_model_draw_morph() draws, for the master CPU
273 // and the slave CPU (one block each: the points
274 // interpolated; the polygons with the normals of the frame
275 // if some are lit, else the ones of the model; the
276 // attributes of the model), and jo_3d_model_draw_pose()
277 // with a skin (its points moved by 2 bones)
278 unsigned int skin_count; // Points that follow 2 bones (0: a rigid skeleton)
280 void *file; // Data of the file (jo_3d_load_model(): the points, the
281 // polygons, etc are in it), JO_NULL: copies
282 bool file_not_owned; // The data of the file belong to the caller
283 // (jo_3d_create_model_in_place()): not freed with the model
284 bool single_block; // The model, its mesh, the attributes and the texture ids
285 // in one memory block (jo_3d_create_model_in_place())
286 void *fast_block; // Copy of the points, the polygons, the bones and the
287 // groups in the high work RAM (see
288 // jo_3d_model_use_fast_memory()), JO_NULL: none
290
298jo_3d_model *jo_3d_create_model_from_memory(const unsigned char * const data, const unsigned int size);
299
308jo_3d_model *jo_3d_create_model_in_place(const unsigned char * const data, const unsigned int size);
309
318const unsigned char *jo_3d_model_find_chunk(const void * const data, const char * const tag, unsigned int * const size);
319
325const unsigned short *jo_3d_model_file_gouraud_colors(const void * const data, const unsigned int polygon_count);
326
332static __jo_force_inline const unsigned short *jo_3d_model_gouraud_colors(const jo_3d_model * const model)
333{
334 if (model == JO_NULL || model->gouraud_tables == 0 || model->file == JO_NULL)
335 return (JO_NULL);
337}
338
349bool jo_3d_model_set_environment(jo_3d_model * const model, const int sprite_id, const int tiles,
350 const unsigned int material_flags);
351
352#ifdef JO_COMPILE_WITH_FS_SUPPORT
353
355# define JO_3D_MODEL_POOL_MAX_BLOCKS (256)
356
362typedef struct
363{
364 unsigned char *block; // Free place in the current block
365 unsigned int left; // Bytes left in it
366 unsigned int bytes_left; // Bytes of the models not read yet (a block no bigger than
367 // them), 0: unknown
368 unsigned int block_size;
372
379void jo_3d_model_pool_init(jo_3d_model_pool * const pool, const unsigned int block_size,
380 const unsigned int bytes);
381
392jo_3d_model *jo_3d_model_pool_read(jo_3d_model_pool * const pool, jo_file * const file, const unsigned int size);
393
398
407jo_3d_model *jo_3d_load_model(const char * const filename);
408
416void jo_3d_set_unique_gouraud_tables(const bool unique);
417
425void jo_3d_set_neutral_gouraud_skipped(const bool skipped);
426
442void jo_3d_set_uniform_gouraud_skipped(const bool skipped);
443
450int jo_3d_model_texture(const char * const filename);
451
457int jo_3d_model_loaded_texture(const char * const name);
458
459#endif
460
464void jo_3d_free_model(jo_3d_model * const model);
465
472void jo_3d_model_free_textures_from(const int sprite_id);
473
479const jo_3d_model_group *jo_3d_model_find_group(const jo_3d_model * const model, const char * const name);
480
486int jo_3d_model_find_bone(const jo_3d_model * const model, const char * const name);
487
493int jo_3d_model_find_animation(const jo_3d_model * const model, const char * const name);
494
502bool jo_3d_model_is_animation(const jo_3d_model * const model, const int animation, const char * const name);
503
509int jo_3d_model_animation_duration(const jo_3d_model * const model, const int animation);
510
517void jo_3d_model_get_pose(const jo_3d_model * const model, const int animation, int time,
518 jo_3d_pose * const pose);
519
526void jo_3d_pose_blend(const jo_3d_model * const model, jo_3d_pose * const pose,
527 const jo_3d_pose * const other, const int weight);
528
538void jo_3d_model_draw_pose(const jo_3d_model * const model, const jo_3d_pose * const pose,
539 const jo_3d_bone_callback callback, void * const param);
540
550void jo_3d_slave_model_draw_pose(const jo_3d_model * const model, const jo_3d_pose * const pose,
551 const jo_3d_bone_callback callback, void * const param,
552 const unsigned int hidden_bones);
553
558void jo_3d_model_set_hidden_bones(const unsigned int mask);
559
565int jo_3d_model_find_morph(const jo_3d_model * const model, const char * const name);
566
572int jo_3d_model_morph_duration(const jo_3d_model * const model, const int morph);
573
586void jo_3d_model_draw_morph(const jo_3d_model * const model, const int morph, const int time);
587
597bool jo_3d_slave_model_draw_morph(const jo_3d_model * const model, const int morph, const int time);
598
604void jo_3d_morph_normal(const int index, jo_pos3D_fixed * const normal);
605
621
626static __jo_force_inline void jo_3d_model_draw(const jo_3d_model * const model)
627{
628#ifdef JO_DEBUG
629 if (model == JO_NULL)
630 {
631 jo_core_error("model is null");
632 return;
633 }
634#endif
635 if (model->bone_count > 0)
637 else
638 jo_3d_mesh_draw(model->mesh);
639}
640
641#endif /* !JO_COMPILE_WITH_3D_SUPPORT */
642
643#endif /* !__JO_MODEL_H__ */
644
645/*
646** END OF FILE
647*/
jo_3d_polygon_data data
Definition 3d.h:249
static __jo_force_inline void jo_3d_mesh_draw(jo_3d_mesh *const mesh)
Draw a mesh.
Definition 3d.h:1181
unsigned int polygon_count
Definition 3d.h:181
Mesh structure.
Definition 3d.h:248
Polygon data (3D model).
Definition 3d.h:177
#define jo_core_error(...)
Definition core.h:47
void * data
Definition entity.h:19
const char * name
Definition entity.h:9
unsigned int skin_count
Definition model.h:278
unsigned int normal_count
Definition model.h:251
jo_3d_model_group * groups
Definition model.h:258
short parent
Definition model.h:176
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...
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_...
bool morph_normals
Definition model.h:271
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 (defa...
char name[16]
Definition model.h:183
const unsigned char * morph_data
Definition model.h:268
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 lig...
Definition model.h:332
unsigned char other
Definition model.h:219
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 ...
Definition model.h:238
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 p...
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 small...
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 sa...
jo_pos3D_fixed pivot
Definition model.h:177
jo_3d_mesh * mesh
Definition model.h:243
unsigned int offset
Definition model.h:207
unsigned short subdivision_error
Definition model.h:146
jo_pos3D_fixed center
Definition model.h:244
int jo_3d_model_find_morph(const jo_3d_model *const model, const char *const name)
Find a vertex animation of a model.
char name[16]
Definition model.h:155
unsigned int texture_count
Definition model.h:249
jo_pos3D_fixed * normals
Definition model.h:252
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.
unsigned char g
Definition model.h:142
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 t...
bool single_block
Definition model.h:284
unsigned short * polygon_materials
Definition model.h:248
unsigned short duplicate
Definition model.h:205
void jo_3d_free_model(jo_3d_model *const model)
Free a model (the textures stay loaded).
unsigned int left
Definition model.h:365
unsigned int bone_count
Definition model.h:259
unsigned short gouraud_tables
Definition model.h:255
char name[16]
Definition model.h:140
unsigned int group_count
Definition model.h:257
unsigned short flags
Definition model.h:204
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...
jo_3d_bone * bones
Definition model.h:260
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,...
jo_3d_polygon_data * morph_draw[2]
Definition model.h:272
unsigned short key_ticks
Definition model.h:185
int jo_3d_model_find_bone(const jo_3d_model *const model, const char *const name)
Find a bone of a model.
unsigned short first_polygon
Definition model.h:158
jo_angle angles[(32)][3]
Definition model.h:228
unsigned int animation_count
Definition model.h:263
jo_3d_animation * animations
Definition model.h:264
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,...
unsigned short group
Definition model.h:175
jo_pos3D_fixed root
Definition model.h:227
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.
unsigned int offset
Definition model.h:189
unsigned short point
Definition model.h:217
jo_fixed radius
Definition model.h:245
signed char * bone_children
Definition model.h:261
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,...
void * file
Definition model.h:280
unsigned int block_size
Definition model.h:368
jo_3d_morph * morphs
Definition model.h:267
static __jo_force_inline void jo_3d_model_draw(const jo_3d_model *const model)
Draw a model with the current matrix.
Definition model.h:626
unsigned char * block
Definition model.h:364
char name[16]
Definition model.h:174
unsigned short first_point
Definition model.h:156
unsigned short reserved
Definition model.h:221
const unsigned char * animation_data
Definition model.h:265
unsigned int flags
Definition model.h:148
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 ca...
const jo_3d_skin_point * skin
Definition model.h:279
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).
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...
#define JO_3D_MODEL_POOL_MAX_BLOCKS
Maximum of memory blocks of a pool of models.
Definition model.h:355
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).
#define JO_3D_MAX_BONES
Bones of a model at most (jo_3d_pose).
Definition model.h:163
jo_3d_material * materials
Definition model.h:247
unsigned short duplicate
Definition model.h:187
unsigned int morph_frame_size
Definition model.h:269
unsigned char bone
Definition model.h:218
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 mode...
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...
char name[16]
Definition model.h:201
unsigned char r
Definition model.h:141
int jo_3d_model_morph_duration(const jo_3d_model *const model, const int morph)
Duration of a vertex animation.
jo_3d_model * jo_3d_load_model(const char *const filename)
Load a model (JOM file) from the current directory of the CD.
int jo_3d_model_find_animation(const jo_3d_model *const model, const char *const name)
Find an animation of a model.
unsigned char * blocks[(256)]
Definition model.h:370
unsigned char b
Definition model.h:143
unsigned short polygon_count
Definition model.h:159
bool file_not_owned
Definition model.h:282
unsigned int bytes_left
Definition model.h:366
unsigned short frame_count
Definition model.h:202
unsigned short morph_shift
Definition model.h:270
int * textures
Definition model.h:250
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...
void * fast_block
Definition model.h:286
unsigned short gouraud_table_count
Definition model.h:256
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.
unsigned short * corner_normals
Definition model.h:253
unsigned short frame_ticks
Definition model.h:203
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,...
short texture
Definition model.h:145
unsigned short key_count
Definition model.h:184
int jo_3d_model_animation_duration(const jo_3d_model *const model, const int animation)
Duration of an animation.
unsigned int material_count
Definition model.h:246
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).
unsigned char shine
Definition model.h:144
unsigned short point_count
Definition model.h:157
jo_pos3D_fixed * vertex_colors
Definition model.h:254
int block_count
Definition model.h:369
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()).
unsigned int morph_count
Definition model.h:266
unsigned int user
Definition model.h:149
unsigned short flags
Definition model.h:186
unsigned short weight
Definition model.h:220
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
3D model loaded from a JOM file
Definition model.h:242
Group of a model: OBJ o or g (the same layout as the file: 24 bytes).
Definition model.h:154
Models read one after the other from a file (the parts of a level) into big memory blocks,...
Definition model.h:363
Vertex animation (morph targets: the position of each point at each frame, the same layout as the fil...
Definition model.h:200
Pose of a skeleton: the angles of the bones (see jo_3d_model_get_pose() and jo_3d_model_draw_pose()).
Definition model.h:226
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
#define JO_NULL
NULL implementation.
Definition tools.h:261
#define __jo_force_inline
force inline attribute (and prevent Doxygen prototype parsing bug)
Definition types.h:39
short jo_angle
Angle.
Definition types.h:65
int jo_fixed
Fixed point Q16.16 number.
Definition types.h:59
File definition.
Definition types.h:311
3D position using fixed numbers
Definition types.h:103