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>
{
public:
    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().
        if( level == mi::base::MESSAGE_SEVERITY_FATAL)
            exit( EXIT_FAILURE);
    }
 
private:
    const char* get_log_level( mi::base::Message_severity level)
    {
        switch( level) {
            case mi::base::MESSAGE_SEVERITY_FATAL:
                return "FATAL";
            case mi::base::MESSAGE_SEVERITY_ERROR:
                return "ERROR";
            case mi::base::MESSAGE_SEVERITY_WARNING:
                return "WARNING";
            case mi::base::MESSAGE_SEVERITY_INFO:
                return "INFO";
            case mi::base::MESSAGE_SEVERITY_VERBOSE:
                return "VERBOSE";
            case mi::base::MESSAGE_SEVERITY_DEBUG:
                return "DEBUG";
            default:
                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);
        mi::base::Handle<mi::neuraylib::ILogging_configuration> logging_configuration(
            neuray->get_api_component<mi::neuraylib::ILogging_configuration>());
        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());
 
    keep_console_open();
    return EXIT_SUCCESS;
}

[Previous] [Next] [Up]