Creating a Simple Plugin - Arnold Developer Guide
Prerequisites
To be able to create Arnold shaders, you need a C++ compiler and the Arnold SDK.
Any recent C++ compiler may be used to compile plugins. Typically GCC or Clang on Linux, Xcode (Clang) on macOS, or Visual Studio on Windows.
You will need to download and extract the Arnold SDK to the folder of your choice. For the purposes of this tutorial, we will assume that you will set the environment variable ARNOLD_PATH
to the path where the Arnold SDK is located.
Simple Shader Example
Here's a very simple example shader plugin, contain a single shader node named simple
that takes a single color
parameter and outputs it.
simple_shader.cpp
#include <ai.h>
AI_SHADER_NODE_EXPORT_METHODS(SimpleMethods);
enum SimpleParams { p_color };
node_parameters
{
AiParameterRGB("color", 0.7f, 0.7f, 0.7f);
}
node_initialize
{
}
node_update
{
}
node_finish
{
}
shader_evaluate
{
sg->out.RGB() = AiShaderEvalParamRGB(p_color);
}
node_loader
{
if (i > 0)
return false;
node->methods = SimpleMethods;
node->output_type = AI_TYPE_RGB;
node->name = "simple";
node->node_type = AI_NODE_SHADER;
strcpy(node->version, AI_VERSION);
return true;
}
Short Description
node_initialize is called only once for each instance of the shader, at the beginning of the first render.
node_update is called once per render call (so, multiple times during progressive rendering or IPR) for each instance of the shader. And this includes the first render.
Summing up, for N calls to AiRender(), you have one call to node_initialize, then N calls to node_update. These numbers are not related to the number of threads at all.
node_finish is called once for each instance of the shader when an AiEnd() is called.
Compiling
Here are example commands for compiling from the command line.
Linux
export ARNOLD_PATH=/path/to/arnold
c++ simple_shader.cpp -o simple_shader.so -Wall -O2 -shared -fPIC -I$ARNOLD_PATH/include -L$ARNOLD_PATH/bin -lai
macOS
export ARNOLD_PATH=/path/to/arnold
c++ simple_shader.cpp -o simple_shader.dylib -Wall -O2 -shared -fPIC -I$ARNOLD_PATH/include -L$ARNOLD_PATH/bin -lai
Windows Visual Studio command prompt
set ARNOLD_PATH=c:/path/to/arnold
cl /LD simple_shader.cpp /I %ARNOLD_PATH%/include %ARNOLD_PATH%/lib/ai.lib /link /out:simple_shader.dll
Compiling in an IDE such as Visual Studio or Xcode is also possible. The main steps are:
- Create a shared library project.
- Add the Arnold
include/
directory to the include directories. - Add the Arnold
bin/
(Linux and macOS) orlib/
(Windows) directory to the library directories. - Link to
libai
Loading the Plugin
All shared libraries in specified plugin paths that contain a node_loader
will be loaded. Plugins paths may be specified in a few ways.
options.plugin_searchpath
can contain one or more paths to load plugins fromThe ARNOLD_PLUGIN_PATH
environment variable can also contain one or more plugin pathskick -l <path_to_plugin>
may be used to load plugins from a specified pathkick
loads plugins from the current working directory
Kick can be used to inspect if the shader is loaded correctly:
$ kick -l <path_to_plugin> -info simple
node: simple
type: shader
output: RGB
parameters: 2
filename: ./simple_shader.so
version: 7.0.0.0
Type Name Default
------------ -------------------------------- --------------------------------
RGB color 0.7, 0.7, 0.7
STRING name
Testing the Plugin
To test how the shader is working, you can use the following simple scene:
simple_scene.ass
### Scene using "simple" shader
options
{
name options
camera "camera"
}
persp_camera
{
name camera
matrix
1 0 0 0
0 1 0 0
0 0 1 0
0 0 30 1
}
sphere
{
name pSphereShape2
center 0 0 0
radius 10
shader "simpleShader"
}
simple
{
name simpleShader
color 1 0 0
}
Render this scene using this command:
Linux or macOS
$ARNOLD_PATH/bin/kick -l <path_to_plugin> simple_scene.ass
Windows
%ARNOLD_PATH%\\bin\\kick -l <path_to_plugin> simple_scene.ass
And you will get the following image:
If the shader cannot be loaded, you will get this error:
00:00:00 10MB ERROR | [ass] line 28: node "simple" is not installed
Metadata
To expose nodes in applications that integrate Arnold, application-specific metadata must be provided.