Creating a Shader

1.1 Pre-requisites

To be able to create Arnold shaders, you need these three components installed: a C++ compiler, the Arnold SDK and the MtoA plugin.

1.1.1 Installing a C++ Compiler

You will need a C++ compiler to create your shaders. If you work in Windows, Visual Studio 2008 or 2010 will be required.

1.1.2 Installing Arnold SDK

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. For example, in Windows, if you have installed Arnold in this folder:


You will set ARNOLD_ PATH to that folder using this command:

set ARNOLD_PATH="C:\solidangle\releases\Arnold-X.X.X.X-platform"


 1.1.3 Installing MtoA

The first thing you have to do is to install MtoA, that is the Maya plugin for Arnold in your system. Depending on your OS, follow the corresponding steps to install it (see the installation instructions).

1.2 Creating a shader

To create your first Arnold shader, write the following code in a file called simpleShader.cpp.


To compile the shader, do the following depending on your OS:


Open a Visual Studio command prompt and execute the following command:

cl /LD /I %ARNOLD_PATH%\include /EHsc simpleShader.cpp /link /LIBPATH:%ARNOLD_PATH%\lib ai.lib

Of course you can also create a Visual Studio project and adjust the settings to specify the include folder, the lib folder, add the ai.lib, and set it to create a .dll file


Execute the following commands in a console:

g++ -o simpleShader.os -c -fPIC -D_LINUX -I$ARNOLD_PATH/include simpleShader.cpp
g++ -o -shared simpleShader.os -L$ARNOLD_PATH/bin -lai


Execute the following commands in a terminal:

gcc -I$ARNOLD_PATH/include -L$ARNOLD_PATH/bin -lai -dynamiclib simpleShader.cpp -o simpleShader

Congratulations! You have created your first shader. Now, to check if Arnold can recognize it, execute the following command: 

%ARNOLD_PATH%\bin\kick -l <path_to_shader> -info simple

If you execute this command in the same folder where your shader is located, the -l <path_to_shader> is not required.

You should get this result:

To test how the shader is working, you can use the following simple scene:


Render this scene using this command:

%ARNOLD_PATH%\bin\kick -l <path_to_shader> simpleScene.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

1.3 Using the shader in Maya

1.3.1 Adding Maya Metadata to your shader with a metadata file

In order that your shader is correctly recognized by Maya, you need to add some metadata to it. The preferred way to do this is to create a metadata file that will be automatically used when the shader is loaded. This way, it willbe easier to make modifications without having to recompile the shader. This will also keep the Maya specific metadata in the MtoA folders, rather than in the shaders themselves (which you might want to re-use outside Maya). 

This is shown in the following code:


If you do not give the shader a, the shader is automatically assigned a name that is its Arnold node name prefixed by ai. In this case, the name would be aiSimple. 

1.3.2 Choosing a Maya ID for the shader

From Autodesk help:

For plug-ins that will forever be internal to your site use the  constructor that takes a single unsigned int parameter. The numeric range 0 - 0x7ffff (524288 ids) has been reserved for such plug-ins. 
The example plug-ins provided with Maya in the plug-in development kit will use ids in the range 0x80000 - 0xfffff (524288 ids). If you customize one of these example plug-ins, you should change the id to avoid future conflicts.
Plug-ins that are intended to be shared between sites will need to have a globally unique id. The Autodesk Developer Network (ADN) will provide such id's in blocks of 256. You will be assigned one or more 24-bit prefixes. Once this has been obtained, use the MTypeId constructor that takes 2 unsigned int parameters. The prefix goes in the first parameter, and you are responsible for managing the allocation of the 256 ids that go into the second parameter. For the purposes of this text, we will use IDs beginning from 0x70000, but feel free to use the IDs that could suit you better. Also, if you are developing a quality shader that you would like to share with the MtoA community, feel free to ask us for an ID granted by Autodesk to MtoA.

1.3.3 Creating the Maya interface for your shader

If you also want to create a Maya interface for this shader, create the following file:

In the addControl method, the first argument is the shader attribute name or the metadata of that attribute. So in this case the parameter could be: constantColor or color.
Note that the name of the defined class should be: AE<shader_name>Template and the file name <shader_name> where <shader_name> is the value of the metadata of the shader.

1.3.4 Where to place your files

In order that your shader works correctly in Maya, it is very important that you name and place the files in the correct locations. You should have three files:

Compiled Shader

This is the shader you compiled, and it will be responsible for the shader behaviour. In this example, it is simpleShader.dll in Windows. You can copy it to: %MTOA_PATH%\shaders\ or to any other folder that is included in the environment variable %ARNOLD_PLUGIN_PATH%

Metadata File

This is the file where all the metadata information is located. This will add information that Maya needs about the shader. The name of this file must be the same as the compiled file, but with a .mtd extension. In this example, the file name is simpleShader.mtd . This file will have to be copied to the same folder where the compiled shader is located. 

Template File 

This is the file where the Maya Template for this shader is defined. The name of this file and the class name inside it has to follow the rules from previous section. In this example it is This file can be copied to this folder: %MTOA PATH%\scripts\mtoa\ui\ae\ or to any other folder that is included in the environment variable %MTOA_TEMPLATES_PATH% 

Now, with everything in its correct place, when you use the aiSimple shader in Maya, you will be able to see this Attribute Editor for it.

Figure 3: Simple Template

1.3.5 Adding Maya Metadata to your shader in its source code (Advanced)

It is also possible, though not recommended, to place Maya metadata in the code, instead of using a metadata file. The following example code shows the syntax for this; but remember that a separate metadata file is more flexible. 
A good use for this method could be to add needed metadata that is not specific to any plugin.


  • No labels