USD Processing Engine API
=========================

|sparkles| **New in Katana 6.5**

This is a very quick introduction to the use of the new API to give a sense of
the basic feel.


There are three main parts to the new API for plugin writers. The first is a
new math and common-function library, the second is the API which wraps USD,
and the third is for shared geometry functionality. These reside in three new
libraries, libFdkBase(fdk), libFnUsdAbstraction(usg) and libFnUsdEngine(usg).
You will need to link against these libraries.
Each library have different namespaces and top include paths to separate
conceptually different code subsections rather than sharing a single folder.
Include files for all new libs are included like so:

.. code-block:: cpp

  #include “fdk/math/Vec3.h”


The Math Library
----------------

The FDK contains a set of math classes which are templated for float, double, half
and (sometimes) int. These include vectors (``Vec2``, ``Vec3``, ``Vec4``), matrices (``Mat4``),
quaternions (``Quat``) and boxes (``Box2``, ``Box3``). These are suffixed by
``f``, ``d``, ``h`` or ``i``. Thus ``fdk::Vec3f`` is a 3-vector of floats and
``fdk::Quath`` is a quaternion of half-floats.

The USD Wrapper
---------------

The UPE has a set of classes which act as thin wrappers around USD classes. The
intention of the wrappers is to insulate Katana from dependence on a particular
version of USD. We may provide the source code of lib FnUsdAbstraction so
customers can build the abstraction lib for different or custom versions of
USD.

The wrapper classes include:

* Token (``TfToken``)
* Path (``SdfPath``)
* Attribute (``UsdAttr``/``SdfAttributeSpec``)
* Prim (``UsdPrim``/``SdfPrimSpec``)
* BoundablePrim, XformablePrim, PointBasedPrim, MeshPrim (``UsdGeomBoundable`` etc.)
* Layer (``SdfLayer``)
* Stage (``UsdStage``)

Note that some of these, such as usg::Attribute, can wrap either a USD or SDF
class. This simplifies the API while keeping it efficient - we can use the same
code to set an attribute whether we’re defining a prim in a layer or changing a
prim from a USD stage.

.. |sparkles| unicode:: U+2728

.. automodule:: usg