README.md

USD Unity SDK: USD C# Bindings for Unity

This repository contains a set of libraries designed to support the use of
USD in C#/Unity. The primary goal is to make it maximally easy to integrate USD
using native Unity & C# data types with a familliar serialization paradigm and
little prior knowledge of USD.

In addition to the high-level API, the raw USD API has been translated as
faithfully as possible and is exposed via the convenient API, following Kay's
adage: "Simple things should be simple, complex things should be possible."

Using the Convenience API

The convenience API is accessed via USD.NET.Scene object. The general
pattern of data access is to define a C# class to represent your data using
native C# and Unity data types. Once a data structure has been defined,
serialization works by calling Scene.Read and Scene.Write as follows:

The use of USD.NET.SampleBase is required and provides the underlying
support for reflection based serialization. In addition to creating your own
Sample types, some core USD types have been provided for convenience:

XformSample - Equivalent of UsdGeomXform,
provides support for writing a Matrix4x4 as a USD transform.

MeshSampleBase - Exposes only the
properties required to populate a UnityEngine.Mesh. This sample type can be used
to improve mesh I/O performance for read-only use cases.

While a reflection based API may seem ineffecient, it has been implemented
carefully to maximize performance and to minimize main-thread stalls. The
example above is simple, but can be extended to support asynchronous I/O
and pooled memory access, in less than 10 additional lines of code.

Using the Raw USD API

The raw USD API has been exposed as close to the C++ API as possible,
for example, the C++ pxr.UsdStage class is exposed as pxr.UsdStage. Using
this API directly requires understanding the C++ Usd library and only the
native C++ data types are supported.

To use a combination of the convenience API and the low level API, a reference
to the current UsdStage can be obtained via USD.NET.Scene.Stage.

Generating Bindings

There are two main steps to code generation, the first is a sequence of
Python scripts which generate type-specific SWIG shims (.i files). The
second step is the SWIG code generator itself.

The Python step has been tested with Ptyhon 2.7 and requires the USD
Python files to be importable via PYTHONPATH.

The SWIG step requires the SWIG 3.0.12 executable on your system PATH.

By setting USD_LOCATION_PYTHON to the root install directory of a USD
python build, all scripts will work without setting the system PATH or
PYTHONPATH. The variable USD_LOCATION should be set to a USD build without
python, to minimize runtime dependencies of the final plugin.

Once these two requirements are met, build.cmd can be run
from a cmd prompt from the root of the UsdBindings directory. It will
generate the additional SWIG inputs via Python, run SWIG, and then copy
the outputs into the correct locations in the source tree. If this script
fails at any step, execution will stop so the error can be observed.

The full build process is:

Clone a USD repository

Check out the desired version to a new branch (e.g. git checkout -b v0.8.4)