Modules are separate GPUThe GPU is responsible for displaying graphical elements on a computer display. The GPU plays a key role in the Octane rendering process as the CUDA cores are utilized during the rendering process. Octane rendering extensions that add new functionality to OctaneRender. These are dependent on the services provided by the Standalone Edition and are created by third-party developer clients through Octane’s Module API for the purpose of integrating in the Standalone Edition. The term ‘Modules” is used in order to avoid confusion with the term plugin which is already used for integrations of OctaneRender in other 3D modelling host applications.
With the module API, the following files are provided:
Loading Modules
Modules are loaded once on startup. Once Octane is running it's not possible anymore to unload loaded modules or load new modules. Octane searches recursively for shared libraries in the modules directory. The libraries are recognized by their file extension (.so for Linux, .dll for Windows and .dylib for OSX). The modules directory can be configured via the preferences dialog. Loading of modules can be skipped by using the --no-modules command line option. (TIP: When Octane seems to hang at startup, it could be that it crashed because of your module code. You can skip module loading to verify this).
You can get more info about the module loading by enabling the moduleLoader log flag. To enable this log flag (and other log flags), create a file named octane_log_flags.txt in the directory of the Octane binary. This file should have each log flag on a new line. To print out all the log flags, add logFlags to this file.
Writing Modules
Modules are writtn in C++. Each module needs a start and stop function. The start function is called once when Octane is loaded from the command line. The stop function is called once before Octane exits. These functions are the entry points for Octane into your code. It's important that these functions have the correct name and signature and that their symbol is visible in your module library. You should define these functions as extern "C" to avoid name-mangling. The easiest is to use the macros defined in apimodule.h. In the start function, the module should register itself with Octane. One library (module) is allowed to implement multiple modules, so register can be called multiple times in the start function. Registration can only be done from within the start function.
The API is made up of all the header files that start with api. This API is C++ but with some limitations to avoid problems that can occur at dll boundaries. Because of this, the API isn't always easy and intuitive to use. That is why we provided C++ convenience wrappers around most of the api code. If the code is trivial, we don't provide wrappers. All the wrappers are in the files prefixed with octanewrap. We recommend using the wrappers because it makes life a lot easier. The wrappers should be compiled as part of the module code. For convenience, we provide octanemoduleapi.h` and `octanemoduleapi.cpp so that you have to include/compile only a single file.
We try our best to provide good documentation for the API in the header files. If you run into problems, the forum is the best place to ask for help.
Module IDs
Each module is identified by a unique ID. Once an ID is assigned to a module, it cannot be re-used for a different module. We are working on a website where users can register unique module IDs. Until then, just pm me to request a module ID and we will keep track of them when the system is there.
Module Types
There are different types of modules and each type integrates different in Octane: The types are:
Threading
The main thread running in OctaneRender is called the "message thread". This is the thread that runs Octane itself and most of the code is executed by the message thread (user interface, node system evaluation, ...). Octane will always call your plugin from the main thread unless documented otherwise. You can only call the API from the main thread except for a few specific classes. This is documented at the top of those classes (e.g. ApiRenderEngine, ApiLogManager, ...).
A good practice is to use the macro OCTANE_API_ASSERT_MESSAGE_THREAD defined in octanewrapthread.h to make sure that you aren't calling the API from the wrong thread.
Compilation
If you are using the wrappers, they should be compiled with your module code. Windows and macOS require some extra things:
The compilers we tested with are Visual Studio 2010 (Windows), g++-4.8.4 (Linux) and Clang 6.10 (macOS).
Examples
The easiest way to get started with the API is by studying the example modules. You can build the examples on Windows with the Visual Studio solution octane-modules.sln. For Linux and macOS, CMake files are provided for each example module. You can build all modules by executing the script build-modules.sh The examples we provide are:
Warnings
Some warnings and potential pitfalls: