Home

Awesome

Tiny USDZ loader

TinyUSDZ is dependency-free(depends only on C++ STL. Yes, you don't need USD library!) USDZ loader library written in C++11.

C/C++ CI

Total alerts

Status

TinyUSDZ is currently in alpha stage. Not usable.

Notice

TinyUSDZ does not support Reality Composer file format(.reality) since it uses proprietary file format and we cannot understand it(so no conversion support from/to Reality also).

Other related projects

Supported platforms

Requirements

USDZ file format

USDZ is actually the uncompressed zip file. USDZ(ZIP) contains usdc(binary) and resources(e.g. image/auduo files)

Security and memory budget

USDZ(USDC) is a binary format and data are compressed. To avoid out-of-bounds access, out-of-memory, and other security issues when loading malcious USDZ(e.g. USDZ file from unknown origin), TinyUSDZ has a memory budget feature to avoid out-of-memory issue.

To limit a memory usage when loading USDZ file, Please set a value max_memory_limit_in_mb in USDLoadOptions.

TinyUSDZ source codes are also checked by Address Sanitizer, CodeQL and Fuzzer.

Build

Integrate to your app

Recomended way is simply copy src and include folder to your app, and add *.cc files to your app's build system.

I do not recommend to use tinyusdz as a git submodule, since the repo contains lots of codes required to build TinyUSDZ examples but these are not required for your app.

Compiler defines

CMake

cmake build is still provided for CI build. CMakeSettings.json is provided for Visual Studio 2019.

Cmake project is not recommended for embedding TinyUSDZ to your app.

$ mkdir build
$ cd build
$ cmake ..
$ make

LLVM-MinGW build

MinGW native and cross-compiling example using llvm-mingw(clang) is provided. See scripts/bootstrap-cmake-mingw-win.sh and scripts/bootstrap-cmake-llvm-mingw-cross.sh for details.

One of benefit to use llvm-mingw is address sanitizer support on Windows app.

To run app(.exe, you'll need libunwind.dll and libc++.dll on your working directory or search path)

For Windows native build, we assume ninja.exe is installed on your system(You can use it from Meson package)

CMake build options

clang-cl on Windows

Assume ninja.exe is installed and path to ninja.exe is added to your %PATH%

Edit path to MSVC SDK and Windows SDK in bootstrap-clang-cl-win64.bat, then

> bootstrap-clang-cl-win64.bat
> ninja.exe

Meson

Meson build is provided for compile tests.

$ meson builddir
$ cd builddir
$ ninja

Examples

See examples directory for more examples.

Data format

See prim_format.md and preview_surface.md

TODO

Fuzzing test

See tests/fuzzer/

License

TinyUSDZ is licensed under MIT license.

Third party licenses