This example accesses the main Iray interface, queries the version interface, prints some version information and then starts and shuts down the Iray SDK API. See the Getting Started Section for a description of how the example programs can be compiled.
The Iray library is written in C++. It uses the mi and mi::neuraylib namespaces for its own identifiers, or the MI_NEURAYLIB_ prefix for macros.
Multiple words are concatenated with _ to form identifiers. Function names are all lower case, while types and classes start with one initial upper-case letter.
The include file mi/neuraylib.h provides all the functionality of the Iray SDK API.
The mi_factory() function is the only public access point to all algorithms and data structures in the API (see Library Design for an explanation why). To obtain a pointer to the main interface mi::neuraylib::INeuray, call this function with the mi::neuraylib::INeuray::IID() as its iid parameter. If no compatible interface can be found in the library, a NULL pointer is returned. In this case, you can use mi::neuraylib::IVersion::IID() to request a mi::neuraylib::IVersion interface from the mi_factory() for diagnostics. The mi::neuraylib::INeuray interface can only be accessed once per process.
Before you are able to call the mi_factory() function, you need to load the Iray DSO and to locate the factory function. The convenience function load_and_get_ineuray() abstracts these platform-dependent steps.
Note that 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 Iray DSO and to locate the factory function. In such cases, you call mi_factory() directly. For simplicity, the examples will use the convenience function load_and_get_ineuray() instead of mi_factory().
Except for trivial classes, such as the math vector class, all classes in the Iray SDK API are implemented using interfaces. See Library Design for an explanation. Interfaces are created and destroyed by the Iray SDK API. They implement reference counting for life-time control and cheap copying operations. Interface names start with an I prefix.
Whenever you do not need an interface any longer, you have to release it by calling its release() method. Omitting such calls leads to memory leaks. To simplify your life we provide a simple handle class mi::base::Handle. This handle class maintains a pointer semantic while supporting reference counting for interface pointers. For example, the -> operator acts on the underlying interface pointer, which means that you can use a handle to a particular interface pointer in a way very similar to the interface pointer itself. The destructor calls release() on the interface pointer, copy constructor and assignment operator take care of retaining and releasing the interface pointer as necessary.
Note that the handle class has two different constructors to deal with ownership of the interface pointer. See the mi::base::Handle documentation for details.
Note that it is also possible to use other handle class implementations, e.g., std::tr1::shared_ptr<T> (or boost::shared_ptr<T>). In case you prefer to use such handle classes, you have to ensure that their destructor calls the release() method of the interface pointer. This can be achieved by passing an appropriate argument as second parameter, e.g.,
The mi::neuraylib::INeuray interface is used to start and shut down the Iray SDK API. The API can only be used after it has been started (and before it has been shut down). Startup does not happen during the mi_factory() call because you might want to configure the behavior of the API, which has to happen before startup (see Example for Configuration of the Iray SDK API for details).
The status of the API can be queried using the mi::neuraylib::INeuray::get_status() method.
Finally, you have to shut down the Iray SDK API. At this point, you should have released all interface pointers except the pointer to the main mi::neuraylib::INeuray interface. If you are using the handle class, make sure that all handles have gone out of scope.
Source Code Location: examples/example_shared.h
Source Code Location: examples/example_start_shutdown.cpp
