Cutter
Integration with mental ray

return to main index

Introduction

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

1. generate and run makefiles for compiling shaders written in the 'C' language,
2. automatically generate shader .mi files to accompany compiled shaders,
3. render .mi scene files into its own image viewer,
4. perform quick lookup and display of mental images docs for .c and .mi files,
5. write html catalogs of users renders and their associated .mi and .c code,
6. perform quick lookup of "included" and "linked" .h, .mi and .c files,
7. apply syntax coloration to .mi and .c shader source code files.

Cutter offers these facilities to users of Windows, Linux and MacOSX operating systems. This tutorial provides a general overview of Cutter's capabilities. It is assumed the user has a compiler installed on their computer. This is not an issue for those using Linux or MacOSX because GNU compilers are part of their base installation. Users of Windows, however, must install either MS Visual Studio 8 or MS VC Express 2008. It is also assumed the reader has access to either a (stand-alone) fully licensed or demo version of mental ray. Currently, there are two demo versions of mental ray. To differentiate them they are refered to, by these notes, as Demo Limited and Demo Complete.

The mental ray renderer is a product of mental images®, a company based in Berlin. A three volume reference, published by Springer Verlag, addresses the technical details of their rendering and shading technologies. Demo Limited is available on the CD that accompanies both
      Volume 1: Programming mental ray , and
      Volume 2: Rendering with mental ray.
Unfortunately, the CD does not include an installer. For suggestions on how to manually install the renderer the reader should refer to the tutorial, Mental Ray: Setup CD vol I & II. As a side note, it appears the CD that accompanies Volumes I and II is formatted for reading only on Windows computers even though it contains versions of mental ray suitable for Windows, Linux and MacOSX (32 bit).

Demo Complete is available on the CD that accompanies
      Volume 3: Writing mental ray Shaders: A perceptual introduction
                        by Andy Kopra.
The CD that accompanies Andy's book has fully featured versions (3.6.54) of mental ray for Windows, Linux and MacOSX (32bit & 64bit). Refer to the tutorial, Mental Ray: Setup CD vol III, for information of how to setup Cutter to work with this demo version of mental ray. It is recommended the reader purchases Volume 3 because learning how to write mental ray shaders is virtually impossible without it. An additional source of valuable information about mental ray and shader writing is the Los Angeles mental ray Users Group.

This tutorial assumes that Cutter's preferences have been set appropriately. Refer to either Mental Ray: Setup CD vol I & II or Mental Ray: Setup CD vol III for more information about this topic.

Rendering

When a .mi scene file is open on Cutter's desktop it can be rendered using the keyboard shortcut alt + e, control + e or apple + e (OSX). Cutter establishes a connection with mental ray that enables it to display a rendered image as it is processed by the renderer - figure 1.

Figure 1

Cutter's Process Monitor window displays the messages returned by mental ray. Information is displayed in black text, warnings are colored blue while errors are displayed in red. Immediately before rendering a .mi scene file, Cutter calls killall (Linux and MacOSX) or pskill (Windows) to shut down existing renders. This is to prevent an accumulation of orphan processes. Cutter has a built-in image viewer called RayView. The RayView window (figure 1) works in much the same way as mental images® imf_disp utility except that it acculumates images that can be scrolled and saved as JPEG's. RayView allows, via a popup menu, a sub-region of an image to be re-rendered. The popup menu shown in figure 1 is activated by right-mouse clicking (control-clicking on OSX) on a RayView image.

Compiling and Linking a Shader

The same keyboard shortcut used for rendering can also be used to compile and link a shader when its source code is open on Cutter's desktop. For example, figure 2 shows the Process Monitor window reporting the successful compilation and linking of a shader called "ambient_occlusion".

Figure 2

Cutter's Use of 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. Cutter writes a makefile/bat file each time a shader is built. For example, when a user builds a shader, say foo.c, Cutter will,
    - look for a template makefile/bat file (more about this later),
    - generate a makefile or a bat file, then
    - execute (Linux/MacOSX) 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 1. It uses a similiar template for MacOSX.

Listing 1 (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 shown in listing 2. Whether or not Cutter is dealing with a template for a makefile or a VS8 bat file, it substitutes text shown in capital letters for values specific to the users environment. For example, in both listing 3 and 4 the strings YOUR_SHADER_NAME is replaced by the name of the shader that is currently being built. Most of the values substituted by Cutter are derived from information contained in Cutter's mi Preference panel.

Listing 2 (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

It is possible to customize the compilation and linking behavior of Cutter. For information about customization refer to the tutorial "Mental Ray: Setup CD Vol 3".

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, if a mi file does exist, Cutter checks if it is authorized to overwrite it. An existing shader .mi file will not be overwritten if it does not begin with the following comment.

    # Generated by Cutter

Cutter generates a shader mi file based on parsing a shader source code file. For example, Cutter interprets text inside the square brackets of a comment as the default values it should specify in a shader .mi file. 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. For example, if tinted_occlusion.c, listing 3, is compiled, Cutter will produce tinted_occlusion.mi - listing 4.

Listing 3 (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 4 (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

MI Documentation

Assuming the location of the directory in which mental image's ("manual") html documentation has been specified correctly (figure 3) users can take advantage of Cutter's ability to quickly lookup topics. In the case of readers who have access to Andy Kopra's book it is recommended they copy the directory
    CD:/mentalray/common/doc/manual
to their "mi" directory (refer to the tutorial "Mental Ray: User Directories"). Figures 4 and 5 show Cutters internal browser displaying docs as a result of alt + double clicking on the function mi_sample in a 'C' file and camera in a '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 3

Double clicking with the alt key down...

Figure 4


Figure 5

Cataloging

The contents of the RayView window can be saved as JPEG files or as a series of images linked to the index web page of a catalog. Figure 6 shows the Save As Html Catalog item.

Figure 6

Once the name and location of the catalog has been chosen by the user, Cutter will automatically generate the thumbnail images and web pages for the catalog - figure 7.

Figure 7

A catalog consists of html documents and two directories of jpeg images. One directory stores the full size rendered images while the other stores 100 x 100 pixel thumbnails. The primary (index) html document displays a grid of thumbnails that are hyper-linked to secondary html pages that display additional text related to the full size image. Text on a secondary page might be .mi scene code or the source code of a shader. The purpose of a catalog is to keep a record of the code base that underpins the production of each rendered image.

Opening Header Files & Source Code

When editing a .mi scene file, right mouse clicking (MacOSX control + click) within the name of a "included" or "linked" file will raise the popup shown in figure 8. The text within the quotations is automatically selected by Cutter. In the case of the user choosing to open a "linked" shader, Cutter will attempt to open the shaders source code. This only works, however, if a users custom 'C' language source code files are saved in their "shader_src" directory - refer to the tutorial Cutter: mi Preferences.

Figure 8

The same facility exists for shader source code files. For example, "shader.h" (figure 9) was opened using the Open Selection menu item. Clicking the procs button, located in the upper panel of a text window, 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 display the structs defined in all the header files contained in a directory.

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