diff options
| author | 3gg <3gg@shellblade.net> | 2026-03-06 13:30:21 -0800 |
|---|---|---|
| committer | 3gg <3gg@shellblade.net> | 2026-03-06 13:30:21 -0800 |
| commit | 2d604425277f56c98a5c8351914178480f68bc23 (patch) | |
| tree | d4f7565adc1ef1e1ee08a295cb9da6fe3c45e758 /contrib/cgltf/README.md | |
| parent | 4e01e91ef623afa06fcfa019d6628ab1162be1aa (diff) | |
Move contrib libraries to contrib repo
Diffstat (limited to 'contrib/cgltf/README.md')
| -rw-r--r-- | contrib/cgltf/README.md | 154 |
1 files changed, 0 insertions, 154 deletions
diff --git a/contrib/cgltf/README.md b/contrib/cgltf/README.md deleted file mode 100644 index 3b49d52..0000000 --- a/contrib/cgltf/README.md +++ /dev/null | |||
| @@ -1,154 +0,0 @@ | |||
| 1 | # :diamond_shape_with_a_dot_inside: cgltf | ||
| 2 | **Single-file/stb-style C glTF loader and writer** | ||
| 3 | |||
| 4 | [](https://travis-ci.org/jkuhlmann/cgltf) | ||
| 5 | |||
| 6 | Used in: [bgfx](https://github.com/bkaradzic/bgfx), [Filament](https://github.com/google/filament), [meshoptimizer](https://github.com/zeux/meshoptimizer), [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. | ||
| 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 | Writing does not yet support "extras" data. | ||
| 87 | |||
| 88 | **For more in-depth documentation and a description of the public interface refer to the top of the `cgltf_write.h` file.** | ||
| 89 | |||
| 90 | |||
| 91 | ## Features | ||
| 92 | cgltf supports core glTF 2.0: | ||
| 93 | - glb (binary files) and gltf (JSON files) | ||
| 94 | - meshes (including accessors, buffer views, buffers) | ||
| 95 | - materials (including textures, samplers, images) | ||
| 96 | - scenes and nodes | ||
| 97 | - skins | ||
| 98 | - animations | ||
| 99 | - cameras | ||
| 100 | - morph targets | ||
| 101 | - extras data | ||
| 102 | |||
| 103 | cgltf also supports some glTF extensions: | ||
| 104 | - KHR_draco_mesh_compression (requires a library like [Google's Draco](https://github.com/google/draco) for decompression though) | ||
| 105 | - KHR_lights_punctual | ||
| 106 | - KHR_materials_clearcoat | ||
| 107 | - KHR_materials_ior | ||
| 108 | - KHR_materials_pbrSpecularGlossiness | ||
| 109 | - KHR_materials_specular | ||
| 110 | - KHR_materials_transmission | ||
| 111 | - KHR_materials_unlit | ||
| 112 | - KHR_texture_transform | ||
| 113 | |||
| 114 | cgltf does **not** yet support unlisted extensions. However, unlisted extensions can be accessed via "extensions" member on objects. | ||
| 115 | |||
| 116 | ## Building | ||
| 117 | 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: | ||
| 118 | |||
| 119 | 1. Include `cgltf.h` where you need the functionality. | ||
| 120 | 1. Have exactly one source file that defines `CGLTF_IMPLEMENTATION` before including `cgltf.h`. | ||
| 121 | 1. Use the cgltf functions as described above. | ||
| 122 | |||
| 123 | 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. | ||
| 124 | |||
| 125 | ## Contributing | ||
| 126 | 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. | ||
| 127 | |||
| 128 | |||
| 129 | ## Dependencies | ||
| 130 | None. | ||
| 131 | |||
| 132 | C headers being used by implementation: | ||
| 133 | ``` | ||
| 134 | #include <stddef.h> | ||
| 135 | #include <stdint.h> | ||
| 136 | #include <string.h> | ||
| 137 | #include <stdlib.h> | ||
| 138 | #include <stdio.h> | ||
| 139 | #include <limits.h> | ||
| 140 | ``` | ||
| 141 | |||
| 142 | Note, this library has a copy of the [JSMN JSON parser](https://github.com/zserge/jsmn) embedded in its source. | ||
| 143 | |||
| 144 | ## Testing | ||
| 145 | 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. | ||
| 146 | |||
| 147 | Here's one way to build and run the test: | ||
| 148 | |||
| 149 | cd test ; mkdir build ; cd build ; cmake .. -DCMAKE_BUILD_TYPE=Debug | ||
| 150 | make -j | ||
| 151 | cd .. | ||
| 152 | ./test_all.py | ||
| 153 | |||
| 154 | There is also a llvm-fuzz test in `fuzz/`. See http://llvm.org/docs/LibFuzzer.html for more information. | ||
