Mental Ray Shaders in 3ds Max

Introduction

This topic describes how a developer can use a mental ray shader to work with 3ds Max. Part of this document also applies to integrating custom phenomena. This document does not describe the details of shader writing and will mainly focus on how the shader's code (or executables) can be used to work within 3ds Max. For information on writing mental ray shader see the mental ray documentation.

The mental ray Connection

The mental ray Connection is a component of 3ds Max that acts as a bridge between the mental ray shaders and 3ds Max, providing UI support for these shaders in 3ds Max. The mental ray Connection supports shaders written in the mental ray Scene Description Language (.mi files).

At startup time, the mental ray Connection looks for shaders installed in a number of locations for 3ds Max, loads them into memory and makes the necessary connections between the shader (specifically its parameters) and the UI of 3ds Max. There are three default install locations:

• Automatically-loaded shaders:

  Shaders configured in the automatic load location are loaded in no particular order, and are assumed to have matching .mi and .dll file names, i.e. same name but different extensions. The .mi files are stored in: [3ds max install]\mentalimages\shaders_autoload\mentalray\includeand the dll files are stored in: [3ds max install]\mentalimages\shaders_autoload\mentalray\shaders

• 3rd party shaders:

  Shaders whose .mi and .dll file names do not match cannot be auto-loaded. In this case their files are stored in the 3rd-party shader location and are linked using the information provided in a file named 3rdparty.mi. The shaders' .mi files are stored in: [3ds max install]\mentalimages\shaders_3rdparty\mentalray\include. The shader's .dll files are stored in: [3ds max install]\mentalimages\shaders_3rdparty\mentalray\shaders

  To associate .mi files to their .dll components using the 3rdparty.mi file, refer to the section Configuring Shader Installation via 3rdparty.mi.

• 3ds Max standard shaders:

  (The following information is provided for instructional and trouble-shooting purposes only).

  These shaders are core components of 3ds Max. Modification of their contents and configurations is not recommended nor supported. These shaders are located under: [3ds max install]\mentalimages\shaders_standard\mentalray.

  It is recommended that developers wishing to install shaders for use with 3ds Max do so only under the auto-load or the 3rd party shader locations.

Shader Declarations

For a mental ray shader to work in 3ds Max (during mental ray renders) a scene description language declaration (a .mi file) is required and possibly the location of its implementation. 3ds Max will generate a basic UI for the shader's parameters.

Phenomena

A phenomenon works as a wrapper for one or more mental ray shaders, to combine their effects or make their user interface simpler for the user. Mental ray phenomena do not require a DLL, so the developer is only required to describe them in .mi files. The following is an example phenomenon named MyBlueDGS that includes a shader named dsg_material:

declare phenomenon
    color "MyBlueDGS" ()

    shader "dgs_material" "myDgs" (	"diffuse " 0 0 1, )
   	root = " myDgs "
   	apply texture
end declare

Shader with Embedded C/C++ Code

Writing an embedded shader can sometimes be useful for the user who has to deal with cross platform development issues like having shaders compiled to .so files instead of .dll. Here is an example file (stark.mi):

$code
#include "shader.h"
DLLEXPORT int stark_version(void) {return (1);}
DLLEXPORT miBoolean stark(miColor*result, miState *state, miTag *light)
{
    miScalar dot_nl;
    mi_trace_light(result, 0, &dot_nl, state, *mi_eval_tag(light));
    result->r = dot_nl > 0.4 ? 1 : .2;
    result->g = dot_nl > 0.7 ? 1 : .2;
    result->b = dot_nl > 0.0 ? 1 : .2;
    result->a =1;
    return (miTRUE);
}
$end code

declare shader "stark" (light "light") 
version 1 
apply texture
end declare

This is relatively easy to use, but has a negative impact on the start-up of 3ds Max, because the mental ray Connection has to compile every embedded shader in the .mi file on start-up.

This approach is not recommended for production shaders, except when doing rapid prototyping or debugging.

Creating a shader with its matching DLL

This is an alternative to embedding C/C++ code in a shader. The developer needs to create separate .mi and .C/.CPP files compiled to a .DLL. The following is an example of this case:

declare shader "stark" (light "light") 
version 1 
apply texture
end declare

#include "shader.h"
DLLEXPORT int stark_version(void) {return (1);}
DLLEXPORT miBoolean stark(miColor*result, miState *state, miTag *light)
{
    miScalar dot_nl;
    mi_trace_light(result, 0, &dot_nl, state, *mi_eval_tag(light));
    result->r = dot_nl > 0.4 ? 1 : .2;
    result->g = dot_nl > 0.7 ? 1 : .2;
    result->b = dot_nl > 0.0 ? 1 : .2;
    result->a =1;
    return (miTRUE);
}

In this example the file "shader.h" is found at: [3ds max install]\ mentalimages\dev\include \shader.h

The 32-bit DLL will need to be compiled against the library: [3ds max install]\ mentalimages\dev\lib32 \shader.lib

The 64-bit DLL will need to be compiled against the library: [3ds max install]\ mentalimages\dev\lib64\shader.lib

It is recommended to use MS Visual Studio .NET to compile the DLLs, but unless the shader has some interaction with 3ds Max SDK, other compilers might be used as well.

Shader with Linked C/C++ Code

It is possible for a user to write a shader with embedded C/C++ code, but to have the source code in a separate C/CPP file. This makes it possible to test compilation of a shader without starting the main application.

As with the embedded C/C++ code, since this technique does not involve a separate DLL, the product will need to compile the shader on startup. Here is an example:

(stark.mi)

(stark.mi)
registry "{stark}"
    code "[source location]\stark.c"
end registry
$lookup "{stark}"

declare shader "stark" (light "light") 
version 1 
apply texture
end declare

Compilation Process

When the mental ray connection compiles a shader compilation errors are sent to the message log. To open the message log, go to the Rendering menu and select "Render Message Window…". The message dialog can be set up to automatically open when errors are triggered.

Configuring Shader Installation via 3rdparty.mi

The file 3rdparty.mi allows the developers to install shaders that do not use the automatic load location of the mental ray Connection, or do not have a matching .dll and .mi file names. The file is stored in: [3ds Max install]\mentalimages\shaders_3rdparty\mentalray\3rdparty.mi

As an example, consider the case that the developer creates three .mi files to contain the shader declarations.

• MyLibPart1.mi
• MyLibPart2.mi
• MyLibPart3.mi

registry "{_AUTODESK_REG_3DSMAX_LOAD_3RDPARTY_SHADERS}"

# Note: this is a comment. 

link "mentalimages\shaders_3rdparty\mentalray\shaders\MybigLib.dll"
mi mylibpart1.mi
mi mylibpart2.mi
mi mylibpart3.mi
 
end registry

For more information please refer to the mental ray documentation.

Apply Statements

The apply statements are used by 3ds Max to restrict the listing of a shader in various locations of the 3ds Max UI. For example, the statement apply lens in a .mi file indicates that the declared shader is a lens shader for cameras and will not show up in the UI when browsing for other kinds of shaders. Shaders that have multiple uses may declare multiple apply types.. While the mental ray shader is not strict about using the apply statements, the Connect will force the developer to use apply statements to clear out the application of the current shader for the user. For more information about apply statements and supported apply types see the "Shader Apply Flags" topic in the mental ray documentation.

GUI Attributes

GUI attributes are extensions to the .mi syntax that allow authors to further refine the declaration of a shader for use in 3ds Max. Some examples of the shader aspects that can be controlled via GUI attributes are:

• Change the shader's name in the UI
• Change any parameter's name in the UI
• Define a default value for each parameter (default sub shader as well)
• Define ranges of valid values for parameters
• Provide additional "apply" commands

The use of GUI attributes for UI generation is not strictly required, as 3ds Max will, by default, generate generic UI elements for any parameters defined as part of the shader declaration in a .mi file. GUI attributes are used to modify how the UI elements are displayed in 3ds Max.

GUI attributes are also used for specifying shader types that are supported by 3ds Max but are not natively present in the mental ray syntax for apply statements.

The syntax for declaring GUI attributes in a shader is described in the mental ray programming book. The following example demonstrates adding contour as a new shader apply type using GUI attributes:

declare shader
    "max_BlendMaterial" (
        struct "Parameters" {
            scalar MixAmount
        }
    )
    version 1
    apply material
	
    gui "gui_max_BlendMaterial"
    {
        control "Global" "Global"
        (
            "addApply" "contour"
        )
        control "Parameters" "struct"
        {
            control "MixAmount" "scalar"
            ( 
                "value" 1.0, 
                "range" 0.0 100.0, 
                "hardrange" -10.0 110.0,
                "step" 0.1,
                "helptext" "Determines amount of Material2 in percent",
                "position" 40 30 20 100

            )
        }
    }
enddeclare

By convention, the name of the GUI is the name of the shader with the prefix "gui_" at the beginning. Each control must correspond to a single parameter by name. The control type must also match. "struct" parameters imply a "struct" control type which starts and ends with curly braces '{}' which define a control group. A control that is not a "struct" starts and ends with parentheses '()' and defines a group of attributes. A parameter that has no corresponding control attributes will use default, automatically generated values.

Every attributes may either define one to four scalars (floats), a single character string, or no parameter at all.

It is important to note that the mental ray syntax is very relaxed for GUI attributes. Thus, a developer will have to implement strict consistency checks themselves, and report warnings/errors when inconsistencies are found.

Note that all the strings (attribute & control names) are CASE SENSITIVE.

Shader Attributes

Parameter Attributes