Getting Started

The DiCE API is a C++ API.

The DiCE library is provided as a dynamic library, which can be linked to your application or dynamically loaded at runtime.

Overview

The DiCE library release contains the following parts:

• A platform-dependent 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 DiCE 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.

The release contains a Makefile to build the examples on Linux and MacOS X platforms as well as solution files for Visual Studio 2012 to build the examples on a Microsoft Windows platform.

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

1. Use the DiCE include files in your source:

   #include <mi/dice.h>

   Load the DiCE library dynamically and access the API entry point:

   mi::neuraylib::INeuray* neuray = 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 DiCE release, make them writable, and change into that directory:

   cp -r $DICE_ROOT/examples .
   chmod -R u+w examples
   cd examples

   
   
2. Compile the program with the appropriate include path switch that points the compiler to the location of the DiCE include files. A g++ compiler call could look like this:

   g++ -I$DICE_ROOT/include -c example_start_shutdown.cpp -o example_start_shutdown.o -pthread

   
   
3. Link the program with the library that provides dlopen(). A g++ linker call could look like this:

   g++ -o example_start_shutdown example_start_shutdown.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.