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®
    LA mental ray Users Group

Introduction

Cutter provides a good level of integration with mental images® shader writing and rendering technologies. Cutter is able to,

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

Item 1 does requires access to a compiler. Linux and MacOSX computers have versions of the GNU compilers pre-installed. Windows users, however, must install MS Visual Studio 8 or MS VC Express 2008.
Item 2 requires either a licenced stand-alone or a demo version of "ray" be installed on a users computer.
Item 3 requires access to the docs that ship with mental ray.

Currently, there are two demo versions of (stand-alone) mental ray available for those who wish to learn shader writing. A demo version is available with the following mental images® publications,
      Programming mental ray, and
      Rendering with mental ray
A second demo version of mental ray is available with Andy Kopra's magnus opus,
      Writing mental ray Shaders
As a side note it appears the CD's that accompany these books are formatted for reading only on Windows computers even though they contain files suitable for Windows, Linux and OSX (32 bit). The CD that accompanies Andy's book has a fully featured version (3.6.54) of "ray" for Windows, Linux and (32bit/64bit) MacOSX. To be honest, it is difficult to see how anyone might become proficient in mental ray shader writing without acquiring Andy's book. The bottom line is, buy Andy's book.

If you have Maya installed on your computer you will not be able to use its built-in "ray" renderer to render an mi scene file. Although Maya has a version of "ray", as part of its Maya-to-mental-ray plugin, it cannot be accessed for the purposes of rendering 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 RayView image

Figure 1


Figure 2

Cataloging

The contents of the RayView 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 automaticall 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 source 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. 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, if tinted_occlusion.c, listing 1, is compiled, Cutter will produce 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 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. If the reader is using the demo version of "ray" from Andy's book they will have to save a modified version of a makefile, or bat file, in their custom_templates directory - more about this later.

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 clicking on the yellow 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. In the case of readers who have access to Andy Kopra's book I recommend they copy the directory
    CD:/mentalray/common/doc/manual
to their "mi" directory. 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 have purchased Volume 1 or Volume 2 of the mental images® books and who wish to install the demo version of mental ray. The names choosen for the shader_src, 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. If you are using the demo version of "ray" installed from the CD included with Andy Kopra's book you should ignore this section and instead refer to Kopra - Writing mental ray Shaders.

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