2 goat3d - 3D scene, and animation file format library.
3 Copyright (C) 2013-2023 John Tsiombikas <nuclear@member.fsf.org>
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU Lesser General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
25 #define GOAT3DAPI __declspec(dllexport)
28 #define GOAT3DAPI __attribute__((visibility("default")))
34 #define GOAT3D_MAT_ATTR_DIFFUSE "diffuse"
35 #define GOAT3D_MAT_ATTR_SPECULAR "specular"
36 #define GOAT3D_MAT_ATTR_SHININESS "shininess"
37 #define GOAT3D_MAT_ATTR_NORMAL "normal"
38 #define GOAT3D_MAT_ATTR_BUMP "bump"
39 #define GOAT3D_MAT_ATTR_REFLECTION "reflection"
40 #define GOAT3D_MAT_ATTR_TRANSMISSION "transmission"
41 #define GOAT3D_MAT_ATTR_IOR "ior"
42 #define GOAT3D_MAT_ATTR_ALPHA "alpha"
44 enum goat3d_mesh_attrib {
45 GOAT3D_MESH_ATTR_VERTEX,
46 GOAT3D_MESH_ATTR_NORMAL,
47 GOAT3D_MESH_ATTR_TANGENT,
48 GOAT3D_MESH_ATTR_TEXCOORD,
49 GOAT3D_MESH_ATTR_SKIN_WEIGHT,
50 GOAT3D_MESH_ATTR_SKIN_MATRIX,
51 GOAT3D_MESH_ATTR_COLOR,
53 NUM_GOAT3D_MESH_ATTRIBS
56 enum goat3d_node_type {
63 /* immediate mode mesh construction primitive type */
64 enum goat3d_im_primitive {
69 enum goat3d_track_type {
74 GOAT3D_TRACK_POS = GOAT3D_TRACK_VEC3 | 0x100,
75 GOAT3D_TRACK_ROT = GOAT3D_TRACK_QUAT | 0x200,
76 GOAT3D_TRACK_SCALE = GOAT3D_TRACK_VEC3 | 0x300
84 /* track interpolation modes */
90 /* track extrapolation modes */
95 GOAT3D_EXTRAP_PINGPONG
99 GOAT3D_OPT_SAVEXML, /* save in XML format (dropped) */
100 GOAT3D_OPT_SAVETEXT, /* save in text format */
101 GOAT3D_OPT_SAVEBINDATA, /* save mesh data in text files as binary blobs */
102 GOAT3D_OPT_SAVEBIN, /* not implemented yet */
103 GOAT3D_OPT_SAVEGLTF, /* not implemented yet */
104 GOAT3D_OPT_SAVEGLB, /* not implemented yet */
110 struct goat3d_material;
111 struct goat3d_mtlattr;
114 struct goat3d_camera;
120 void *cls; /* closure data */
122 long (*read)(void *buf, size_t bytes, void *uptr);
123 long (*write)(const void *buf, size_t bytes, void *uptr);
124 long (*seek)(long offs, int whence, void *uptr);
131 /* construction/destruction */
132 GOAT3DAPI struct goat3d *goat3d_create(void);
133 GOAT3DAPI void goat3d_free(struct goat3d *g);
135 GOAT3DAPI void goat3d_setopt(struct goat3d *g, enum goat3d_option opt, int val);
136 GOAT3DAPI int goat3d_getopt(const struct goat3d *g, enum goat3d_option opt);
139 GOAT3DAPI int goat3d_load(struct goat3d *g, const char *fname);
140 GOAT3DAPI int goat3d_save(const struct goat3d *g, const char *fname);
142 GOAT3DAPI int goat3d_load_file(struct goat3d *g, FILE *fp);
143 GOAT3DAPI int goat3d_save_file(const struct goat3d *g, FILE *fp);
145 GOAT3DAPI int goat3d_load_io(struct goat3d *g, struct goat3d_io *io);
146 GOAT3DAPI int goat3d_save_io(const struct goat3d *g, struct goat3d_io *io);
148 /* load/save animation files (g must already be loaded to load animations) */
149 GOAT3DAPI int goat3d_load_anim(struct goat3d *g, const char *fname);
150 GOAT3DAPI int goat3d_save_anim(const struct goat3d *g, const char *fname);
152 GOAT3DAPI int goat3d_load_anim_file(struct goat3d *g, FILE *fp);
153 GOAT3DAPI int goat3d_save_anim_file(const struct goat3d *g, FILE *fp);
155 GOAT3DAPI int goat3d_load_anim_io(struct goat3d *g, struct goat3d_io *io);
156 GOAT3DAPI int goat3d_save_anim_io(const struct goat3d *g, struct goat3d_io *io);
158 /* misc scene properties */
159 GOAT3DAPI int goat3d_set_name(struct goat3d *g, const char *name);
160 GOAT3DAPI const char *goat3d_get_name(const struct goat3d *g);
162 GOAT3DAPI void goat3d_set_ambient(struct goat3d *g, const float *ambient);
163 GOAT3DAPI void goat3d_set_ambient3f(struct goat3d *g, float ar, float ag, float ab);
164 GOAT3DAPI const float *goat3d_get_ambient(const struct goat3d *g);
166 GOAT3DAPI int goat3d_get_bounds(const struct goat3d *g, float *bmin, float *bmax);
169 GOAT3DAPI int goat3d_add_mtl(struct goat3d *g, struct goat3d_material *mtl);
170 GOAT3DAPI int goat3d_get_mtl_count(struct goat3d *g);
171 GOAT3DAPI struct goat3d_material *goat3d_get_mtl(struct goat3d *g, int idx);
172 GOAT3DAPI struct goat3d_material *goat3d_get_mtl_by_name(struct goat3d *g, const char *name);
174 GOAT3DAPI struct goat3d_material *goat3d_create_mtl(void);
175 GOAT3DAPI void goat3d_destroy_mtl(struct goat3d_material *mtl);
177 GOAT3DAPI int goat3d_set_mtl_name(struct goat3d_material *mtl, const char *name);
178 GOAT3DAPI const char *goat3d_get_mtl_name(const struct goat3d_material *mtl);
180 GOAT3DAPI int goat3d_set_mtl_attrib(struct goat3d_material *mtl, const char *attrib, const float *val);
181 GOAT3DAPI int goat3d_set_mtl_attrib1f(struct goat3d_material *mtl, const char *attrib, float val);
182 GOAT3DAPI int goat3d_set_mtl_attrib3f(struct goat3d_material *mtl, const char *attrib, float r, float g, float b);
183 GOAT3DAPI int goat3d_set_mtl_attrib4f(struct goat3d_material *mtl, const char *attrib, float r, float g, float b, float a);
184 GOAT3DAPI const float *goat3d_get_mtl_attrib(struct goat3d_material *mtl, const char *attrib);
186 GOAT3DAPI int goat3d_set_mtl_attrib_map(struct goat3d_material *mtl, const char *attrib, const char *mapname);
187 GOAT3DAPI const char *goat3d_get_mtl_attrib_map(struct goat3d_material *mtl, const char *attrib);
189 GOAT3DAPI int goat3d_get_mtl_attrib_count(struct goat3d_material *mtl);
190 GOAT3DAPI const char *goat3d_get_mtl_attrib_name(struct goat3d_material *mtl, int idx);
194 GOAT3DAPI int goat3d_add_mesh(struct goat3d *g, struct goat3d_mesh *mesh);
195 GOAT3DAPI int goat3d_get_mesh_count(struct goat3d *g);
196 GOAT3DAPI struct goat3d_mesh *goat3d_get_mesh(struct goat3d *g, int idx);
197 GOAT3DAPI struct goat3d_mesh *goat3d_get_mesh_by_name(struct goat3d *g, const char *name);
199 GOAT3DAPI struct goat3d_mesh *goat3d_create_mesh(void);
200 GOAT3DAPI void goat3d_destroy_mesh(struct goat3d_mesh *mesh);
202 GOAT3DAPI int goat3d_set_mesh_name(struct goat3d_mesh *mesh, const char *name);
203 GOAT3DAPI const char *goat3d_get_mesh_name(const struct goat3d_mesh *mesh);
205 GOAT3DAPI void goat3d_set_mesh_mtl(struct goat3d_mesh *mesh, struct goat3d_material *mtl);
206 GOAT3DAPI struct goat3d_material *goat3d_get_mesh_mtl(struct goat3d_mesh *mesh);
208 GOAT3DAPI int goat3d_get_mesh_vertex_count(struct goat3d_mesh *mesh);
209 GOAT3DAPI int goat3d_get_mesh_attrib_count(struct goat3d_mesh *mesh, enum goat3d_mesh_attrib attrib);
210 GOAT3DAPI int goat3d_get_mesh_face_count(struct goat3d_mesh *mesh);
212 /* sets all the data for a single vertex attribute array in one go.
213 * vnum is the number of *vertices* to be set, not the number of floats, ints or whatever
214 * data is expected to be something different depending on the attribute:
215 * - GOAT3D_MESH_ATTR_VERTEX - 3 floats per vertex
216 * - GOAT3D_MESH_ATTR_NORMAL - 3 floats per vertex
217 * - GOAT3D_MESH_ATTR_TANGENT - 3 floats per vertex
218 * - GOAT3D_MESH_ATTR_TEXCOORD - 2 floats per vertex
219 * - GOAT3D_MESH_ATTR_SKIN_WEIGHT - 4 floats per vertex
220 * - GOAT3D_MESH_ATTR_SKIN_MATRIX - 4 ints per vertex
221 * - GOAT3D_MESH_ATTR_COLOR - 4 floats per vertex
223 GOAT3DAPI int goat3d_set_mesh_attribs(struct goat3d_mesh *mesh, enum goat3d_mesh_attrib attrib,
224 const void *data, int vnum);
225 GOAT3DAPI int goat3d_add_mesh_attrib1f(struct goat3d_mesh *mesh, enum goat3d_mesh_attrib attrib, float val);
226 GOAT3DAPI int goat3d_add_mesh_attrib2f(struct goat3d_mesh *mesh, enum goat3d_mesh_attrib attrib,
228 GOAT3DAPI int goat3d_add_mesh_attrib3f(struct goat3d_mesh *mesh, enum goat3d_mesh_attrib attrib,
229 float x, float y, float z);
230 GOAT3DAPI int goat3d_add_mesh_attrib4f(struct goat3d_mesh *mesh, enum goat3d_mesh_attrib attrib,
231 float x, float y, float z, float w);
232 /* returns a pointer to the beginning of the requested mesh attribute array */
233 GOAT3DAPI void *goat3d_get_mesh_attribs(struct goat3d_mesh *mesh, enum goat3d_mesh_attrib attrib);
234 /* returns a pointer to the requested mesh attribute */
235 GOAT3DAPI void *goat3d_get_mesh_attrib(struct goat3d_mesh *mesh, enum goat3d_mesh_attrib attrib, int idx);
237 /* sets all the faces in one go. data is an array of 3 int vertex indices per face */
238 GOAT3DAPI int goat3d_set_mesh_faces(struct goat3d_mesh *mesh, const int *data, int fnum);
239 GOAT3DAPI int goat3d_add_mesh_face(struct goat3d_mesh *mesh, int a, int b, int c);
240 /* returns a pointer to the beginning of the face index array */
241 GOAT3DAPI int *goat3d_get_mesh_faces(struct goat3d_mesh *mesh);
242 /* returns a pointer to a face index */
243 GOAT3DAPI int *goat3d_get_mesh_face(struct goat3d_mesh *mesh, int idx);
245 /* immediate mode OpenGL-like interface for setting mesh data
246 * NOTE: using this interface will result in no vertex sharing between faces
247 * NOTE2: the immedate mode interface is not thread-safe, either use locks, or don't
248 * use it at all in multithreaded situations.
250 GOAT3DAPI void goat3d_begin(struct goat3d_mesh *mesh, enum goat3d_im_primitive prim);
251 GOAT3DAPI void goat3d_end(void);
252 GOAT3DAPI void goat3d_vertex3f(float x, float y, float z);
253 GOAT3DAPI void goat3d_normal3f(float x, float y, float z);
254 GOAT3DAPI void goat3d_tangent3f(float x, float y, float z);
255 GOAT3DAPI void goat3d_texcoord2f(float x, float y);
256 GOAT3DAPI void goat3d_skin_weight4f(float x, float y, float z, float w);
257 GOAT3DAPI void goat3d_skin_matrix4i(int x, int y, int z, int w);
258 GOAT3DAPI void goat3d_color3f(float x, float y, float z);
259 GOAT3DAPI void goat3d_color4f(float x, float y, float z, float w);
261 GOAT3DAPI void goat3d_get_mesh_bounds(const struct goat3d_mesh *mesh, float *bmin, float *bmax);
264 GOAT3DAPI int goat3d_add_light(struct goat3d *g, struct goat3d_light *lt);
265 GOAT3DAPI int goat3d_get_light_count(struct goat3d *g);
266 GOAT3DAPI struct goat3d_light *goat3d_get_light(struct goat3d *g, int idx);
267 GOAT3DAPI struct goat3d_light *goat3d_get_light_by_name(struct goat3d *g, const char *name);
269 GOAT3DAPI struct goat3d_light *goat3d_create_light(void);
270 GOAT3DAPI void goat3d_destroy_light(struct goat3d_light *lt);
272 GOAT3DAPI int goat3d_set_light_name(struct goat3d_light *lt, const char *name);
273 GOAT3DAPI const char *goat3d_get_light_name(const struct goat3d_light *lt);
276 GOAT3DAPI int goat3d_add_camera(struct goat3d *g, struct goat3d_camera *cam);
277 GOAT3DAPI int goat3d_get_camera_count(struct goat3d *g);
278 GOAT3DAPI struct goat3d_camera *goat3d_get_camera(struct goat3d *g, int idx);
279 GOAT3DAPI struct goat3d_camera *goat3d_get_camera_by_name(struct goat3d *g, const char *name);
281 GOAT3DAPI struct goat3d_camera *goat3d_create_camera(void);
282 GOAT3DAPI void goat3d_destroy_camera(struct goat3d_camera *cam);
284 GOAT3DAPI int goat3d_set_camera_name(struct goat3d_camera *cam, const char *name);
285 GOAT3DAPI const char *goat3d_get_camera_name(const struct goat3d_camera *cam);
288 GOAT3DAPI int goat3d_add_node(struct goat3d *g, struct goat3d_node *node);
289 GOAT3DAPI int goat3d_get_node_count(struct goat3d *g);
290 GOAT3DAPI struct goat3d_node *goat3d_get_node(struct goat3d *g, int idx);
291 GOAT3DAPI struct goat3d_node *goat3d_get_node_by_name(struct goat3d *g, const char *name);
293 GOAT3DAPI struct goat3d_node *goat3d_create_node(void);
294 GOAT3DAPI void goat3d_destroy_node(struct goat3d_node *node);
296 GOAT3DAPI int goat3d_set_node_name(struct goat3d_node *node, const char *name);
297 GOAT3DAPI const char *goat3d_get_node_name(const struct goat3d_node *node);
299 GOAT3DAPI void goat3d_set_node_object(struct goat3d_node *node, enum goat3d_node_type type, void *obj);
300 GOAT3DAPI void *goat3d_get_node_object(const struct goat3d_node *node);
301 GOAT3DAPI enum goat3d_node_type goat3d_get_node_type(const struct goat3d_node *node);
303 GOAT3DAPI void goat3d_add_node_child(struct goat3d_node *node, struct goat3d_node *child);
304 GOAT3DAPI int goat3d_get_node_child_count(const struct goat3d_node *node);
305 GOAT3DAPI struct goat3d_node *goat3d_get_node_child(const struct goat3d_node *node, int idx);
306 GOAT3DAPI struct goat3d_node *goat3d_get_node_parent(const struct goat3d_node *node);
308 GOAT3DAPI void goat3d_set_node_position(struct goat3d_node *node, float x, float y, float z);
309 GOAT3DAPI void goat3d_set_node_rotation(struct goat3d_node *node, float qx, float qy, float qz, float qw);
310 GOAT3DAPI void goat3d_set_node_scaling(struct goat3d_node *node, float sx, float sy, float sz);
312 GOAT3DAPI void goat3d_get_node_position(const struct goat3d_node *node, float *xptr, float *yptr, float *zptr);
313 GOAT3DAPI void goat3d_get_node_rotation(const struct goat3d_node *node, float *xptr, float *yptr, float *zptr, float *wptr);
314 GOAT3DAPI void goat3d_get_node_scaling(const struct goat3d_node *node, float *xptr, float *yptr, float *zptr);
316 GOAT3DAPI void goat3d_set_node_pivot(struct goat3d_node *node, float x, float y, float z);
317 GOAT3DAPI void goat3d_get_node_pivot(const struct goat3d_node *node, float *xptr, float *yptr, float *zptr);
319 GOAT3DAPI void goat3d_get_node_matrix(const struct goat3d_node *node, float *matrix);
320 /* same as above, but also takes hierarchy into account */
321 GOAT3DAPI void goat3d_get_matrix(const struct goat3d_node *node, float *matrix);
323 GOAT3DAPI void goat3d_get_node_bounds(const struct goat3d_node *node, float *bmin, float *bmax);
326 GOAT3DAPI struct goat3d_track *goat3d_create_track(void);
327 GOAT3DAPI void goat3d_destroy_track(struct goat3d_track *trk);
329 GOAT3DAPI int goat3d_set_track_name(struct goat3d_track *trk, const char *name);
330 GOAT3DAPI const char *goat3d_get_track_name(const struct goat3d_track *trk);
332 GOAT3DAPI void goat3d_set_track_type(struct goat3d_track *trk, enum goat3d_track_type type);
333 GOAT3DAPI enum goat3d_track_type goat3d_get_track_type(const struct goat3d_track *trk);
335 GOAT3DAPI void goat3d_set_track_node(struct goat3d_track *trk, struct goat3d_node *node);
336 GOAT3DAPI struct goat3d_node *goat3d_get_track_node(const struct goat3d_track *trk);
338 GOAT3DAPI void goat3d_set_track_interp(struct goat3d_track *trk, enum goat3d_interp in);
339 GOAT3DAPI enum goat3d_interp goat3d_get_track_interp(const struct goat3d_track *trk);
340 GOAT3DAPI void goat3d_set_track_extrap(struct goat3d_track *trk, enum goat3d_extrap ex);
341 GOAT3DAPI enum goat3d_extrap goat3d_get_track_extrap(const struct goat3d_track *trk);
343 GOAT3DAPI int goat3d_set_track_key(struct goat3d_track *trk, const struct goat3d_key *key);
344 GOAT3DAPI int goat3d_get_track_key(const struct goat3d_track *trk, int keyidx, struct goat3d_key *key);
345 GOAT3DAPI int goat3d_get_track_key_count(const struct goat3d_track *trk);
347 GOAT3DAPI int goat3d_set_track_val(struct goat3d_track *trk, long msec, float val);
348 GOAT3DAPI int goat3d_set_track_vec3(struct goat3d_track *trk, long msec, float x, float y, float z);
349 GOAT3DAPI int goat3d_set_track_vec4(struct goat3d_track *trk, long msec, float x, float y, float z, float w);
350 GOAT3DAPI int goat3d_set_track_quat(struct goat3d_track *trk, long msec, float x, float y, float z, float w);
352 GOAT3DAPI void goat3d_get_track_val(const struct goat3d_track *trk, long msec, float *valp);
353 GOAT3DAPI void goat3d_get_track_vec3(const struct goat3d_track *trk, long msec, float *xp, float *yp, float *zp);
354 GOAT3DAPI void goat3d_get_track_vec4(const struct goat3d_track *trk, long msec, float *xp, float *yp, float *zp, float *wp);
355 GOAT3DAPI void goat3d_get_track_quat(const struct goat3d_track *trk, long msec, float *xp, float *yp, float *zp, float *wp);
357 GOAT3DAPI long goat3d_get_track_timeline(const struct goat3d_track *trk, long *tstart, long *tend);
360 GOAT3DAPI int goat3d_add_anim(struct goat3d *g, struct goat3d_anim *anim);
361 GOAT3DAPI int goat3d_get_anim_count(const struct goat3d *g);
362 GOAT3DAPI struct goat3d_anim *goat3d_get_anim(const struct goat3d *g, int idx);
363 GOAT3DAPI struct goat3d_anim *goat3d_get_anim_by_name(const struct goat3d *g, const char *name);
365 GOAT3DAPI struct goat3d_anim *goat3d_create_anim(void);
366 GOAT3DAPI void goat3d_destroy_anim(struct goat3d_anim *anim);
368 GOAT3DAPI int goat3d_set_anim_name(struct goat3d_anim *anim, const char *name);
369 GOAT3DAPI const char *goat3d_get_anim_name(const struct goat3d_anim *anim);
371 GOAT3DAPI int goat3d_add_anim_track(struct goat3d_anim *anim, struct goat3d_track *trk);
372 GOAT3DAPI struct goat3d_track *goat3d_get_anim_track(const struct goat3d_anim *anim, int idx);
373 GOAT3DAPI struct goat3d_track *goat3d_get_anim_track_by_name(const struct goat3d_anim *anim, const char *name);
374 GOAT3DAPI struct goat3d_track *goat3d_get_anim_track_by_type(const struct goat3d_anim *anim, enum goat3d_track_type type);
375 GOAT3DAPI int goat3d_get_anim_track_count(const struct goat3d_anim *anim);
377 GOAT3DAPI long goat3d_get_anim_timeline(const struct goat3d_anim *anim, long *tstart, long *tend);
383 #endif /* GOAT3D_H_ */