Member Functions

virtual void mi::​nservices::​IRender_loop_handler::cancel_render( mi::Sint32 cancel_level, mi::Sint32 purpose = 0) [pure virtual]

Cancels any ongoing render.

Parameters

cancel_level

The intention of the cancel level is to specify how fast the rendering should be finished. If 1 then the cancel will occur ASAP possibly at the expense of having to restart rendering even if not necessary.

purpose

why the render is getting cancelled.

• 0 - scene has changed
• 1 - render loop is about to shut down

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

Returns the name of this render handler.

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

Gets a render loop parameter.

Parameters

key

the parameter key

Returns

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

virtual mi::Float64 mi::​nservices::​IRender_loop_handler::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 handler. 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 Estimated progression between 0 and 1, indicating progress until error threshold is reached.
• error Current estimate of per-pixel error.
• iteration 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_handler::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_handler::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_handler::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::Sint32 mi::​nservices::​IRender_loop_handler::initialize( ICommand_context_neuray* context, const char* scene_name) [pure virtual]

Initializes the render loop handler with the scene to render. This method is called by the owning IRender_loop when it is initialized. Note that the handler must not retain the scene obtained from the name passed into it, nor anything obtained from context. Any initial parameters should be set using set_parameter before initialization.

Parameters

context

the command context which created this loop.

scene_name

the name of the scene to render. The render loop wrapping the handler will have already checked this for validity with the context's command transaction.

Returns

• 0 - success
• -1 - failure
• -2 - invalid parameters
• -3 - unable to find scene called scene_name
• -4 - unable to create render contexts

virtual mi::neuraylib::IPick_array* mi::​nservices::​IRender_loop_handler::pick( mi::neuraylib::ITransaction* transaction, mi::Float32_2 position, mi::Float32_2 size, mi::Uint32 max_levels = 1, const mi::IMap* params = nullptr) [pure virtual]

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

Parameters

transaction

the transaction to execute the pick on.

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

params

Handler specific pick parameters.

Returns

An array of pick results or NULL in the case of error.

virtual const IRender_loop_handler_render_result* mi::​nservices::​IRender_loop_handler::render( mi::neuraylib::ITransaction* transaction, mi::neuraylib::IProgress_callback* progress = nullptr) [pure virtual]

Performs the actual render.

Parameters

transaction

the transaction in which to render.

progress

callback for reporting rendering progress.

Returns

the result of the render or NULL on error.

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

Sets a render loop parameter. The provided context can be used to obtain any further data required to set the parameter, for example the rendered scene representation. Note that any interfaces obtained from the context must be released before returning.

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 mi::Sint32 mi::​nservices::​IRender_loop_handler::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. The provided context can be used to obtain any further data required to set the parameter, for example the rendered scene representation. Note that any interfaces obtained from the context must be released before returning

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 void mi::​nservices::​IRender_loop_handler::shutdown() [pure virtual]

Called when the render loop is shutdown to perform any clean up. This will be called after the last call to mi::nservices::IRender_loop_handler::render has been made.