Member Functions

virtual void mi::​neuraylib::​IRender_context::cancel_render() [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) [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.

Parameters

transaction

The transaction used to access the database.

point

The picked 2D point in screenspace.

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) [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.

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.

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 that 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 render_mode_selection 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 that 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 render_mode_selection Render mode selection] in the Iray Programmer's Manual for details.

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:

• 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.