Debian Codegraph @

third_party/cgltf/README.md

raw
1 # :diamond_shape_with_a_dot_inside: cgltf
2 **Single-file/stb-style C glTF loader and writer**
3
4 [![Build Status](https://github.com/jkuhlmann/cgltf/workflows/build/badge.svg)](https://github.com/jkuhlmann/cgltf/actions)
5
6 Used in: [bgfx](https://github.com/bkaradzic/bgfx), [Filament](https://github.com/google/filament), [gltfpack](https://github.com/zeux/meshoptimizer/tree/master/gltf), [raylib](https://github.com/raysan5/raylib), and more!
7
8 ## Usage: Loading
9 Loading from file:
10 ```c
11 #define CGLTF_IMPLEMENTATION
12 #include "cgltf.h"
13
14 cgltf_options options = {0};
15 cgltf_data* data = NULL;
16 cgltf_result result = cgltf_parse_file(&options, "scene.gltf", &data);
17 if (result == cgltf_result_success)
18 {
19 /* TODO make awesome stuff */
20 cgltf_free(data);
21 }
22 ```
23
24 Loading from memory:
25 ```c
26 #define CGLTF_IMPLEMENTATION
27 #include "cgltf.h"
28
29 void* buf; /* Pointer to glb or gltf file data */
30 size_t size; /* Size of the file data */
31
32 cgltf_options options = {0};
33 cgltf_data* data = NULL;
34 cgltf_result result = cgltf_parse(&options, buf, size, &data);
35 if (result == cgltf_result_success)
36 {
37 /* TODO make awesome stuff */
38 cgltf_free(data);
39 }
40 ```
41
42 Note that cgltf does not load the contents of extra files such as buffers or images into memory by default. You'll need to read these files yourself using URIs from `data.buffers[]` or `data.images[]` respectively.
43 For buffer data, you can alternatively call `cgltf_load_buffers`, which will use `FILE*` APIs to open and read buffer files. This automatically decodes base64 data URIs in buffers. For data URIs in images, you will need to use `cgltf_load_buffer_base64`.
44
45 **For more in-depth documentation and a description of the public interface refer to the top of the `cgltf.h` file.**
46
47 ## Usage: Writing
48 When writing glTF data, you need a valid `cgltf_data` structure that represents a valid glTF document. You can construct such a structure yourself or load it using the loader functions described above. The writer functions do not deallocate any memory. So, you either have to do it manually or call `cgltf_free()` if you got the data by loading it from a glTF document.
49
50 Writing to file:
51 ```c
52 #define CGLTF_IMPLEMENTATION
53 #define CGLTF_WRITE_IMPLEMENTATION
54 #include "cgltf_write.h"
55
56 cgltf_options options = {0};
57 cgltf_data* data = /* TODO must be valid data */;
58 cgltf_result result = cgltf_write_file(&options, "out.gltf", data);
59 if (result != cgltf_result_success)
60 {
61 /* TODO handle error */
62 }
63 ```
64
65 Writing to memory:
66 ```c
67 #define CGLTF_IMPLEMENTATION
68 #define CGLTF_WRITE_IMPLEMENTATION
69 #include "cgltf_write.h"
70 cgltf_options options = {0};
71 cgltf_data* data = /* TODO must be valid data */;
72
73 cgltf_size size = cgltf_write(&options, NULL, 0, data);
74
75 char* buf = malloc(size);
76
77 cgltf_size written = cgltf_write(&options, buf, size, data);
78 if (written != size)
79 {
80 /* TODO handle error */
81 }
82 ```
83
84 Note that cgltf does not write the contents of extra files such as buffers or images. You'll need to write this data yourself.
85
86 **For more in-depth documentation and a description of the public interface refer to the top of the `cgltf_write.h` file.**
87
88
89 ## Features
90 cgltf supports core glTF 2.0:
91 - glb (binary files) and gltf (JSON files)
92 - meshes (including accessors, buffer views, buffers)
93 - materials (including textures, samplers, images)
94 - scenes and nodes
95 - skins
96 - animations
97 - cameras
98 - morph targets
99 - extras data
100
101 cgltf also supports some glTF extensions:
102 - EXT_meshopt_compression
103 - KHR_draco_mesh_compression (requires a library like [Google's Draco](https://github.com/google/draco) for decompression though)
104 - KHR_lights_punctual
105 - KHR_materials_clearcoat
106 - KHR_materials_ior
107 - KHR_materials_pbrSpecularGlossiness
108 - KHR_materials_sheen
109 - KHR_materials_specular
110 - KHR_materials_transmission
111 - KHR_materials_unlit
112 - KHR_materials_variants
113 - KHR_materials_volume
114 - KHR_texture_transform
115
116 cgltf does **not** yet support unlisted extensions. However, unlisted extensions can be accessed via "extensions" member on objects.
117
118 ## Building
119 The easiest approach is to integrate the `cgltf.h` header file into your project. If you are unfamiliar with single-file C libraries (also known as stb-style libraries), this is how it goes:
120
121 1. Include `cgltf.h` where you need the functionality.
122 1. Have exactly one source file that defines `CGLTF_IMPLEMENTATION` before including `cgltf.h`.
123 1. Use the cgltf functions as described above.
124
125 Support for writing can be found in a separate file called `cgltf_write.h` (which includes `cgltf.h`). Building it works analogously using the `CGLTF_WRITE_IMPLEMENTATION` define.
126
127 ## Contributing
128 Everyone is welcome to contribute to the library. If you find any problems, you can submit them using [GitHub's issue system](https://github.com/jkuhlmann/cgltf/issues). If you want to contribute code, you should fork the project and then send a pull request.
129
130
131 ## Dependencies
132 None.
133
134 C headers being used by implementation:
135 ```
136 #include <stddef.h>
137 #include <stdint.h>
138 #include <string.h>
139 #include <stdlib.h>
140 #include <stdio.h>
141 #include <limits.h>
142 ```
143
144 Note, this library has a copy of the [JSMN JSON parser](https://github.com/zserge/jsmn) embedded in its source.
145
146 ## Testing
147 There is a Python script in the `test/` folder that retrieves the glTF 2.0 sample files from the glTF-Sample-Models repository (https://github.com/KhronosGroup/glTF-Sample-Models/tree/master/2.0) and runs the library against all gltf and glb files.
148
149 Here's one way to build and run the test:
150
151 cd test ; mkdir build ; cd build ; cmake .. -DCMAKE_BUILD_TYPE=Debug
152 make -j
153 cd ..
154 ./test_all.py
155
156 There is also a llvm-fuzz test in `fuzz/`. See http://llvm.org/docs/LibFuzzer.html for more information.