Introduction to the module SDK.

Forums: Introduction to the module SDK.
Forum for OctaneRender module development.

Introduction to the module SDK.

Postby stratified » Mon Jul 11, 2016 3:18 am

stratified Mon Jul 11, 2016 3:18 am
This post gives a high-level overview of the module API which we will make available in the next weeks. The module API is still a work in progress and changes are likely.

The most up-to-date version of this text is always shipped as part of the latest OctaneRender standalone release. With the module API, developers can create modules that integrate in the standalone. In other programs modules are usually called plugins but we prefer modules to avoid confusion with the host application integration plugins for OctaneRender.

With the module API, the following files are provided:

  • Most up-to-date version of this document.
  • API header files. All their names start with api (e.g. apiprojectmanager.h).
  • API wrapper header and source files. All their names start with octanewrap (e.g. octanewrapprojectmanager.h).
  • octane.lib is provided for linking on Windows.
  • Example modules directory.

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 writing 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:

  • Command module: Modules of this type execute a command. Executing a command is very generic and can be everything from saving a file, opening a window, ... . Each command module gets a menu entry in the modules menu. When the menu entry is clicked, the command's execute function is called. Commands are the most flexible plugins in Octane.
  • Work pane module: Work pane modules implement a gui component that can be docked into the Octane workspace. Work pane modules have a menu entry in the window menu and when launched they are initially created in a separate undocked window. There can be only a single instance of a work pane module. Work pane modules are destroyed when a new project is loaded. Users can save the work pane module as part of their default layout.

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 OSX require some extra things:

  • Windows: your module code needs to link against octane.lib.
  • OSX: you need to specify -undefined dynamic_lookup to the linker options.

The compilers we tested with are Visual Studio 2010 (Windows), g++-4.8.4 (Linux) and Clang 6.10 (OSX).

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 OSX, 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:

  • Hello world module: Shows how to register a module, use the log manager and create a window.
  • Work pane module: Shows how to create a work pane module and demonstrates the creation of various user interface components.
  • Texture commander module: Shows how to use the table component and how to correctly interact with the node system and events generated by the node system.

Warnings

Some warnings and potential pitfalls:

  • Your code is not running in a sandbox. A crash in your code will crash Octane.
  • Keep an eye on the log output, errors generated by your module will be displayed here.
User avatar
stratified
OctaneRender Team
OctaneRender Team
 
Posts: 945
Joined: Wed Aug 15, 2012 6:32 am
Location: Auckland, New Zealand

Re: Introduction to the module SDK.

Postby Phantom107 » Mon Jul 25, 2016 3:54 am

Phantom107 Mon Jul 25, 2016 3:54 am
Very interesting
User avatar
Phantom107
Licensed Customer
Licensed Customer
 
Posts: 686
Joined: Tue Jul 24, 2012 11:31 am
Location: The Netherlands

Re: Introduction to the module SDK.

Postby face_off » Wed Aug 31, 2016 6:36 am

face_off Wed Aug 31, 2016 6:36 am
Thomas - would it be better to have the modules location defaulted to the Roaming folder rather than Local folder on Windows?

Paul
Win7/Win10/Mavericks/Mint 17 - GTX550Ti/GT640M
Octane Plugin Support : Poser, ArchiCAD, Revit, Inventor, AutoCAD, Rhino, Modo, Nuke
Pls read before submitting a support question
User avatar
face_off
Octane Plugin Developer
Octane Plugin Developer
 
Posts: 15465
Joined: Fri May 25, 2012 10:52 am
Location: Adelaide, Australia

Re: Introduction to the module SDK.

Postby face_off » Wed Aug 31, 2016 11:41 am

face_off Wed Aug 31, 2016 11:41 am
Thomas - octane-hello-world.cpp has gButton declared globally, however when the button is created, and local stack version of gButton is used. So you need to change
Code: Select all
        Octane::ApiTextButton *gButton = Octane::ApiTextButton::create("Hello!",
                                                                       buttonClicked,
                                                                       NULL);
to
Code: Select all
        /* Octane::ApiTextButton * */gButton = Octane::ApiTextButton::create("Hello!",
                                                                       buttonClicked,
                                                                       NULL);
Paul
Win7/Win10/Mavericks/Mint 17 - GTX550Ti/GT640M
Octane Plugin Support : Poser, ArchiCAD, Revit, Inventor, AutoCAD, Rhino, Modo, Nuke
Pls read before submitting a support question
User avatar
face_off
Octane Plugin Developer
Octane Plugin Developer
 
Posts: 15465
Joined: Fri May 25, 2012 10:52 am
Location: Adelaide, Australia

Re: Introduction to the module SDK.

Postby Goldorak » Fri Sep 02, 2016 4:36 pm

Goldorak Fri Sep 02, 2016 4:36 pm
Thanks for the feedback. The module SDK will be getting a large overhaul as we get closer to 3.1 release.
User avatar
Goldorak
OctaneRender Team
OctaneRender Team
 
Posts: 2321
Joined: Sun Apr 22, 2012 8:09 pm

Re: Introduction to the module SDK.

Postby pixerati2 » Wed Oct 05, 2016 11:49 pm

pixerati2 Wed Oct 05, 2016 11:49 pm
Will the modules load when a host initiates Octane? I.e. if the Octane engine is started by the Modo, Maya or Cinema4D plugin rather than standalone, will the modules be loaded?
pixerati2
Licensed Customer
Licensed Customer
 
Posts: 42
Joined: Sun Jul 06, 2014 4:06 pm

Re: Introduction to the module SDK.

Postby face_off » Thu Oct 06, 2016 1:33 am

face_off Thu Oct 06, 2016 1:33 am
Will the modules load when a host initiates Octane? I.e. if the Octane engine is started by the Modo, Maya or Cinema4D plugin rather than standalone, will the modules be loaded?
At the moment modules are only started within Octane Standalone. The Module SDK has a bunch of hooks into the Octane Standalone UI, so is dependent on it. For modules within Modo, Maya, etc, you need to use the plugin SDK which the OctaneRender for Modo/Maya/etc plugins use, which is not publicly available.

Paul
Win7/Win10/Mavericks/Mint 17 - GTX550Ti/GT640M
Octane Plugin Support : Poser, ArchiCAD, Revit, Inventor, AutoCAD, Rhino, Modo, Nuke
Pls read before submitting a support question
User avatar
face_off
Octane Plugin Developer
Octane Plugin Developer
 
Posts: 15465
Joined: Fri May 25, 2012 10:52 am
Location: Adelaide, Australia

Re: Introduction to the module SDK.

Postby pixerati2 » Fri Oct 07, 2016 12:42 am

pixerati2 Fri Oct 07, 2016 12:42 am
Ah, had a feeling it might be that way. Thanks Paul.
pixerati2
Licensed Customer
Licensed Customer
 
Posts: 42
Joined: Sun Jul 06, 2014 4:06 pm

Re: Introduction to the module SDK.

Postby grimm » Fri Nov 25, 2016 8:44 pm

grimm Fri Nov 25, 2016 8:44 pm
The last version of the example code doesn't run on the new version of standalone, is there going to be an updated version of the module code? Thanks,

Code: Select all
OctaneRender 3.04.5 (3040500)

failed to open '/home/jason/.OctaneRender/modules/libtexcommander.so': '/home/jason/.OctaneRender/modules/libtexcommander.so: undefined symbol: _ZN6Octane20ApiCommandModuleInfoC1EiPKcS2_S2_jPFbvE'
failed to open '/home/jason/.OctaneRender/modules/test/liboctane-hello-world.so': '/home/jason/.OctaneRender/modules/test/liboctane-hello-world.so: undefined symbol: _ZN6Octane20ApiCommandModuleInfoC1EiPKcS2_S2_jPFbvE'
failed to open '/home/jason/.OctaneRender/modules/libworkpanemodule.so': '/home/jason/.OctaneRender/modules/libworkpanemodule.so: undefined symbol: _ZN6Octane21ApiWorkPaneModuleInfoC1EiPKcS2_S2_jPFbPNS_13ApiGridLayoutEEPFbvE'


P.S. Any chance of getting access to a git repo for the module code?
Linux Mint 20 x64 | Nvidia GTX 980 4GB (displays) RTX 2070 8GB| Intel I7 5820K 3.8 Ghz | 32Gb Memory | Nvidia Driver 460.56
User avatar
grimm
Licensed Customer
Licensed Customer
 
Posts: 1321
Joined: Wed Jan 27, 2010 8:11 pm
Location: Spokane, Washington, USA

Re: Introduction to the module SDK.

Postby calus » Fri May 26, 2017 1:18 pm

calus Fri May 26, 2017 1:18 pm
Where is the module SDK ?

I see in 3.04 release:
"Removed the module SDK from the Standalone archives. We will provide them via a separate download link."
Where is the download link ? :?



Also,
Goldorak wrote:The module SDK will be getting a large overhaul as we get closer to 3.1 release.

Will the large overall come with 3.07 ?
Pascal ANDRE
calus
Licensed Customer
Licensed Customer
 
Posts: 1308
Joined: Sat May 22, 2010 9:31 am
Location: Paris
Next

Return to Module Development


Who is online

Users browsing this forum: No registered users and 1 guest

Tue Mar 19, 2024 9:58 am [ UTC ]