| 1 |
# :diamond_shape_with_a_dot_inside: cgltf |
| 2 |
**Single-file/stb-style C glTF loader and writer** |
| 3 |
|
| 4 |
[](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. |