This interface is used for doing actual rendering and picking. More...

#include <irender_context.h>

Inheritance diagram for mi::neuraylib::IRender_context:

Public Types
enum	Cancel_mode { CANCEL_AND_CONTINUE = 0 , CANCEL_AND_RESTART = 1 , CANCEL_FORCE_32_BIT = 0xffffffffU }
	Different modes of canceling a rendering operation. More...

Public Types inherited from mi::base::Interface_declare< 0xad5ccd43, ... >
using	Self = Interface_declare< id1, ... >
	Own type. More...

using	IID = Uuid_t< id1, ... >
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
using	IID = Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>
	Declares the interface ID (IID) of this interface. More...

Public Member Functions
virtual Sint32	render (ITransaction transaction, IRender_target_base render_target_base, IProgress_callback *progress_callback)=0
	Renders the associated scene with the associated render mode. More...

virtual Sint32	render_async (ITransaction transaction, IRender_target_base render_target_base, IReady_callback ready_callback, IProgress_callback progress_callback)=0
	Renders the associated scene with the associated render mode. More...

virtual void	cancel_render (Cancel_mode mode=CANCEL_AND_CONTINUE)=0
	Allows to cancel rendering currently done using this render context. More...

virtual IPick_array *	pick (ITransaction *transaction, const Float32_2_struct &point, Uint32 max_pick_levels=1)=0
	Picks what is behind a point in the scene. More...

virtual IPick_array *	pick (ITransaction *transaction, const Float32_2_struct &center, const Float32_2_struct &size, Uint32 max_pick_levels=1)=0
	Picks what is behind a rectangle in the scene. More...

virtual IRender_counters *	get_render_counters ()=0
	Returns the render counters for this render context. More...

virtual Sint32	set_option (const char name, const IData value)=0
	Sets the value of a render context option. More...

virtual const IData *	get_option (const char *name) const =0
	Returns the value of a render context option. More...

template<class T>
const T *	get_option (const char *name) const
	Returns the value of a render context option. More...

virtual Size	get_options_length () const =0
	Returns the number of render context options. More...

virtual const char *	get_option_name (Size index) const =0
	Returns the name of a render context option. More...

virtual const char *	get_option_type (Size index) const =0
	Returns the type of a render context option. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Additional Inherited Members
Static Public Member Functions inherited from mi::base::Interface_declare< 0xad5ccd43, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. More...

Detailed Description

This interface is used for doing actual rendering and picking.

It can be obtained from mi::neuraylib::IScene::create_render_context().

Member Enumeration Documentation

^◆ Cancel_mode

enum mi::neuraylib::IRender_context::Cancel_mode

Different modes of canceling a rendering operation.

The canceling mode is a hint to the render mode what is probably going to happen next. It allows the render mode to select the best way of canceling the rendering operation. The canceling mode does not affect the correctness of the converged result of the next rendering operation (but it might affect the time needed to achieve it and/or the quality of intermediate results).

Note: Support for different canceling modes is optional. Render modes might ignore this hint completely.

See also: cancel_render()

Enumerator

CANCEL_AND_CONTINUE

Cancel the rendering in such a way that it is possible to continue.

This mode should be used if scene changes do not require restarting the rendering, e.g., tonemapper settings, if it is likely that rendering will continue, or simply as default mode.

CANCEL_AND_RESTART

Cancel the rendering as fast as possible, even at the cost of not being able to continue rendering from the current state.

This mode should only be used if it is clear that a restart is required anyway, e.g., due to scene changes like camera movements.

Member Function Documentation

^◆ cancel_render()

virtual void mi::neuraylib::IRender_context::cancel_render ( Cancel_mode mode = CANCEL_AND_CONTINUE )

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.

^◆ get_option() [1/2]

template<class T>

const T * mi::neuraylib::IRender_context::get_option ( const char * name ) const

inline

Returns the value of a render context option.

See also: set_option(), get_option_name()

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.

Template Parameters

T	The interface type of the render-context option.

Parameters

name	The name of the option.

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

^◆ get_option() [2/2]

virtual const IData * mi::neuraylib::IRender_context::get_option ( const char * name ) const

pure virtual

Returns the value of a render context option.

See also: set_option(), get_option_name()

Parameters

name	The name of the option.

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

^◆ get_option_name()

virtual const char * mi::neuraylib::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 nullptr if index is out of bounds.

^◆ get_option_type()

virtual const char * mi::neuraylib::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 nullptr if index is out of bounds.

^◆ get_options_length()

virtual Size mi::neuraylib::IRender_context::get_options_length ( ) const

pure virtual

Returns the number of render context options.

See also: get_option_name()

^◆ get_render_counters()

virtual IRender_counters * mi::neuraylib::IRender_context::get_render_counters ( )

pure virtual

Returns the render counters for this render context.

Returns: The render counters for this render context, or nullptr if this render mode does not support render counters.

^◆ pick() [1/2]

virtual IPick_array * mi::neuraylib::IRender_context::pick	(	ITransaction *	transaction,
		const Float32_2_struct &	center,
		const Float32_2_struct &	size,
		Uint32	max_pick_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 rays. If multiple rays hit the same object, only one mi::neuraylib::IPick_result is added to the result array. The implementation defines which of the rays determines the corresponding world position.

Rays are cast at the crossings of an integer grid around center through those pixels which are addressed by a rectangle of the given size, centered around center, and rounded to the nearest coordinate.

A call to this function with a size of (1,1) is equivalent to a call to the overload.

The max_pick_levels parameter controls the number of rays that may be cast, per ray, during the picking operation. A level of 1 will only trace primary rays. Any other value will continue tracing rays through the scene until nothing was hit or the maximum depth is exhausted, with a value of 0 indicating unconstrained depth.

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_pick_levels	The maximum ray depth for picking.

Returns: The array of picked objects, nullptr on error.

^◆ pick() [2/2]

virtual IPick_array * mi::neuraylib::IRender_context::pick	(	ITransaction *	transaction,
		const Float32_2_struct &	point,
		Uint32	max_pick_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.

See the overload for details on the max_pick_levels parameter.

Parameters

transaction	The transaction used to access the database.
point	The picked 2D point in screenspace.
max_pick_levels	The maximum ray depth for picking.

Returns: The array of picked objects, nullptr on error.

^◆ render()

virtual Sint32 mi::neuraylib::IRender_context::render	(	ITransaction *	transaction,
		IRender_target_base *	render_target_base,
		IProgress_callback *	progress_callback
	)

pure virtual

Renders the associated scene with the associated render mode.

The result is written to the given render target.

This method is synchronous, it returns after a certain amount of work has been done. See render_async() for an asynchronous variant of this method.

Note: Some render modes might continue rendering in the background, even after the method returned. Background rendering stops at the latest if the transaction is committed or aborted. Additionally, render modes might have render mode-specific options to disable such background rendering. See section "Render mode selection" of the Iray Programmer's Manual for details.

Parameters

transaction	The transaction used to access the database.
render_target_base	The rendered image is written into this render target before the method returns. It is guaranteed that the render target will only be modified during the runtime of this call, even if background rendering happens.
progress_callback	This callback is called when progress in rendering occurs (might be `nullptr`).

Returns

0: Success. The termination criteria have not yet been reached. Subsequent calls will return an image with improved quality.
1: Success. The termination criteria have been reached. Subsequent calls will not improve the image quality any longer.
-1: cancel_render() was called.
-2: Another thread is currently rendering using this render context, or the transaction has already been committed or aborted.
-3: Invalid parameters (nullptr).
-4: Internal rendering error.
-5: The render mode ran out of memory, e.g., GPU memory.
-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: The render target type is not supported by the selected renderer (for example rendering to OpenGL).
-9: The transaction belongs to a different scope than the transaction that was used to create the render context.
-10: No sufficiently capable GPUs or selected device combination not supported.
-11: Invalid setup for rendering to OpenGL, e.g., the user context is not current, or the target texture ID is not valid.
-12: Connection error, e.g., connection to Bridge server failed. Check server address and security token.
-13: Streaming disabled, e.g., the Bridge server is not currently allowing remote rendering.
-14: Bridge server unresponsive, e.g., time out while waiting for server response.
-15: Bridge video error, e.g., problems encoding/ decoding video frames, or problems with server side rendering.

^◆ render_async()

virtual Sint32 mi::neuraylib::IRender_context::render_async	(	ITransaction *	transaction,
		IRender_target_base *	render_target_base,
		IReady_callback *	ready_callback,
		IProgress_callback *	progress_callback
	)

pure virtual

Renders the associated scene with the associated render mode.

The result is written to the given render target.

The method returns immediately while the rendering is in progress. See render() for a synchronous variant of this method.

Note: Some renderers might continue rendering in the background, even after the ready callback was called. Background rendering stops at the latest if the transaction is committed or aborted. Additionally, renderers might have renderer-specific options to disable such background rendering. See the section "Render mode selection" in the Iray Programmer's Manual for details.; You must not use the passed transaction before you have received the ready callback. This method essentially calls render() in a separate thread and invokes the ready callback when render() returns. If the transaction was also used by the caller, then this would result in sharing a transaction between threads without explicit synchronization and the render mode has no consistent view on the database.

Parameters

transaction	The transaction used to access the database. The transaction needs to be kept open until the ready callback was called.
render_target_base	The rendered image is written into this render target. It is guaranteed that the render target will only be modified between this call and the invocation of the ready callback (see below), even if background rendering happens.
ready_callback	This callback is called when rendering is finished. The `result` parameter of the callback matches the return values of the render() method.
progress_callback	This callback is called when progress in rendering occurs (might be `nullptr`).

Returns

0: Success.
-2: Another thread is currently rendering using this render context.
-3: Invalid parameters (nullptr).

^◆ set_option()

virtual Sint32 mi::neuraylib::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(), get_option_name(), get_option_type()

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.

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Cancel_mode

Member Function Documentation

◆ cancel_render()

◆ get_option() [1/2]

◆ get_option() [2/2]

◆ get_option_name()

◆ get_option_type()

◆ get_options_length()

◆ get_render_counters()

◆ pick() [1/2]

◆ pick() [2/2]

◆ render()

◆ render_async()

◆ set_option()

^◆ Cancel_mode

^◆ cancel_render()

^◆ get_option() [1/2]

^◆ get_option() [2/2]

^◆ get_option_name()

^◆ get_option_type()

^◆ get_options_length()

^◆ get_render_counters()

^◆ pick() [1/2]

^◆ pick() [2/2]

^◆ render()

^◆ render_async()

^◆ set_option()