To be able to create Arnold shaders, you need these three components installed: a C++ compiler, the Arnold SDK and the MtoA plugin.
You will need a C++ compiler to create your shaders. If you work in Windows, Visual Studio 2008 or 2010 will be required.
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
PATH to that folder using this command:
The ﬁrst 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).
To create your ﬁrst Arnold shader, write the following code in a ﬁle 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 ﬁle
Execute the following commands in a console:
g++ -o simpleShader.os -c -fPIC -D_LINUX -I$ARNOLD_PATH/include simpleShader.cpp
g++ -o simpleShader.so -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 ﬁrst 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
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 ﬁle that will be automatically used when the shader is loaded. This way, it willbe easier to make modiﬁcations without having to recompile the shader. This will also keep the Maya speciﬁc 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 maya.name, the shader is automatically assigned a name that is its Arnold node name preﬁxed by ai. In this case, the name would be aiSimple.
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 - 0x7ﬀﬀ (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 - 0xﬀﬀf (524288 ids). If you customize one of these example plug-ins, you should change the id to avoid future conﬂicts.
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 preﬁxes. Once this has been obtained, use the MTypeId constructor that takes 2 unsigned int parameters. The preﬁx goes in the ﬁrst 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.
If you also want to create a Maya interface for this shader, create the following ﬁle:
addControl method, the ﬁrst argument is the shader attribute name or the maya.name metadata of that attribute. So in this case the parameter could be:
Note that the name of the deﬁned class should be:
AE<shader_name>Template and the ﬁle name
<shader_name> is the value of the maya.name metadata of the shader.
In order that your shader works correctly in Maya, it is very important that you name and place the ﬁles in the correct locations. You should have three ﬁles:
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
This is the ﬁle where all the metadata information is located. This will add information that Maya needs about the shader. The name of this ﬁle must be the same as the compiled file, but with a .mtd extension. In this example, the file name is simpleShader.mtd . This ﬁle will have to be copied to the same folder where the compiled shader is located.
This is the ﬁle where the Maya Template for this shader is deﬁned. The name of this ﬁle and the class name inside it has to follow the rules from previous section. In this example it is mySimpleTemplate.py. This ﬁle can be copied to this folder:
%MTOA PATH%\scripts\mtoa\ui\ae\ or to any other folder that is included in the environment variable
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
It is also possible, though not recommended, to place Maya metadata in the code, instead of using a metadata ﬁle. The following example code shows the syntax for this; but remember that a separate metadata ﬁle is more ﬂexible.
A good use for this method could be to add needed metadata that is not speciﬁc to any plugin.