MayaMan Help Contents

# Extending the MayaMan Magic Shaders Support

MayaMan has the ability to write out RenderMan shaders on-the-fly to emulate your Maya material hierarchies. We have built in support for most of Maya's native shading nodes, but with a bit of work you can extend this support for 3rd party Maya shaders too.

As of mayaman 1.2.58 this facility has been significantly upgraded. If you have been extending the magic shaders then please review this document to see how deployment and management issues have been simplified. It is no longer any need to modify any file that comes with mayaman, nor to add any files to the distribution. The information that mayaman requires is all stored with your plugins.

### The Role Of MAYA_PLUG_IN_PATH

MayaMan assumes that the shading nodes that you want to emulate have been loaded from locations specified in the MAYA_PLUG_IN_PATH, during shader generation mayaman will survey these directories and check each for a folder called 'mm_magic'. Any that have this folder are surveyed for any 'maya_material_description', 'maya_texture_description' and/or 'maya_light_description' files.

MayaMan comes with material, texture and light description files in it's 'shaders' directory and they should be studied for examples and further documentation about their syntax and layout.

### The maya_material_description File

This file lists the top level materials (generally something that implements an illumination equation) that are to be emulated.

For emulation of user shading nodes of this category you need to create an 'mm_magic' folder inside the folder that contains the .mll file that implements the node. Then place a maya_material_description file in that folder.

The general structure of the file is:

`

      # this addes support for a shading node called 'nodeType'
      nodeType
        some_attr
        another_attr
        etc

`

Where 'nodeType' is the case sensitive node name that is to be emulated (must start at the 0th column of the line), then one line (with two spaces used to indent) with the name of each attribute to be passed from maya into the shader's parameter list. There are also a bunch of qualifiers that can be applied to attributes and the description files provided with mayaman should be used as the guide to what is available and when they are needed.

Any attributes listed under a node will be available to the RenderMan source code chunk for that node as 'cat2(_N_,PARAMNAME)', where PARAMNAME is the name of the parameter. See the example below for more details.

### The maya_texture_description File

This file describes which texture shading nodes are supported by MayaMan. It is similar to the maya_material_description file, but describes textures rather than materials.

For emulation of user shading nodes of this category you need to create an 'mm_magic' folder inside the folder that contains the .mll file that implements the node. Then place a maya_material_description file in that folder.

### The maya_light_description File

This file describes which light nodes are supported by MayaMan. It is similar to the maya_material_description file, but describes lights rather than materials.

For emulation of user shading nodes of this category you need to create an 'mm_magic' folder inside the folder that contains the .mll file that implements the node. Then place a maya_material_description file in that folder.

### The maya_magic_shaders.h File

This file contains a collection of library code for supporting the emulation of shading nodes, the actual per-node implementation is now split out into seperate files.

### The mm_magic/MM_<nodeType>.h Files

For each supported node you will find a file in the mm_magic folder that contains two macros which look like: `

      #define NODETYPE_SETUP(_N_)

` and `

      #define NODETYPE_SIM(_N_)

`

In these macros you define your emulation code. The '_N_' parameter is used so that multiple nodes of the same time can be present in one RenderMan shader source file. MayaMan will automatically use a different number for each node when calling each macro, using cat2 to roll this number into variable names allows you to create temporary variables that will be unique to each instance of the node.

The _SIM macro is ultimately responsible for setting the 'outColor' and 'outAlpha' variables (or any other outputs the node is expected to produce), which must be referred to by prepending the '_N_' variable passed to the macro using the cat2 technique described above.

Study the node emulators provided with mayaman, grab one that's close to what you're trying to do and use it as a starting point.

### Nodes That Want To Create Special Extra Output Channels

Some node types will want to create custom extra output channel data. See the notes at the top of maya_texture_description related to eoc for specific details. The example extension below contains an example:

### An Example Extension

If you had a 3rd party shader called 'simpleColor', which had a parameter called 'intensity', it should also produce an extra output channel called 'foo' which is a color. You could extend MayaMan to support that shader by creating a 'maya_material_description' file in the 'mm_magic' subfolder of the location that holds simpleColor.mll. This file would contain:

`

    simpleColor
      intensity
      color_foo eoc varies

`

You would then create a file called 'MM_simpleColor.h' in the mm_magic sub folder undernead the location that holds simpleColor.mll and it would two required and one optional macro to implement your node:

`

    /* this node type has no additional parameter requirements */
    #define SIMPLECOLOR_SURFACE_PARAMS
    #define SIMPLECOLOR_DISPLACEMENT_PARAMS
    #define SIMPLECOLOR_VOLUME_PARAMS
    #define SIMPLECOLOR_LIGHT_PARAMS

    /* do nothing, this node has no globals */
    #define SIMPLECOLOR_GLOBALS

    /* do nothing for setup in this case */
    #define SIMPLECOLOR_SETUP(_N_)

    #define SIMPLECOLOR_SIM(_N_)                       \
      color cat2(_N_,outColor) = color (1,0,0);        \
      cat2(_N_,outColor) *= cat2(_N_,intensity);       \
      foo = cat2(_N_,outColor)               /* assign the EOC */

`

The _SETUP macro is used to initialise local variables and other things that can occur at the top of a source file.

The _SIM macro is called to actually do the work.

An optional _GLOBALS macro can be provided to initialize global variables for the node type, this is called without a numeric argument since the only values you should create/manipulate should be visible to all instances of the node. It is the responsibility of the user to avoid definitions that clash with ones that mayaman will insert... or with the definitions of any other node type that you may use.

The optional _PARAMS macros can be provided to add additional arbitrary parameters to the shader for the node type, this is also called without a numeric argument since the only values you should declare will be visible to all instances of the node. As with the _GLOBALS macro, be mindful of potential duplication. There is one macro for each shader type as a typical use is going to be the declaration of AOV channels and those will typically only be required in the surface shader.

MayaMan could then use this new information to support this shader, ensuring that the value set in Maya's Hypershade for the 'intensity' parameter is passed in correctly. Also, if this were a texture node rather than a material node, then MayaMan would ensure that the value set here for 'outColor' was passed on to any other nodes using that output. The cat2() function used throughout these macros is a simple macro that joins identifiers together to form a single name. The macro will be called with an _N_ setting like "v_4_" and the code will be expanded to 'color v_4_outColor' and so on.

There are many examples to be found in the mm_magic subfolder of the 'shaders' folder of the mayaman distribution, please refer to them for more help if you are writing your own extensions.

DEBUGGING TIP: When you're first getting used to the macro notation it's easy to make mistakes. You can see the shader source that is written out by MayaMan. The source file is written to the 'shaders' subdirectory under the RIB output directory set in the MayaMan Basic Options. However, this file will contain many macros. You can use a cpp.exe pre-processor to view the fully expanded source with a command such as: `

    cpp -Ic:\animallogic\mayaman\shaders ...your include paths... c:\temp\mayaman\shaders\mms_lambert1.sl > expanded.sl

`

This will write a fully expanded version into 'expanded.sl'. If you scroll to the bottom of that file you will see the bulk of the shader source code.

### Share The Wealth

If you have extended the Maya Magic Shaders functionality in a way that could be beneficial to others, it would be great if you could email your changes to support@al.com.au or use the MayaMan mailing list to tell others about it. We would also like to know if you have made any changes to the existing code in maya_magic_shaders.h which have yielded improvements in the emulation.

MayaMan Help Contents