omni::core::Api

template<typename T> class Api : public omni::core::Generated<T>

The API layer of an Omniverse interface.

This template is the main construct used by users to interact with Omniverse interfaces.

This template inherits from the omni::core::Generated template which in turn inherits from another omni::core::Api template instantiation. Eventually, we’ll find that the root base class is IObject_abi. For example, omni::log::ILog has the following inheritance chain:

Api<omni::log::ILog_abi>                    // interface author bindings for ILog
  Generated<omni::log::ILog_abi>            // omni.bind (generated) bindings for ILog
    omni::log::ILog_abi                     // raw ABI (defined by author)
      Api<omni::core::IObject_abi>          // hand-written bindings to IObject
        Generated<omni::core::IObject_abi>  // omni.bind (generated) bindings for IObject
          omni::core::IObject_abi           // raw ABI

where:

namespace omni::log
{
    using ILog = Api<omni::log::ILog_abi>;
}

Each point in the inheritance chain serves a different component in the system:

The _abi layer defines the raw ABI. The _abi object’s methods define how the interface can be used across DLL boundaries. Defining a stable ABI is the primary goal of Omniverse interfaces. In practice, methods in the ABI have many restrictions. See Omniverse Native Interfaces for details.
The Generated template gives the omni.bind code generation tool a place to create a template specialization that defines boiler-plate methods that make using the ABI easier. Again, see Omniverse Native Interfaces for details.
The Api template gives the interface author a place to create wrappers (via specialization) to make using the interface easier. Since the Api layer inherits from the Generated layer, specializing the the Api layer allows interface authors to augment the boiler-plate code generated by omni.bind. Interfaces authors should use the OMNI_DEFINE_INTERFACE_API() macro to specialize the Api layer.

Expected usage is:

// forward declare the interface.  this sets up the Api<> typedef.
OMNI_DECLARE_INTERFACE(foo::IMyInteface);

namespace foo {
class IMyInterface_abi : public omni::core::Inherits<omni::core::IObject, OMNI_TYPE_ID("foo.IMyInterface")>
{
protected:
    void myMethod_abi(uint32_t x) noexcept = 0;
    // ...
};
} // namespace foo

// include code generated by the omni.bind tool.
// this include should be outside of any namespace {} blocks
#include "IMyInterface.gen.h"

// use OMNI_DEFINE_INTERFACE_API() to add hand-written API wrappers
// this macro should be invoked outside of any namespace {} blocks
OMNI_DEFINE_INTERFACE(foo::IMyInterface_abi)
{
    void myReallyCoolMethod() { /* inline code here */ }
    // ...
};

Subclassed by omni::core::ImplementsCast< omni::str::IReadOnlyCString, Rest… >