Mental Ray Shader Writing Startup

OK, I am still quite a beginner in this area. This note is about how to compile, load, and use the “Hello World” Mental Shader. The public source is quite a good start point and giving a lot of hints, but I want to make it as simple as possible.

Like RenderMan, MR shaders are written in C. But MR has no dedicated shader compiler, Shader to PRMan, to compile source to machine code. Means even writing the simplest MR shader requires some skill about  C/C++ compiler. On Windows, it is MSVC; On Unix, it is GCC. Here I only cover the Windows side.

In the shader source,  illumconstant.cpp, first include the MR headers:

#include "shader.h"
 #include "mi_shader_if.h"

Typically they are located in directory MAYA/devkit/mentalray/include/, so make sure it is in the header search path. For some unknown reason, shader_sds34.h is missing in the dev package, download it here.

Now define the parameters of the shader, as a struct:

struct zhang_illum_constant_t {
 miColor        surfaceColor;

Just one color in this case. Then define the version number:

extern "C" DLLEXPORT int zhang_illum_constant_version(void) {return(1);}

Finally it is the body of the function:

extern "C" DLLEXPORT miBoolean zhang_illum_constant(
 miColor        *result,
 miState        *state,
 struct zhang_illum_constant_t *paras)
 /* check for illegal calls */
 if (state->type == miRAY_SHADOW || state->type == miRAY_DISPLACE ) {
*result    = *mi_eval_color(&paras->surfaceColor);
result->a  = 1;

The shader does nothing but returns the input color, so it is a Constant. Compile it by build.nt-x64.bat:

cl /TP -c /GR /Zp8 /W3 /GS- /GR /GF /Ox /MD /nologo /W3 /Zc:forScope /EHsc /Ob2 -DQMC -DMI_MODULE= -DMI_PRODUCT_RAY -DWIN_NT -DEVIL_ENDIAN -D_WIN32_WINNT=0x0400 -DNV_CG -D_SECURE_SCL=0 -DBIT64 -DHYPERTHREAD -DX86 -I../../include  illumconstant.cpp
 link /delayload:opengl32.dll /nologo /nodefaultlib:LIBC.LIB /MAP:mapfile /OPT:NOREF /INCREMENTAL:NO /LIBPATH:..\..\lib /STACK:0x400000 ws2_32.lib user32.lib mpr.lib /DLL /OUT:constant.dll illumconstant.obj ../../nt-x64/lib/shader.lib
 mt.exe -nologo -manifest constant.dll.manifest -outputresource:constant.dll;2

This must be run inside MSVC 64-bit command line tool. It links shader.lib which is located in directory MAYA/devkit/mentalray/lib/, so make sure it is in the library search path.

Once it is compile, will bring constant.dll. That is the resulting shader file. Still we need constant.mi:

# guard against multiple inclusions
 $ifndef "constant_mi_included"
 set "constant_mi_included" "true"
min version "2.0.20"
 max version "3.6.99"
#-------------------------------------------- Illumination
declare shader
 color "zhang_illum_constant" (
 color        "surfaceColor",  #: default .2, .7, .9, 1.
 #: nodeid 573101
 apply material
 version 1
 end declare
$endif # if not "my_mi_included"

Basically it declares the shader as a material and set the default value to its parameters. Give it a nodeid, so the custom node will be saved into Maya binary file correctly.

Now copy the .mi file to MAYA/mentalray/include/ and .dll file to MAYA/mentalray/lib/, and reload Maya. On start up, Maya will report parsing and loading those file:

A new node will appear in the MR create materials options:

It has one color parameter:

Assign it to some model and render with MR:

Success! Now you have your first and useless MR shader. Grab the source.


Leave a comment

Filed under Mental Ray

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s