Katana APIs Reference

Katana's functionality can be extended by C++ plug-ins. There are several APIs that can be used in their implementation. Each API can be found in the Modules page of this documentation.

Both plug-ins and the APIs are versioned, which means that Katana can verify if a certain plug-in is compatible with its APIs. The plug-ins communicate with Katana through a C interface, which means that any compiler can be used to build them. It also means that a plugin doesn't need to be recompiled for a new version of Katana, as long as the API versions used by the plugin are still supported inside Katana.

Note: Currently there is only one version of the APIs, so there is no need to be aware of their versioning for now.

Because of this architecture some C++ source files (provided in the PLUGIN_APIS directory) have to be compiled together with the plug-in source files. Please refer to the Makefiles of the example plug-ins to know which files are needed for each API type.

More than one plug-in (including different versions of a certain plug-in) can be compiled into a single shared object.

Implementing and Registering the Plug-ins

Each API will have a set of include files and C++ source files (provided in the PLUGIN_APIS directory) that need to be compiled together with the plug-in code. Please check the Makefiles provided with the example Plug-ins in the PLUGINS directory for more information about this.

For each plug-in there will be one main class. This needs to be registered from within its shared object so that the plug-in host (Katana in this case) can detect the plug-ins. This is achieved by:

• Calling the DEFINE_XXX_PLUGIN(CLASS) macro - in which XXX is the acronym of the API name (for example VIEWPORT for a viewport plug-in) and CLASS the main plug-in class.

• Implementing the void registerPlugins() in which the macro REGISTER_PLUGIN(PLUGIN_CLASS, PLUGIN_NAME, MAJOR, MINOR_VERSION) should be called for each plug-in class in the shared library

For example, if we are compiling a shared object with a viewer delegate and a viewport plug-in called ExampleViewerDelegate and ExampleViewport, respectively, both in version 0.1, we would need to have the following calls:

  DEFINE_VIEWER_DELEGATE_PLUGIN(ExampleViewerDelegate);
  DEFINE_VIEWPORT_PLUGIN(ExampleViewport);

  void registerPlugins()
  {
     REGISTER_PLUGIN(ExampleViewerDelegate, "ExampleViewerDelegate", 0, 1);
     REGISTER_PLUGIN(ExampleViewport, "ExampleViewport", 0, 1);
  }

Compile Plugins

Please check the Makefiles provided with the example plug-ins in the PLUGINS directory for

Once compiled, the shared objects should be placed in a Libs/ sub-directory of the standard resource search path. By default, this includes UI4/Resources, PLUGINS/Resources/Core, and and paths specified via $KATANA_RESOURCES.