mi::nservices::IRender_loop_handler Class Reference
[Render Loops]
Description
Defines a render loop handler. These handlers are intended to be implemented by the end user and provide the core rendering component of a loop. The render method is called on every loop to perform the actual rendering job and return the resulting canvas to the loop. Instances of handlers are created by mi::nservices::IRender_loop_handler_factory which need to be registered with the mi::nservices::IRender_loop_manager api component. This registration would typically take place in a web services plugin (as opposed to a neuray library plugin) to ensure the handler is registered after the loop manager.
Public Member Functions
- virtual void cancel_render( mi::Sint32 cancel_level, mi::Sint32 purpose = 0) =0
- Cancels any ongoing render. More...
- virtual const char* get_name() const =0
- Returns the name of this render handler.
- virtual const mi::IData* get_parameter( const char* key) =0
- Gets a render loop parameter. More...
- virtual mi::Float64 get_progress( const char* area) const =0
- Returns the progress of the render being performed by the render context used by this render loop handler. More...
- virtual mi::IMap* get_progress() const =0
- Returns a map containing all render progress statistics for the current render.
- virtual const mi::IData* get_render_context_option( const char* key) const =0
- Returns the value of a render-context option. More...
- template< class T>const T* get_render_context_option( const char* name) const
- Returns the value of a render-context option. More...
- virtual mi::Sint32 initialize( ICommand_context_neuray* context, const char* scene_name) =0
- Initializes the render loop handler with the scene to render. More...
- virtual mi::neuraylib::IPick_array* pick( mi::neuraylib::ITransaction* transaction, mi::Float32_2 position, mi::Float32_2 size, mi::Uint32 max_levels = 1, const mi::IMap* params = nullptr) =0
- Picks objects behind a given rectangle in the scene. More...
- virtual const IRender_loop_handler_render_result* render( mi::neuraylib::ITransaction* transaction) =0
- Performs the actual render. More...
- virtual mi::Sint32 set_parameter( const char* key, const mi::IData* value, mi::nservices::ICommand_context_neuray* context) =0
- Sets a render loop parameter. More...
- virtual mi::Sint32 set_render_context_option( const char* key, const mi::IData* value, ICommand_context_neuray* context) =0
- Sets the value of a render-context option. More...
- virtual void shutdown() =0
- Called when the render loop is shutdown to perform any clean up. More...
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:
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) [pure virtual]
-
Performs the actual render.
Parameters
- transaction
- the transaction in which to render.
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.