Example for a Queue Manager Client

[Previous] [Up]

This example demonstrates the use of the queue manager.

New Topics

• Submitting jobs to the queue manager

Detailed Description

Submitting jobs to the queue manager

To submit a job to the queue manager you first need to upload the scene via the Iray Bridge and create a snapshot of it. See Example for the Bridge for details.

A connection to the queue manager is established with mi::neuraylib::IQueue_manager_api::connect(). If successful, it returns an instance of mi::neuraylib::IQueue_manager_connection which allows to submit jobs.

A job is described by a set of job parameters, most notably the snapshots and the render target. The snapshot array contains the snapshots to be rendered, along with a template name for the rendered canvases. The render target is, as usual, an array of canvas names and pixel types. Additionally, one can specify an output name that is used with the template name specified in the snapshots array.

Note that the job results are stored on the server. It is not possible to retrieve the job results via the API (or control other aspects of the queue manager).

Example Source

Source Code Location: examples/example_queue_manager_client.cpp

/******************************************************************************
 * Copyright 2023 NVIDIA Corporation. All rights reserved.
 *****************************************************************************/
 
// examples/example_queue_manager_client.cpp
//
// Connects to a queue manager server, uploads a scene, makes a snapshot, and asks the server to
// render it.
//
// The example expects the following command line argument:
//
//   example_queue_manager_client <scene_file> <mdl_path> <queue_manager_address> <user_name>
//                                <password>
//
// scene_file              some scene file, e.g., main.mi
// mdl_path                path to the MDL modules, e.g., iray-<version>/mdl
// queue_manager_address   URL of the queue manager server, e.g., ws://127.0.0.1:9090 (no SSL) or
//                         wss://irayvca.nvidia.com:443 (SSL)
// user_name               User name of the queue manager account to be used
// password                Password of the queue manager account to be used
//
// The rendered images are written to files named "example_queue_manager_client_snapshot_result.png"
// and "example_queue_manager_client_snapshot_normal.png" in a subdirectory of the results directory
// configured for the queue manager.
 
#include <iostream>
#include <sstream>
#include <string>
 
#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"
 
 
// Snapshot callback implementation.
class Iray_bridge_snapshot_callback
  : public mi::base::Interface_implement<mi::bridge::IIray_bridge_snapshot_callback>
{
public:
    void ready( mi::Sint32 error_code, const char* /*file_name*/)
    {
        if( error_code == 0)
            fprintf( stderr, "Successfully created cb snapshot.\n");
        else
            fprintf( stderr, "Failed to create cb snapshot.\n");
        m_condition.signal();
    }
 
    void progress( mi::Float64 value, const char* area, const char* message)
    {
        fprintf( stderr, "Progress: %.4f %s %s\n", value, area, message);
    }
 
    void wait_for_ready_callback()
    {
        m_condition.wait();
    }
 
private:
    mi::base::Condition m_condition;
};
 
 
void configuration( mi::neuraylib::INeuray* neuray, const char* mdl_path)
{
    // 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 Bridge client, 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( "iray_bridge_client" MI_BASE_DLL_FILE_EXT) == 0);
    check_success( pc->load_plugin_library( "mi_importer" MI_BASE_DLL_FILE_EXT) == 0);
}
 
void import_and_store_scene( 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.
    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"));
    check_success( scene.is_valid_interface());
    scene->set_rootgroup(       import_result->get_rootgroup());
    scene->set_options(         import_result->get_options());
    scene->set_camera_instance( import_result->get_camera_inst());
 
    // And store it in the database
    transaction->store( scene.get(), "the_scene");
    scene = 0;
    transaction->commit();
}
 
void make_snapshot(
    mi::neuraylib::INeuray* neuray,
    const char* queue_manager_address,
    const char* user_name,
    const char* password)
{
    // Get the database, the global scope of the database, and create a transaction in the global
    // scope.
    mi::base::Handle<mi::neuraylib::IDatabase> database(
        neuray->get_api_component<mi::neuraylib::IDatabase>());
    mi::base::Handle<mi::neuraylib::IScope> scope( database->get_global_scope());
    mi::base::Handle<mi::neuraylib::ITransaction> transaction( scope->create_transaction());
 
    // Connect to the queue manager api first to get a compatible bridge url for snapshot
    // creation.
    mi::base::Handle<mi::neuraylib::IQueue_manager_api> queue_manager_api(
        neuray->get_api_component<mi::neuraylib::IQueue_manager_api>());
    mi::Sint32 errors = 0;
    mi::base::Handle<mi::neuraylib::IQueue_manager_connection> connection(
        queue_manager_api->connect( queue_manager_address, user_name, password, &errors));
    check_success( errors == 0);
    check_success( connection.is_valid_interface());
 
    // Configure the Iray Bridge client
    const std::string bridge_server_url(connection->get_compatible_snapshot_bridge_url());
    const std::string authentication_token(connection->get_authentication_token());
 
    mi::base::Handle<mi::bridge::IIray_bridge_client> iray_bridge_client(
        neuray->get_api_component<mi::bridge::IIray_bridge_client>());
    check_success( iray_bridge_client.is_valid_interface());
    check_success( iray_bridge_client->set_application_url( bridge_server_url.c_str()) == 0);
    check_success( iray_bridge_client->set_security_token( authentication_token.c_str()) == 0);
 
    // Create a context for the snapshot.
    mi::base::Handle<mi::bridge::IIray_bridge_snapshot_context> snapshot_context(
        iray_bridge_client->create_snapshot_context( transaction.get(), "the_scene"));
 
    // Create a callback instance, trigger snapshot creation, and wait for the callback to signal
    // completion of the snapshot.
    mi::base::Handle<Iray_bridge_snapshot_callback> callback( new Iray_bridge_snapshot_callback());
    mi::Sint32 result
        = snapshot_context->create_snapshot( transaction.get(), "snapshot.cb", callback.get());
    if( result >= 0)
        callback->wait_for_ready_callback();
 
    transaction->commit();
}
 
void rendering(
    mi::neuraylib::INeuray* neuray,
    const char* queue_manager_address,
    const char* user_name,
    const char* password)
{
    mi::base::Handle<mi::neuraylib::IQueue_manager_api> queue_manager_api(
        neuray->get_api_component<mi::neuraylib::IQueue_manager_api>());
    mi::Sint32 errors = 0;
    mi::base::Handle<mi::neuraylib::IQueue_manager_connection> connection(
        queue_manager_api->connect( queue_manager_address, user_name, password, &errors));
    check_success( errors == 0);
    check_success( connection.is_valid_interface());
 
    mi::base::Handle<mi::neuraylib::IFactory> factory(
        neuray->get_api_component<mi::neuraylib::IFactory>());
    mi::base::Handle<mi::IArray> snapshots( factory->create<mi::IArray>( "Snapshot_data[1]"));
 
    mi::base::Handle<mi::IStructure> snapshot(
        snapshots->get_value<mi::IStructure>( static_cast<mi::Size>( 0)));
    mi::base::Handle<mi::IString> snapshot_name(
        snapshot->get_value<mi::IString>( "snapshot_name"));
    snapshot_name->set_c_str( "snapshot.cb");
    mi::base::Handle<mi::IString> result_name(
        snapshot->get_value<mi::IString>( "result_name"));
    result_name->set_c_str( "example_queue_manager_client_snapshot_%B");
 
    mi::base::Handle<mi::IArray> render_targets( factory->create<mi::IArray>( "Canvas_type[2]"));
 
    mi::base::Handle<mi::IStructure> render_target0(
        render_targets->get_value<mi::IStructure>( static_cast<mi::Size>( 0)));
    mi::base::Handle<mi::IString> name0(
       render_target0->get_value<mi::IString>( "name"));
    name0->set_c_str( "result");
    mi::base::Handle<mi::IString> pixel_type0(
        render_target0->get_value<mi::IString>( "pixel_type"));
    pixel_type0->set_c_str( "Color");
    mi::base::Handle<mi::IString> output_name0(
        render_target0->get_value<mi::IString>( "output_name"));
    output_name0->set_c_str( "result");
 
    mi::base::Handle<mi::IStructure> render_target1(
        render_targets->get_value<mi::IStructure>( 1));
    mi::base::Handle<mi::IString> name1(
        render_target1->get_value<mi::IString>( "name"));
    name1->set_c_str( "normal");
    mi::base::Handle<mi::IString> pixel_type1(
        render_target1->get_value<mi::IString>( "pixel_type"));
    pixel_type1->set_c_str( "Float32<3>");
    mi::base::Handle<mi::IString> output_name1(
        render_target1->get_value<mi::IString>( "output_name"));
    output_name1->set_c_str( "normal");
 
    errors = connection->submit_job(
        "example", snapshots.get(), render_targets.get(), 512, 384, 100, 3600, 1.0f, "png", 0);
    check_success( errors == 0);
}
 
int main( int argc, char* argv[])
{
    // Collect command line parameters
    if( argc != 6) {
        std::cerr << "Usage: example_queue_manager_client <scene_file> <mdl_path> \\\n"
                  << "           <queue_manager_address> <user_name> <password>" << std::endl;
        keep_console_open();
        return EXIT_FAILURE;
    }
    const char* scene_file            = argv[1];
    const char* mdl_path              = argv[2];
    const char* queue_manager_address = argv[3];
    const char* user_name             = argv[4];
    const char* password              = argv[5];
 
    // 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);
 
    // Import the scene into the DB
    import_and_store_scene( neuray.get(), scene_file);
 
    // Upload scene to the queue manager server and store it as snapshot there.
    make_snapshot( neuray.get(), queue_manager_address, user_name, password);
 
    // Render the snapshot on the server.
    rendering( neuray.get(), queue_manager_address, user_name, password);
 
    // 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] [Up]