Share

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) or lib/ (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 from
  • The ARNOLD_PLUGIN_PATH environment variable can also contain one or more plugin paths
  • kick -l <path_to_plugin> may be used to load plugins from a specified path
  • kick 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:

render example

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.

Was this information helpful?