Header only C++ tiny glTF library(loader/saver).

TinyGLTF is a header only C++ glTF 2.0 https://github.com/KhronosGroup/glTF library.

TinyGLTF v3 (new major release)

tiny_gltf_v3.h is the new major version of TinyGLTF and the recommended API for new projects.

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.h, a high-performance, locale-independent JSON parser with optional SIMD acceleration (SSE2 / AVX2 / NEON) and a float32 fast-path.
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.

Quick start (v3)

Copy tiny_gltf_v3.h and tinygltf_json.h to your project. In one .cpp file:

#define TINYGLTF3_IMPLEMENTATION
#define TINYGLTF3_ENABLE_FS          // enable file I/O
#define TINYGLTF3_ENABLE_STB_IMAGE   // enable image decoding
#include "tiny_gltf_v3.h"

Loading a glTF file:

tg3_load_options_t opts = tg3_load_options_default();
tg3_error_stack_t errors = {0};
tg3_model_t *model = tg3_load_from_file("scene.gltf", &opts, &errors);
if (!model) {
    for (int i = 0; i < errors.count; i++)
        fprintf(stderr, "[%s] %s\n", tg3_severity_str(errors.items[i].severity),
                errors.items[i].message);
}
// ... use model ...
tg3_model_free(model);

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. New projects should use tiny_gltf_v3.h.

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.
- [x] macOS + clang(LLVM)
- [x] iOS + clang
- [x] Linux + gcc/clang
- [x] Windows + MinGW
- [x] 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.
- [x] Android NDK
- [x] Android + CrystaX(NDK drop-in replacement) GCC
- [x] Web using Emscripten(LLVM)
Moderate parsing time and memory consumption.
glTF specification v2.0.0
- [x] ASCII glTF
  - [x] Load
  - [x] Save
- [x] Binary glTF(GLB)
  - [x] Load
  - [x] Save(.bin embedded .glb)
Buffers
- [x] Parse BASE64 encoded embedded buffer data(DataURI).
- [x] Load .bin file.
Image(Using stb_image)
- [x] Parse BASE64 encoded embedded image data(DataURI).
- [x] Load external image file.
- [x] Load PNG(8bit and 16bit)
- [x] Load JPEG(8bit only)
- [x] Load BMP
- [x] Load GIF
- [x] Custom Image decoder callback(e.g. for decoding OpenEXR image)
Morph traget
- [x] Sparse accessor
Load glTF from memory
Custom callback handler
- [x] Image load
- [x] Image save
Extensions
- [x] 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 .

Projects using TinyGLTF

px_render Single header C++ Libraries for Thread Scheduling, Rendering, and so on... https://github.com/pplux/px
Physical based rendering with Vulkan using glTF 2.0 models https://github.com/SaschaWillems/Vulkan-glTF-PBR
GLTF loader plugin for OGRE 2.1. Support for PBR materials via HLMS/PBS https://github.com/Ybalrid/Ogre_glTF
TinyGltfImporter plugin for Magnum, a lightweight and modular C++11/C++14 graphics middleware for games and data visualization.
Diligent Engine - A modern cross-platform low-level graphics library and rendering framework
Lighthouse 2: a rendering framework for real-time ray tracing / path tracing experiments. https://github.com/jbikker/lighthouse2
QuickLook GLTF - quicklook plugin for macos. Also SceneKit wrapper for tinygltf.
GlslViewer - live GLSL coding for MacOS and Linux
Vulkan-Samples - The Vulkan Samples is collection of resources to help you develop optimized Vulkan applications.
TDME2 - TDME2 - ThreeDeeMiniEngine2 is a lightweight 3D engine including tools suited for 3D game development using C++11
SanityEngine - A C++/D3D12 renderer focused on the personal and professional development of its developer
Open3D - A Modern Library for 3D Data Processing
Supernova Engine - Game engine for 2D and 3D projects with Lua or C++ in data oriented design.
Wicked Engine<img src="https://github.com/turanszkij/WickedEngine/blob/master/Content/logo_small.png" width="28px" align="center"/> - 3D engine with modern graphics
Your projects here! (Please send PR)

TODOs

[ ] Robust URI decoding/encoding. https://github.com/syoyo/tinygltf/issues/369
[ ] Mesh Compression/decompression(Open3DGC, etc)
- [x] Load Draco compressed mesh
- [ ] Save Draco compressed mesh
- [ ] Open3DGC?
[x] 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. Y

Tinygltf

Install / Use

README