Arnold C++ Shader Writing

return to main index


Cutter version 8.0.5 incorporates, for the first time, features specifically designed to help artists expore the writing of Arnold shaders using the C programming language. This tutorial provides step-by-step instructions on the downloading and installation of the Arnold SDK from SolidAngle, a C/C++ compiler and the configuration of Maya and Cutter.

Step 1: Which Version of the Arnold SDK?

Launch Maya and from the Arnold menu select the "About" item. Note the version number of the "Arnold Core". In figure 1 it shows, on my computer, "". However, the readers version will probably be different.

Figure 1

Step 2: Download the Arnold SDK

Go to:
and choose "Create New Account".

Once you have access to their website go to:
The current versions of the SDK are near the bottom of the page.

Alternatively, go to:
to access all versions of the SDK both present and past.

Step 3: Unzipping the Arnold SDK

Once the .zip or .tgz file that is appropriate for your operating system has been "unpacked" move the folder to a location that suits you. It does not have to be located in a specific directory. For example I have my SDK in this path.
but it could have located it in my Documents folder!

Step 4: Setting Up Maya

On my computer I have created the following directories. However, for the present purposes the Arnold_osl and Arnold_osl/src folders can be ignored (see Arnold OSL: Getting Started for information about the use of the "osl" directories).

             |_ Arnold_osl/
             |            |_ src/
             |_ Arnold_shaders/           <-- compiled shaders and .mtd files will go here
      	                      |_ src_c++/ <-- c++ source code files will go here

The users Maya.env must be edited so that the Arnold mtoa plugin will "know" where to find your custom shaders. (On MacOSX computers the Maya.env file is located in the users Library/Preferences/Autodesk/maya/2019 directory). Add the following environment variable to the Maya.env file.

If a path has already been assigned to the ARNOLD_PLUGIN_PATH environment variable an additional path can be specified using a colon (:) as a path separator. For example,


Step 5: Installing a C/C++ Compiler - Windows & OSX Users Only

Follow these instructions C/C++ Compiler Installation.

Step 6: Setting Up Cutter

Make sure you are using Cutter version 8.0.5 or higher. From the Edit menu open the Preferences Tool and go to the Languages->Arnold SDK tab.
6.1   The first path must point to the location of the unzipped Arnold SDK.
6.2   The second path must point to the full path of your src_c++ folder.
6.3   The third path must contain the full path to your Arnold_shaders folder.

When the paths have been set make sure the Save Arnold SDK button is clicked.

Figure 2

Step 7: Using Cutter to Compile a Shader

From the Templates menu choose Arnold Shader->mkSampleShader.cpp.

Figure 3

7.1   Save the file as mkU2Color.cpp in the,
        maya/projects/Arnold_shaders/src_c++ directory.
7.2   Go to line 33 and change,
        node->name = "NAME_OF_YOUR_SHADER";
        node->name = "mkU2Color";
7.3   Use the keyboard shortcut Alt + e, Control + e or Apple + e to compile the shader.
7.4   Check the Process Monitor window to ensure the shader has been compiled.

Figure 4

If compilation has been successful the maya/projects/Arnold_shaders directory will contain two files, mkU2Color.dll or (depending on the operating system) and mkU2Color.mtd (an Arnold metadata file).

Step 8: Using Cutter to "Render" the Shader

Right mouse button click anywhere in the mkU2Color document. A popup menu will appear. Choose "Render Shader". Cutter will create and open a document named "mkU2Color.ass".

Figure 5

After a short pause a "kick" window will open showing the effect of the shader displayed on a sphere.

Figure 6

Edit line 36 of the mkU2Color.ass file so that the RGB values of the "patternColor 0.7 0 0" parameter become, say, "patternColor 0.7 0 1". Use the keyboard shortcut Alt + e, Control + c or Apple + e to render the .ass file. The lower part of the sphere should now become purple.

Figure 7

A good deal of shader developement can accomplished by modifying the shader C++ code, re-compiling and re-rendering without using Maya.

Step 9: Using the Shader with Maya

Each time Cutter is used to compile a shader it automatically generates/updates an Arnold metadata file. Look into the your Arnold_shader folder and you will find a file named "mkU2Color.mtd". It is this document that Arnold's mtoa plugin will expect to find when it attempts to load the users custom shaders. The .mtd files are maintained by Cutter so there is no need to open or edit their contents.

Launch Maya and open Hypershade. The mkU2Color node should appear in the Arnold/Utility section of the create panel.

Figure 8

If the node does not appear it will because of one of the following reasons:
    - the ARNOLD_PLUGIN_PATH environment variable is incorrect,
    - the node->name = "mkU2Color"; (line 33) is incorrect.

© 2002- Malcolm Kesson. All rights reserved.