Member Functions

virtual void mi::​nservices::​IRender_loop::cancel_render( mi::Sint32 cancel_level) [pure virtual]

Cancels any ongoing render.

Parameters

cancel_level

How fast to cancel rendering, 0 cancels, and if possible continues rendering without restarting progression. 1 will cancel faster at the expense of always needing to restart.

virtual void mi::​nservices::​IRender_loop::end_loop() [pure virtual]

Ends the loop. Note that this call will block until the render loop thread quits.

virtual mi::Sint32 mi::​nservices::​IRender_loop::execute_commands( mi::IArray* commands, const char* id = nullptr, mi::Sint32 sequence_id = -1, bool abort_on_error = false, mi::Sint32 cancel_level = -1, ICommand_execute_response_handler* callback = nullptr, mi::IMap* service_request_attachments = nullptr) [pure virtual]

Executes an array of commands on this render loop between the current and the next render call. By default commands are executed in the scope of the render loop however this can be changed by calling set_execution_scope_name. Alternatively a use_scope command can be used in the commands array to change the scope just for this execution batch.

Parameters

commands

an array of mi::nservices::ICommand_request objects to execute.

id

an identifier for this command set. If provided, and callback is nullptr then results will be available using get_command_results under this id.

sequence_id

if positive then this sequence id is returned with the image statistics over web sockets. If strictly increasing values are provided then the user can easily determine if a given image contains changes from a given set of commands.

abort_on_error

if true then all subsequent commands are aborted if a command returns an error. If false then command execution continues.

cancel_level

whether to cancel the current render to make the commands execute sooner. 0 cancels, and if possible continues rendering without restarting progression. 1 will cancel faster at the expense of always needing to restart. A negative value, the default, means not to cancel.

callback

optional callback to be called when command execution is complete.

service_request_attachments

optional map of attachments to be set when creating the service request.

Returns

• 0: Success
• -1: Error
• -2: Invalid parameters, commands is NULL or cancel_level is invalid.
• -3: commands contains entries that are not mi::nservices::ICommand_request objects.

virtual mi::neuraylib::ICanvas* mi::​nservices::​IRender_loop::get_canvas() [pure virtual]

Retrieves the most recently render canvas. This will be the most recent result render returned by the handler.

virtual const mi::IMap* mi::​nservices::​IRender_loop::get_command_responses( const char* id) [pure virtual]

Called to get the results of an executed command set. Valid results for a given id will only be returned once, subsequent calls with the same id will return nullptr. The returned map contains two elements. responses which is an mi::IArray of either mi::nservices::ICommand_response or mi::neuraylib::IConst_pointer pointing to an mi::nservices::ICommand_response . commands also contains an mi::IArray of the commands called. If execution was aborted due to error then the responses array may be smaller than the commands array, or have invalid or null values for commands that were not executed.

Parameters

id

the identifier provided with the command set when execute_commands was called.

Returns

A map containing the responses and commands. If id is nullptr ; an empty string or an unknown id then nullptr is returned. nullptr is also returned if the commands have not completed executing or have been previously retrieved.

virtual const char* mi::​nservices::​IRender_loop::get_execution_scope_name() const [pure virtual]

returns the name of the execution scope to use or NULL if the global scope is to be used.

Returns

the scope name or NULL

virtual mi::Sint32 mi::​nservices::​IRender_loop::get_last_render_result() [pure virtual]

Returns the result of the last render. A value of -100 means that no render has yet completed in the loop.

virtual const char* mi::​nservices::​IRender_loop::get_name() const [pure virtual]

returns the name of the render loop

virtual const mi::IData* mi::​nservices::​IRender_loop::get_parameter( const char* key) [pure virtual]

Gets a render loop parameter from the render handler. This call is passed through to IRender_loop_handler::get_parameter().

Parameters

key

the parameter key

Returns

the value of parameter key or NULL if key does not exist

virtual Render_loop_pause_state mi::​nservices::​IRender_loop::get_paused() [pure virtual]

Gets the paused state of the render loop.

Returns

The paused state of the render loop.

virtual mi::Float64 mi::​nservices::​IRender_loop::get_progress( const char* area) const [pure virtual]

Returns the progress of the render being performed by the render context used by this render loop. The type of progress returned is selected by the area parameter.

Parameters

area

This describes the area where progress has been made. The following values are currently supported depending on the renderer used:

• progression (in progressive rendering mode) Estimated progression between 0 and 1, indicating progress until error threshold is reached.
• error (in progressive rendering mode) Current estimate of per-pixel error.
• iteration (iray/hybrid) Number of iterations accumulated in the current progression.

Returns

Some value which gives information about how much the work progressed. The interpretation depends on the area string. In some areas it might be a percentage, in some it might be an absolute value. Will be -1 if area is NULL , an empty string or an unknown value.

virtual mi::IMap* mi::​nservices::​IRender_loop::get_progress() const [pure virtual]

Returns a map containing all render progress statistics for the current render.

virtual const mi::IData* mi::​nservices::​IRender_loop::get_render_context_option( const char* key) const [pure virtual]

Returns the value of a render-context option.

See also:

set_option()

Returns

The value of the option, or NULL in case of failure, e.g, if there is no such option.

template< class T>

const T* mi::​nservices::​IRender_loop::get_render_context_option( const char* name) const [inline]

Returns the value of a render-context option.

See also:

set_render_context_option()

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface(const Uuid &) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Parameters

name

The name of the option.

Returns

The value of the option, or NULL in case of failure, e.g, if there is no such option.

virtual mi::Uint32 mi::​nservices::​IRender_loop::get_render_loop_counter() const [pure virtual]

Returns the current render loop counter value. This represents the absolute number of times that the render loop has looped. This can be used with the register_render_counter_callback to request the render at a given counter.

Returns

The render loop counter.

virtual const char* mi::​nservices::​IRender_loop::get_user_scope_name() const [pure virtual]

returns the name of the user scope to use or NULL if there is no user scope

Returns

the scope name or NULL

virtual mi::Sint32 mi::​nservices::​IRender_loop::initialize( ICommand_context_neuray* context, const char* scene_name, mi::Uint32 timeout) [pure virtual]

Initializes the render loop with the scene to render. This must be called before the loop is started. Other parameters should be set using the set_parameter method before calling this method. NB: the render loop may not retain the scene passed into it.

Parameters

context

the command context which created this loop.

scene_name

the name of the scene to render.

timeout

the render loops timeout value in seconds.

Returns

• 0 - success
• -1 - failure
• -2 - invalid parameters
• -3 - unable to find scene called scene_name
• -4 - unable to create render context
• -5 - no underlying render handler
• -6 - scene not ready to render (root group, camera or options missing)

virtual mi::Sint32 mi::​nservices::​IRender_loop::install_pause_progress_callback( mi::neuraylib::IProgress_callback* callback) [pure virtual]

Installs a progress callback for reporting whenever the render loop is paused. The id field of the progress event will follow the format '[render_loop_name]pause'.

Parameters

callback

The callback handler.

Returns

• 0: Success.
• -1: callback is null.
• -2: callback is already registered.

virtual mi::Sint32 mi::​nservices::​IRender_loop::install_render_callback( IRender_loop_rendered_callback* callback) [pure virtual]

Installs a render callback with this render loop. Every time a render call returns the callback will be called with the render results.

Parameters

callback

The callback handler.

Returns

• 0: Success.
• -1: callback is null.
• -2: callback is already registered.

virtual mi::Sint32 mi::​nservices::​IRender_loop::install_render_progress_callback( mi::neuraylib::IProgress_callback* callback) [pure virtual]

Installs a progress callback for reporting rendering progress events. The id field of the progress event will follow the format '[render_loop_name]render'.

Parameters

callback

The callback handler.

Returns

• 0: Success.
• -1: callback is null.
• -2: callback is already registered.

virtual void mi::​nservices::​IRender_loop::keep_alive() [pure virtual]

Restarts the expiry timer.

virtual mi::Sint32 mi::​nservices::​IRender_loop::pick( mi::Float32_2 position, mi::Float32_2 size, mi::Uint32 max_levels, IPick_response_handler* callback, const mi::IMap* params) [pure virtual]

Picks objects behind a given rectangle in the scene. The pick is executed on the render loop between the current and the next render call.

Parameters

position

the 2D center of the picked region in screenspace.

size

the rectangular size of the picked region in screenspace.

max_levels

The maximum number of rays cast per ray

callback

optional response handler callback class that will receive the pick results.

params

optional Handler specific pick parameters.

Returns

• 0: Success
• -1: Error

virtual mi::Sint32 mi::​nservices::​IRender_loop::register_render_counter_callback( IRender_loop_render_counter_callback* callback, mi::Uint32 counter_value) [pure virtual]

Registers a callback to be triggered at the given render counter. If a render counter of 0 (zero) is given then the render loop will assume the next render. If the callback is needs a render, then the values on the callback will be used to create a buffer before calling the callback.

Parameters

callback

The callback handler.

counter_value

The goal counter value for when the callback will be triggered.

Returns

• 0: Success.
• -1: callback is null or empty.
• -2: counter_value is lower than or equal to the current render loop counter (would never trigger).

virtual mi::Sint32 mi::​nservices::​IRender_loop::remove_pause_progress_callback( mi::neuraylib::IProgress_callback* callback) [pure virtual]

Removes a pause state progress callback registered with this render loop.

Parameters

callback

The callback handler.

Returns

• 0: Success.
• -1: callback is null.
• -2: callback was not previously registered.

virtual mi::Sint32 mi::​nservices::​IRender_loop::remove_render_callback( IRender_loop_rendered_callback* callback) [pure virtual]

Removes a render callback with this render loop.

Parameters

callback

The callback handler.

Returns

• 0: Success.
• -1: callback is null.
• -2: callback was not previously registered.

virtual mi::Sint32 mi::​nservices::​IRender_loop::remove_render_progress_callback( mi::neuraylib::IProgress_callback* callback) [pure virtual]

Removes a render progress callback registered with this render loop.

Parameters

callback

The callback handler.

Returns

• 0: Success.
• -1: callback is null.
• -2: callback was not previously registered.

virtual void mi::​nservices::​IRender_loop::set_dirty() [pure virtual]

Informs the loop that the scene is dirty. This enables rendering to begin again if it has converged.

virtual mi::Sint32 mi::​nservices::​IRender_loop::set_execution_scope_name( const char* scope_name) [pure virtual]

Sets the name of the scope which should initially be used for command execution instead of the render loop scope. If NULL is passed in then the global scope is used. If an empty string is passed then the render loop scope is used.

Parameters

scope_name

the name of the scope

Returns

• NRS_ERROR_NONE : success.
• NRS_ERROR_INVALID_PARAMETERS : scope_name is not an existing scope.
• NRS_ERROR_FAILED : general failure, usually means initialize has not yet been called.

virtual mi::Sint32 mi::​nservices::​IRender_loop::set_parameter( const char* key, const mi::IData* value, ICommand_context_neuray* context) [pure virtual]

Sets a render loop parameter on the render handler. This call is passed through to IRender_loop_handler::set_parameter().

Parameters

key

the parameter key

value

the parameter value

context

the command context from which this parameter is being set, may be NULL.

Returns

• 0 - success
• -1 - failure
• -2 - invalid parameter, NULL or empty key string
• -3 - unsupported key
• -4 - value could not be converted to required type

virtual void mi::​nservices::​IRender_loop::set_paused( bool paused) [pure virtual]

Sets the paused flag on the render loop. Pausing the loop prevents further rendering, it will not pause the current frame being rendered however.

Parameters

paused

The flag to either pause or unpause the loop.

virtual mi::Sint32 mi::​nservices::​IRender_loop::set_render_context_option( const char* key, const mi::IData* value, ICommand_context_neuray* context) [pure virtual]

Sets the value of a render-context option. There are three different types of options:

• scene-specific options (see mi::neuraylib::IOptions),

• render context-specific options, and

• general rendering options (independent of the scene or the render context, see mi::neuraylib::IRendering_configuration::set_renderer_option()). For all three types there might be options that are common to all render modes as well as options specific for a certain render mode.

This method deals with the second of the three types. Currently, there are no options common for all render modes. See the documentation of the render mode in question for render mode-specific options.

These options are not set until the beginning of the next render iteration.

See also:

get_option()

Parameters

key

value

The value of the option to be set.

context

The command context from which this option is being set, may be NULL.

Returns

• 0: Success.
• -1: name is null or empty.
• -2: value is null.

virtual mi::Sint32 mi::​nservices::​IRender_loop::set_sequence_id( mi::Sint32 sequence_id) [pure virtual]

Sets the sequence id sent over web sockets.

Parameters

sequence_id

if positive then this sequence id is returned with the image statistics over web sockets. If strictly increasing values are provided then the user can easily determine if a given image contains changes from a given set of commands.

Returns

• 0: Success
• -1: Error
• -2: sequence_id is less than current sequence id.

virtual mi::Sint32 mi::​nservices::​IRender_loop::set_user_scope_name( const char* scope_name) [pure virtual]

sets the name of the user scope to use when executing commands. If NULL or an empty string is passed in then no user scope is used. If a non-existent scope name is supplied then the user scope is not changed.

Parameters

scope_name

the name of the scope

Returns

• NRS_ERROR_NONE : success.
• NRS_ERROR_INVALID_PARAMETERS : scope_name is not an existing scope.
• NRS_ERROR_FAILED : general failure.

virtual mi::Sint32 mi::​nservices::​IRender_loop::start_loop() [pure virtual]

Starts the render loop in another thread.

Returns

• 0 - started successfully
• -1 - failure
• -2 - not initialized
• -3 - thread already running
• -4 - thread already started once