Iray Programmer's Manual

Main API access point

To access the Iray API, you create a neuray object using a factory function. This object is your only access point to the system. You use it to authenticate your application against the neuray library, configure the system, start it up, work with the scene database, render images, and shut it down. Only one instance of this object can exist at any time.

The factory function is a C function that tries to access the Iray API. If successful, it returns a pointer to the neuray object, which has the interface type mi::neuraylib::INeuray. The factory function may be called only once per process. This C function is the only exported global function of the neuray library:

This function has actually two parameters, one to configure a memory allocator and one to guarantee the correct API version. Both parameters have default values and the examples use this function without special arguments.

This allows you to easily use neuray as a shared library, which can be loaded on demand without requiring to statically link an interface library to the application. The details of loading a shared library on demand and calling this factory function are operating system specific. Since this functionality is needed in all examples, it has been factored into a separate convenience function, load_and_get_ineuray(), and placed in the shared header file example_shared.h described in the Starting and shutting down the Iray API topic.

For a the underlying rationale of a single access function returning an interface pointer, see also Interfaces.

Note: It is not required to use load_and_get_ineuray(). In particular in larger setups you might want to write your own code to load the neuray DSO and to locate the factory function. In such cases, you call mi_neuray_factory() directly. For simplicity, the examples will use the convenience function load_and_get_ineuray() instead of mi_neuray_factory().