tiny_gltf_v3.h is the new major version of TinyGLTF. The new C implementation (tiny_gltf_v3.c + tinygltf_json_c.h) is currently experimental.

What's new in v3

v3 is a ground-up rewrite with a C-centric, low-overhead design:

Pure C POD structs — no STL containers in the public API; easy to bind to other languages.
Arena-based memory management — all parse-time allocations come from a single arena; a single tg3_model_free() frees everything.
Structured error reporting — tg3_error_stack provides machine-readable errors with severity levels and source locations.
Custom JSON backend — backed by tinygltf_json_c.h, a locale-independent pure-C JSON parser/serializer used by the v3 runtime.
Streaming callbacks — opt-in streaming parse/write via user-supplied callbacks.
No RTTI, no exceptions required — suitable for embedded and game-engine use.
Opt-in filesystem and image I/O — TINYGLTF3_ENABLE_FS / TINYGLTF3_ENABLE_STB_IMAGE are off by default; you control when and how assets are loaded.
C++20 coroutine facade (optional, auto-detected). C17/C++17 default.
Hardened against untrusted input — URI sanitization, post-parse index-bounds validation (default-on, opt-out via tg3_parse_options.validate_indices = 0), strict numeric range checks; exercised by a libFuzzer harness and by a cross-version verifier that compares parsed output against the v1 C++ reference loader. See Security model below and the Security Considerations block at the top of tiny_gltf_v3.h.

Quick start (v3)

Copy tiny_gltf_v3.h, tiny_gltf_v3.c, and tinygltf_json_c.h to your project. Compile tiny_gltf_v3.c as C11 or newer. Define TINYGLTF3_ENABLE_FS when building tiny_gltf_v3.c if you want tg3_parse_file() to use stdio-backed filesystem helpers. The legacy TINYGLTF3_IMPLEMENTATION include path remains available for compatibility.

#include "tiny_gltf_v3.h"

Loading a glTF file:

tg3_parse_options opts;
tg3_error_stack errors;
tg3_model model;

tg3_parse_options_init(&opts);
tg3_error_stack_init(&errors);

tg3_error_code err = tg3_parse_file(&model, &errors, "scene.gltf", 10, &opts);
if (err != TG3_OK) {
    for (uint32_t i = 0; i < errors.count; i++) {
        fprintf(stderr, "[%d] %s\n", (int)errors.entries[i].severity,
                errors.entries[i].message ? errors.entries[i].message : "(null)");
    }
}
// ... use model ...
tg3_model_free(&model);
tg3_error_stack_free(&errors);

Security model (v3 C runtime)

The v3 C runtime is built for processing untrusted glTF/GLB input (server-side asset pipelines, user uploads, etc.) and ships hardened by default:

URI sanitization — external buffer/image URIs are rejected before any filesystem call if they are empty, contain NUL bytes, begin with / or \, look like a Windows drive prefix (X:), or contain a .. segment. Production callers SHOULD still provide a custom tg3_fs_callbacks.read_file that confines reads to a known directory (e.g. via openat plus a realpath prefix check) when the input is attacker-controlled.
Index bounds validation — every int32_t index field populated from JSON (accessor.bufferView, primitive.indices/material/attributes, scene.nodes[], skin.joints[], animation channel/sampler refs, KHR_audio + MSFT_lod refs, …) is checked after the structural parse. Out-of-range indices produce TG3_ERR_INVALID_INDEX. Default tg3_parse_options.validate_indices = 1; set to 0 only when you need raw round-trip and have your own validator.
Buffer/accessor range validation — declared buffer lengths, bufferView ranges, accessor element spans, sparse accessor spans, component types, and overflow-prone size math are checked before returning a model.
Strict numeric range checks — JSON numbers feeding integer fields go through finite/round-trip-validated coercion (tg3__json_number_to_int32 / _uint64). byteStride is restricted to 0 or [4, 252].
Memory budget — the arena and C JSON parser enforce TINYGLTF3_MAX_MEMORY_BYTES by default; max_single_alloc and TINYGLTF3_MAX_STRING_LENGTH bound individual allocation and string size.
Opt-in fast paths — skip_extras_values avoids materializing extras and unknown extension value trees, and borrow_input_buffers lets GLB buffer spans reference caller-owned input bytes instead of copying the BIN chunk.
Image decoding off by default — the parser does not decode image bytes; use tg3_parse_options.images_as_is = 1 to skip any decoder entirely when handling untrusted input.
Error message lifetime — error strings on tg3_error_stack are arena-allocated and remain valid until tg3_model_free(). Read or copy them BEFORE freeing the model.

See the Security Considerations block at the top of tiny_gltf_v3.h for the authoritative threat-model summary.

Testing & verification

The v3 C runtime ships with three layers of automated coverage:

tests/tester_v3_c.c — internal unit checks plus security regression tests (path traversal, negative byteStride, OOB indices, error-message lifetime, …). Build via make in tests/; run ./tester_v3_c for the internal suite or ./tester_v3_c <file.gltf|file.glb> to parse a single asset.
test_runner.py — a cross-version verifier that runs the v1 C++ reference loader (loader_example) and the v3 C tester against every model in glTF-Sample-Models/2.0, then diffs a structured DIGEST block (buffer FNV64 hashes, accessor/bufferView fields, primitive attribute maps, node TRS, material PBR factors, skin/animation/scene topology, …). v1 is the ground truth.
tests/v3/fuzzer/ — libFuzzer harness with ASan + UBSan (make run builds and runs fuzz_gltf_v3_c). Crafted regression inputs live in tests/v3/security/ and are seeded into tests/v3/fuzzer/corpus/.

Status

⚠️ v2 deprecation notice: tiny_gltf.h (v2) remains fully functional and is still supported, but it is now in maintenance mode only — no new features will be added. v2 will be sunset after mid-2026. tiny_gltf_v3.h is the intended successor, but the new C v3 runtime is still experimental.

TinyGLTF v3's C runtime (tiny_gltf_v3.h + tiny_gltf_v3.c) is available for evaluation and early adoption, but its API/behavior may still change while the implementation matures.

Currently TinyGLTF v2 is stable and in maintenance mode. No drastic changes and feature additions planned.

v2.9.0 Various fixes and improvements. Filesystem callback API change.
v2.8.0 Add URICallbacks for custom URI handling in Buffer and Image. PR#397
v2.7.0 Change WriteImageDataFunction user callback function signature. PR#393
v2.6.0 Support serializing sparse accessor(Thanks to @fynv).
v2.5.0 Add SetPreserveImageChannels() option to load image data as is.
v2.4.0 Experimental RapidJSON support. Experimental C++14 support(C++14 may give better performance)
v2.3.0 Modified Material representation according to glTF 2.0 schema(and introduced TextureInfo class)
v2.2.0 release(Support loading 16bit PNG. Sparse accessor support)
v2.1.0 release(Draco decoding support)
v2.0.0 release(22 Aug, 2018)!

Branches

sajson : Use sajson to parse JSON. Parsing only but faster compile time(2x reduction compared to json.hpp and RapidJson), but not well maintained.

Builds

Features

Probably mostly feature-complete. Last missing feature is Draco encoding: https://github.com/syoyo/tinygltf/issues/207

Written in portable C++. C++-11 with STL dependency only.
- macOS + clang(LLVM)
- iOS + clang
- Linux + gcc/clang
- Windows + MinGW
- Windows + Visual Studio 2015 Update 3 or later.
  - Visual Studio 2013 is not supported since they have limited C++11 support and failed to compile json.hpp.
- Android NDK
- Android + CrystaX(NDK drop-in replacement) GCC
- Web using Emscripten(LLVM)
Moderate parsing time and memory consumption.
glTF specification v2.0.0
- ASCII glTF
  - Load
  - Save
- Binary glTF(GLB)
  - Load
  - Save(.bin embedded .glb)
Buffers
- Parse BASE64 encoded embedded buffer data(DataURI).
- Load .bin file.
Image(Using stb_image)
- Parse BASE64 encoded embedded image data(DataURI).
- Load external image file.
- Load PNG(8bit and 16bit)
- Load JPEG(8bit only)
- Load BMP
- Load GIF
- Custom Image decoder callback(e.g. for decoding OpenEXR image)
Morph traget
- Sparse accessor
Load glTF from memory
Custom callback handler
- Image load
- Image save
Extensions
- Draco mesh decoding
- Draco mesh encoding

Note on extension property

In extension(ExtensionMap), JSON number value is parsed as int or float(number) and stored as tinygltf::Value object. If you want a floating point value from tinygltf::Value, use GetNumberAsDouble() method.

IsNumber() returns true if the underlying value is an int value or a floating point value.

Examples

glview : Simple glTF geometry viewer.
validator : Simple glTF validator with JSON schema.
basic : Basic glTF viewer with texturing support.
build-gltf : Build simple glTF scene from a scratch.

WASI/WASM build

Users who want to run TinyGLTF securely and safely(e.g. need to handle malcious glTF file to serve online glTF conver), I recommend to build TinyGLTF for WASM target. WASI build example is located in wasm .

TODOs

Robust URI decoding/encoding. https://github.com/syoyo/tinygltf/issues/369
Mesh Compression/decompression(Open3DGC, etc)
- Load Draco compressed mesh
- Save Draco compressed mesh
- Open3DGC?
Support extensions and extras property
HDR image?
- OpenEXR extension through TinyEXR.
16bit PNG support in Serialization
Write example and tests for animation and skin

Optional

Write C++ code generator which emits C++ code from JSON schema for robust parsing?

Licenses

TinyGLTF is licensed under MIT license.

TinyGLTF uses the following third party libraries.

stb_image.h : v2.08 - public domain image loader - Github link
stb_image_write.h : v1.09 - public domain image writer - Github link

Build and example

Copy stb_image.h, stb_image_write.h, json.hpp and tiny_gltf.h to your project.

Loading glTF 2.0 model

// Define these only in *one* .cc file.
#define TINYGLTF_IMPLEMENTATION
#define STB_IMAGE_IMPLEMENTATION
#define STB_IMAGE_WRITE_IMPLEMENTATION
// #define TINYGLTF_NOEXCEPTION // optional. disable exception handling.
#include "tiny_gltf.h"

using namespace tinygltf;

Model model;
TinyGLTF loader;
std::string err;
std::string warn;
std::string filename = "input.gltf";

bool ret = loader.LoadASCIIFromFile(&model, &err, &warn, filename);
//bool ret = loader.LoadBinaryFromFile(&model, &err, &warn, filename); // for binary glTF(.glb)

if (!warn.empty()) {
  printf("Warn: %s\n", warn.c_str());
}

if (!err.empty()) {
  printf("Err: %s\n", err.c_str());
}

if (!ret) {
  printf("Failed to parse glTF: %s\n", filename.c_str());
}

Loader options

TinyGLTF::SetPreserveimageChannels(bool onoff). true to preserve image channels as stored in image file for loaded image. false by default for backward compatibility(image channels are widen to RGBA 4 channels). Effective only when using builtin image loader(STB image loader).

Compile options

TINYGLTF_NOEXCEPTION : Disable C++ exception in JSON parsing. You can use -fno-exceptions or by defining the symbol JSON_NOEXCEPTION and TINYGLTF_NOEXCEPTION to fully remove C++ exception codes when compiling TinyGLTF.
TINYGLTF_NO_STB_IMAGE : Do not load images with stb_image. Instead use TinyGLTF::SetImageLoader(LoadimageDataFunction LoadImageData, void *user_data) to set a callback for loading images.
TINYGLTF_NO_STB_IMAGE_WRITE : Do not write images with stb_image_write. Instead use TinyGLTF::SetImageWriter(WriteimageDataFunction WriteImageData, void *user_data) to set a callback for writing images.
TINYGLTF_NO_EXTERNAL_IMAGE : Do not try to load external image file. This option would be helpful if you do not want to load image files during glTF parsing.
TINYGLTF_ANDROID_LOAD_FROM_ASSETS: Load all files from packaged app assets instead of the regular file system. Note: You must pass a valid asset manager from your android app to tinygltf::asset_manager beforehand.
TINYGLTF_ENABLE_DRACO: Enable Draco compression. User must provide include path and link correspnding libraries in your project file.
TINYGLTF_NO_INCLUDE_JSON : Disable including json.hpp from within tiny_gltf.h because it has been already included before or you want to include it using custom path before including tiny_gltf.h.
TINYGLTF_NO_INCLUDE_RAPIDJSON : Disable including RapidJson's header files from within tiny_gltf.h because it has been already included before or you want to include it using custom path before including tiny_gltf.h.
TINYGLTF_NO_INCLUDE_STB_IMAGE : Disable including stb_image.h from within tiny_gltf.h because it has been already included before or you want to include it using custom path before including tiny_gltf.h.
TINYGLTF_NO_INCLUDE_STB_IMAGE_WRITE : Disable including stb_image_write.h from within tiny_gltf.h because it has been already included before or you want to include it using custom path before including tiny_gltf.h.
TINYGLTF_USE_RAPIDJSON : Use RapidJSON as a JSON parser/serializer. RapidJSON files are not included in TinyGLTF repo. Please set an include path to RapidJSON if you enable this feature.

CMake options

You can add tinygltf using add_subdirectory feature. If you add tinygltf to your project using add_subdirectory, it would be better to set TINYGLTF_HEADER_ONLY on(just add an include path to tinygltf) and TINYGLTF_INSTALL off(Which does not install tinygltf files).

// Your project's CMakeLists.txt
...

set(TINYGLTF_HEADER_ONLY ON CACHE INTERNAL "" FORCE)
set(TINYGLTF_INSTALL OFF CACHE INTERNAL "" FORCE)
add_subdirectory(/path/to/tinygltf)

NOTE: Using tinygltf as a submodule doesn't automatically add the headers to your include path (as standard for many libraries). To get this functionality, add the following to the CMakeLists.txt file from above:

target_include_directories(${PROJECT_NAME} PRIVATE "/path/to/tinygltf")

Saving gltTF 2.0 model

Buffers.
- To file
- Embedded
- Draco compressed?
Images
- To file
- Embedded
Binary(.glb)
- .bin embedded single .glb
- External .bin

Running tests.

glTF parsing test

Setup

Python required. Git clone https://github.com/KhronosGroup/glTF-Sample-Models to your local dir.

Run parsing test

After building loader_example, edit test_runner.py, then,

$ python test_runner.py

Unit tests

$ cd tests
$ make
$ ./tester
$ ./tester_noexcept

Fuzzing tests

See tests/fuzzer for details.

After running fuzzer on Ryzen9 3950X a week, at least LoadASCIIFromString looks safe except for out-of-memory error in Fuzzer. We may be better to introduce bounded memory size checking when parsing glTF data.

Third party licenses

json.hpp : Licensed under the MIT License http://opensource.org/licenses/MIT. Copyright (c) 2013-2017 Niels Lohmann http://nlohmann.me.
stb_image : Public domain.
dlib(uridecode, uriencode) : Copyright (C) 2003 Davis E. King Boost Software License 1.0. http://dlib.net/dlib/server/server_http.cpp.html

Languages

HTML 46.8%

C++ 31.1%

C 20.3%

JavaScript 0.9%

Makefile 0.2%

Other 0.5%