Keywords: main

Next: 3.1 Dynamic Linking of Up: No Title Previous: 2.9 Scene Example

# 3. Using and Writing Shaders

All color, displacement, contour, and other computation in mental ray is based on shaders. There are various types of shaders for different situations, such as material shaders to evaluate the material properties of a surface, light shaders to evaluate the light-emitting properties of a light source, lens shaders to specify camera properties other than the default pinhole camera, and so on.

There are external shader libraries that support compatibility with Alias, Autodesk 3D Studio MAX, Dassault CATIA, SOFTIMAGE, SolidWorks, Wavefront, and others. Much of the power of mental ray relies on the possibility to write custom shaders and link them dynamically to mental ray at runtime. Custom shaders are written in C or C++, using the full language and library support available in these languages.

Here are the steps necessary to create a new shader:

- Write a .mi declaration for the shader, providing the shader name, return type, shader parameter names and types, and the version to mental ray.

- Write a C shader parameter data structure that agrees exactly with the .mi parameter declaration. (The mkmishader utility can do this translation.)

- Write the shader function in C or C++, using the correct signature. The shader computes a result from its shader parameters and the state, and by calling shader interface functions provided by mental ray.

- Write a version shader (same name with `_version` appended to the name) that returns a version number that matches the version number in the .mi declaration.

- If required, write initialization and exit shaders (same name as the shader with `_init` and `_exit` appended, respectively).

- Compile and link the shader, and create a shared library (DSO or DLL). This step can be omitted but DSO/DLLs are easiest to use and much faster to link than objects or sources. Libraries must be installed on all machines on the net that are used as clients or network rendering servers.

- Use a `$include` statement in the scene .mi file to load the .mi declaration and a `link` (or `code` or `$code`) statement to load the shader DSO/DLL (or source code).

Note that if the shader is expected to work on Windows NT, all four function definitions (the shader, the version function, and the init and exit shaders) must be preceded with `DLLEXPORT`. This is a pseudo type specifier that makes the functions visible to users of the generated shader library. On Unix systems `DLLEXPORT` evaluates to an empty word.

The shader is then ready to be used in the scene. These steps are described in detail below.

- 3.1 Dynamic Linking of Shaders
- 3.2 Coordinate Systems
- 3.3 Shader Type Overview
- 3.4 State Variables
  - 3.4.1 Frame
  - 3.4.2 Image Samples
  - 3.4.3 Rays
  - 3.4.4 Intersection
  - 3.4.5 Textures, Motion, Derivatives
  - 3.4.6 User Fields
  - 3.4.7 State Variables by Shader Type
- 3.5 Shader Parameter Declarations
- 3.6 Parameter Assignments and mi_eval
- 3.7 Shader Versioning
- 3.8 Material Shaders
- 3.9 Texture Shaders
- 3.10 Volume Shaders
- 3.11 Environment Shaders
- 3.12 Light Shaders
- 3.13 Shadow Shaders
- 3.14 Photon Shaders
- 3.15 Photon Emitter Shaders
- 3.16 Lens Shaders
- 3.17 Output Shaders
  - 3.17.1 Parallel Output Shaders
- 3.18 Displacement Shaders
- 3.19 Geometry Shaders
- 3.20 Contours
  - 3.20.1 Contour Computation
  - 3.20.2 Contour Store Function
  - 3.20.3 Contour Contrast Function
  - 3.20.4 Contour Shaders
  - 3.20.5 Contour Output Shaders
- 3.21 Functions for Shaders
  - 3.21.1 DB Functions
  - 3.21.2 RC Functions
  - 3.21.3 Sampling with mi_sample
  - 3.21.4 RC Photon Functions
  - 3.21.5 RC Direction Functions
  - 3.21.6 IMG Functions
  - 3.21.7 Math Functions
  - 3.21.8 Noise Functions
  - 3.21.9 Auxiliary Functions
  - 3.21.10 Obsolete Auxiliary Functions
  - 3.21.11 Contour Functions
  - 3.21.12 Memory Allocation
  - 3.21.13 Thread Parallelism and Locks
  - 3.21.14 Messages and Errors
  - 3.21.15 Callable Functions by Shader Type
- 3.22 Initialization and Cleanup
- 3.23 Automatic Source Generation with mkmishader
- 3.24 Shaders and Trace Functions
- 3.25 Example Scene with Custom Shader

Next: 3.1 Dynamic Linking of Up: No Title Previous: 2.9 Scene Example