neuray API Programmer's Manual

mi::neuraylib::IRender_context Class Reference

[Rendering and Picking]

Description

This interface is used for doing actual rendering and picking. It can be obtained from mi::neuraylib::IScene::create_render_context().

Public Enumerations

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 Member Functions

virtual void cancel_render( Cancel_mode mode = CANCEL_AND_CONTINUE) =0
Allows to cancel rendering currently done using this render context. More...
virtual const IDataget_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 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...
virtual Size get_options_length() const =0
Returns the number of render context options. More...
virtual IRender_countersget_render_counters() =0
Returns the render counters for this render context. More...
virtual IPick_arraypick( 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_arraypick( 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 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 Sint32 set_option( const char* name, const IData* value) =0
Sets the value of a render context option. More...

Enums

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 = 0
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 = 1
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.
CANCEL_FORCE_32_BIT = 0xffffffffU

Member Functions

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.

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 NULL in case of failure, e.g., if there is no such option.

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.

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::​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 NULL if index is out of bounds.

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 NULL if index is out of bounds.

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

Returns the number of render context options.

See also:

get_option_name()

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 NULL if this render mode does not support render counters.

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, NULL on error.

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, NULL on error.

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 [:ipmlink rendering 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 NULL).

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 (NULL pointer).
  • -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.

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 [:ipmlink rendering 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 NULL).

Returns

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

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:

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.