Shader Compilation and Linking

    code "filename"

The named filename is interpreted as a C source file, ending with the extension ".c", is compiled and linked into mental ray. From this point on, the shaders it defines are available in mental ray as shading functions. For example, if the source defines a C function myshader, with the usual three parameters result, state, and paras (see chapter shaders for details), the name myshader may be used in materials, lights, textures and so on as the quoted shader name. The command-line option -code provides an alternative way of compiling and linking C source. Multiple code commands are possible. This is intended mainly for debugging because linking precompiled shader libraries is much more efficient. Note that every shading function must also be declared; see section declaration.

Compiling C++ code requires that the shader function prototypes and any included mental ray headers such as shader.h are included in extern "C". It may also be necessary to switch the compiler using the -c_compiler and -c_linker command-line options.

    $code  
    C source text  
    $end code

The $ signs must appear in column 1 of the line. This command also compiles and links C source code, but the code is read directly from the .mi file rather than from a separate source file. The C source text follows standard C syntax. In fact, it is written out to a temporary file, which is then compiled as if a code command had been used. Multiple $code commands are allowed. Note that every shading function must also be declared; see below. C++ requires the same steps as for the code command.

    link "filename"

Like the code command, the link command attaches external shaders to mental ray, which can then be used as shading functions. While the code command accepts ".c" files as filename, the link command expects either object files ending in ".o", or dynamic shared object (DSO on Unix, DLL on Windows NT) files ending in ".so". Object files are linked, while DSOs are just attached without any preprocessing. DSOs are the fastest way of attaching an external shader, and require no compilers or development options, which are sometimes sold separately by system vendors [10]. However, certain old systems do not support DSOs. The -link command-line option provides an alternative way of linking object files and DSOs. Any number of files can be linked. Note that every shading function must also be declared; see section declaration. If Dynamical Shared Objects are to be linked on Unix machines, the LD_LIBRARY_PATH or LD_LIBRARYN32_PATH (SGI) environment variable must include the path of the DSO file to be linked; see section dynlink.

[10] For system and development software requirements, see the Release and Installation Notes.