Feature Disabling
Ignore all lens shaders if set to off. The default is on. Ignore all volume shaders if set to off. The default is on. Ignore all geometry shaders if set to off. The default is on. Ignore all displacement shaders if set to off. The default is on. Ignore all output shaders if set to off. The default is on. File output statements are not affected. Note that all five disable options also affect shaders installed by phenomena. This means that the phenomenon can fail if it installs cooperating...
Contour Output Shaders
Output shaders are called after the image has been computed. An output shader can use the function mLget-contourJine to get endpoints of a contour. When mi-get-contour dine returns mi FALSE, there are no more contour lines. Here is a very simple output shader that prints the screen-space coordinates of the contour endpoints. miBoolean my_contour_output_shader miColor result, unused miState state no parameters miContour_endpoint pi miContour_endpoint p2 mi_info Contour endpoints Get and write...
Surfaces Face List
Defaults all nulls except where otherwise noted A translator must provide range, no.surf aces, surf ace_idx, material, gap_vert_info. A translator may provide def_trim_approx, no.curves, curve_idx. def_trim_approx is the approximation for default trimming curves. Default trimming curves are automatically created if the face has no explicit trimming curves attached. The default trimming curve follows the edges of the face. The miAPPROX_DEFTRIM approximation technique, which is allowed only here,...
Diagnostic Modes 1
diagnostic grid off object world camera S21 Draws a colored grid on all objects in the scene visualizing the coordinate space given. The distance between grid lines is S units. This is useful to estimate the size and distances between objects and to visualize the object space of objects. The off argument turns this mode off. diagnostic photon off density irradiance N2J When using photon maps, this mode replaces all material shaders in a scene with an internal shader that produces a false-color...
Functions for Shaders
mental ray makes a range of functions available to shaders that can be used to access data, cast rays, looking up images, and perform standard mathematical computations. The functions are grouped by the module that supplies them. The shader writer may also use C library functions, but it is mandatory to include lt stdio.h gt and lt math.h gt if printing functions such as fprintf use mLinfo or similar for console debugging messages or math functions such as sin are used. Not including these...
Caustics 1
Caustics are turned on or off. They are off by default. Caustics are lighting effects caused by specular focusing of light rays, such as the irregular light patterns on the floor of a swimming pool. Note that caustics are only computed for light sources that specify an energy explicitly. The material shader that receives the caustics must also cooperate, and either the options block or the object to receive caustics must have appropriate caustic flag set. This option controls how caustics are...
OpenGL Acceleration
2JBy default, mental ray uses a scanline rendering algorithm for primary rays when no lens shaders are present that modify the ray direction. This algorithm can cope with both static and motion blurred scenes. In addition, mental ray supports OpenGL hardware to further accelerate scanline rendering of static scenes without motion blurring . If the client host provides OpenGL acceleration with sufficient resolution, mental ray can use this to generate acceleration data that is subsequently used...
Example Scene with Custom Shader
This section shows how to create a .mi file that uses a custom shader that is linked at runtime. This example uses a texture shader, but the same procedure is used to create and link any other type of shader. This texture shader operates in object space and colors the object into eight cubes that meet at the object coordinate origin. A cube mapped with this texture looks like a Rubik's cube for beginners that consists of eight subcubes, each with a different color. The brightness and saturation...
Volume Shaders
Volume shaders may be attached to the camera or to a material. They modify the color returned from an intersection point to account for the distance the ray traveled through a volume. The most common application for volume shaders is atmospheric fog effects for example, a simple volume shader may simulate fog by fading the input color to white depending on the ray distance. By definition, the distance dist given in the state is 0.0 and the intersection point is undefined if the ray has infinite...
Scene Geometry
All geometry is expected to be defined in camera space. Camera space assumes that the camera is at the coordinate origin 0,0, 0 and looks down the negative Z axis. This means that geometry will typically have negative Z coordinates. This is the default. In camera space mode, instance transformations have no effect. All geometry is expected to be defined in object space. Each object, light, and camera has its own coordinate space, typically but not necessarily with the coordinate origin 0, 0, 0...
Table of Contents
Edge Merging and Adjacency Detection 7 Texture, Bump, Displacement, and Reflection Mapping 11 Elliptical Projection Filter Lookup 16 Material Shaders and Photon Shaders for Caustics 27 Physically Plausible Material Shaders 27 Fine-tuning Global Illumination 30 Global Illumination in Participating Media2 1 32 Phenomenon Interface Parameters 44 Trimming, Hole, and Special Curves Special Points 91 Color and Width of Contours 106 Textures, Motion, Derivatives 133 State Variables by Shader Type 135...
Approximations 1
Defaults as set by miAPPROX_DEFAULT miAPPROX_PARAMETRIC, miAPPROX_REGULAR, miAPPROX_SPATIAL, miAPPROX_CURVATURE, miAPPROX_LDA, miAPPROX_ADJACENCY, only for curves miAPPROX_ALGEBRAIC, only for surfaces miAPPROX_DEFTRIM, only for miFace def_trim_approx miAPPEOX_STYLE_NONE, miAPPEOX_STYLE_GEID, miAPPEOX_STYLE_TEEE, miAPPEOX_STYLE_DELAUNAY, miAPPEOX_NSTYLES typedef struct miApprox miGeoScalar miCBoolean miCBoolean miCBoolean enum miApprox_method method enum miApprox_style style miUshort miGeoIndex...
Caustics
Caustics are light patterns that are created when light from a light source illuminates a diffuse surface via one or more specular reflections or transmissions. Examples are The light patterns created on the bottom of a swimming pool as light is refracted by the water surface and reflected by the diffuse pool bottom. Light being focused by a glass of water onto a diffuse table cloth. The light emanating from the headlights of a car the light is emitted by the filament of a light bulb, reflected...
Geometry Shader API
The API module has been patterned after the .mi2 language, to the point where the .mi2 yacc grammar consists almost entirely of one or very few API calls or variable assignments for every statement and clause. To understand the correct order of API calls, refer to the .mi2 language description. The complete yacc grammar that parses the .mi2 language, including C code, is reprinted in the appendix of this document. For information on the syntax of a yacc grammar description, refer to the Unix...
Instances and Instance Groups
Instances and instance groups are used to construct the scene DAG directed acyclic graph . Instance groups are unordered lists of one or more instances. Instances are nodes of the DAG, they reference an item to be placed into the DAG together with a space transformation, optional inheritance parameters, and various flags. Elements that can be referenced by instances are geometric objects, cameras, lights, and instance groups. If more than one instance references the same item, this is called...
Material Shaders
Material shaders are the primary type of shaders. All materials defined in the scene must at least define a material shader. Materials may also define other types of shaders, such as shadow, volume, and environment shaders, which are optional and of secondary importance. When mental ray casts a visible ray, such as those cast by the camera called primary rays or those that are cast for reflections and refractions collectively called secondary rays , mental ray determines the next object in the...
Parameter Types
The declaration gives the type and name of the shader to declare, which is the name of the C function and the name used when the shader is called, followed by a list of parameters with types. Names are normally quoted to disambiguate them from keywords reserved by mental ray. Commas separate parameter declarations. The following types are supported A boolean is either true or false. Possible values are on, off, true, and false. Integers are in the range 231 ,231 1. Scalars are floating-point...
Examples
The following example shader creates an axis-aligned unit cube at the origin. Using unit sizes and centering objects at the origin is usually a good idea because the position, orientation, and sizes of objects are better adjusted with instances than by hardcoding them into the object. This assumes that mental ray is switched to object space mode, which is recommended for all scenes anyway this is done in the options statement . include lt shader.h gt include lt geoshader.h gt int geocube_vers...
Cameras
A camera describes a view of the scene, including the list of files to write, the lens shaders to use, volume shaders to be used as the global atmosphere or fog, global environment shaders that control what happens to rays that leave the scene, and other parameters. Cameras are scene entities that need to be placed in the scene with an instance element. In object space mode see options element above , the location of the camera in world space is determined by the camera instance transformation....
Boxes
Element type miSCENE_BOX Data type miBox int nvert, npri, enum miBox_type type, miBoolean moving Defaults all nulls except stored arguments enum miBox_type miBOX_TEIANGLES, miBOX_ALGEBEAICS A translator must provide vectors, vertices1, primitives. A translator may provide label, next_box using mi_scene_link , visible, shadow, trace, caustic, globillum2J, and mtl_is_label. Provided by miscene.create'. type, vert_info, vect-info, no-vertices, and no_primitives Boxes consists of a miBox header,...
Miscellaneous
The front side of a geometric object in the scene is defined to be the side its normal vector points away from. By specifying that only front-facing triangles are to be rendered, speed can be improved because fewer triangles need to be tested for a ray. This works well unless there are objects whose back side is seen by refracted or reflected rays -with face front, the back side would not be visible. The default is face both, and works best if volume effects are used, which usually depend on...
Noise Functions
The functions in this group provide pseudo-random numbers, quasi-Monte Carlo numbers using low-discrepancy sequences that converge faster than pseudo-random numbers , and deterministic Perlin noise. Return a random number in the range 0,1 . This is similar to drand48 in the standard Unix libraries, but it is available on all platforms including Windows NT, which does not support drand48. Begin a new random number sequence for mLrandom. This is equivalent to the standard Unix library function...
RC Functions
These are the functions supplied by the render modules of mental ray, RC . All following trace functions return miTRUE if any subsequent call of a shader returned miTRUE to indicate presence of illumination. Otherwise no illumination is present and miFALSE is returned. All trace functions derive the state of the ray to be cast from the given state of the parent ray. This state becomes the child state that is passed to subsequent shaders that are called by the trace function. The state is always...
Function Definitions
Functions, also called function calls, are references to a particular C function bundled with a set of parameter values. A function definition begins with naming the desired C function, which must have been declared see above , followed by assignments of numerical or other values to individual parameters. The order of assignments is irrelevant it is done by parameter name. Parameters that remain unassigned have a numerical value 0 or the empty string. char name called function Every function...
Lights Materials Textures
char name light name Begin the definition of a light with the specified name. A pointer to the light is returned the caller may modify the structure. Complete the definition of a light after all parameters have been set. char name material name Begin the definition of a material with the specified name. A pointer to the material is returned the caller may modify the structure. Complete the definition of a material after all parameters have been set. If an error occurs, a null tag is returned...
Shader Writing
Even if none of the following points apply, shaders must be recompiled with the shader.h file that comes with mental ray 2.x. It is not possible to use the same shader object or library file for both mental ray 1.9 and 2.x. A shader compiled with the wrong shader.h file will not be able to access state variables correctly. shader.h contains define RAY2 to allow shader sources to make sure that the correct file is included. The shader.h file that comes with mental ray 2.x is fully...
Symbol Tables
The API module identifies all entities by name. Different name spaces are provided for different purposes. In particular, the API module supports both the .mil and .mi2 languages, which have a different name space concept. The .mi2 module uses a shared global name space for all element types, while the .mil format uses separate name spaces for each element type. Note that shader parameter names do not use a persistent name space and have no assigned symbol table. Shader parameters are stored in...
Texture Shaders
Texture shaders evaluate a texture and typically return a color, scalar, or vector but like any shader, return values can be freely chosen and may even be structures of multiple values . Textures can either be procedural, for example evaluating a 3D texture based on noise functions or calling other shaders, or they can do an image lookup. The .mi format provides different texture statements for these two types, one with a function call and one with a texture file name. Refer to section 2.7.3...
Introduction 1
Geometry shaders can be used in two places in instance definitions that reference a shader instead of an object, light, camera, or instance group instance name geometry function or in phenomena, where they can be attached to the geometry root declare phenomenon geometry function end declare In either case, the geometry shader is evaluated during scene preprocessing before any other operation such as rendering starts. The geometry shader is expected to create an object, light, camera, or...
Auxiliary Functions
The following functions are provided for support of shaders, to simplify common mathematical operations required in shaders const miScalar u, const miScalar v, miScalar const gu, miScalar const gv Compute the reflected intensity according to Fresnel Call mLfresnel with parameters appropriate for the given indices of refraction iorJn and iorjout, and for the dot-nd state variable. miScalar mi_phong_specular miScalar spec_exp, Calculate the Phong factor based on the direction of illumination dir,...
Memory Allocation
mental ray's memory allocation functions replace the standard malloc packages found on most systems. They have built-in functions for memory leak tracing and consistency checks, and handle errors automatically. Shaders should always use these functions and not malloc or similar libc functions directly. void mi_mem_allocate const int size Accepts one argument specifying the size of the memory to allocate. A pointer to the allocated memory is returned. If the allocation fails, an error is...
RC Direction Functions
The functions in this section compute ray or photon directions. In both photon and ray tracing, shaders normally first compute a direction for secondary photons or rays using one of the functions with _dir in the name, and then call the corresponding photon or ray tracing function with the resulting direction. The functions mLchoose.scatter.type, mi.reflection.dirJ''', miJtransmission.dirJ', and miscattering-dir_ can also be used in other contexts than photon tracing, but they are listed in the...
RC Photon Functions
The functions in this section implement photon tracing. They are to be used in photon shaders. If caustics or global illumination21 are enabled, rendering distinguishes two phases photon tracing and scanline rendering ray tracing. Photon tracing is done first. It sends photons from certain light sources into the scene. When a photon hits an object, the object's photon shader is called, which then gets the opportunity to absorb the photon or use one of the mi-photon J' functions to let the...
Phenomenon Roots
The above example also illustrates a new option allowed in phenomenon but not shader definitions, the phenomenon root. There are several types of root statements type format opt filename environment priority priorityint All of these except one of the first two are optional. The first root statement specifies the primary root shader of a phenomenon that is called when the phenomenon is called. In the above example, the mtlsh shader, when called, calls the phenomenon phong-phen, which immediately...
Math Functions
Math functions include common vector and matrix operations. More specific noise and rendering functions can be found in the next two sections, Noise Functions and Auxiliary Functions. miVector r, miVector a, miVector b miVector r, miVector a, miVector b void mi_vector_mul miVector r, double f void mi_vector_div miVector r, double f r r- I If is zero, leave f unchanged. void mi_vector_prod miVector r, miVector a, miVector b double mi_vector_dot miVector a, miVector b void mi_vector_normalize...
Incremental Changes
miBoolean mi_api_incremental miBoolean incr Enable or disable incremental mode. Incremental mode is off by default. If turned on, the next options, camera, texture, light, material, object, instance, or instance group definition initiated with the appropriate begin call listed below is not created with fresh defaults, but with the values it was created with earlier. It is an error to request an incremental change to an element that does not exist, and to define an element that already exists...
Thread Parallelism and Locks
In addition to network parallelism, mental ray also supports shared memory parallelism through threads. Network parallelism is a form of distributed memory parallelism where processes cooperate by exchanging messages. Messages are used to exchange data as well as to synchronize. With shared memory data can easily be exchanged, a process must only access the common memory to do so. A different mechanism has to be used for synchronization. This is usually done by locking. Basically what has to be...
Geometric Objects
Geometric objects can be divided into polygonal, free-form surface, and space curve21 objects. Each object contains one or more object groups that group geometry. Object groups are maintained for backwards compatibility with the .mil language newer designs should use multiple objects rather than a single object with multiple object groups. Object groups are unrelated to instance groups as described above. char name object name Begin the definition of an object with the given name. If the name...
Environment Shaders
Environment shaders provide a color for rays that leave the scene entirely, and for rays that would exceed the trace depth limit. Environment shaders are called automatically by mental ray if a ray leaves the scene, or when a ray exceeds the trace depth. It can also be done explicitly by shaders using the mi Jrace-environment function mi_reflection_dir amp dir, state if do ray tracing mi_trace_reflection amp color, state, amp dir mi_trace_environment amp color, state, amp dir use the returned...
Color and Width of Contours
The contour properties color, width, etc. depend on the object the contour is on and its material. For each material that should have a contour, one has to specify a contour shader. A material will not get a contour if it does not have a contour shader. The colors consist of four components red, green, and blue color, and opacity. All four components of the color are normally between 0 and 1. The width is specified as a percentage of the minimum of image x resolution and y resolution. For...
Lens Effects
Lens effects are distortions of the rendered image achieved by changing the light path through the camera lens. Because lens effects are applied to first-generation rays, there is no loss of quality that would be unavoidable if the distortion were applied in a post-processing stage after rendering. Lens effects are introduced by specifying one or more lens shaders in the camera statement. If no lens shaders are present, the standard pinhole camera is used. Each lens shader is called with two...
Objects Mdh
All geometry is specified in either camera space or object space, depending on the corresponding statement in the options statement see section 2.7.1 . In camera space mode, the camera is assumed to sit at the coordinate origin and point down the negative Z axis, and objects are defined using camera space coordinates. In object space mode, the camera location is determined by its instance, and objects are defined in local object coordinates that are positioned in the scene with its object...
Function Declarations 1
Element type miSCENE_FUNCTION_DECL Defaults all nulls, type mi FUNCTION_C typedef enum miTYPE. miTYPE. miTYPE. miTYPE. miTYPE. miTYPE. miTYPE. miTYPE. miTYPE. miTYPE. miTYPE. miTYPE BOOLEAN INTEGER, .SCALAR, .STRING, .COLOR, .VECTOR, TRANSFORM, .SHADER, .SCALAR_TEX, .C0L0R_TEX, ,VECT0R_TEX, LIGHT, simple types used for returns and parameters complex types used for parameters only miTYPE_STRUCT, miTYPE_ARRAY, miTYPE_TEX, miTYPE_MATERIAL, miTYPE_GEOMETRY, miTYPE_DATA, miNTYPES miParam_type...
Light Shaders
Light shaders are called from other shaders by sampling a light using the mLsampleJight or mLtraceJight functions, which perform some calculations and then call the given light shader, or directly if a ray hits a source, misampleJight may also request that it is called more than once if an area light source is to be sampled. For an example for using mLsampleJight, see the section on material shaders above. mLtraceJight performs less exact shading for area lights, and is provided for backwards...
User Data
Sometimes large amounts of opaque data must be entered into the scene that cannot be efficiently handled with shader parameters. For example, shaders may need large amounts of particle data. For this purpose, user data blocks can be defined. A user data block consists of a header describing the data block, and the data itself. User data blocks are named. miUserdata mi_api_data_begin char name, name of user data block 0 literal, l file, 2 declared type 0 size, l file, 2 decl Begin the definition...
Photon Emitter Shaders
Photon emitter shaders are used in the photon tracing phase to control the emission of photons from the light sources. There exists a number of built-in photon emitters that handle the following types of light sources Point lights emit photons with equal flux in all directions around the point light. Spot lights emit photons with equal flux within the cone specified by the spotlight parameters. Directional lights emit photons with equal radiance based on the energy . Since a directional light...
Surface Derivatives
mental ray can automatically generate surface derivative vectors if requested. First derivatives describe the UV parametric gradient of a surface second derivatives describe the curvature. They are computed and stored only if requested by derivative-request statements in the surface definition There can be one or more derivative statements that request first and or second derivatives. Valid values for number are 1 and 2, for first and second derivatives, respectively. mental ray does not use...
Geometry Shaders
Geometry shaders are functions that procedurally create geometric objects. They are different from most of the shaders described here because they do not return a color, but a miTag reference to the object or instance group created by the shader. The geometry shader is called with a miState containing valid fields for camera, options, current shader, and version. The shader parameters are passed as the third argument. The geometry shader is expected to return the tag of the object or instance...
Shadow Shaders
As described in the previous section, light shaders may trace shadow rays between the light source and the point to be illuminated. When this ray hits an occluding object, that object's shadow shader is called, if present. If the object has no shadow shader, the object is assumed to block all light. Shadow shaders accept an input color that is dimmed according to the transparency and color of the occluding object. If the resulting color is black, that is, if the object is fully opaque, the...
State Variables
Every shader needs to access information about the current state of mental ray, and information about the intersection that led to the shader call. This information is stored in a single structure known as the state. Not all information in the state is of interest or defined for all shaders for example, lens shaders are called before an intersection is done and hence have no information such as the intersection point or the normal there. It is recommended to call the state parameter that...