Sections covered:
- Logic
- Arnold shader structure
- MTD file
- Interface file
- Compiling
- Installing
What you’ll need:
- The Arnold SDK [http://www.solidangle.com/arnold/download/]
- A C++ compiler. I like G++ on osx/linux and MingW on Windows (which is a port of G++). But really - any compiler will do the job.
- The Arnold API docs [https://trac.solidangle.com/arnoldpedia/chrome/site/Arnold-4.2.15.0/doc/api/index.html]
Downloads:
- Windows / Arnold 4.2.14.3: colorAttenuationFilter_windows_arnold_4_2_13_4.zip
- OSX / Arnold 4.2.14.3: Check back soon!
Before we start coding, let’s figure out the logic. The light filter will control the light’s colour, depending on a distance from the light source. Since we want a colour gradient, we need two colours - “Color Start” and “Color End”. To control the colour gradient, we will have to define two distances from the light. We’ll call the first one “Attenuation Start” and the second one “Attenuation End”. We’ll name the distance from the shading point (at which the shader is evaluated) to the light source “Light Distance”.
This means, in pseudocode:
if Light Distance < Attenuation Start:
Light Colour = Color Start
else if Light Distance > Attenuation End:
Light Colour = Color End
else:
Light Colour = Some colour in the gradient based on the distance to the light
The only thing we still need to figure out is what colour we should pick when the light distance is in between the two attenuation points. This is easy - we will need to use some kind of linear colour interpolation and supply some percentage. We can calculate this percentage (between 0 and 1):
That’s all the logic there is to it - really rather simple. Now, let’s start writing code.
The basic Arnold shader structure (or template) looks like this. I’ve commented in parts to explain the sections.
// INCLUDE ARNOLD FUNCTIONS
#include <ai.h>
#include <cstring>
// PARAMATER DEFINES IN ENUM
// ARNOLD THINGY
AI_SHADER_NODE_EXPORT_METHODS(lightColorAttenuationMethods)
// PARAMETERS
node_parameters {}
// CALCULATIONS WHEN NODE IS INITIALISED
node_initialize {}
// CALCULATIONS WHEN NODE IS UPDATED FROM UI
node_update {}
// CALCULATIONS WHEN NODE IS KILLED
node_finish {}
// CALCULATIONS AT EVERY SHADING POINT
shader_evaluate {}
// ARNOLD THINGY
node_loader {
if (i > 0)
return false;
node->methods = lightColorAttenuationMethods;
node->output_type = AI_TYPE_RGB;
node->name = "lightColorAttenuation";
node->node_type = AI_NODE_SHADER;
strcpy(node->version, AI_VERSION);
return true;
}
In our case, we’re interested in calculations done at every shading point. For now, we’ll write some code and we’ll worry about the UI integration later.
So, what values do we need from Arnold? We need to know both the distance from the shading point to the light and the light intensity at that shading point. Looking through the Arnold API, we can see that the distance from the shading point to the light can be queried and written. The distance value is stored in sg->Ldist and the light intensity in sg->Liu . And since colour interpolation is a task regularly performed in a raytracer, it already provides a linear colour interpolation function. This can be called with AiColorLerp() .
Writing the logic down then, leaves us with:
...
shader_evaluate {
// temporary variables, we'll do these properly later
AtColor colorStart = {1.0, 1.0, 0.0};
AtColor colorEnd = {0.0, 1.0, 1.0};
float attenuationStart = 20.0;
float attenuationEnd = 40.0;
if (sg->Ldist < attenuationStart){
sg->Liu *= colorStart;
} else if (sg->Ldist > attenuationEnd){
sg->Liu *= colorEnd;
} else {
double percentage = ((sg->Ldist - attenuationStart) / (attenuationEnd - attenuationStart));
sg->Liu *= AiColorLerp(percentage, colorStart, colorEnd);
}
}
...
The logic is working, but now we should make our variables work with the whole Arnold system. Like this, we would have no way to change the variables through the Maya UI.
There’s 3 key parts to this. The variables need to be defined in an enumeration type, they need to be defined in node_parameters{} , and we need to get them inside of shader_evaluate{} .
#include <ai.h>
enum lightColorAttenuationParams {
p_colorStart,
p_colorEnd,
p_attenuationStart,
p_attenuationEnd
};
AI_SHADER_NODE_EXPORT_METHODS(lightColorAttenuationMethods)
...
...
node_parameters {
AiParameterRGB("colorStart", 1.0, 1.0, 0.0);
AiParameterRGB("colorEnd", 0.0, 1.0, 1.0);
AiParameterFLT("attenuationStart", 20.0);
AiParameterFLT("attenuationEnd", 40.0);
}
...
...
shader_evaluate {
// get values
AtColor colorStart = AiShaderEvalParamRGB(p_colorStart);
AtColor colorEnd = AiShaderEvalParamRGB(p_colorEnd);
float attenuationStart = AiShaderEvalParamFlt(p_attenuationStart);
float attenuationEnd = AiShaderEvalParamFlt(p_attenuationEnd);
...
This leaves us with the finished .cpp file! It is worth noting that throughout the process of writing this shader, I continually compile and run it, so Arnold gives me feedback about the variable values and I know whether I’m on the right track. The easiest way to return values with these multithreaded processes is by using AiMsgInfo(“SOME_TEXT %f”, some_float_variable);
#include <ai.h>
#include <cstring>
enum lightColorAttenuationParams {
p_colorStart,
p_colorEnd,
p_attenuationStart,
p_attenuationEnd
};
AI_SHADER_NODE_EXPORT_METHODS(lightColorAttenuationMethods)
node_parameters {
AiParameterRGB("colorStart", 0.3, 1.0, 1.0);
AiParameterRGB("colorEnd", 1.0, 0.3, 0.6);
AiParameterFLT("attenuationStart", 55.0);
AiParameterFLT("attenuationEnd", 105.0);
}
node_initialize {}
node_update {}
node_finish {}
shader_evaluate {
// get values
AtColor colorStart = AiShaderEvalParamRGB(p_colorStart);
AtColor colorEnd = AiShaderEvalParamRGB(p_colorEnd);
float attenuationStart = AiShaderEvalParamFlt(p_attenuationStart);
float attenuationEnd = AiShaderEvalParamFlt(p_attenuationEnd);
if (sg->Ldist < attenuationStart){
sg->Liu *= colorStart;
} else if (sg->Ldist > attenuationEnd){
sg->Liu *= colorEnd;
} else {
double percentage = ((sg->Ldist - attenuationStart) / (attenuationEnd - attenuationStart + 0.001));
sg->Liu *= AiColorLerp(percentage, colorStart, colorEnd);
}
}
node_loader {
if (i > 0)
return false;
node->methods = lightColorAttenuationMethods;
node->output_type = AI_TYPE_RGB;
node->name = "lightColorAttenuation";
node->node_type = AI_NODE_SHADER;
strcpy(node->version, AI_VERSION);
return true;
}
For this tutorial, I’ll be compiling through the command line with G++. If you prefer doing this through an IDE, there’s a tutorial for that on the Arnold support site. What’s important here is that we link the Arnold libraries and set the include path properly, so the compiler can find #include <ai.h>. Don’t forget to change the pseudocode like $PATH_TO or Arnold-X.X.X.X.
On OSX:
If you’re on Linux, I’m sure you can already do this part (lol).
g++ -std=c++11 -03 -o $ZENOCAMERA/src/zoic.os -c -fPIC -D_LINUX -I$PATH_TO/Arnold-X.X.X.X-linux/include $PATH_TO/zoic.cpp; g++ -o $PATH_TO/zoic.so -shared $PATH_TO/zoic.os -L$PATH_TO/Arnold-X.X.X.X-linux/bin -lai
On Windows (using MingW (64 bit version - important!), not the usual cmd prompt):
g++ -std=c++11 -O3 -I”$PATH_TO/Arnold-X.X.X.X-windows/include” -L”$PATH_TO/Arnold-X.X.X.X-windows/bin” -lai -shared $PATH_TO/lightColorAttenuation.cpp -o $PATH_TO/lightColorAttenuation.dll
Now we need to write the .MTD metadata file. These metadata files will be automatically loaded when the library is first loaded.
Extra information on metadata files can be found here: [https://support.solidangle.com/display/ARP/Arnold+Metadata+Files]
Writing this file is rather straightforward apart from a few quirks. We need to supply a HEX number since Maya needs a unique ID assigned to nodes to keep track of custom nodes. You can take whichever number.
# lightColorAttenuation 0x00070155
[node lightColorAttenuation]
desc STRING "Light filter providing control over color attenuation"
maya.name STRING "lightColorAttenuation"
maya.id INT 0x00070155
maya.classification STRING "light/filter"
maya.lights STRING "pointLight spotLight areaLight aiAreaLight directionalLight"
[attr colorStart]
maya.name STRING "aiColorStart"
default RGB 1 1 1
[attr colorEnd]
maya.name STRING "aiColorEnd"
default RGB 1 1 1
[attr attenuationStart]
maya.name STRING "aiAttenuationStart"
softmin FLOAT 0.001
softmax FLOAT 999.0
default FLOAT 0.001
[attr attenuationEnd]
maya.name STRING "aiAttenuationEnd"
softmin FLOAT 0.001
softmax FLOAT 999.0
default FLOAT 0.001
All that’s left to do now is write the Maya interface file. This is a small python file. I won’t go into this as it is pretty self-explanatory.
More information on these interface files can be found here: [https://support.solidangle.com/display/AFMUG/Adding+Parameters]
import pymel.core as pm
from mtoa.ui.ae.shaderTemplate import ShaderAETemplate
class AEaiLightColorAttenuationTemplate(ShaderAETemplate):
def setup(self):
self.beginScrollLayout()
self.beginLayout('Color Attenuation', collapse=False)
self.addControl("aiColorStart", label="Start Color")
self.addControl("aiColorEnd", label="End Color")
self.addControl("aiAttenuationStart", label="Attenuation Start")
self.addControl("aiAttenuationEnd", label="Attenuation End")
self.endLayout()
pm.mel.AEdependNodeTemplate(self.nodeName)
self.addExtraControls()
self.endScrollLayout()
Usually Arnold shaders get organised into two folders, bin and ae. Inside the bin folder go both the compiled shader (.dll, .dylib, .so) and inside the ae folder goes the python maya interface file. It is important that the metadata file is in the same folder as the compiled shader.
Set the following environment variables, replacing “$PATH_TO_SHADER” with the actual path on your machine.
Linux:
export MTOA_TEMPLATES_PATH=$MTOA_TEMPLATES_PATH:$PATH_TO_SHADER/ae
Windows:
ARNOLD_PLUGIN_PATH = $PATH_TO_SHADER/bin
MTOA_TEMPLATES_PATH = $PATH_TO_SHADER/ae
It’s also possible to copy the files into your MtoA install, but I personally prefer the first option. Just copy the files like this:
Files in /bin go to [$MTOA_LOCATION]/shaders
Files in /ae go to [$MTOA_LOCATION]/scripts/mtoa/ui/ae
That’s it guys! Hope it was clear enough. If you’ve got any questions, post it in the comments or send me an email - I’ll make sure to respond.
Powered by themekiller.com
Pal Mezei
Hey. A couple of errors with the tutorial.
- You are missing the -O3 (or the optimizations flag of your choice) from the compilation flags. It doesn’t matter at this scale, but it does with larger shaders.
- You are not correctly querying the parameters. The AiNodeGetParams or the direct access via the macros are not designed to be used during shader evaluate. You need to use the AiShaderEvalParamXXX functions, or else the parameter mappings (i.e., connections to your shader) won’t be picked up.
- There are (rare) cases when this code generates divides by zero.
Zeno Pelgrims
Thanks for these improvements. I’ve updated the code and tutorial! Happy to have learned something here!
Brian
How is enum lightColorAttenuateParams{} associated with node_parameters{} and shader_evaluateP{}. what is the difference between “p_colorStart” and “colorStart”?
David Jensen
hi,
maybe release the compile code as a shader for download too ?
this is very interesting,
thanks for posting
Zeno Pelgrims
Good idea! I’ll add them to the tutorial. For now, you can find an OS X release on my GitHub.
David Jensen
thanks Zeno,
I’m looking forward to the windows version
I will check back
David Jensen
is it uploaded yet ?
I would like to test it ? thanks
Zeno Pelgrims
https://github.com/zpelgrims/arnoldLightFilters/releases/download/v1.0/colorAttenuationFilter_windows_arnold_4_2_13_4.zip
David Jensen
this is useful too
https://support.solidangle.com/display/AFMUG/Creating+a+Light+Filter+Shader
David Jensen
Thanks Zeno. I was pretty close to compiling this using the recipe you set out.
I’m really interested in mixing subtle tones of light in a scene
Using gamut masking and in camera light mixing could create some tonally sophisticated results ?
http://www.livepaintinglessons.com/gamutmask.php
I’m going to check out Zoic too.
There are not many light shaders for Arnold online.
Using ramp as colour, volume and attenuation is something I was trying too.
A 3D ramp over the light frustrum could be interesting too.
Sven
Great Zeno thanks, so little info around about that but it’s so powerful.
mariano
Thank you for taking the time out to write these tutorials. They’re quite helpful.