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

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

TinyGLTF uses Niels Lohmann's json library (https://github.com/nlohmann/json), so now it requires C++11 compiler. (Also, you can use RadpidJSON as an JSON backend) If you are looking for old, C++03 version, please use devel-picojson branch (but not maintained anymore).

Status

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

  • 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

Build Status

Build status

C/C++ CI

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.
  • 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.

  • json.hpp : Copyright (c) 2013-2017 Niels Lohmann. MIT license.
  • base64 : Copyright (C) 2004-2008 RenĂ© Nyffenegger
  • 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;

bool ret = loader.LoadASCIIFromFile(&model, &err, &warn, argv[1]);
//bool ret = loader.LoadBinaryFromFile(&model, &err, &warn, argv[1]); // 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\n");
  return -1;
}

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.
  • TINYGLTF_USE_CPP14 : Use C++14 feature(requires C++14 compiler). This may give better performance than C++11.

Wuffs image loader option(faster and secure JPEG/PNG deocoding)

You can use wuffs image loader to load JPEG and PNG in fast and securely. (stb_image has some security issues, whereas wuffs is well fuzz tested)

Not that some uncommon JPEG format is unsupported in wuffs std/jpeg decoder.

  • TINYGLTF_USE_WUFFS_IMAGE_LOADER : Use wuffs to load images. stb_image related stuff will be disabled.
    • TINYGLTF_NO_STB_IMAGE supercedes wuffs macros. i.e. when TINYGLTF_NO_STB_IMAGE is defined, both stb_image and wuffs are disabled.
  • TINYGLTF_NO_WUFFS_IMPLEMENTATION : Do not define WUFFS_IMPLEMENTATION inside tiny_gltf.h. Define this macro if you use wuffs in another C/C++ file.

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)

Saving gltTF 2.0 model

  • Buffers.
    • [x] To file
    • [x] Embedded
    • [ ] Draco compressed?
  • [x] Images
    • [x] To file
    • [x] Embedded
  • Binary(.glb)
    • [x] .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