Example for MDL

[Previous] [Next] [Up]

This example demonstrates typical MDL-related tasks. Based on the scene main.mi we show how to modify inputs of material instances, how to create new material instances, and how to attach function calls to material inputs.

New Topics

• Modification of inputs of existing material instances
• Creation of new material instances
• Attaching function calls to material inputs

Detailed Description

Modification of inputs of existing material instances

First we show how to change the color of the material instance "yellow_material" which is used for the cube. To do so, we retrieve the current argument expression and clone it to obtain a mutable instance. Here, the argument expression is a constant and the get_value() method gives access to its value. Alternatively, we could have created the value and the corresponding expression from scratch as shown in the topic below.

To set the value, the free function mi::neuraylib::set_value() is used. Alternatively, we could have retrieved the interface mi::neuraylib::IValue_color and used its set_value() method directly.

The new value is then simply set with the set_argument() method.

These steps are shown here in full detail for illustrative purposes. The helper class mi::neuraylib::Argument_editor can be used to simplify such workflows, as shown in the second code block.

Creation of new material instances

Again we want to change the color of the cube, but now without modifying "yellow_material" (for example, because that material instance is shared with other scene elements that should stay unchanged). This requires three steps: preparation of the arguments of the new material instance, creation of the new material instance, and attaching it to the scene element in question.

First we prepare an expression list that holds the arguments of the new material instance. This is mandatory if the material definition has parameters without default initializers, otherwise it is optional. In both cases, arguments can be modified after creation of the material instance as shown above. Here, we create the new argument expression from scratch.

Next we use the method create_material_instance() to create a new material instance from the material definition "mdl::main::diffuse_material" (the same definition that was used for "yellow_material"). The newly created material instance is stored in the database.

Finally we replace the previously used material instance "yellow_material" with the just created one by changing the "material" attribute of "cube_instance".

Attaching function calls to material inputs

The previous two topics worked with constant inputs for the material instances. In this topic we connect another MDL function to the input of the material instance.

All arguments of material instances or function calls are expressions. There are two important types of expressions: constants (represents by mi::neuraylib::IExpression_constant) and calls (represents by mi::neuraylib::IExpression_call). In the previous two topics we used constants to represent the color, now we use a call expression to attach a different MDL function.

In this example we show how to apply a texture to the ground plane. First we create the necessary DB elements of type mi::neuraylib::IImage and mi::neuraylib::ITexture to hold the texture we want to use. Next we import the MDL module base which contains the MDL function "mdl::base::file_texture" that we are going to use here.

Similar as in the previous topic for material definitions we now instantiate the function definition "mdl::base::file_texture" with the argument "texture" set to the DB element of type mi::neuraylib::ITexture that we created earlier. Actually, the true name of the DB element representing the MDL function "base::file_texture" is not "mdl::base::file_texture", but a quite long name that includes the function signature. Hence, we use the method mi::neuraylib::IModule::get_function_overloads() to retrieve the exact name of the DB element without hard-coding it.

The return type of "mdl::base::file_texture" is the structure "texture_return" which does not match the desired argument type mi::neuraylib::IType_color of the "tint" argument of our material instance. Hence we use the MDL function "mdl::base::texture_return.tint" which extracts the "tint" field of the "texture_return" structure. In this case we did not use the helper function get_function_overloads() but simply used the full name "mdl::base::texture_return.tint(::base::texture_return)" directly. Again we instantiate that function definition and set its "s" argument to our instance of "mdl::base::file_texture".

As shown in the first example we finally just change the "tint" argument of the material instance used for the ground plane to point to the just created function call. We also show how this step can be simplified using the helper class mi::neuraylib::Argument_editor.

Example Source

Source Code Location: examples/example_mdl.cpp

/******************************************************************************
 * Copyright 2023 NVIDIA Corporation. All rights reserved.
 *****************************************************************************/
 
// examples/example_mdl.cpp
//
// Imports a scene file, performs various MDL-related operations, and writes the rendered results
// to disk.
//
// The example expects the following command line arguments:
//
//   example_mdl <mdl_path>
//
// mdl_path         path to the MDL modules, e.g., iray-<version>/mdl
//
// The rendered images are written to files named "example_mdl_*.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);
    check_success( rc->add_resource_path( ".") == 0);
 
    // Load the OpenImageIO, Iray Photoreal, .mi importer, and MDL distiller 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);
    check_success( pc->load_plugin_library( "mdl_distiller" MI_BASE_DLL_FILE_EXT) == 0);
}
 
void render_and_export(
    mi::neuraylib::INeuray* neuray,
    mi::neuraylib::ITransaction* transaction,
    const char* uri)
{
    // Create the render context using the Iray Photoreal render mode.
    mi::base::Handle<mi::neuraylib::IScene> scene(
        transaction->edit<mi::neuraylib::IScene>( "the_scene"));
    mi::base::Handle<mi::neuraylib::IRender_context> render_context(
        scene->create_render_context( transaction, "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, 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( uri, canvas.get());
}
 
void import_and_render_original_scene(
    mi::neuraylib::INeuray* neuray, mi::neuraylib::IScope* scope)
{
    // Create a transaction for importing the scene file and storing the scene.
    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::neuraylib::IImport_result> import_result(
        import_api->import_elements( transaction.get(), "file:main.mi"));
    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");
 
    render_and_export( neuray, transaction.get(), "file:example_mdl_original.png");
    transaction->commit();
}
 
void modify_material_instance(
    mi::neuraylib::INeuray* neuray,
    mi::neuraylib::IScope* scope,
    mi::neuraylib::IMdl_factory* mdl_factory)
{
    // Create a transaction and MDL expression factory.
    mi::base::Handle<mi::neuraylib::ITransaction> transaction(
        scope->create_transaction());
    check_success( transaction.is_valid_interface());
    mi::base::Handle<mi::neuraylib::IExpression_factory> expression_factory(
        mdl_factory->create_expression_factory( transaction.get()));
 
    {
        // Create a new argument for the "tint" parameter and set it to bright grey.
        mi::base::Handle<mi::neuraylib::IFunction_call> yellow_material(
            transaction->edit<mi::neuraylib::IFunction_call>( "yellow_material"));
        mi::base::Handle<const mi::neuraylib::IExpression_list> arguments(
            yellow_material->get_arguments());
        mi::base::Handle<const mi::neuraylib::IExpression> argument(
            arguments->get_expression( "tint"));
        mi::base::Handle<mi::neuraylib::IExpression> new_argument(
            expression_factory->clone( argument.get()));
        mi::base::Handle<mi::neuraylib::IExpression_constant> new_argument_constant(
            new_argument->get_interface<mi::neuraylib::IExpression_constant>());
        mi::base::Handle<mi::neuraylib::IValue> new_value( new_argument_constant->get_value());
        mi::math::Color bright_grey( 0.7f, 0.7f, 0.7f);
        mi::neuraylib::set_value( new_value.get(), bright_grey);
 
        // Set the new argument for the "tint" parameter of "yellow_material".
        check_success( yellow_material->set_argument( "tint", new_argument.get()) == 0);
    }
    // The same effect as in the preceding code block can alternatively be achieved by using the
    // helper class Argument_editor as follows:
    {
        // Set the "tint" argument of "yellow_material" to bright grey.
        mi::neuraylib::Argument_editor yellow_material(
            transaction.get(), "yellow_material", mdl_factory);
        mi::math::Color bright_grey( 0.7f, 0.7f, 0.7f);
        check_success( yellow_material.set_value( "tint", bright_grey) == 0);
 
    }
 
    render_and_export(
        neuray, transaction.get(), "file:example_mdl_modified_material_argument.png");
    transaction->commit();
}
 
void create_new_material_instance(
    mi::neuraylib::INeuray* neuray,
    mi::neuraylib::IScope* scope,
    mi::neuraylib::IMdl_factory* mdl_factory)
{
    // Create a transaction, MDL value and expression factory.
    mi::base::Handle<mi::neuraylib::ITransaction> transaction(
        scope->create_transaction());
    check_success( transaction.is_valid_interface());
    mi::base::Handle<mi::neuraylib::IValue_factory> value_factory(
        mdl_factory->create_value_factory( transaction.get()));
    mi::base::Handle<mi::neuraylib::IExpression_factory> expression_factory(
        mdl_factory->create_expression_factory( transaction.get()));
 
    {
        // Prepare the arguments for the new material instance: set the "tint" argument to white.
        mi::base::Handle<mi::neuraylib::IValue> value(
            value_factory->create_color( 1.0f, 1.0f, 1.0f));
        mi::base::Handle<mi::neuraylib::IExpression> expression(
            expression_factory->create_constant( value.get()));
        mi::base::Handle<mi::neuraylib::IExpression_list> arguments(
            expression_factory->create_expression_list());
        arguments->add_expression( "tint", expression.get());
 
        // Create a material instance of the definition "mdl::main::diffuse_material" with the just
        // prepared arguments.
        mi::base::Handle<const mi::neuraylib::IFunction_definition> material_definition(
            transaction->access<mi::neuraylib::IFunction_definition>(
                "mdl::main::diffuse_material(color)"));
        mi::Sint32 result;
        mi::base::Handle<mi::neuraylib::IFunction_call> material_instance(
            material_definition->create_function_call( arguments.get(), &result));
        check_success( result == 0);
        transaction->store( material_instance.get(), "white_material");
 
        // Attach the newly created material instance to the scene element "cube_instance", thereby
        // replacing the existing material instance "yellow_material".
        mi::base::Handle<mi::neuraylib::IInstance> instance(
            transaction->edit<mi::neuraylib::IInstance>( "cube_instance"));
        mi::base::Handle<mi::IArray> material( instance->edit_attribute<mi::IArray>( "material"));
        check_success(
            mi::set_value( material.get(), static_cast<mi::Size>( 0), "white_material") == 0);
    }
 
    render_and_export( neuray, transaction.get(), "file:example_mdl_new_material_instance.png");
    transaction->commit();
}
 
void attach_function_call(
    mi::neuraylib::INeuray* neuray,
    mi::neuraylib::IScope* scope,
    mi::neuraylib::IMdl_factory* mdl_factory)
{
    // Create a transaction, MDL value and expression factory.
    mi::base::Handle<mi::neuraylib::ITransaction> transaction(
        scope->create_transaction());
    check_success( transaction.is_valid_interface());
    mi::base::Handle<mi::neuraylib::IValue_factory> value_factory(
        mdl_factory->create_value_factory( transaction.get()));
    mi::base::Handle<mi::neuraylib::IExpression_factory> expression_factory(
        mdl_factory->create_expression_factory( transaction.get()));
    {
        // Create a DB element for the image and the texture referencing it.
        mi::base::Handle<mi::neuraylib::IImage> image(
            transaction->create<mi::neuraylib::IImage>( "Image"));
        check_success( image->reset_file( "nvidia_logo.png") == 0);
        transaction->store( image.get(), "nvidia_image");
        mi::base::Handle<mi::neuraylib::ITexture> texture(
            transaction->create<mi::neuraylib::ITexture>( "Texture"));
        texture->set_image( "nvidia_image");
        // Setting the gamma override value here is not strictly necessary, since the canvas of
        // the image has already a gamma value of 2.2. However, if new MDL source code is
        // generated based on this texture, the explicit setting here causes "::tex::gamma_srgb" to
        // be used instead of "::tex::gamma_default", which might be desired.
        texture->set_gamma( 2.2f);
        transaction->store( texture.get(), "nvidia_texture");
    }
    {
        // Import the "base.mdl" module.
        mi::base::Handle<mi::neuraylib::IImport_api> import_api(
            neuray->get_api_component<mi::neuraylib::IImport_api>());
        mi::base::Handle<const mi::neuraylib::IImport_result> import_result(
            import_api->import_elements( transaction.get(), "${shader}/base.mdl"));
        check_success( import_result->get_error_number() == 0);
    }
    {
        // Lookup the exact name of the DB element for the MDL function "base::file_texture".
        mi::base::Handle<const mi::neuraylib::IModule> module(
            transaction->access<mi::neuraylib::IModule>( "mdl::base"));
        mi::base::Handle<const mi::IArray> overloads(
            module->get_function_overloads( "mdl::base::file_texture"));
        check_success( overloads->get_length() == 1);
        mi::base::Handle<const mi::IString> file_texture_name(
            overloads->get_element<mi::IString>( static_cast<mi::Uint32>( 0)));
 
        // Prepare the arguments of the function call for "mdl::base::file_texture": set the
        // "texture" argument to the "nvidia_texture" texture.
        mi::base::Handle<const mi::neuraylib::IFunction_definition> function_definition(
            transaction->access<mi::neuraylib::IFunction_definition>(
                file_texture_name->get_c_str()));
        mi::base::Handle<const mi::neuraylib::IType_list> types(
            function_definition->get_parameter_types());
        mi::base::Handle<const mi::neuraylib::IType> type(
            types->get_type( "texture"));
        mi::base::Handle<mi::neuraylib::IValue> value(
            value_factory->create( type.get()));
        check_success( mi::neuraylib::set_value( value.get(), "nvidia_texture") == 0);
        mi::base::Handle<mi::neuraylib::IExpression> expression(
            expression_factory->create_constant( value.get()));
        mi::base::Handle<mi::neuraylib::IExpression_list> arguments(
            expression_factory->create_expression_list());
        arguments->add_expression( "texture", expression.get());
 
        // Create a function call from the definition "mdl::base::file_texture" with the just
        // prepared arguments.
        mi::Sint32 result;
        mi::base::Handle<mi::neuraylib::IFunction_call> function_call(
            function_definition->create_function_call( arguments.get(), &result));
        check_success( result == 0);
        function_definition = 0;
        transaction->store( function_call.get(), "file_texture_call");
    }
    {
        // Prepare the arguments of the function call for "mdl::base::texture_return.tint": set the
        // "s" argument to the "file_texture_call" function call.
        mi::base::Handle<mi::neuraylib::IExpression> expression(
            expression_factory->create_call( "file_texture_call"));
        mi::base::Handle<mi::neuraylib::IExpression_list> arguments(
            expression_factory->create_expression_list());
        arguments->add_expression( "s", expression.get());
 
        // Create a function call from the definition "mdl::base::file_texture.tint" with the just
        // prepared arguments.
        mi::base::Handle<const mi::neuraylib::IFunction_definition> function_definition(
            transaction->access<mi::neuraylib::IFunction_definition>(
                "mdl::base::texture_return.tint(::base::texture_return)"));
        mi::Sint32 result;
        mi::base::Handle<mi::neuraylib::IFunction_call> function_call(
            function_definition->create_function_call( arguments.get(), &result));
        check_success( result == 0);
        transaction->store( function_call.get(), "texture_return.tint_call");
    }
    {
        // Create a new expression for the "tint" argument and set it to the
        // "texture_return.tint_call" function call.
        mi::base::Handle<mi::neuraylib::IExpression> expression(
            expression_factory->create_call( "texture_return.tint_call"));
 
        // Set the new argument for the "tint" parameter of "grey_material".
        mi::base::Handle<mi::neuraylib::IFunction_call> grey_material(
            transaction->edit<mi::neuraylib::IFunction_call>( "grey_material"));
        check_success( grey_material->set_argument( "tint", expression.get()) == 0);
    }
    // The same effect as in the preceding code block can alternatively be achieved by using the
    // helper class Mdl_argument_editor as follows:
    {
        // Attach "texture_return.tint_call" to the "tint" argument of "grey_material".
        mi::neuraylib::Argument_editor grey_material(
            transaction.get(), "grey_material", mdl_factory);
        check_success( grey_material.set_call( "tint", "texture_return.tint_call") == 0);
    }
 
    render_and_export( neuray, transaction.get(), "file:example_mdl_attached_function_call.png");
    transaction->commit();
}
 
void use_struct_and_array_constructors(
    mi::neuraylib::INeuray* neuray,
    mi::neuraylib::IScope* scope,
    mi::neuraylib::IMdl_factory* mdl_factory)
{
    // Create a transaction, MDL value and expression factory.
    mi::base::Handle<mi::neuraylib::ITransaction> transaction(
        scope->create_transaction());
    check_success( transaction.is_valid_interface());
    mi::base::Handle<mi::neuraylib::IType_factory> type_factory(
        mdl_factory->create_type_factory( transaction.get()));
    mi::base::Handle<mi::neuraylib::IValue_factory> value_factory(
        mdl_factory->create_value_factory( transaction.get()));
    mi::base::Handle<mi::neuraylib::IExpression_factory> expression_factory(
        mdl_factory->create_expression_factory( transaction.get()));
 
    {
        // Create a first color "color_layer0" layer using "texture_return.tint_call" and
        // "color_layer_brightness" as mode.
 
        // Set the "layer_color" argument to "texture_return.tint_call".
        mi::base::Handle<mi::neuraylib::IExpression_call> expression_layer_color(
            expression_factory->create_call( "texture_return.tint_call"));
 
        // Set the "mode" argument to "color_layer_brightness".
        mi::base::Handle<const mi::neuraylib::IType_enum> type_mode(
            type_factory->create_enum( "::base::color_layer_mode"));
        mi::Size index = type_mode->find_value( "color_layer_brightness");
        check_success( index != static_cast<mi::Size>( -1));
        mi::base::Handle<mi::neuraylib::IValue> value_mode(
            value_factory->create_enum( type_mode.get(), index));
        mi::base::Handle<mi::neuraylib::IExpression> expression_mode(
            expression_factory->create_constant( value_mode.get()));
 
        // Create the arguments list with both arguments above.
        mi::base::Handle<mi::neuraylib::IExpression_list> arguments(
            expression_factory->create_expression_list());
        arguments->add_expression( "layer_color", expression_layer_color.get());
        arguments->add_expression( "mode", expression_mode.get());
 
        // Create a function call of the struct constructor for "mdl::base::color_layer" with
        // the just prepared arguments and store it as "color_layer0".
        mi::base::Handle<const mi::neuraylib::IFunction_definition> function_definition(
            transaction->access<mi::neuraylib::IFunction_definition>(
                "mdl::base::color_layer(color,float,::base::color_layer_mode)"));
        mi::Sint32 result;
        mi::base::Handle<mi::neuraylib::IFunction_call> function_call(
            function_definition->create_function_call( arguments.get(), &result));
        check_success( result == 0);
        transaction->store( function_call.get(), "color_layer0");
    }
    {
        // Create a second color layer "color_layer1" with "layer_color" set to blue and
        // "color_layer_average" as mode. Store it as "color_layer1".
 
        // Set the "layer_color" argument to blue.
        mi::base::Handle<mi::neuraylib::IValue> value_layer_color(
            value_factory->create_color( 0.0f, 0.0f, 1.0f));
        mi::base::Handle<mi::neuraylib::IExpression_constant> expression_layer_color(
            expression_factory->create_constant( value_layer_color.get()));
 
        // Set the "mode" argument to "color_layer_average".
        mi::base::Handle<const mi::neuraylib::IType_enum> type_mode(
            type_factory->create_enum( "::base::color_layer_mode"));
        mi::Size index = type_mode->find_value( "color_layer_average");
        check_success( index != static_cast<mi::Size>( -1));
        mi::base::Handle<mi::neuraylib::IValue> value_mode(
            value_factory->create_enum( type_mode.get(), index));
        mi::base::Handle<mi::neuraylib::IExpression> expression_mode(
            expression_factory->create_constant( value_mode.get()));
 
        // Create the arguments list with both arguments above.
        mi::base::Handle<mi::neuraylib::IExpression_list> arguments(
            expression_factory->create_expression_list());
        arguments->add_expression( "layer_color", expression_layer_color.get());
        arguments->add_expression( "mode", expression_mode.get());
 
        // Create a function call of the struct constructor for "mdl::base::color_layer" with
        // the just prepared arguments and store it as "color_layer1".
        mi::base::Handle<const mi::neuraylib::IFunction_definition> function_definition(
            transaction->access<mi::neuraylib::IFunction_definition>(
                "mdl::base::color_layer(color,float,::base::color_layer_mode)"));
        mi::Sint32 result;
        mi::base::Handle<mi::neuraylib::IFunction_call> function_call(
            function_definition->create_function_call( arguments.get(), &result));
        check_success( result == 0);
        transaction->store( function_call.get(), "color_layer1");
    }
    {
        // Create an array of the two color layers "color_layer0" and "color_layer1" using the array
        // constructor. Store it as "color_layers".
 
        // Create the argument list with both arguments "color_layer0" and "color_layer1".
        mi::base::Handle<mi::neuraylib::IExpression> expression_color_layer0(
            expression_factory->create_call( "color_layer0"));
        mi::base::Handle<mi::neuraylib::IExpression> expression_color_layer1(
            expression_factory->create_call( "color_layer1"));
        mi::base::Handle<mi::neuraylib::IExpression_list> arguments(
            expression_factory->create_expression_list());
        arguments->add_expression( "value0", expression_color_layer0.get());
        arguments->add_expression( "value1", expression_color_layer1.get());
 
        // Create a function call of the array constructor with the just prepared arguments and
        // store it as "color_layers".
        mi::base::Handle<const mi::neuraylib::IFunction_definition> function_definition(
            transaction->access<mi::neuraylib::IFunction_definition>( "mdl::T[](...)"));
        mi::Sint32 result;
        mi::base::Handle<mi::neuraylib::IFunction_call> function_call(
            function_definition->create_function_call( arguments.get(), &result));
        check_success( result == 0);
        transaction->store( function_call.get(), "color_layers");
    }
    {
        // Create a blend of the two color layers and red as base color. Store it as
        // "blended_color_layers".
 
        // Set the "layers" argument to "color_layers".
        mi::base::Handle<mi::neuraylib::IExpression> expression_layers(
            expression_factory->create_call( "color_layers"));
 
        // Set the "base" argument to red.
        mi::base::Handle<mi::neuraylib::IValue> value_base(
            value_factory->create_color( 1.0f, 0.0f, 0.0f));
        mi::base::Handle<mi::neuraylib::IExpression> expression_base(
            expression_factory->create_constant( value_base.get()));
 
        // Create the argument list with both arguments above.
        mi::base::Handle<mi::neuraylib::IExpression_list> arguments(
            expression_factory->create_expression_list());
        arguments->add_expression( "layers", expression_layers.get());
        arguments->add_expression( "base", expression_base.get());
 
        // Create a function call from the definition "mdl::base::blend_color_layers" with the just
        // prepared arguments and store it as "blended_color_layers".
        mi::base::Handle<const mi::neuraylib::IFunction_definition> function_definition(
            transaction->access<mi::neuraylib::IFunction_definition>(
                "mdl::base::blend_color_layers(::base::color_layer[P],color,::base::mono_mode)"));
        mi::Sint32 result;
        mi::base::Handle<mi::neuraylib::IFunction_call> function_call(
            function_definition->create_function_call( arguments.get(), &result));
        check_success( result == 0);
        transaction->store( function_call.get(), "blended_color_layers");
    }
    {
        // Prepare the arguments of the function call for "mdl::base::texture_return.tint": set the
        // "s" argument to the "file_texture_call" function call.
        mi::base::Handle<mi::neuraylib::IExpression> expression(
            expression_factory->create_call( "blended_color_layers"));
        mi::base::Handle<mi::neuraylib::IExpression_list> arguments(
            expression_factory->create_expression_list());
        arguments->add_expression( "s", expression.get());
 
        // Create a function call from the definition "mdl::base::file_texture.tint" with the just
        // prepared arguments and store it as "texture_return.tint_call2".
        mi::base::Handle<const mi::neuraylib::IFunction_definition> function_definition(
            transaction->access<mi::neuraylib::IFunction_definition>(
                "mdl::base::texture_return.tint(::base::texture_return)"));
        mi::Sint32 result;
        mi::base::Handle<mi::neuraylib::IFunction_call> function_call(
            function_definition->create_function_call( arguments.get(), &result));
        check_success( result == 0);
        transaction->store( function_call.get(), "texture_return.tint_call2");
    }
    {
        // Attach "texture_return.tint_call2" to the "tint" argument of "grey_material".
        mi::neuraylib::Argument_editor grey_material(
            transaction.get(), "grey_material", mdl_factory);
        check_success( grey_material.set_call( "tint", "texture_return.tint_call2") == 0);
    }
 
    render_and_export(
        neuray, transaction.get(), "file:example_mdl_struct_and_array_constructors.png");
    transaction->commit();
}
 
void create_variant(
    mi::neuraylib::INeuray* neuray,
    mi::neuraylib::IScope* scope,
    mi::neuraylib::IMdl_factory* mdl_factory)
{
    // Create a transaction, MDL value and expression factory.
    mi::base::Handle<mi::neuraylib::ITransaction> transaction(
        scope->create_transaction());
    check_success( transaction.is_valid_interface());
    mi::base::Handle<mi::neuraylib::IValue_factory> value_factory(
        mdl_factory->create_value_factory( transaction.get()));
    mi::base::Handle<mi::neuraylib::IExpression_factory> expression_factory(
        mdl_factory->create_expression_factory( transaction.get()));
    {
        // Prepare new defaults as clone of the current arguments of "grey_material".
        mi::base::Handle<const mi::neuraylib::IFunction_call> grey_material(
            transaction->access<mi::neuraylib::IFunction_call>( "grey_material"));
        mi::base::Handle<const mi::neuraylib::IExpression_list> arguments(
            grey_material->get_arguments());
        mi::base::Handle<mi::neuraylib::IExpression_list> defaults(
            expression_factory->clone( arguments.get()));
 
        // Create an ::anno::description annotation.
        mi::base::Handle<mi::neuraylib::IValue> anno_arg_value(
            value_factory->create_string( "a textured variant of ::main::diffuse_material"));
        mi::base::Handle<mi::neuraylib::IExpression> anno_arg_expression(
            expression_factory->create_constant( anno_arg_value.get()));
        mi::base::Handle<mi::neuraylib::IExpression_list> anno_args(
            expression_factory->create_expression_list());
        anno_args->add_expression( "description", anno_arg_expression.get());
        mi::base::Handle<mi::neuraylib::IAnnotation> anno(
            expression_factory->create_annotation( "::anno::description(string)", anno_args.get()));
        mi::base::Handle<mi::neuraylib::IAnnotation_block> anno_block(
            expression_factory->create_annotation_block());
        anno_block->add_annotation( anno.get());
 
        // Create the module bulder.
        mi::base::Handle<mi::neuraylib::IMdl_execution_context> context(
            mdl_factory->create_execution_context());
        mi::base::Handle<mi::neuraylib::IMdl_module_builder> module_builder(
            mdl_factory->create_module_builder(
                transaction.get(),
                "mdl::variants",
                mi::neuraylib::MDL_VERSION_1_0,
                mi::neuraylib::MDL_VERSION_LATEST,
                context.get()));
        check_success( module_builder);
 
        // Create the variant.
        check_success( module_builder->add_variant(
            "textured_material",
            "mdl::main::diffuse_material(color)",
            defaults.get(),
            anno_block.get(),
            /*return_annotations*/ 0,
            /*is_exported*/ true,
            context.get()) == 0);
    }
    {
        // Instantiate the variant.
        mi::base::Handle<const mi::neuraylib::IFunction_definition> textured_material_def(
            transaction->access<mi::neuraylib::IFunction_definition>(
                "mdl::variants::textured_material(color)"));
        mi::Sint32 result = 0;
        mi::base::Handle<mi::neuraylib::IFunction_call> textured_material(
            textured_material_def->create_function_call( 0, &result));
        check_success( result == 0);
        transaction->store( textured_material.get(), "textured_material");
 
        // Attach the instantiated variant to the scene element "ground_instance", thereby
        // replacing the existing material instance "grey_material" it was created from.
        mi::base::Handle<mi::neuraylib::IInstance> instance(
                transaction->edit<mi::neuraylib::IInstance>( "ground_instance"));
        mi::base::Handle<mi::IArray> material( instance->edit_attribute<mi::IArray>( "material"));
        check_success(
            mi::set_value( material.get(), static_cast<mi::Size>( 0), "textured_material") == 0);
    }
    {
        // Export the variant.
        mi::base::Handle<mi::IArray> elements( transaction->create<mi::IArray>( "String[1]"));
        mi::base::Handle<mi::IString> element(
            elements->get_element<mi::IString>( static_cast<mi::Size>( 0)));
        element->set_c_str( "mdl::variants");
        mi::base::Handle<mi::neuraylib::IExport_api> export_api(
            neuray->get_api_component<mi::neuraylib::IExport_api>());
        mi::base::Handle<const mi::neuraylib::IExport_result> export_result(
            export_api->export_elements( transaction.get(), "file:variants.mdl", elements.get()));
    }
 
    render_and_export( neuray, transaction.get(), "file:example_mdl_variant.png");
    transaction->commit();
}
 
// Distills a material instance to the diffuse target, bakes a path from the distilled
// material, creates another material that fits the target model and assigns the
// result of the baking to its input parameters. Then, the new material is attached to the
// cube instance and the scene is rendered.
void distill(
    mi::neuraylib::INeuray* neuray,
    mi::neuraylib::IScope* scope,
    mi::neuraylib::IMdl_factory* mdl_factory)
{
    // Create a transaction, MDL value, type and expression factory.
    mi::base::Handle<mi::neuraylib::ITransaction> transaction(
        scope->create_transaction());
    check_success( transaction.is_valid_interface());
 
    mi::base::Handle<mi::neuraylib::IExpression_factory> expression_factory(
        mdl_factory->create_expression_factory( transaction.get()));
    mi::base::Handle<mi::neuraylib::IValue_factory> value_factory(
        mdl_factory->create_value_factory( transaction.get()));
    mi::base::Handle<mi::neuraylib::IType_factory> type_factory(
        mdl_factory->create_type_factory( transaction.get()));
 
    {
        // Access and compile material instance
        mi::base::Handle<const mi::neuraylib::IMaterial_instance> grey_material(
            transaction->access<mi::neuraylib::IMaterial_instance>( "grey_material"));
        check_success(grey_material.is_valid_interface());
 
        mi::Uint32 flags = mi::neuraylib::IMaterial_instance::DEFAULT_OPTIONS;
        mi::base::Handle<const mi::neuraylib::ICompiled_material> comiled_material(
            grey_material->create_compiled_material(flags));
        check_success(comiled_material.is_valid_interface());
 
        // Use Distiller API to distill material to diffuse target
        mi::base::Handle<mi::neuraylib::IMdl_distiller_api> distiller_api(
            neuray->get_api_component<mi::neuraylib::IMdl_distiller_api>());
        check_success(distiller_api.is_valid_interface());
 
        mi::base::Handle<const mi::neuraylib::ICompiled_material> distilled_material(
            distiller_api->distill_material(comiled_material.get(), "diffuse"));
        check_success(distilled_material.is_valid_interface());
 
        // Bake a path from the distilled material and apply the
        // baking result to another material instance
 
        mi::base::Handle<const mi::neuraylib::IBaker> baker(distiller_api->create_baker(
            distilled_material.get(),
            "surface.scattering.tint"));
        check_success(baker.is_valid_interface());
 
        // Setup target material arguments
        mi::base::Handle<mi::neuraylib::IExpression_list> target_material_arguments(
            expression_factory->create_expression_list());
 
        mi::base::Handle<mi::neuraylib::IValue_bool> use_tex(
            value_factory->create_bool(!baker->is_uniform()));
        mi::base::Handle<mi::neuraylib::IExpression_constant> use_tex_expr(
            expression_factory->create_constant(use_tex.get()));
        target_material_arguments->add_expression("tint_use_texture", use_tex_expr.get());
 
        // Bake the path
        if(baker->is_uniform())
        {
            // Bake constant
            mi::base::Handle<mi::IColor> constant_color(
                transaction->create<mi::IColor>());
            check_success(baker->bake_constant(constant_color.get()) == 0);
 
            // Setup color argument for target material
            mi::Color c(0.0f, 0.0f, 0.0f);
            mi::get_value(constant_color.get(), c);
            mi::base::Handle<mi::neuraylib::IValue_color> color(
                value_factory->create_color(c.r, c.g, c.b));
            mi::base::Handle<mi::neuraylib::IExpression_constant> color_expr(
                expression_factory->create_constant(color.get()));
 
            target_material_arguments->add_expression("tint_color", color_expr.get());
        }
        else
        {
            // Create a canvas for storing the baked texture
            mi::base::Handle<mi::neuraylib::IImage_api> image_api(
                neuray->get_api_component<mi::neuraylib::IImage_api>());
            check_success(image_api.is_valid_interface());
 
            mi::base::Handle<mi::neuraylib::ICanvas> canvas(
                image_api->create_canvas("Rgb_fp", 1024, 1024));
            check_success(canvas.is_valid_interface());
 
            // Bake the texture
            check_success(baker->bake_texture(canvas.get(), 4) == 0);
 
            // Write the image to disk (for illustration purposes)
            mi::base::Handle<mi::neuraylib::IExport_api> export_api(
                neuray->get_api_component<mi::neuraylib::IExport_api>());
            check_success( export_api.is_valid_interface());
            export_api->export_canvas( "file:bake_result.png", canvas.get());
 
            // Store the baked texture into a database texture
            mi::base::Handle<mi::neuraylib::IImage> image(
                transaction->create<mi::neuraylib::IImage>( "Image"));
            check_success( image->set_from_canvas(canvas.get()));
            transaction->store( image.get(), "baked_image");
            mi::base::Handle<mi::neuraylib::ITexture> texture(
                transaction->create<mi::neuraylib::ITexture>( "Texture"));
            texture->set_image( "baked_image");
            transaction->store( texture.get(), "baked_texture");
 
            // Setup texture argument for target material
            mi::base::Handle<const mi::neuraylib::IType_texture> tex_type(
                type_factory->create_texture(mi::neuraylib::IType_texture::TS_2D));
            mi::base::Handle<mi::neuraylib::IValue_texture> tex(
                value_factory->create_texture(tex_type.get(), "baked_texture"));
            mi::base::Handle<mi::neuraylib::IExpression_constant> tex_ref(
                expression_factory->create_constant(tex.get()));
 
            target_material_arguments->add_expression("tint_texture", tex_ref.get());
        }
 
        // Create target material instance
        mi::neuraylib::Definition_wrapper target_material_def(
            transaction.get(),
            "mdl::main::textured_diffuse_material(texture_2d,bool,color)",
            mdl_factory);
        check_success(target_material_def.is_valid());
 
        mi::base::Handle<mi::neuraylib::IScene_element> target_material(
            target_material_def.create_instance(target_material_arguments.get()));
        transaction->store(target_material.get(), "target_material");
 
        // Attach the newly created material instance to the scene element "cube_instance"
        mi::base::Handle<mi::neuraylib::IInstance> instance(
            transaction->edit<mi::neuraylib::IInstance>( "cube_instance"));
        mi::base::Handle<mi::IArray> material( instance->edit_attribute<mi::IArray>( "material"));
        check_success(
            mi::set_value( material.get(), static_cast<mi::Size>( 0), "target_material") == 0);
    }
 
    render_and_export( neuray, transaction.get(), "file:example_mdl_distilling.png");
    transaction->commit();
}
 
void rendering( mi::neuraylib::INeuray* neuray)
{
    // Get the database and the global scope of the database.
    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());
 
   // Import the scene and render it.
   import_and_render_original_scene( neuray, scope.get());
 
   // Perform various MDL-related modifications, render the scene, and export the image to disk.
   mi::base::Handle<mi::neuraylib::IMdl_factory> mdl_factory(
       neuray->get_api_component<mi::neuraylib::IMdl_factory>());
   modify_material_instance( neuray, scope.get(), mdl_factory.get());
   create_new_material_instance( neuray, scope.get(), mdl_factory.get());
   attach_function_call( neuray, scope.get(), mdl_factory.get());
   use_struct_and_array_constructors( neuray, scope.get(), mdl_factory.get());
   create_variant( neuray, scope.get(), mdl_factory.get());
   distill( neuray, scope.get(), mdl_factory.get());
}
 
int main( int argc, char* argv[])
{
    // Collect command line parameters
    if( argc != 2) {
        std::cerr << "Usage: example_mdl <mdl_path>" << std::endl;
        keep_console_open();
        return EXIT_FAILURE;
    }
    const char* mdl_path = argv[1];
 
    // 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());
 
    // 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]