neuray API Programmer's Manual

Getting Started

neuray is a rendering component that you can embed in your application to provide advanced rendering functionality for your application.

The neuray API is a C++ API. The neuray library can be provided as a static or as a dynamic library, which can be linked to your application. The dynamic library also allows dynamic loading at runtime.

Overview

The neuray library release contains the following parts:

  • A platform dependent static and shared library (a.k.a. DLL) named libneuray.

  • A set of platform independent C++ include files, see the Include Files Section for all available module specific include files.

  • A collection of example programs; see the Tutorial and Example Programs Section.

  • A programmers manual (this document).

  • Installation instructions.

Recommendation

It is recommended that you read the brief Library Design Section and continue with the Tutorial and Example Programs Section. The Configuration Options Section describes how to configure aspects of the library to your particular integration demands.

How to Compile a Program

The neuray library release contains a set of example programs. It is recommended that you compile them and take them as a starting point for your own development.

You can integrate the neuray library easily in other build environments. You can even compile the examples by hand following the steps below. Let the environment variable $NEURAY_ROOT refer to the installation root of the neuray library.

  1. Use the neuray include files in your source: 
    ‎#include <mi/neuraylib.h>
    Load the neuray library dynamically and access the API entry point: 
    ‎mi::neuraylib::INeuray* ineuray = load_and_get_ineuray();
    See examples/example_shared.h for the definition of this convenience method. Alternatively, if you want to use the mi::base::Handle class: 
    ‎mi::base::Handle< mi::neuraylib::INeuray> neuray( load_and_get_ineuray());
    For a start, you can copy the examples that come with the neuray release, such as: 
    ‎cp $NEURAY_ROOT/examples/example_start_shutdown.cpp example.cpp

  2. Compile the program with the appropriate include path switch that points the compiler to the location of the neuray include files. A g++ compiler call could look like this: 
    ‎g++ -I$NEURAY_ROOT/include -c example.cpp -o example.o -pthread

  3. Link the program with the library that provides dlopen(). A g++ linker call could look like this: 
    ‎g++ -o example example.o -ldl -pthread

  4. Make the shared library (a.k.a. DLL) known to your runtime system so that it is found when starting the example program. You can do this by placing the shared library in an appropriate location, and/or setting environment variables such as PATH or LD_LIBRARY_PATH. Note: This step is platform and installation dependent.

There is another method for using the neuray library, linking the library at build time. Using this approach it is no longer necessary to load the library dynamically at runtime. Note: This method may not be available on some platforms, e.g., on Windows.

To use this method, just omit the function load_and_get_ineuray() above and call INVALID_DOXYREF directly. In the link command replace -ldl by 
‎ -L$NEURAY_ROOT/linux-x86-64/lib -lneuray
(or similar).

Note: It is strongly recommended to load the library dynamically at run time. Linking the library at build time might have undesired effects, e.g., overridden versions of the global new and delete operator in the library might become visible in your code.