raylib

This manual describes the library version of mental ray, also called raylib. In its library form, mental ray can be integrated into client applications that provide a graphical front-end, and also implement modeling and animation functionality. Such applications can use raylib to

render modeled scenes and animations to images,
tessellate scenes or parts of scenes into triangles or wireframe models,
which can then be displayed in realtime using the system's graphics hardware,
visualize results of shaders and shader graphs in realtime,
make use of raylib's multithreaded and networked Virtual Shared Database for scene storage,
read and write scenes in the .mi scene file format.
Converters exist that translate scenes in a wide variety of formats to the .mi format.

In principle, raylib offers all functionality that is available in the standalone mental ray executable. In fact, mental ray itself is a small front-end to raylib that only handles command-line parsing and licensing. The Examples chapter will describe a miniature standalone rendering program based on raylib. For a description of the mental ray standalone executable and its general feature set, refer to ``Rendering with mental ray'' [Handbook 1].

This document relies heavily on the mental ray Manual, also available as the book ``Programming mental ray'' [Handbook 2], which describes the geometry shader API of raylib. Geometry shaders are plug-in functions that can procedurally create scene elements such as geometric objects. Essentially, this includes all functions required to create a scene database.

When integrating raylib into a client application, most of the integration work involves converting the internal, time-dynamic representation of the scene in the application into the static, frame-by-frame scene representation of mental ray. This is done by fully creating the scene in the raylib database once (a process typically called translation), and from that point on using incremental changes to modify the scene from frame to frame. All this is identical to what a geometry shader does - creating and modifying the scene database. Hence, this document only discusses the extensions of the raylib call interface that permit its integration into the client application, omitting the scene database API.

The common name of the mental ray library is libray. It is typically provided as a shared library, named libray.so on Unix, libray.dylib on Mac OS X systems, and libray.dll on Windows systems. A static library version exist as well. Three include files are required:

shader.h: is the standard shader interface. It must be included because it contains definitions of the basic raylib data types such as miVector and miBoolean.
geoshader.h: is the geometry shader interface. It contains the mi_api_* API functions and scene data type declarations required for building a scene in raylib's database.
mi_shader_if.h: is the new C++ shader interface. It contains the class definitions for latest features of mental ray. New public interface will only be added here, since this allows to avoid symbol handling problems for individual functions which is common with a C interface. This interface provides version support to detect incompatible binary interface from within applications.
mirelay.h: contains the remaining calls required for integrating raylib in a client application, beyond the geometry shader functions in geoshader.h.

Note that all functions and macros provided by raylib begin with the prefix mi. Macros and Constants are all-uppercase after the mi prefix, except where a function was implemented as a macro for performance reasons. Typedefs begin with a capital letter after the mi prefix, and continue with lower case. All C language functions are all-lowercase.

This document describes raylib version 3.10.