Cutter
Integration with mental ray

return to main index

Contents

    introduction
    rendering & shader writing
    html cataloging
    open headers & source code
    auto-generation of shader declarations
    makefiles & templates for makefiles
    cutter preferences
            - syntax coloration
            - mi help docs - quick lookup
    mental ray demo version setup

other links

    mental images®
    Los Angeles mental ray Users Group

Introduction

Cutter's scripting facilities provide a good level of integration with mental images® mental ray shader writing and rendering technologies. Cutter is able to,

1. apply syntax coloration to .mi and .c shader source code files,
2. perform quick lookup and display of html docs for .mi and .c files,
3. perform quick lookup of "included" and "linked" .h, .mi and .c files,
4. build shader .so and .dll files from shader source files,
5. render scene files into its own interactive image viewer.

Item 1 does not require an installation of mental ray. Item 2 requires the docs that ship with mental ray (not the demo version) be installed on the users computer. Item 4 requires an "external" compiler. Linux and MacOSX computers have the GNU compilers pre-installed. Windows users must install MS Visual Studio 8 or MS VC Express 2008.

Finally, item 5, requires that either a fully licenced stand-alone version, or a demo version of mental ray be installed on a users computer. The demo version is available with the following mental images® publications,
      Programming mental ray, and
      Rendering with mental ray

The CD's (mental ray version 3.4.3.61) that accompany these books appear to be formatted for reading only on Windows computers even though they contain the files required for Windows, Linux and OSX.

If you have Maya installed on your computer you will not be able to render an mi scene file. Maya has the library version of the mental ray renderer and as such it cannot be accessed for the purposes of rendering stand alone mi scene files.

Rendering & Shader Writing

Alt + e, control + e or apple + e (OSX) are keyboard shortcuts for rendering a ".mi" scene file and for compiling a shader - figures 1 and 2. In both cases a Process Monitor window displays the messages returned by ray or the compiler. Warning messages are colored blue while error messages are displayed in red.

Immediately before rendering a ".mi" scene file, Cutter calls killall (linux and MacOSX) or pskill (windows) to shut down any existing "ray" processes. This is to prevent an "accumulation" of orphan ray processes.

Cutters RayView window (figure 1) works in much the same way as mental images® imf_disp application except that it acculumates images that can be saved as JPEG's. It also enables a sub-region of an image to be re-rendered.

Cutter has a html cataloging facility. A catalog consists of a html document and two directories of jpeg images. One directory stores the full size rendered images. The other directory stores 100x100 pixel (jpeg) thumbnails. The html document displays a grid of thumbnails each of which is hyper-linked to their corresponding full size image.

The popup menu shown in figure 1 is activated by right-mouse clicking (control-clicking on OSX) on a rendered image

Figure 1


Figure 2

Cataloging

The contents of the RayViewer window can be saved as JPEG files or as a series of images linked to an index HTML web page. Figure 3 shows the Save As Html Catalog item. Once the name and a location of the "catalog" has been chosen by the user, Cutter will generate the thumbnail images and HTML web page - figure 4.

Figure 3


Figure 4

Menu's - Open Header Files & Source Code

Right mouse clicking (MacOSX control + click) within the name of a header file raises a popup menu - figure 5. The text within the quotes or angle bracket is automatically selected by Cutter. For example, "shader.h" (figure 6) was opened by control clicking the header file "included" in the document seen in the background. Using the procs button displays a full listing of the structs declared in a header file. Holding down the shift key and clicking the procs button triggers Cutter to read all other headers in the directory.

In the case of a scene file the same facility is available when right mouse clicking on the name of a "linked" .so file. Obviously, Cutter cannot open the compiled shader so it opens the souce code instead. This only works, however, if the users 'C' language source code files are saved in the "shader_src" directory specified in the mi Prefs (refer to figure 13).

Figure 5

Figure 6

Automatic Generation of Shader Declarations

Cutter can generate a shader mi declaration file when a shader is compiled. Before doing so, Cutter checks on the existance and authorship of an existing mi file. If an mi file is not found (in the same directory as the shader source code file) Cutter will proceed to generate one. If, however, an mi file does exist, Cutter checks if it is authorized to overwrite it. If the mi file does not begin with the following comment,

    # Generated by Cutter

the existing mi file will not be overwritten. Cutter generates a shader mi file based on the information in the shader source code file. For example, when tinted_occlusion.c, listing 1, was compiled, Cutter produced tinted_occlusion.mi - listing 2. Cutter interprets text within square brackets as default values. A comment immediately following the concluding ";" of the struct can provide an optional hint about the shaders apply type. The final hint is optional. Cutter generally assigns an appropriate value for the "apply" flag.

Listing 1 (tinted_occlusion.c)

#include "shader.h"
  
struct tinted_occlusion {
    miUint  samples; /* some [16] comment */
    miColor tint;    /* [1 1 1]  another comment */
}; /* [material] optional hint */
  
DLLEXPORT
int tinted_occlusion_version(void) {return(1);}
  
DLLEXPORT
miBoolean tinted_occlusion(
    miColor  *result,
    miState  *state,
    struct tinted_occlusion *params)
{
// remaining source code omitted

Listing 2 (tinted_occlusion.mi)

# Generated by Cutter version 5.0.0
  
declare shader
    color "ambient_occlusion" (
        integer "samples"  default 16,   # some comment
        color "tint"       default 1 1 1 # another comment
        )
    version 1
    # The apply tag is ignored by mental ray. Its used only as
    # a gui hint to the application that uses the shader.
    apply material
end declare

Makefiles/VS8 Bat Files

When compiling a 'C' language shader source code file via Cutter it is not necessary for a user to write and maintain their own makefiles or, on Windows, their own Visual Studio bat files. Instead, Cutter writes and generates a makefile/bat file each time a user builds a shader. For example, when a user builds a shader, say foo.c, (alt + e) Cutter will,
    - look for a template makefile/bat file (more about this later),
    - generate a makefile or a bat file, then
    - execute (Linux/OSX) either,
          make -f Makefile.compileMiShader
      or the command (Windows)
          cmd /Q /C compileMiShader.bat

On Linux, Cutter generates a makefile based on the template Makefile shown in listing 3. It uses a similiar template for MacOSX.

Listing 3 (Makefile.mishader_LINUX)

STRICT = -Wall
CFLAGS = ${STRICT} -g -I/usr/include -I/usr/local/mi/rayinc -I./ OTHER_INCLUDE_PATHS -O3 -fPIC -fno-common
  
YOUR_SHADER_SO_PATH.so : YOUR_SHADER_NAME.c OTHER_OBJ_PATHS
    gcc ${CFLAGS} -c -O3 -fPIC YOUR_SHADER_NAME.c
    ld -export-dynamic -shared -o YOUR_SHADER_SO_PATH.so OTHER_OBJ_PATHS YOUR_SHADER_NAME.o
  
YOUR_SHADER_NAME.o : YOUR_SHADER_NAME.c
    gcc ${CFLAGS} -c YOUR_SHADER_NAME.c
  
all : YOUR_SHADER_SO_PATH.so

On Windows, Cutter generates a bat file, for use with Visual Studio 8, based on the template bat file shown in listing 4.

Listing 4 (Compile_mishader.bat)

cl /c /MD -nologo -I"./" -I"C:\Program Files\mental images\mental ray\include" OTHER_INCLUDE_PATHS YOUR_SHADER_NAME.c
link -nologo -nodefaultlib:libc.lib -opt:noref -incremental:no -dll -out:YOUR_SHADER_DLL_PATH.dll YOUR_SHADER_NAME.obj \
    OTHER_OBJ_PATHS "C:\Program Files\mental images\mental ray\lib\shader.lib"
mt.exe -nologo -manifest YOUR_SHADER_NAME.dll.manifest -outputresource:YOUR_SHADER_NAME.dll;2

Templates for Makefiles

The makefile/bat file generated by Cutter is based on a template. By default there are three operating system specific templates. Cutter searches for an appropriate template file in the following sequence. On linux and MacOSX it first looks for a template called Makefile.mishader_LINUX or Makefile.mishader_OSX located in the users directory,

    custom_templates/Makefile/

If a custom template file does not exist, Cutter looks for a default template, namely, Makefile.mishader_LINUX or Makefile.mishader_OSX located in,

    Cutter_Help/templates/Makefile/

On Windows, Cutter follows a similiar search stategy. Initially, it looks for Compile_mishader.bat in,

    custom_templates/Bat/

If this file does not exist it looks for Compile_mishader.bat in,

    Cutter_Help/templates/Bat/

For most setups it will not be necessary for a user to create a custom template file. However, the search stategy used by Cutter makes it possible for a user, should the need arise, to customize the compilation behavior of Cutter.

Cutter Preferences

Two preference panels deal with syntax coloration for mental ray - figures 7 and 8. The majority of "sub" panels in Cutter have yellow info buttons. Info can be activated by simply clicking on the button. Using the right mouse (control + click on MacOSX) raises a help info window. An examaple of such a window is shown in figure 9.

The only text fields that require entries are shown in figure 9,
    HTML Documentation "manual",
    Shader Source "path" and
    Compiled Shaders "path"

Figure 7

Figure 8

Figure 9

Syntax Coloration

Examples of syntax coloration are shown in figures 10 and 11. The procs { } button allows easy navigation of the main elements of shader code, header and 'mi' scene files. The source files shown below were written by Andy Kopra and Bart Gawboy.

Figure 10


Figure 11

MI Help Documentation

Assuming the location of the directory in which mental image's "manual" html documentation has been specified correctly (figure 12), users can take advantage of Cutter's ability to quickly lookup online documentation. Figures 13 and 14 show Cutters internal browser displaying docs as a result of alt + double clicking on the function mi_sample in the 'C' file and camera in the 'mi' file. Use shift + alt + double click to display the mental images documentation in an external browser. The external browser may be set using,

    Preferences Tool->UI Prefs->Net

Figure 12

Double clicking with the alt key down...

Figure 13


Figure 14

Demo Version of Mental Ray

The following notes are intended to help those who purchase either or both of the mental images® books and who wish to install the demo version of mental ray. The names that you choose for your shader source, shaders and scenes directories in step 2 must match the paths specified in an all-important mental ray document called the rayrc file - its the mental ray "preference" file.

Step 1 - System Files for Linux & MacOSX

    /usr/local/mi

    /usr/local/mi/
                 bin/
                    imf_copy
                    imf_diff
                    imf_disp (not OSX)
                    imf_info
                    mkmishader
                    ray
                 include/
                    base.mi
                    contour.mi
                    geoshader.h
                    mi_version.h
                    mirelay.h
                    physics.mi
                    shader.h
                    subsurface.mi
                 lib/
                    libray.so
                 shaders/
                    base.so
                    contour.so
                    physics.so
                    subsurface.so

The files for the include directory (linux, MacOSX and windows) can be found on the mental images CD in,

    common/include

Step 1 - System Files for Windows

    C:\Program Files\mental images\mental ray

    C:\Program Files\mental images\mental ray\
                 bin\
                    imf_copy.exe
                    imf_diff.exe
                    imf_disp.exe
                    imf_info.exe
                    mkmishader.exe
                    ray.exe
                 include\
                    base.mi
                    contour.mi
                    geoshader.h
                    mi_version.h
                    mirelay.h
                    physics.mi
                    shader.h
                    subsurface.mi
                 lib\
                    base.lib        contour.lib
                    libray.dll      libray.lib
                    physics.lib     shader.lib
                    subsurface.dll
                 shaders\
                    base.dll
                    contour.dll
                    physics.dll
                    subsurface.dll

Step 2 User Files for Linux

    /home/USER_ACCOUNT/mi/shader_src
    /home/USER_ACCOUNT/mi/shaders
    /home/USER_ACCOUNT/mi/scenes

Step 2 User Files for MacOSX

    /Users/USER_ACCOUNT/Documents/mi/shader_src
    /Users/USER_ACCOUNT/Documents/mi/shaders
    /Users/USER_ACCOUNT/Documents/mi/scenes

Step 2 User Files for Windows

    USER_DRIVE_LETTER:\mi\shaders
    USER_DRIVE_LETTER:\mi\scenes
    USER_DRIVE_LETTER:\mi\manual

Step 3 The rayrc File

The rayrc documents shown below have been adapted from versions of the same docs written by Andy Kopra and Bart Gawboy. If the rayrc doc fails to work on your computer it is most likely due to the way I have edited their documents. The .rayrc file (note the leading dot) provides a series of search paths that enable the renderer to find compiled shaders and their accompanying .mi descriptors. The .rayrc file required by linux, MacOSX and windows are almost identical.

If you are working on,

• linux - delete lines 2 to 8
• MacOSX - delete lines 1 to 3 and 6 to 8
• windows - delete lines 1 to 6

Please note the text has been formatted to fit the page. The text shown in blue should be on the same line as the text that preceeds it. For example, lines 13 and 15 have been "broken" with the "newline continuation character" ie. a backslash. It is advisable to ensure the text on lines 13 and 14 are continuous. Likewise, with lines 15 and 16. Do not leave any spaces when you "roll together" the (registry) lines of text.

Linux and MacOSX users should save the edited .rayrc file into the root directory of their USER_ACCOUNT. Windows users should save the rayrc file, without the leading dot, directly into the mental ray directory on their C: drive.

rayrc

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

registry "{MI_DIR}" value "/usr/local/mi" end registry
registry "{USER_DIR}" value "/home/USER_ACCOUNT" end registry

registry "{MI_DIR}" value "/usr/local/mi" end registry
registry "{USER_DIR}" value "/Users/USER_ACCOUNT/Documents" end registry

registry "{MI_DIR}" value "C:/Program Files/mental images/mental ray" end registry
registry "{USER_DIR}" value "USER_DRIVE_LETTER:/mi" end registry

$lookup "{MI_DIR}"
$lookup "{USER_DIR}"

registry "{_MI_REG_INCLUDE}" value "{MI_DIR}/include \
;{USER_DIR}/mi/shaders" end registry
registry "{_MI_REG_LIBRARY}" value "{MI_DIR}/shaders;{MI_DIR}/lib \
;{USER_DIR}/mi/shaders" end registry

link "base.so"
$include "base.mi"
link "contour.so"
$include "contour.mi"
link "physics.so"
$include "physics.mi"
link "subsurface.so"
$include "subsurface.mi"

Step 4 Cutter Directories for Linux & MacOSX

    /home/USER_ACCOUNT/cutter

    /Users/USER_ACCOUNT/Documents/cutter

    java -classpath .:cutter.jar Cutter

    chmod 777 run

    ./run

Step 4 Cutter Directories for Windows

    USER_DRIVE_LETTER:\cutter

    java -classpath .;cutter.jar Cutter