Example for Configuration of the neuray API

• Error handling

• Configuration of the neuray API

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 ommitted in the examples for simplicity.

Configuration of the neuray API

The behavior of the neuray 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 neuray is started.

In this example we demonstrate how to configure the logging behavior of neuray. The configuration of the rendering behavior is contained in the next example .

You can customize the logging behavior of neuray 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.

‎/******************************************************************************
 * Copyright 1986, 2011 NVIDIA Corporation. All rights reserved.
 *****************************************************************************/

// examples/example_configuration.cpp

#include <mi/neuraylib.h>

// Include code shared by all examples.
#include "example_shared.h"

class Logger : public mi::base::Interface_implement<mi::base::ILogger>
{
public:
    void message( INVALID_DOXYREFmi::base::Message_severity level, const char* category, const char* message)
    {
        const char* log_level = get_log_level( level);
        fprintf( stderr, "Log level = '%s', category = '%s', message = '%s'\n",
            log_level, category, message);
    }

private:
    const char* get_log_level( INVALID_DOXYREFmi::base::Message_severity level)
    {
        switch( level) {
            case INVALID_DOXYREFmi::base::MESSAGE_SEVERITY_FATAL:
                return "FATAL";
            case INVALID_DOXYREFmi::base::MESSAGE_SEVERITY_ERROR:
                return "ERROR";
            case INVALID_DOXYREFmi::base::MESSAGE_SEVERITY_WARNING:
                return "WARNING";
            case INVALID_DOXYREFmi::base::MESSAGE_SEVERITY_INFO:
                return "INFO";
            case INVALID_DOXYREFmi::base::MESSAGE_SEVERITY_VERBOSE:
                return "VERBOSE";
            default:
                return "";
        }
    }
};

int main( int argc, char* argv[])
{
    // Access the neuray 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 neuray 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>());
        check_success( logging_configuration.is_valid_interface());
        logging_configuration->set_receiving_logger( logger.get());

        // other configuration settings go here, none in this example

        // Start the neuray library
        check_success( neuray->start( true) == 0);
        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 neuray library
    check_success( unload());

    return EXIT_SUCCESS;
}