Example for Rendering

[Previous] [Next] [Up]

This example imports a scene file, renders the scene, and writes the image to disk.

New Topics

• Providing the rendering infrastructure
• Accessing the database
• Importing a scene file
• Rendering of a scene

Detailed Description

Providing the rendering infrastructure

To render a scene, you have to provide some rendering infrastructure for the Iray SDK API. Basically, you have to provide buffers where the rendered image is written to. These buffers are defined by the interfaces mi::neuraylib::IRender_target, mi::neuraylib::ICanvas, and mi::neuraylib::ITile.

This example demonstrate a very simple implementation of the mi::neuraylib::IRender_target interface. It makes use of default implementations for the interfaces mi::neuraylib::ICanvas and mi::neuraylib::ITile (the next example demonstrates how to use custom implementations of these interfaces). The implementation of the render target shown here has only a single canvas consisting of a single tile.

Accessing the database

The mi::neuraylib::IDatabase interface is one of the central interface classes that become available after the Iray SDK has been started. Using this interface, you can access the scene database. In particular, you can either access the global scope or create your own scope. The mi::neuraylib::IScope interface allows you to create transactions, which are required for all operations that access the database.

This example uses the database interface to access the global scope and creates a transaction in the global scope. All transactions need either to get committed or aborted. By committing a transaction, all changes (if any) will become visible for subsequently started transactions. Aborting a transaction discards any changes made in that transaction.

Importing a scene file

The import of files is handled by the API component mi::neuraylib::IImport_api. The actual import is done by the method mi::neuraylib::IImport_api::import_elements(). The result of the import operation is described by the interface mi::neuraylib::IImport_result. This interface provides among other things the method mi::neuraylib::IImport_result::get_error_number() to retrieve the resulting error number. This error number is 0 in case of success, all other numbers indicate failures.

The example also creates an instance of the mi::neuraylib::IScene interface, which is later used for rendering. To this end, the name of the root group, the camera, and the options are set in the scene. These names are available from the import result.

Rendering of a scene

Rendering a scene requires a render target and a render context. The render target has to be provided by you, as explained earlier in this example. The render context can be obtained from mi::neuraylib::IScene::create_render_context().

Example Source

Source Code Location: examples/example_render_target_simple.h

/******************************************************************************
 * Copyright 2023 NVIDIA Corporation. All rights reserved.
 *****************************************************************************/
 
// examples/example_render_target_simple.h
//
// Code shared by many rendering examples
 
#ifndef EXAMPLE_RENDER_TARGET_SIMPLE_H
#define EXAMPLE_RENDER_TARGET_SIMPLE_H
 
#include <mi/neuraylib.h>
 
// A simple implementation of the IRender_target interface using default implementations
// for the abstract ICanvas and ITile interfaces.
class Render_target : public mi::base::Interface_implement<mi::neuraylib::IRender_target>
{
public:
    // Constructor.
    //
    // Creates a render target with a single canvas of the given pixel type, width, and height.
    // This variant uses the default implementation for canvases and tiles available via
    // mi::neuraylib::IImage_api.
    Render_target(
        mi::neuraylib::IImage_api* image_api,
        const char* pixel_type,
        mi::Uint32 width,
        mi::Uint32 height)
    {
        m_canvas = image_api->create_canvas( pixel_type, width, height);
    }
    
    // Implement the interface of mi::neuraylib::IRender_target
    mi::Uint32 get_canvas_count() const { return 1; }
    mi::neuraylib::Canvas_type get_canvas_type( mi::Uint32 index) const
    { return index == 0 ? mi::neuraylib::TYPE_RESULT : mi::neuraylib::TYPE_UNDEFINED; }
    const mi::neuraylib::ICanvas_parameters* get_canvas_parameters( mi::Uint32) const
    { return 0; }
    const mi::neuraylib::ICanvas* get_canvas( mi::Uint32 index) const
    {
        if( index > 0)
            return 0;
        m_canvas->retain();
        return m_canvas.get();
    }
    mi::neuraylib::ICanvas* get_canvas( mi::Uint32 index)
    {
        if( index > 0)
            return 0;
        m_canvas->retain();
        return m_canvas.get();
    }
 
private:
    // The only canvas of this render target
    mi::base::Handle<mi::neuraylib::ICanvas> m_canvas;
};
 
#endif // MI_EXAMPLE_RENDER_TARGET_SIMPLE_H

Source Code Location: examples/example_rendering.cpp

/******************************************************************************
 * Copyright 2023 NVIDIA Corporation. All rights reserved.
 *****************************************************************************/
 
// examples/example_rendering.cpp
//
// Imports a scene file, renders the scene, and writes the image to disk.
//
// The example expects the following command line arguments:
//
//   example_rendering <scene_file> <mdl_path>
//
// scene_file       some scene file, e.g., main.mi
// mdl_path         path to the MDL modules, e.g., iray-<version>/mdl
//
// The rendered image is written to a file named "example_rendering.png".
 
#include <iostream>
 
#include <mi/neuraylib.h>
 
// Include code shared by all examples.
#include "example_shared.h"
// Include an implementation of IRender_target.
#include "example_render_target_simple.h"
 
void configuration( mi::neuraylib::INeuray* neuray, const char* mdl_path)
{
    // Configure the neuray library. Here we set the search path for .mdl files.
    mi::base::Handle<mi::neuraylib::IRendering_configuration> rc(
        neuray->get_api_component<mi::neuraylib::IRendering_configuration>());
    check_success( rc->add_mdl_path( mdl_path) == 0);
    check_success( rc->add_mdl_path( ".") == 0);
 
    // Load the OpenImageIO, Iray Photoreal, and .mi importer plugins.
    mi::base::Handle<mi::neuraylib::IPlugin_configuration> pc(
        neuray->get_api_component<mi::neuraylib::IPlugin_configuration>());
    check_success( pc->load_plugin_library( "nv_openimageio" MI_BASE_DLL_FILE_EXT) == 0);
    check_success( pc->load_plugin_library( "libiray" MI_BASE_DLL_FILE_EXT) == 0);
    check_success( pc->load_plugin_library( "mi_importer" MI_BASE_DLL_FILE_EXT) == 0);
}
 
void rendering(
    mi::neuraylib::INeuray* neuray, const char* scene_file)
{
    // Get the database, the global scope of the database, and create a transaction in the global
    // scope for importing the scene file and storing the scene.
    mi::base::Handle<mi::neuraylib::IDatabase> database(
        neuray->get_api_component<mi::neuraylib::IDatabase>());
    check_success( database.is_valid_interface());
    mi::base::Handle<mi::neuraylib::IScope> scope(
        database->get_global_scope());
    mi::base::Handle<mi::neuraylib::ITransaction> transaction(
        scope->create_transaction());
    check_success( transaction.is_valid_interface());
 
    // Import the scene file
    mi::base::Handle<mi::neuraylib::IImport_api> import_api(
        neuray->get_api_component<mi::neuraylib::IImport_api>());
    check_success( import_api.is_valid_interface());
    mi::base::Handle<const mi::IString> uri( import_api->convert_filename_to_uri( scene_file));
    mi::base::Handle<const mi::neuraylib::IImport_result> import_result(
        import_api->import_elements( transaction.get(), uri->get_c_str()));
    check_success( import_result->get_error_number() == 0);
 
    // Create the scene object
    mi::base::Handle<mi::neuraylib::IScene> scene(
        transaction->create<mi::neuraylib::IScene>( "Scene"));
    scene->set_rootgroup(       import_result->get_rootgroup());
    scene->set_options(         import_result->get_options());
    scene->set_camera_instance( import_result->get_camera_inst());
    transaction->store( scene.get(), "the_scene");
 
    // Create the render context using the Iray Photoreal render mode
    scene = transaction->edit<mi::neuraylib::IScene>( "the_scene");
    mi::base::Handle<mi::neuraylib::IRender_context> render_context(
        scene->create_render_context( transaction.get(), "iray"));
    check_success( render_context.is_valid_interface());
    mi::base::Handle<mi::IString> scheduler_mode( transaction->create<mi::IString>());
    scheduler_mode->set_c_str( "batch");
    render_context->set_option( "scheduler_mode", scheduler_mode.get());
    scene = 0;
 
    // Create the render target and render the scene
    mi::base::Handle<mi::neuraylib::IImage_api> image_api(
        neuray->get_api_component<mi::neuraylib::IImage_api>());
    mi::base::Handle<mi::neuraylib::IRender_target> render_target(
        new Render_target( image_api.get(), "Color", 512, 384));
    check_success( render_context->render( transaction.get(), render_target.get(), 0) >= 0);
 
    // Write the image to disk
    mi::base::Handle<mi::neuraylib::IExport_api> export_api(
        neuray->get_api_component<mi::neuraylib::IExport_api>());
    check_success( export_api.is_valid_interface());
    mi::base::Handle<mi::neuraylib::ICanvas> canvas( render_target->get_canvas( 0));
    export_api->export_canvas( "file:example_rendering.png", canvas.get());
 
    // All transactions need to get committed or aborted.
    transaction->commit();
}
 
int main( int argc, char* argv[])
{
    // Collect command line parameters
    if( argc != 3) {
        std::cerr << "Usage: example_rendering <scene_file> <mdl_path>" << std::endl;
        keep_console_open();
        return EXIT_FAILURE;
    }
    const char* scene_file = argv[1];
    const char* mdl_path   = argv[2];
 
    // Access the neuray library
    mi::base::Handle<mi::neuraylib::INeuray> neuray( load_and_get_ineuray());
    check_success( neuray.is_valid_interface());
 
    // Configure the neuray library
    configuration( neuray.get(), mdl_path);
 
    // Start the neuray library
    mi::Sint32 result = neuray->start();
    check_start_success( result);
 
    // Do the actual rendering
    rendering( neuray.get(), scene_file);
 
    // Shut down the neuray library
    check_success( neuray->shutdown() == 0);
    neuray = 0;
 
    // Unload the neuray library
    check_success( unload());
 
    keep_console_open();
    return EXIT_SUCCESS;
}

[Previous] [Next] [Up]