The scene is the top-level element describing a subset of DB elements to be rendered. More...

#include <iscene.h>

Inheritance diagram for mi::neuraylib::IScene:

Public Types
enum	Dirty_flags { DIRTY_NONE = 0 , DIRTY_INSTANCE_TRANSFORMS = 1 << 0 , DIRTY_FORCE_32_BIT = 0xffffffffU }
	Different flags for specifying what is dirty in the scene and needs recomputing. More...

Public Types inherited from mi::base::Interface_declare< 0x44e2a997, ... >
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	set_rootgroup (const char *root)=0
	Sets the root group of this scene. More...

virtual const IString *	get_rootgroup () const =0
	Returns the name of the root group of this scene. More...

virtual Sint32	set_options (const char *options)=0
	Sets the options of this scene. More...

virtual const IString *	get_options () const =0
	Returns the name of the options of this scene. More...

virtual Sint32	set_camera_instance (const char *camera)=0
	Sets the camera instance of this scene. More...

virtual const IString *	get_camera_instance () const =0
	Returns the name of the camera instance of this scene. More...

virtual Bbox3_struct	get_bbox (Sint32 *errors=nullptr)=0
	Returns the bounding box of this scene. More...

virtual IRender_context *	create_render_context (ITransaction transaction, const char render_mode, Sint32 *errors=nullptr)=0
	Creates a render context suitable for rendering the scene with a given render mode. More...

virtual Sint32	set_dirty (Uint32 flags=0)=0
	Marks as dirty some parts of the scene which will be recomputed. 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< 0x44e2a997, ... >
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

The scene is the top-level element describing a subset of DB elements to be rendered.

A scene is described by three elements:

a root group (which is the root node of the scene graph) of type mi::neuraylib::IGroup,
the global options of type mi::neuraylib::IOptions, and
the camera instance of type mi::neuraylib::IInstance (needs to be reachable from the root group).

Preprocessing of scene data is deferred until it is needed. In particular, get_bbox() and create_render_context() trigger preprocessing of the scene data.

Note that editing an instance of this class stored in the DB will localize it to the scope of the current transaction. That is, calling mi::neuraylib::ITransaction::edit() on instances of mi::neuraylib::IScene will automatically invoke mi::neuraylib::ITransaction::copy() with identical names for source and target and mi::neuraylib::ITransaction::LOCAL_SCOPE as third argument.

Member Enumeration Documentation

^◆ Dirty_flags

enum mi::neuraylib::IScene::Dirty_flags

Different flags for specifying what is dirty in the scene and needs recomputing.

These flags identify what is dirty in the scene and must be recomputed.

Note: Support for dirty flags is optional. Render modes might ignore them completely.

See also: set_dirty()

Enumerator

DIRTY_NONE

No flags.

DIRTY_INSTANCE_TRANSFORMS

Set the instance transforms as dirty.

This forces an update of the camera shift offset due to instancing.

Member Function Documentation

^◆ create_render_context()

virtual IRender_context * mi::neuraylib::IScene::create_render_context	(	ITransaction *	transaction,
		const char *	render_mode,
		Sint32 *	errors = `nullptr`
	)

pure virtual

Creates a render context suitable for rendering the scene with a given render mode.

Parameters

	transaction	The transaction to be used.
	render_mode	The render mode to be used, for example, `"iray"`. Possible values are documented in Section "Render mode selection" of the Iray Programmer's Manual.
[out]	errors	An optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning: 0: Success. -1: Invalid parameters (`nullptr`). -2: The scene object was not stored and retrieved from the database (this is required for this method to succeed). -3: The parameter `render_mode` is not a valid render mode (see notes below). -4: The root group, the options, or the camera instance are invalid. -5: The render mode failed to create the render context for render mode-specific reasons.

Returns: The render context for the given render mode, or nullptr in case of failure.

See also: Certain render modes are only available if their corresponding plugin is loaded, see mi::neuraylib::IPlugin_configuration::load_plugin_library().; Not all render modes are available in all configurations. You can use mi::neuraylib::IRendering_configuration::get_renderers_length() and mi::neuraylib::IRendering_configuration::get_renderer() to query the render modes that are actually available.

^◆ get_bbox()

virtual Bbox3_struct mi::neuraylib::IScene::get_bbox ( Sint32 * errors = nullptr )

pure virtual

Returns the bounding box of this scene.

This method is not a const method because it might trigger loading the actual scene data.

Parameters

errors

An optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning:

0: Success.
-1: The root group, the options, or the camera instance are invalid.
-2: The scene object was not stored and retrieved from the database (this is required for this method to succeed).

Returns: The bounding box of the scene (or a default-constructed bounding box in case of errors).

^◆ get_camera_instance()

virtual const IString * mi::neuraylib::IScene::get_camera_instance ( ) const

pure virtual

Returns the name of the camera instance of this scene.

Returns: The name, or nullptr if there is no camera instance.

^◆ get_options()

virtual const IString * mi::neuraylib::IScene::get_options ( ) const

pure virtual

Returns the name of the options of this scene.

Returns: The name, or nullptr if there is no options object.

^◆ get_rootgroup()

virtual const IString * mi::neuraylib::IScene::get_rootgroup ( ) const

pure virtual

Returns the name of the root group of this scene.

Returns: The name, or nullptr if there is no root group.

^◆ set_camera_instance()

virtual Sint32 mi::neuraylib::IScene::set_camera_instance ( const char * camera )

pure virtual

Sets the camera instance of this scene.

Note: It is undefined behavior whether setting a new camera instance affects already created render contexts. The behavior might vary from render mode to render mode. Consider editing the current camera instance instead. Alternatively, you can destroy all render contexts of the scene, and re-create them.; The camera instance needs to reachable from the root group.

Parameters

camera The name of the camera instance.

Returns

0: Success.
-1: Invalid parameters (nullptr).
-2: There is no element with that name.
-3: The element can not be set as camera instance because it is in a more private scope than the scene.
-4: The element is not an instance.

^◆ set_dirty()

virtual Sint32 mi::neuraylib::IScene::set_dirty ( Uint32 flags = 0 )

pure virtual

Marks as dirty some parts of the scene which will be recomputed.

To force an update of the camera shift offset due to instancing it is possible to call this method with the flag that sets the instance transforms as dirty.

Parameters

flags See Dirty_flags for possible values (they can be OR'ed).

Returns

0: Success.
-1: Scene data has not been preprocessed yet.

^◆ set_options()

virtual Sint32 mi::neuraylib::IScene::set_options ( const char * options )

pure virtual

Sets the options of this scene.

Note: It is undefined behavior whether setting new options affects already created render contexts. The behavior might vary from render mode to render mode. Consider editing the current options instead. Alternatively, you can destroy all render contexts of the scene, and re-create them.

Parameters

options The name of the options.

Returns

0: Success.
-1: Invalid parameters (nullptr).
-2: There is no element with that name.
-3: The element can not be set as options because it is in a more private scope than the scene.
-4: The element is not an options object.

^◆ set_rootgroup()

virtual Sint32 mi::neuraylib::IScene::set_rootgroup ( const char * root )

pure virtual

Sets the root group of this scene.

Note: It is undefined behavior whether setting a new root group affects already created render contexts. The behavior might vary from render mode to render mode. Consider editing the current root group instead. Alternatively, you can destroy all render contexts of the scene, and re-create them.

Parameters

root	The root group.

Returns

0: Success.
-1: Invalid parameters (nullptr).
-2: There is no element with that name.
-3: The element can not be set as root group because it is in a more private scope than the scene.
-4: The element is not a group.

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Dirty_flags

Member Function Documentation

◆ create_render_context()

◆ get_bbox()

◆ get_camera_instance()

◆ get_options()

◆ get_rootgroup()

◆ set_camera_instance()

◆ set_dirty()

◆ set_options()

◆ set_rootgroup()

^◆ Dirty_flags

^◆ create_render_context()

^◆ get_bbox()

^◆ get_camera_instance()

^◆ get_options()

^◆ get_rootgroup()

^◆ set_camera_instance()

^◆ set_dirty()

^◆ set_options()

^◆ set_rootgroup()