Manual Revision History

This section describes changes to the manual since the first manual release, 1.1.

1.2: In the ``Writing Shaders'' section, semaphores were replaced with locks. Locks are much faster than semaphores.

1.3: An explanation of the environment variable LD_LIBRARY_PATH was added to the section ``Dynamic Linking of Shaders''. Most float and double declarations have been replaced with miScalar declarations, and ``int'' declarations have been replaced with ``miInteger'' declarations. The term ``dissolve'' was replaced with ``transparency'' (as opposed to refraction). Camera origin, direction, and up vector have been removed; frame and frame_time have been introduced. Perlin noise functions that return the gradient have been added. Inheritance of environment shaders was clarified. The chapter on free-form surface syntax in .mi files has been rewritten and adorned with examples. The term ``internal space'' and coordinate space transformation functions have been introduced. Memory allocation functions and locks have been added. Errors in the light sampling example have been fixed.

1.4: The fisheye lens shader example has been fixed. Shader parameter arrays now are explained in detail. Documentation of the shadow sorting option and the nonlocal filter state variable was missing. The volume shader diagram has been clarified. Four IMG access functions have been added. Several miScalar return values and function arguments have been replaced with double to let people use classic C. The recursive statement in the view was missing, and some comments on sampling methods have been added. A section on output shaders has been added. In the scene syntax description, all names now end in _name, and all are double-quoted. The free-form surface syntax description has been improved. The SOFTIMAGE material shader components are now documented. Many small corrections.

1.5: Added notrace parameter to SOFTIMAGE material that allows non-raytraced reflection maps. Small improvements in surface syntax explanations. The syntax for groups in objects does not require a name, description changed. Many minor clarifications and typo fixes.

1.6: Removed warning that texture shaders have to distinguish file and procedural textures in the 1.8/1.9 changes section, this is done by the lookup functions. Local and global textures have been introduced in the Scene grammar chapter. The shutter view statement was missing. A chapter on command line options was added. In the shaders chapter, the motion and surface derivative state variables were introduced. The depth-of-field output shader was added to the list of built-in shaders. The missing mi_call_shader documentation was added.

1.7: Second argument of mi_img_put_scalar is not a pointer, and never was. The mi_mtl_refraction shader interface function has changed to accommodate reflected rays due to indices of refraction less than 1, and the resulting interaction with environment shaders. The soft_layered_fog and out_depth_of_field shaders are now supported and documented. Passing material shader parameters as shadow shader parameters was clarified in the Materials section in the Scene chapter. A description of the environment variables controlling server download was added to the

1.8: The method number was added to the soft_material parameter list. Adapted manual to SOFTIMAGE style.

1.9: Added suggestions for choosing BSP tree parameters to improve rendering speed.

1.10: Integrated the paper on interpretation of the verbose output of mental ray, and the discontinuity statement. The underscore in the -trace_depth command-line option was missing.

1.11: mi_light_info sets null vectors, not null pointers. Improvements in the interpretation section added in 1.10.

1.12: Clarified the mi_sample_light loop some more. Explained about when to assign 0 to state->pri before sampling a ray. Fixed the example material shader and its declarations. Floating-point frame buffers are now supported. The code listing of mi_mtl_refraction_index changed to reflect the modified ray code that fixes inside/outside problems. Brief explanation of byte layout of the mental images file formats. The use of empty parameter lists in shader calls is clarified. The shader interface function mi_trace_transparent was misspelled. The -imgpipe command-line option was added. The miOutstate acquired several extra fields. Added section on memory-mapping textures.

1.13: Added documentation for new state variables inv_normal and ior_in, and for the new version command and backquoted compressed vectors in the .mi file format. The 2.0 version was extended to explain surface derivatives, including the d and derivative keywords and the extensions to the mi_tri_vectors shader function call. Explanations how a material shader can control the non-color frame buffers was added. The code example using image->width and image->height was changed so it works under 1.9. An appendix containing the yacc grammar for the .mi format was added.

1.14: The 1.9 manual no longer claims coordinate range checking by frame buffer access functions. In vertex definitions, the order of m and t was reversed.

1.15: Fixed typo in Outstate. One example erroneously used $code instead of code. The vertex order for d vector references was wrong. Frame buffer access functions in 1.9 do not do bounds-checking. state->light_instance was introduced, and the mi_mtl_is_casting_shadow builtin was modified accordingly.

1.16: The soft_color texture shader acquired an extra argument, method. Better explanation with example for instance init/exit shaders. A new state variable child was introduced.

1.17: Introduced miIntersection finding, new shader call functions mi_trace_shadow_seg and mi_call_shader_x.

1.18: Introduced shadow segments and three new shader interface calls: mi_global_lights_info, mi_shader_info, and mi_instance_info.

1.19: Added mi_vector_transform_T to the Math section along with an explanation of why the w component is not used in mi_vector_transform and mi_vector_transform_T: the w component is 0 for vectors. Moved mi_random to the Auxiliary Functions section. Fixed a few incorrectly named parameters in the Math section.

1.20: shadow_segments is now a command-line option and can be specified in the view. Therefore a brief description of shadow segments is added, including grammar changes. Also added sample command lines to create shared libraries for various systems. If ray tracing is disabled, mi_trace_refraction behaves like mi_trace_transparent.

2.0: Massive changes in all chapters caused by the switch from the .mi1 to the .mi2 language. New contouring, global illumination, and caustics introduced.

2.1: Sorted the command-line options, re-indented all code examples for narrow paper. The mi_global_lights_info argument type was given incorrectly. Added the TIFF, Targa, PPM, and BMP file formats. Added new soft_vertex_color shader.

2.2: Added description of shadow maps in functionality chapter and in the scene chapter. Also updated the grammar description. Updated the section on caustics and global illumination. Added advertisement for the new faster motion blur (with trace off). Fixed a nonsensical sentence about contour shaders. The paper_size parameter of contour_ps is changed from a string to a number. Added an explanation and illustration of the shader calls in the global illumination preprocessing step. Added a description of dgs_material and dielectric_material in the chapter on built-in shaders. Added the built-in contour shaders there, too.

2.3: state->child was missing in the state member table. The 1.8 vs. 2.0 shader table incorrectly said that matrices are now in column-major order; they are in row-major order. Added documentation for the new LDA surface approximation modes, and for the new premultiply option.

2.4: Syntax change: camera and material shader lists are reset first when respecified in an incremental change. Removed all references to state->contour. Clarified the use of VPU numbers in shaders. Added the filter keyword to texture definitions. Changed soft_material so that it is up to date: add computations of global illumination and shadow segments. Added an example of a photon material shader. Added descriptions of the built-in global illumination helper functions that compute directions resulting from different types of scattering. Added descriptions of the six new functions that shoot a photon. Changed forward shader to photon shader. Added new photon types. Updated the description of the dielectric material. Added mi_query shader interface function. Added description of the anisotropic glossy reflection function and the anisotropic capabilities of dgs_material. Deleted the nocontour flag. Described glowing contours and the compositing of contours in contour_only and contour_composite. Introduced geometry shaders in the Objects chapter and added new chapters for Dynamically Created Objects and Geometry Shaders including example geometry shader code.

2.5: Replaced light source keyword cone with spread since it should have the the same value as the spread parameter of Softimage light sources. Described how the extent of shadow maps are computed. Added description of the shadow map command line option.

2.6: Documented displacement maps for polygons. Documented the padding (interpolation or max'ing) feature in output type strings. Changed the description of contour store and contour contrast functions. Uncommented dgs_example. Uncommented mi_choose_scatter_type(). Added description of caustic photons and caustic filters. Updated the grammar. Added mi_blinn_specular on request from SoftImage. Changed mi_mtl_illumination. Changed doubles to miScalars in the section ``Auxiliary Functions'', so that the function prototypes match the code. Documented new approximate displace statement and adaptive tessellation of surface displacements.

2.9: Corrected description of the number of samples for a given min/max sample depth. Added description of the handling of missing shaders due to failed compilation of shader code. Added visible area light sources.

2.10: Trailing commas in array member lists are now silently ignored. state->dist is undefined in directional light shaders, not 0.

2.11: Added instance motion transformations. Added description of echo option. Changed field even|odd|both to field even|odd|off. Deleted documentation of the Custom Sample Algorithm (CSA) option. Added documentation of dgs_material as an anisotropic material. Added method 5 to the soft_material shader and diffuse lights to the soft_material shader, and brought the documentation of the builtin shaders up to date.

2.12: Added information on using debuggers on shaders. Corrected the parameters of mi_transmission_dir_glossy and mi_transmission_dir_anisglossy. Added photon shader examples and description of mi_choose_scatter_type. Documented tagged objects and polygon and surface labels. Rewrote caustics chapter. Added photon trace depth.

2.13: Added more mi_query modes. Added documentation to the fields of miState that get set when a visible area light source gets hit. Updated the documentation of mi_choose_scatter_type. Added new declaration syntax and declaration and shader versions. Updated the Convex compile and link options.

2.14: Introduced phenomena and geometry shaders in the .mi language and the shader interface. Improved the description of interpolation/padding of frame buffers. Improved description of photon emitting light sources. Added text on displacement shaders. Many minor changes to shader text. Brought state variables up to date. Clarified material phenomena. Added environment, contour store, and contour contrast requirements to phenomena. Added visibility, trace, shadow, and caustic inheritance. Added full source version of the .mi2 language parser in the appendix. Added description of photon emitters. Added instance material lists. This version is almost 50 pages longer than the previous, and uses a new layout and new fonts. It first shipped with mental ray 2.0.20.

2.15: Documented mi_srandom and mi_erandom. Introduced apply statements in declarations. Added new function mi_api_geovector_xyz_add, and changed surface ranges in mi_api_surface_params and struct miVref from single-precision to double-precision. Introduced elliptical filtering. Documented mi_texture_filter_project and mi_texture_filter_transform, and extended documentation of mi_lookup_filter_color_texture. Introduced immediate-mode tesselation in geometry shaders, using mi_geoshader_tesselate and mi_geoshader_tesselate_end. Added advice on how to compute contours very fast.

2.16: Added a footnote on global illumination in mental ray 2.1. Added documentation of mi_scattering_dir_diffuse, mi_scattering_dir_directional, and mi_schlick_scatter. Introduced new feature disable options in the options statement and on the command line. Added a lightlist field to miFunction. Added the functions mi_inclusive_lightlist and mi_exclusive_lightlist. Documented mi_cooktorr_specular, reflection according to the Cook-Torrance reflection model. Changed the meaning and parameters of mi_blinn_specular --- now it is according to Foley at al.

2.17: mi_trace_eye now overwrites the org and dir state variables. New -shadowmap rebuild command-line option. New shadowmap motion option added; also changed the -shadowmap command-line option. Added mi_par_aborted shader interface function. Fixed Convex shader compilation command line (libc.1). Added mi_point_to_raster. Sphere lights can emit photons now. New command line option -ld_path or -L to supply the user shader search path. New environment variable MI_LIBRARY_PATH to supply additional shader search path. New approximation statements in the options statement, and a new regular parametric approximation method.

2.18: The time contrast now defaults to 0.2. Added new field option in frame statements. Clarified trim/hole curve order and global/shader lock initialization. Added description of mi_photon_transparent() and the new miPHOTON_TRANSPARENT ray type. Added description of the photonmap filename and the photonmap rebuild on|off options.

2.19: Fixed a bug in the first shader example scene. In the LDA description text, the approximate keyword was called approx; fixed. Added information on rayrc files. Moved mi_reflection_dir and mi_refraction_dir from RC functions to Auxiliary functions. Removed all builtin shaders. Added bounding box of intersected primitive to mi_query. Added title parameter to contour_ps.

2.20: Changed the NT startup file name from ray.ini to rayrc. Added description of the miRAY_* macros. Removed the claim that contour shaders do not have version shaders.

2.21: Changed the contour shader interface: a contour shader now returns a result of type miContour_endpoint instead of a color and a width (and glow). Introduced the function mi_get_contour_line that output shaders can use to get contour line data. Users can now write their own contour output shaders. Introduced space curves. It is not actually possible to call mi_trace_shadow from volume shaders.

2.22: Fixed shader assignment example. Removed four API functions that are not supported in the current version of mental ray. Added text about setting polygon labels with the geometry shader API. Added section about stack sizes and virtual memory.

2.23: Dithering is off by default. Added mi_flush_cache. Added information about stack sizes.

2.24: Added cylindrical area light source. Added light labels. Introduced area light undersampling depending on the trace depth.

2.25: Documented global illumination for mental ray 2.1. New file config.tex. Changed a contour figure from a sphere to a teapot.

2.26: Added expand argument to the -cut_windows command-line parameter.
Table of Contents