Member Functions

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

Allows to cancel rendering currently done using this render context. It is not guaranteed how much time it takes until the rendering is actually finished. Note, that this function can be called by a different thread than the one currently doing the rendering.

Parameters

cancel_level

If 1 then the cancel will occur ASAP possibly at the expense of having to restart rendering even if not necessary.

virtual Sint32 mi::​nservices::​IRender_context::delete_canvas( const char* name) [pure virtual]

Deletes a previously stored canvas.

Parameters

name

the name of the canvas to delete

Returns

• NRS_ERROR_NONE : success.
• NRS_ERROR_INVALID_PARAMETERS : a parameter is NULL.
• NRS_ERROR_INVALID_OPERATION : no canvas was stored under this name.
• NRS_ERROR_FAILED : internal error.

virtual mi::neuraylib::IRender_target* mi::​nservices::​IRender_context::get_last_render() const [pure virtual]

Returns the render target containing the results of the last render call on this render context. See render. NB: The renders from render_async calls are not returned by this method.

Returns

the render target or NULL if no successful render has occurred yet within this context or the last render target used was not derived from mi::neuraylib::IRender_target

virtual mi::neuraylib::IRender_target_base* mi::​nservices::​IRender_context::get_last_render_base() const [pure virtual]

Returns the base render target used by the last render call on this render context. See render. NB: The renders from render_async calls are not returned by this method.

Returns

the base render target or NULL if no successful render has occurred yet within this context. mi::neuraylib::IRender_target_base

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

Returns the result of the last render call on this render context. See render. NB: The results of render_async calls are not returned by this method.

Returns

a return value as defined in render or -9 if no render has occurred yet within this context

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

Returns the name of this render context or NULL if it is not a named context.

Returns

the name

virtual const IData* mi::​nservices::​IRender_context::get_option( const char* name) const [pure virtual]

Returns the value of a render-context option.

See also:

set_option()

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.

template< class T>

const T* mi::​nservices::​IRender_context::get_option( const char* name) const [inline]

Returns the value of a render-context option.

See also:

set_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 const char* mi::​nservices::​IRender_context::get_option_name( Size index) const [pure virtual]

Returns the name of a render context option.

See also:

get_options_length(), get_option_type(), get_option(), set_option()

Parameters

index

The index of the render context option in question.

Returns

The name of the specified render context option, or NULL if index is out of bounds.

virtual const char* mi::​nservices::​IRender_context::get_option_type( Size index) const [pure virtual]

Returns the type of a render context option.

See also:

get_options_length(), get_option_name(), get_option(), set_option()

Parameters

index

The index of the render context option in question.

Returns

The type of the specified render context option, or NULL if index is out of bounds.

virtual Size mi::​nservices::​IRender_context::get_options_length() const [pure virtual]

Returns the number of render context options.

See also:

get_option_name()

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

Returns the progress of the render being performed by this render context. 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_context::get_progress() const [pure virtual]

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

virtual mi::neuraylib::IRender_counters* mi::​nservices::​IRender_context::get_render_counters() [pure virtual]

Returns the render counters for this render context.

Returns

The render counters for this render context, or NULL if this renderer does not support render counters.

virtual const char* mi::​nservices::​IRender_context::get_renderer() const [pure virtual]

Returns the name renderer used by this render context.

Returns

the renderer name

virtual const char* mi::​nservices::​IRender_context::get_scene_name() const [pure virtual]

Returns the name of the scene used by this render context.

Returns

the scene name

virtual const char* mi::​nservices::​IRender_context::get_scope_name() const [pure virtual]

Returns the name of the scope this render context uses. Returns NULL if using the global scope.

Returns

the scope name

virtual Uint32 mi::​nservices::​IRender_context::get_timeout() const [pure virtual]

Returns the timeout value of this render context. If this is not a named render context then returns 0.

Returns

the timeout

virtual mi::neuraylib::IPick_array* mi::​nservices::​IRender_context::pick( mi::neuraylib::ITransaction* transaction, const Float32_2_struct& point, const Uint32 max_levels = 1) [pure virtual]

Picks what is behind a point in the scene. Casts a single ray into the scene at raster pixel coordinate point, with (0,0) in the bottom left corner. Returns an array that contains information about any objects hit by the ray. Only objects that have the pickable attribute set are considered.

Parameters

transaction

The transaction used to access the database.

point

The picked 2D point in screenspace.

max_levels

The maximum number of rays cast per ray

Returns

The array of picked objects, NULL on error.

virtual mi::neuraylib::IPick_array* mi::​nservices::​IRender_context::pick( mi::neuraylib::ITransaction* transaction, const Float32_2_struct& center, const Float32_2_struct& size, const Uint32 max_levels = 1) [pure virtual]

Picks what is behind a rectangle in the scene. Casts a ray into the scene for each raster pixel coordinate in the given rectangle. Returns an array that contains information about any objects hit by the ray. Only objects that have the pickable attribute set are considered.

Parameters

transaction

The transaction used to access the database.

center

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

Returns

The array of picked objects, NULL on error.

virtual Sint32 mi::​nservices::​IRender_context::render( mi::neuraylib::ITransaction* transaction, mi::neuraylib::IRender_target_base* render_target, mi::neuraylib::IProgress_callback* progress_callback) [pure virtual]

Renders the scene associated with this render context to the given render target according to the passed in parameters using the renderer associated with the context. Note that it is necessary to commit the transaction after calling this method.

Returns when all tiles are finished.

The return value of this render is cached and can later be retrieved using get_last_render_result. Additionally, if rendering succeeds (return value == 0) then render_target is also retained and can later be retrieved with get_last_render. This can be useful when progressive rendering to detect that the image is converged and simply retrieve the previous target rather than doing a whole new render call.

Parameters

transaction

The transaction used to access the database.

render_target

This defines where to render the information to. It also allows to query the meaning of the different canvas layers by name.

progress_callback

This callback is called when progress in rendering occurs.

Returns

• 0: Success.
• -1: cancel_render() was called.
• -2: Another thread is currently rendering using this render context.
• -3: Invalid parameters (NULL pointer).
• -4: Internal rendering error.
• -5: The renderer ran out of memory, e.g., the GPU renderer.
• -6: The canvas is too large to fit into GPU memory.
• -7: The render context is invalid, e.g., because the transaction that was used to create it was aborted.
• -8: There is no neuray library render context associated with this wrapper.
• 1: The same image as in the last iteration was returned because the image is sufficiently refined in all areas according to the chosen quality parameters (progressive mode only).

virtual Sint32 mi::​nservices::​IRender_context::render_async( mi::neuraylib::ITransaction* transaction, mi::neuraylib::IRender_target_base* render_target, mi::neuraylib::IReady_callback* ready_callback, mi::neuraylib::IProgress_callback* progress_callback) [pure virtual]

Renders the scene associated with this render context to the given render target according to the passed in parameters using the renderer associated with the context. In contrast to the render call this call will return immediately while the rendering continues. Note that it is necessary to keep the transaction open during the time the rendering is running. It should be closed after the ready_callback was called.

Parameters

transaction

The transaction used to access the database.

render_target

This defines where to render the information to. It also allows to query the meaning of the different canvas layers by name.

ready_callback

This callback is called when rendering is finished.

progress_callback

This callback is called when progress in rendering occurs.

Returns

• 0: Success.
• -2: Another thread is currently rendering using this render context.
• -3: Invalid parameters (NULL pointer).-4: There is no neuray library render context associated with this wrapper.

virtual neuraylib::ICanvas* mi::​nservices::​IRender_context::retrieve_canvas( const char* name) const [pure virtual]

Retrieves a previously stored canvas.

Parameters

name

the name of the canvas

Returns

the canvas or NULL if no canvas is stored under the given name

virtual Sint32 mi::​nservices::​IRender_context::set_option( const char* name, const IData* value) [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.

See also:

get_option()

Parameters

name

The name of the option to be set.

value

The value of the option to be set.

Returns

• 0: Success.
• -1: name is invalid.
• -2: value is invalid.
• -3: The option can not be set at this point in time, e.g., some options can only be set before render() or render_async() is called for the first time.

virtual Sint32 mi::​nservices::​IRender_context::store_canvas( const char* name, neuraylib::ICanvas* canvas) [pure virtual]

Stores a canvas in this render context. The canvas will be retrievable until this render context is destroyed. Note that the canvas will only be available on the host it is stored on and only retrievable from this render context.

Parameters

name

the name to store as

canvas

the canvas to store

Returns

• NRS_ERROR_NONE : success.
• NRS_ERROR_INVALID_PARAMETERS : a parameter is NULL.
• NRS_ERROR_FAILED : internal error.