DiCE API nvidia_logo_transpbg.gif Up
Example for Configuration of the DiCE API
[Previous] [Next] [Up]

This example demonstrates how to configure the DiCE API.

New Topics

  • Error handling
  • Configuration of the DiCE API

Detailed Description

Error handling

Detecting failures depends on the particular method in question.

Some methods indicate their success or failure by an integral return value, e.g., mi::neuraylib::INeuray::start(), as already seen in the previous example. The general rule is that 0 indicates success, and all other values indicate failure.

Methods returning interface pointers indicate failure by a NULL pointer. Therefore you should check returned pointers for NULL. If you use the provided handle class, you can do so by calling mi::base::Handle::is_valid_interface().

In this and the following examples we use a helper macro called check_success() to check for errors. If the condition is not true, the macro just prints an error message and exits. Of course, in real code proper error-handling needs to be done. This has been omitted in the examples for simplicity.

Configuration of the DiCE API

The behavior of the DiCE library can be configured through several interfaces which can be obtained from mi::neuraylib::INeuray::get_api_component(). See Configuration Interfaces for a list of these interfaces. Almost all of the configuration has to happen before DiCE has been started.

In this example we demonstrate how to configure the logging behavior of DiCE.

You can customize the logging behavior of DiCE by providing your own logging object. This object has to implement the mi::base::ILogger interface. A very minimal implementation that prints all messages to stderr is shown in this example. A similar implementation is used by default if you do not provide your own implementation.

Example Source

Source Code Location: examples/example_configuration.cpp

* Copyright 2023 NVIDIA Corporation. All rights reserved.
// examples/example_configuration.cpp
#include <mi/dice.h>
// Include code shared by all examples.
#include "example_shared.h"
class Logger : public mi::base::Interface_implement<mi::base::ILogger>
void message(
mi::base::Message_severity level, const char* module_category,
const mi::base::Message_details&, const char* message)
const char* log_level = get_log_level( level);
fprintf( stderr, "Log level = '%s', module:category = '%s', message = '%s'\n",
log_level, module_category, message);
// Do not return in case of fatal log messages since the process will be terminated anyway.
// In this example just call exit().
const char* get_log_level( mi::base::Message_severity level)
switch( level) {
return "FATAL";
return "ERROR";
return "WARNING";
return "INFO";
return "VERBOSE";
return "DEBUG";
return "";
int main( int /*argc*/, char* /*argv*/[])
// Access the DiCE library
mi::base::Handle<mi::neuraylib::INeuray> neuray( load_and_get_ineuray());
check_success( neuray.is_valid_interface());
// Create an instance of our logger
mi::base::Handle<mi::base::ILogger> logger( new Logger());
// Open new block to ensure that all handles except neuray went out of scope
// when calling shutdown() after the end of this block.
// Configure the DiCE library before startup. Here we set our own logger.
check_success( neuray->get_status() == mi::neuraylib::INeuray::PRE_STARTING);
logging_configuration->set_receiving_logger( logger.get());
// other configuration settings go here, none in this example
// Start the DiCE library
mi::Sint32 result = neuray->start();
check_start_success( result);
check_success( neuray->get_status() == mi::neuraylib::INeuray::STARTED);
// scene graph manipulations and rendering calls go here, none in this example.
// Shut down the library
check_success( neuray->shutdown() == 0);
check_success( neuray->get_status() == mi::neuraylib::INeuray::SHUTDOWN);
neuray = 0;
// Unload the DiCE library
check_success( unload());
Handle class template for interfaces, automatizing the lifetime control via reference counting.
Definition: handle.h:113
Mixin class template for deriving interface implementations.
Definition: interface_implement.h:41
This interface is used for configuring the logging for the DiCE library.
Definition: ilogging_configuration.h:68
The library or the cluster is ready for operation.
Definition: ineuray.h:98
The library or the cluster has been shut down.
Definition: ineuray.h:102
The library or the cluster has not yet been started.
Definition: ineuray.h:94
Constants for possible message severities.
Definition: enums.h:31
A fatal error has occurred.
Definition: enums.h:33
This is debug message.
Definition: enums.h:43
A warning has occurred.
Definition: enums.h:37
This is a normal operational message.
Definition: enums.h:39
This is a more verbose message.
Definition: enums.h:41
An error has occurred.
Definition: enums.h:35
signed int Sint32
32-bit signed integer.
Definition: types.h:46
Structured details to log messages.
Definition: ilogger.h:71
[Previous] [Next] [Up]