Arnold Shaders Tutorial

35 Pages·2012·0.2 MB·English

Arnold Shaders Tutorial
Pedro Fernando Gomez Fernandez
2012/11/16
Contents
1 Creating your first Arnold shader 1
1.1 Pre-requisites . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.1 Installing a C++ Compiler . . . . . . . . . . . . . . . . 1
1.1.2 Installing Arnold SDK . . . . . . . . . . . . . . . . . . 1
1.1.3 Installing MtoA . . . . . . . . . . . . . . . . . . . . . . 1
1.1.4 Installing MtoA — Troubleshooting . . . . . . . . . . . 2
1.1.5 Installing MtoA and Arnold in separate folders (Ad-
vanced) . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Creating a shader . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 Using the shader in Maya . . . . . . . . . . . . . . . . . . . . 7
1.3.1 Adding Maya Metadata to your shader with a meta-
data file . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.2 Choosing a Maya ID for the shader . . . . . . . . . . . 8
1.3.3 Creating the Maya interface for your shader . . . . . . 8
1.3.4 Where to place your files . . . . . . . . . . . . . . . . . 9
1.3.5 Adding Maya Metadata to your shader in its source
code (Advanced) . . . . . . . . . . . . . . . . . . . . . 10
2 Creating a Shader Loader 12
2.1 Two basic shaders . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2 The loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3 Add the metadata file . . . . . . . . . . . . . . . . . . . . . . 15
3 Adding parameters to your shader 17
3.1 Creating the shader . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2 Integrating the shader in Maya . . . . . . . . . . . . . . . . . 19
3.2.1 Adding metadata information . . . . . . . . . . . . . . 19
3.2.2 Adding a Maya template . . . . . . . . . . . . . . . . . 21
3.2.3 Avoid Space Optimization in the Template . . . . . . . 22
3.2.4 Method called when an attribute is changed . . . . . . 24
3.2.5 Enabling and Disabling a Control . . . . . . . . . . . . 25
3.2.6 Creating a custom control . . . . . . . . . . . . . . . . 27
3.2.7 Summary of Template Commands . . . . . . . . . . . . 28
4 Creating a Light Filter Shader 30
4.1 Creating the shader . . . . . . . . . . . . . . . . . . . . . . . . 30
4.2 Integrating the light filter in Maya . . . . . . . . . . . . . . . 31
4.2.1 Adding light filter metadata information . . . . . . . . 31
4.2.2 Adding a Maya template . . . . . . . . . . . . . . . . . 32
i
1 Creating your first Arnold shader
1.1 Pre-requisites
To be able to create Arnold shaders, you need these three components in-
stalled: 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 Win-
dows, 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:
C:\solidangle\releases\Arnold-X.X.X.X-platform
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.
Windows
In order to install MtoA in windows, you will have to download the
requiredversionpackage, forexample: MtoA-0.20.0-win64-2012.exe,
and you will have two options:
1. You can use the installer with the two component MtoA for
Maya 20XX and MtoA for Maya 20XX Env Variables se-
lected.
2. You can use the installer with only the component MtoA for
Maya 20XX selected. In this case you will need to add these
definitions to your Maya.env file
Edit this file:
C:\Users\<User_Name>\Documents\maya\20XX-x64\Maya.env
and add these definitions:
1
MAYA_RENDER_DESC_PATH = C:\solidangle\mtoadeploy\20XX
PATH = %PATH%;C:\solidangle\mtoadeploy\20XX\bin
Now, when you start Maya, you will be able to load MtoA in the Plug-in
Manager.
Of course you can select another folder that suits you better, so for the rest
of the tutorial, we will assume that you have set the environment variable
MTOA PATH to the path where the MtoA plugin is located. In this case, you
should have to execute this command:
set MTOA_PATH="C:\solidangle\mtoadeploy\20XX"
1.1.4 Installing MtoA — Troubleshooting
If after following these instructions, MtoA does not work, try these steps:
If you cannot see the MtoA plugin in Maya Plug-in Manager
If MtoA plugin does not appear atumatically in the Maya Plug-in Man-
ager, try these steps:
1. Check that a file mtoa.mod exists in this folder:
C:\Users\<User_Name>\Documents\maya\20XX-x64\modules
And it contains this text:
+ mtoa any C:\solidangle\mtoadeploy\20XX
2. Try to set the following environment variables in your system:
MAYA_PLUG_IN_PATH=C:\solidangle\mtoadeploy\20XX\plug-ins
MAYA_SCRIPT_PATH=C:\solidangle\mtoadeploy\20XX\scripts
XBMLANGPATH=C:\solidangle\mtoadeploy\20XX\icons
If you can see the MtoA plugin, but it does not load
If you can see the MtoA plugin but it does not load or it crashes when
trying to load, try these steps:
1. Set the following environment variable:
PYTHONPATH=C:\solidangle\mtoadeploy\20XX\scripts
2. Create the following global environment variables
ARNOLD_PLUGIN_PATH = C:\solidangle\mtoadeploy\20XX\shaders
MTOA_EXTENSIONS_PATH = C:\solidangle\mtoadeploy\20XX\extensions
MAYA_RENDER_DESC_PATH = C:\solidangle\mtoadeploy\20XX
PATH = %PATH%;C:\solidangle\mtoadeploy\20XX\bin
2
3. Remove (and backup) your Maya preferences folder:
C:\Users\<User_Name>\Documents\maya\20XX-x64\prefs
4. Try MtoA using a clean Maya installation
5. Try MtoA using a clean configured computer
1.1.5 Installing MtoA and Arnold in separate folders (Advanced)
If you wish to install MtoA and Arnold in separate folders you can do this
by following the next steps after you have installed Arnold and MtoA.
Windows
1. Remove Arnold from MtoA. This will involve two things:
• Remove Arnold libs (ai.dll, OpenImageIO.dll and tbb.dll)
from %MTOA PATH%\bin
• Remove Arnold Python bindings deleting the folders arnold and
pykick from %MTOA PATH%\scripts
2. Add the Arnold bin folder (%ARNOLD PATH\bin) you want to use to the
PATH environment variable.
3. AddtheArnoldpythonfolder(%ARNOLD PATH\python)tothePYTHONPATH
environment variable.
Linux
1. Follow the same steps as in Windows, but the Arnold libs to remove in
the first step would be: libai.so.
2. Add the Arnold bin folder (%ARNOLD PATH\bin) you want to use to the
LD LIBRARY PATH environment variable.
Mac
1. Follow the same steps as in Windows, but the Arnold libs to remove in
the first step would be: libai.dylib and libOpenImageIO.dylib.
2. Add the Arnold bin folder (%ARNOLD PATH\bin) you want to use to the
DYLD LIBRARY PATH environment variable.
3
1.2 Creating a shader
To create your first Arnold shader, write the following code in a file called
simpleShader.cpp.
simpleShader.cpp
1 #include <ai.h>
2 #include <cstring>
3 // A Simple Shader
4 AI_SHADER_NODE_EXPORT_METHODS(SimpleMethods);
5
6 namespace
7 {
8
9 enum SimpleParams { p_color };
10
11 };
12
13 node_parameters
14 {
15 AiParameterRGB("constantColor", 0.7f, 0.7f, 0.7f);
16 }
17
18 node_initialize
19 {
20 }
21
22 node_update
23 {
24 }
25
26 node_finish
27 {
28 }
29
30 shader_evaluate
31 {
32 AtColor color = AiShaderEvalParamRGB(p_color);
33 sg->out.RGB = color;
34 }
35
36 node_loader
37 {
38 if (i > 0)
39 return false;
40
41 node->methods = SimpleMethods;
42 node->output_type = AI_TYPE_RGB;
43 node->name = "simple";
4
44 node->node_type = AI_NODE_SHADER;
45 strcpy(node->version, AI_VERSION);
46 return true;
47 }
To compile the shader, do the following depending on your OS:
Windows
OpenaVisualStudiocommandpromptandexecutethefollowingcom-
mand:
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
Linux
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
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:
node: simple
type: shader
output: RGB
parameters: 2
filename: <path_to_shader>/simpleShader.dll
version: X.X.X.X
Type Name Default
------------ -------------------------------- --------------------------
RGB constantColor 0.7, 0.7, 0.7
STRING name default_name
To test how the shader is working, you can use the following simple scene:
5
simpleScene.ass
1 ### Scene using "simple" shader
2
3 options
4 {
5 name options
6 camera "camera"
7 }
8
9 persp_camera
10 {
11 name camera
12 matrix
13 1 0 0 0
14 0 1 0 0
15 0 0 1 0
16 0 0 30 1
17 }
18
19 sphere
20 {
21 name pSphereShape2
22 center 0 0 0
23 radius 10
24 shader "simpleShader"
25 }
26
27 simple
28 {
29 name simpleShader
30 constantColor 1 0 0
31 }
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
6
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 will
beeasiertomakemodificationswithouthavingtorecompiletheshader. 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:
simpleShader.mtd
1 # simple 0x00070000
2
3 [node simple]
4 maya.name STRING "mySimple"
5 maya.id INT 0x00070000
6 maya.classification STRING "shader/surface"
7 maya.output_name STRING "outColor"
8 maya.output_shortname STRING "out"
9
10 [attr constantColor]
11 maya.name STRING "color"
If you do not give it a maya.name metadata, it will be assigned a name that
is its Arnold name prefixed by ai. In this case it would be aiSimple.
You should have to follow instructions from section 1.3.6 to name and place
this metadata file.
7
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 nu-
meric range 0 - 0x7ffff (524288 ids) has been reserved for such
plug-ins.
The example plug-ins provided with Maya in the plug-in de-
velopment 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-insthatareintendedtobesharedbetweensiteswillneed
to have a globally unique id. The Autodesk Developer Network
(ADN)willprovidesuchid’sinblocksof256. Youwillbeassigned
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 begining 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 comunity, 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 follow-
ing file:
mySimpleTemplate.py
1 import pymel.core as pm
2 import mtoa.utils as utils
3 import mtoa.ui.ae.utils as aeUtils
4 from mtoa.ui.ae.shaderTemplate import ShaderAETemplate
5
6
7 class AEmySimpleTemplate(ShaderAETemplate):
8
9 def setup(self):
10 # Add the shader swatch to the AE
11 self.addSwatch()
8