exploring mentalray phenomena

david | mel script,mentalray,rendering,tutorials | Wednesday, November 21st, 2007

In the "Introduction to Mentalray" section of the maya documentation I read this:

The Phenomenon concept provides the missing framework for the completion of the definition of a scene for the purpose of rendering in a unified manner.

It inspired me to find out more about this concept and to see if I could do something useful with it.

A phenomenon is a mentalray shader network that has been exported in a special format that allows it to appear like a custom shader as a single node with its own interface.

I conceived a simple task as a practical way of exploring how to create a phenomenon. My aim would be to take one of the mentalray Data Conversion shaders called mib_color_mix and give it a make-over so people will find it easier to use.

Click here to read the full article describing the steps I took to achieve my aim.

Download dj_mix_colors example files here.

The objective:


The mentalray mib_color_mix is a bit like the maya blendColors . The main functional difference is that blendColors can mix 2 inputs, where as mib_color_mix can mix 8.

I think the blendColors Attribute Editor interface is simple and intuitive


but the mib_color_mix has a confusing layout


So I decided to reorganize the layout of the interface by creating a phenomenon, which will be called dj_mix_colors.

Creating the .mi file:

A phenomenon file is a simple text file that, in theory, could be written from scratch using a text editor. But it is much easier to create the file using the phenomenizer node in the maya hypershade window.

In the hypershade window I started by creating a mentalrayPhenomenon node (aka the phenomenizer) which is found in the Miscellaneous section of the mentalray render nodes list.


Next I created a mib_color_mix node (from the Data Conversion section).


To begin the build process I shift-middle-dragged the mib_color_mix onto the mentalrayPhenomenon which causes the connection editor to open.


I clicked message on the left and root on the right which makes a connection that tells the phenomenizer that mib_color_mix will form the basis for my phenomenon. The hypershade shows it like this.


Next I have to tell the phenomenizer what parameters I want to be visible in the Attribute Editor window of my new phenomenon. So I shift-middle-dragged the mentalrayPhenomenon onto the mib_color_mix. This is the opposite of what I did just before, so now mentalrayPhenomenon is on the left and mib_color_mix on the right.

My make-over of mib_color_mix is mainly concerned with the layout of the interface so I want most of the existing attributes to be visible in my new AE interface. I have to select them one by one in the connection editor.

I started by clicking interface on the left and num on the right to make the connection. In the image below you can see how the connection editor has updated to show this connection - between interface[0] and num. In particular, notice how there is now a new interface[1] parameter on the left.


I continued connecting the mentalrayPhenomenon interface[?] parameters to the mib_color_mix parameters.


Eventually I had made connections for all the parameters that I wanted in myphenomenon.


Later I will explain more about why I chose to omit certain parameters.

The hypershade now looks like this


I opened the mentalrayPhenomenon in the Attribute Editor window and named my phenomenon dj_mix_colors, as shown below.


Notice that in the Apply Flags tab I have set the Texture flag. This mean that maya will eventually place my phenomenon in the Textures section of the mentalray render node list.

Next I selected the mentalrayPhenomenon node (which is now called dj_mix_colors) and from the maya File menu chose Export Selection... [] to open the export options.

I set the following options: File type = mentalRay, Renderable scene, Default file extensions, ASCII, tab 4, Compression Off, Export selected items only, Predefined export filters Factory shaders, Phenomenizers.

Then I clicked Export Selection and named the file dj_mix_colors. A file extension of .mi is added automatically.

The raw phenomenom:

I then used the Shader Manager window to load my dj_mix_colors.mi into maya.



The folder shown here, d:/mentalray/include, is specified as my MI_CUSTOM_SHADER_PATH in Maya.env This is where I place custom shaders that I have downloaded. It is a different location to the maya installation so that I dont accidentally mess it up.

Adding a new shader (or in this case a new phenomenon) with the Shader Manager causes the hypershade window to be redrawn and the additional render node is added to the Create list. When I created the phenomenon, I specified the ApplyFlag to be Texture so now I navigated to the Create mental ray Nodes|Textures section to locate dj_mix_colors, where I found it with a blank icon.

I dragged it into the work area and opened the new node with the Attribute Editor. At this point I was a little disappointed. My new phenomenon had virtually the same AE layout as the original mib_color_mix.

As it turns out, creating the .mi file is only part of the story. Next we need an Attribute Editor Template file.

But it renders black!

I hooked up dj_mix_colors to the material slot in a shading group and did a test render to make sure it worked. So far so good! I closed maya and restarted it. dj_mix_colors now loads automatically like my other custom shaders since it is in the same folder, so no need for the Shader Manager window. But this time when I render it is all black!

I spent a long time trying different things, including unloading and reloading the shader with the Shader Manager window. Nothing seemed to work, so I created it again from scratch and it worked so long as I didnt exit maya after exporting the .mi file.

Lucky for me I found help at http://forum.lamrug.org where Bart posted the solution. The problem is the order that maya loads shader files combined with me putting my custom shaders in a different folder to the maya installation. Since a phenomenon depends on other shaders (in this case mib_color_mix) then maya needs to have loaded those shaders before it loads the phenomenon. Unfortunately the mel script that tells maya where to look for shaders puts the maya base shaders last in the list.

To change the list order I had to edit mentalrayForMaya.mel (from the scripts/others folder of the Maya installation location). I did not edit the original file though. I made a copy to my local scripts folder and changed that one instead.

I changed

$shaderPath = $env + ";" + $mrayInclude;


$shaderPath = $mrayInclude + ";" + $env;

and restarted maya.

AE Template File and dj_mix_colors.mi:

Next I wanted to control the way dj_mix_colors appears in the Attribute Editor window. This was really my main objective from the start. I want a more intuitive user interface. To achieve it I had to edit the contents of dj_mix_colors.mi and create an Attribute Editor Template mel script. These two files work together to define the look of the interface. The .mi file defines the parameters and the AE Template files defines the layout of those parameters in the editor.

I wont go into too much detail about the specific mel commands here. You can download my phenomenon and all associated files at the end of this article. Look at them in a text editor to get some idea of the syntax involved.

The .mi file that is exported from maya is just a "bare bones" file. By looking at other custom shader .mi files I was able to discover additional things that can be included to refine the parameter definitions. If you compare the two .mi files that I have provided you will see that the final dj_mix_colors.mi has statements to define default values for most of the parameters, as well as statements that set minimum and maximum values for them. I added these extra statements using a simple text editor.

The name of the AE Template file is important. For my dj_mix_colors phenomenon the required name is AEdj_mix_colorsTemplate.mel. When dj_mix_colors is loaded into the attribute editor maya looks for AEdj_mix_colorsTemplate.mel and uses the contained mel commands to define the AE layout.

The main mel command in use here is editorTemplate which you can search for in the commands section of the maya user manual. I also studied the AE Template files of other shaders to see examples of how they work. It is a fairly standard mel syntax that specifys how the parameters will be presented in the AE window. The tricky thing here is that this mel script defines a template that will be reused for each occurance of the shader in your scene file, so commands need to be constructed with this in mind.

Forcing my preferences:

Ok I'm nearly done now. Here is a look at the layout I ended up with.


As you can see I have grouped the color layers with their mode and weight parameters to make it easier to see at a glance what is going on. Remember, this is just a reworking of the mib_color_mix shader. Notice that I have hidden from view the mib_color_mix Color Base parameter, because for me it served no purpose. For the same reason I have hard coded the Mode_0 to mix (and hidden it) and the Weight_0 to 1 (also hidden).

I have hidden the Num parameter from mib_color_mix and replaced it with something called Number of Additional Colors. There is a hidden connection between the two; Num = Number of Additional Colors + 1. I did this because I found it confusing that setting Num=2 meant I was using Color_0 and Color_1. In dj_mix_colors setting Number of Additional Colors = 2 means that in addition to Color_0 I am using Color_1 and Color_2. To me this is easier to think about.

Making my Number of Additional Colors happen required an extra parameter called numX to be defined in the .mi file. Then I had to add a new proc to the AE Template that would be called whenever the value of Number of Additional Colors was changed and do the math to assign the correct value to the old hidden Num parameter.

Next I disabled the blend mode called blend. I dont find that mode to be of any use and I think its meaning is not obvious to less experienced users - where as the mix mode does exactly what you would expect. I made mix the default. I couldn't figure out how to hide the blend mode in the drop-down menu


So, to disable blend mode I added another proc to the AE Template which would simply change the mode back to mix if blend was ever selected. A warning message is printed in the info window so the user will know what happened.

Swatches in the hypershade window:

Custom shaders often appear in the hypershade window with generic icons or static icons that do not reflect their state. I prefer the ones that display a swatch - either a color or a shader ball - so that you can see a visual reminder of what the node is doing.

To make this possible for dj_mix_colors required some editing of a local copy of a maya installed mel file called mentalrayCustomNodeClass.mel. I just needed to add dj_mix_colors to the list of texture shaders supported by swatch. (The edited file is included in my example files; I have added DJ MOD comments where I made changes).

Here is a snapshot of a very simple shader network using dj_mix_colors


I have put a ramp into Color_1 and mixed it over a light grey Color_0 using the checker texture to map the Weight_1 parameter. I'm feeding the result into the diffuse color of a mia_material_x.

The icon on the cake:

My final task was to create an icon that would appear in the Create bar of the hypershade window. The required icons are 32x32 pixel .xpm files. I made my icon in photoshop and output it as a .bmp file. Then I used the freely available XnView program to convert the .bmp to an .xpm.

The name of the icon file is also important. It must be called render_dj_mix_colors.xpm and it must be placed in the icons folder.

But there was one last hurdle...

Maya didnt like the .xpm created by XnView. No error message; it just seemed to ignore it. But a .xpm file is just a simple text file so I opened it in a text editor and compared it to the icons of other custom shaders. There I noticed that the first couple of lines (the file header) were different in my .xmp.

So I changed this

static const char *render_dj_mix_colors_xpm[] = {
/* width height num_colors chars_per_pixel */

into this

static char *magick[] = {
/* columns rows colors chars-per-pixel */

Now maya is able to read my icon.



I achieved my objective and dj_mix_colors works the way I wanted. It doesnt do anything that mib_color_mix didnt already do, but it is easier to use. The process of creating this phenomenon was reasonably messy - but I guess I should have expected that since it was my first time. Given the number of hoops that I had to jump through, I can see why there are not many people sharing phenomena online. People with the skill to create more complex phenomenon probably choose to write real shaders instead.

Download dj_mix_colors example files here.


  1. Hi David,
    Thanks for delving into the guts of Mental Ray Phenomena Nodes, great read. Happy Thanksgiving from San Francisco!
    Jacques Broquard

    Comment by jacquesBroquard — November 24, 2007 @ 6:45 am

  2. Hi David
    Great work
    but why you have made 02 .mi files [B]dj_mix_colors.mi[/B] and [B]dj_mix_colors_ExportSelected.mi[/B]??
    your phenomena work perfect with one file [B]dj_mix_colors[/B] !
    anyway thanks you
    H. Rachid

    Comment by rachid — March 2, 2008 @ 7:09 am

  3. Rachid, the dj_mix_colors_ExportSelected.mi is included just to show a mid-way stage in the creation of dj_mix_colors.mi. It is the raw result of using the maya phenomenizer node. After that I modified it to get the final result. I wanted to show people the "before" and "after".

    Comment by david — March 2, 2008 @ 9:49 pm

  4. Can i mix mia_materials with this? If so can you explain how?

    Comment by Rubent100 — September 30, 2009 @ 1:54 pm

  5. Yes, but you'll need the connection editor to hook them up. The mia_material has many possible outputs, but often you'll want to hook up the mia_material_x.result to one of the dj_mix_colors color inputs. Notice that the mia output attribute is called "result" and not "outColor" like in most of the other shaders.

    Comment by david — September 30, 2009 @ 10:49 pm

RSS feed for comments on this post.

Leave a comment

You must be logged in to post a comment.

Powered by WordPress | Based on a theme by Roy Tanck