Adding Parameters

Here we will add more different parameters to our shader and they will be integrated to the Maya interface. This will allow us to have an easy way to modify our shader in Maya.

3.1 Creating the shader

We can add a new shader to the previous shader loader we created in the previous section:

First, create the shader:


Enum values

Strings for enum values should not start with a number. So this: "1st value" is not a valid enum value.


You can see that node parameters of different types are defined, but only the RGBParam is used.
Now, to add the shader to the loader, you only need to add this code to the previous Loader.cpp file from the previous section:


You will be able to compile the loader again as described in the previous section, check that Arnold can load the shader correctly, and copy the compiled shader to the correct folder so that Maya can use it. If you do so, you will discover that it is usable but not well integrated in Maya.

3.2 Integrating the shader in Maya

To integrate this new shader, we can, as in the first section, add information to the metadata file and create a template script for this shader.

3.2.1 Adding metadata information

To add the metadata information, you only have to add this to the loader.mtd file created in the previous section that you placed in this folder: %MTOA_PATH%\shaders\


This describes attributes that will be used for the Maya representation of the parameters as name, shortname, slider limits, descriptions and default values.

3.2.2 Adding a Maya template

The last task to do is to create a Maya template for this shader. This is similar to the one created in the first section: self.addControl(parameterName, label="Parameter Label"). But adding the rest of the controls. The correct control for each attribute will be created automatically.
Create an file in %MTOA_PATH%\scripts\mtoa\ui\ae\ or in any folder that is definded in %MTOA_TEMPLATES_PATH%

When you use the ParametersShader in Maya, you will be able to see this Attribute Editor for it.

Figure 4: ParametersShader Template

Now you will be able to configure your shader's input parameters from Maya. 

3.2.3 Avoid Space Optimization in the Template

Maya automatically tries to optimize the layout space, for example, if in the previous code you change from this:

To this:

You will see this result:

Figure 5: Optimized Template

To avoid this, we can use this code instead:

And you will get this result:

Figure 6: Optimized Template

3.2.4 Method called when an attribute is changed

Sometimes we may need a certain action to be performed everytime an attribute is changed. For example to evaluate that the introduced value is correct. Let's imagine we require that the value of the uinteger attribute is always greater or equal to the integer attribute. We can try to achieve thit with the following code.

Now everytime that that the integer attribute is updated, if it has a value greater that the uinteger value, this will be increased to be equals to that value. But, of course, if you decrease the uinteger parameter, this could be lower than the integer one. To deal also with this case we can easily write this code:
3.2.5 Enabling and Disabling a Control

Sometimes some parameters does not have any meaning depending on other attributes values. For example, let's imagine that the float attribute only makes sense when the bool attribute is true. We can make this clear for the user if disabling the float attribute when bool is false. To do this, first we can define a  hangeCommand method as in the previous section, and use there the arnoldDimControlIfFalse method to disable the attribute. Here is an example:

If we want the opposite, making the float attribute to be enabled only when bool if false, you can use aeUtils.arnoldDimControlIfTrue instead of aeUtils.arnoldDimControlIfFalse. But in some cases the condition to enable or dissable an attribute could be more complex. For example we may enable the float value only in the case that the red component of color is greater than 0. You can write a code like this for that case:
3.2.6 Creating a custom control

MtoA will automatically create a control for the attributes based on its type, but sometimes you may need more flexibility and create a custom control for a certain attribute. For example, let's imagine that the string attribute in the previous example is used to point to a file. Then you may want a control with a button that shows a file explorer so you can enter the file name in a more intuitive way. Here is an example to get that behavior: 

3.2.7 Summary of Template Commands

Here we will summarize all the previously used template methods and add some new ones:

As previously seen, this command creates a Swatch in the Attribute Editor that shows a preview of the Shader.

beginScrollLayout endScrollLayout
Begins and ends a Vertical Scroll Layout where you can place sections and attributes.

beginLayout endLayout
Begins and ends a Layout. You can give it a name and define if it will be collapsed or not by default.
self.beginLayout("Section Name", collapse=False)

Creates a control for a shader attribute. It automatically creates the correct control depending on the type of attribute. You can define alabel and a changeCommand.
self.addControl("attrname", label="My Attr", changeCommand=self.changeAttr])

Creates a custom control for a shader attribute.
self.addCustom(attrName, newMethod, replaceMethod)

Adds a separator in the layout.

beginNoOptimize endNoOptimize
Stops and starts again the layout space optimization.

Creates a section that will allow you to connect a bump normal mapping to the shader.

All extra attributes will be grouped in an ”Extra Controls” section.

Creates a ”Type” scroll list where you can change the shader type of the node.

Creates the ”Node Behavior” section in the shader template.


  • No labels