cgltf

cgltf, the single-file glTF 2.0 loader and writer for C, through C++23 modules.

English · 简体中文 · Upstream · Releases · mcpp · Index

The upstream C API is unchanged: every cgltf_* type, enumerator and function of <cgltf.h> and <cgltf_write.h> is the upstream global. The two headers are vendored byte for byte from the 1.15 release; their implementation is built by one C translation unit of this package (port/cgltf.c) with upstream's defaults: malloc / free, atoi / atof / atoll, no validation asserts.

Modules

• import mcpplibs.mwrap.cgltf;: the loader (cgltf_parse, cgltf_parse_file, cgltf_load_buffers, cgltf_validate, accessor reads, node transforms; 72 types, 102 enumerators, 37 functions), re-exporting the one below
• import mcpplibs.mwrap.cgltf.write;: cgltf_write, cgltf_write_file, a cgltf_data back to glTF JSON

More Modules API -> upstream's README

Getting started

mcpp new asset --template mcpplibs.mwrap.cgltf@1.15
cd asset
mcpp run

The default template parses a built-in glTF document (its buffer base64 in the document), loads and validates it, and lists each mesh's primitives; mcpp run -- <file> reads a .gltf or .glb of your own.

[dependencies]
mcpplibs.mwrap.cgltf = "1.15"

import std;
import mcpplibs.mwrap.cgltf;

int main(int argc, char** argv) {
    const cgltf_options options{};
    cgltf_data* data = nullptr;
    if (argc < 2 || cgltf_parse_file(&options, argv[1], &data) != cgltf_result_success) return 1;
    if (cgltf_load_buffers(&options, data, argv[1]) == cgltf_result_success)
        std::println("{} meshes, {} materials", data->meshes_count, data->materials_count);
    cgltf_free(data);
}

Macros

Neither header's public part defines an object-like constant, so there is no .macros module. CGLTF_MALLOC, CGLTF_FREE, CGLTF_ATOI, CGLTF_ATOF, CGLTF_ATOLL and CGLTF_VALIDATE_ENABLE_ASSERTS configure the implementation, which this package builds with upstream's defaults; for an allocator of your own use cgltf_options::memory (at run time, a call at a time).

What is and is not wrapped

• Wrapped: every name of the two headers' public parts (213 in all).
• The implementation exists once, in the package; do not build another with CGLTF_IMPLEMENTATION in the same program.
• A translation unit that also includes <cgltf.h> (add upstream/cgltf to its include path) sees the same entities (tests/header_mix_test.cpp).
• Not here: upstream's tests and fuzzing harness; decoding of Draco or meshopt compression (cgltf gives the extensions' data; decoding is the consumer's, with the library for it).

Verification

• mcpp test: parsing, loading an embedded buffer, validation, accessor reads, a material, a node's transform, the reasons broken documents are refused with, writing and parsing again, URI and string decoding, header mixing.
• python3 tools/check_exports.py: both modules are exactly what tools/surface.py derives from the headers; no type is left out.
• python3 tools/test_template.py: mcpp new from an installed copy, a strict build, and a run of the generated project.
• CI: Linux (GCC 16, LLVM 23), macOS and Windows (LLVM 23).

License

The wrapper is Apache-2.0 (mcpp-community). cgltf is MIT, © Johannes Kuhlmann (it embeds jsmn, © Serge A. Zaitsev, MIT); its README and license are kept in upstream/cgltf/ and deployed with a program's licenses. Provenance: upstream/documents.json.