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.

#include <ai.h>


enum SimpleParams { p_color };

   AiParameterRGB("color", 0.7f, 0.7f, 0.7f);




   sg->out.RGB() = AiShaderEvalParamRGB(p_color);

   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.


Here are example commands for compiling from the command line.

export ARNOLD_PATH=/path/to/arnold
c++ simple_shader.cpp -o -Wall -O2 -shared -fPIC -I$ARNOLD_PATH/include -L$ARNOLD_PATH/bin -lai
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:     ./
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:

### Scene using "simple" shader

 name options
 camera "camera"

 name camera
  1 0 0 0
  0 1 0 0
  0 0 1 0
  0 0 30 1

 name pSphereShape2
 center 0 0 0
 radius 10
 shader "simpleShader"

 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
%ARNOLD_PATH%\bin\kick -l <path_to_plugin> simple_scene.ass

And you will get the following image:

Figure 1: simpleScene

If the shader cannot be loaded, you will get this warning:

00:00:00 10MB WARNING | [ass] line 28: node "simple" is not installed

And this image:

Figure 2: simpleScene Error


To expose nodes in applications that integrate Arnold, application-specific metadata must be provided.


  • No labels