neuray Services API Programmer's Manual

mi::nservices::IScene Class Reference

[neuray Services API Abstractions]

Description

The neuray services scene abstraction. This class reflects all members of the mi::neuraylib::IScene object it abstracts as well as providing automated scene expiry, access to an extended render context and an attribute container associated with the scene. Scenes are created within commands using mi::nservices::ICommand_context::create_scene() and later accessed using mi::nservices::ICommand_context::get_scene(). It is not possible to access the scene abstraction directly via the neuray library database. Accessing directly by name will return the attribute container associated with the scene rather than the scene itself. This can be used to associate additional data with the scene. For Example: 

‎ mi::nservices::ICommand_context *context = ....;
 mi::nservices::IScene *scene;
 mi::neuraylib::IAttribute_container *scene_attribute_container;
 mi::neuraylib::ITransaction *transaction = context->get_transaction();

 scene = context->create_scene("my_scene");
 scene_attribute_container = transaction->edit<mi::neuraylib::IAttribute_container>("my_scene");
 ...
 // work on scene and scene_attribute_container
 ...
 scene_attribute_container->release();
 scene->release();
 transaction->release();

To access the scene outside of command execution use mi::nservices::IFactory::get_element().

mi::base::Interface_declare\< ... \>

Public Member Functions

virtual Bbox3_struct get_bbox( Sint32* errors = 0) =0
Returns the bounding box of this scene. More...
virtual const mi::IString* get_camera_instance() const =0
Returns the name of the camera instance used for this scene. More...
virtual const mi::IString* get_options() const =0
Returns the name of the options object for this scene. More...
virtual IRender_context* get_render_context( neuraylib::ITransaction* transaction, const char* renderer, const char* name = NULL, mi::Uint32 timeout = 0, mi::Sint32* errors = 0) =0
Returns a render context suitable for rendering the scene with a given renderer. More...
virtual IRender_context* get_render_context( const char* name) const =0
Retrieves a render context by name. More...
virtual const mi::IString* get_rootgroup() const =0
Returns the name of the root group object of this scene. More...
virtual neuraylib::IScene* get_scene() const =0
Returns the underlying Neuray Library scene representation. More...
virtual Sint32 remove() =0
Deletes the scene from the database regardless of any timers that may still exist. More...
virtual mi::Sint32 remove_render_context( const char* name) =0
Removes a render context by name. More...
virtual Sint32 set_camera_instance( const char* camera) =0
Sets the camera instance used for rendering. More...
virtual Sint32 set_dirty( mi::Uint32 flags = 0) =0
Marks as dirty some parts of the scene which will be recomputed. More...
virtual Sint32 set_options( const char* options) =0
Sets the options used for rendering. More...
virtual Sint32 set_rootgroup( const char* root) =0
Sets the root group used for rendering. More...
virtual mi::Sint32 start_expiry_timer( mi::Uint32 delay) =0
starts the expiry timer for the scene More...
virtual mi::Sint32 stop_expiry_timer() =0
Stops the expiry timer for the scene. More...

Member Functions

virtual Bbox3_struct mi::​nservices::​IScene::get_bbox( Sint32* errors = 0) [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).

virtual const mi::IString* mi::​nservices::​IScene::get_camera_instance() const [pure virtual]

Returns the name of the camera instance used for this scene.

See also:

mi::neuraylib::IScene::get_camera_instance()

Returns

The name, or NULL if there is no camera instance.

virtual const mi::IString* mi::​nservices::​IScene::get_options() const [pure virtual]

Returns the name of the options object for this scene.

See also:

mi::neuraylib::IScene::get_options()

Returns

The name, or NULL if there is no options object.

virtual IRender_context* mi::​nservices::​IScene::get_render_context( neuraylib::ITransaction* transaction, const char* renderer, const char* name = NULL, mi::Uint32 timeout = 0, mi::Sint32* errors = 0) [pure virtual]

Returns a render context suitable for rendering the scene with a given renderer.

Note:

The root group, options, and camera instance must be set to valid values before this method can return a non NULL value.

If a name is given to the render context then the render context is accessible from other commands that may be running in parallel to this one. By naming a context it is possible to cancel a render or to perform progressive rendering.

The lifetime of a named render context is controlled by the timeout value. If 0 then the render context will be destroyed when the mi::nservices::IScene object that created it is destroyed. Such a timeout is only really useful for enabling renders to be cancelled. If greater than 0 then it will be destroyed timeout seconds after it was last used. This allows render commands in separate command requests to access the same render context and perform progressive renders.

Render contexts are stored only by name. However if a render context is requested whos root group, options, camera instance or renderer do not match the stored render context then a new render context is created which replaces the stored one. If the old render context is currently in use then it will still be valid however it will not be possible to cancel it.

See also:

mi::neuraylib::IScene::create_render_context()

Parameters

transaction
The transaction to be used
renderer
The name of the renderer to be used.
name
The name of the render context.
timeout
The lifetime of the render context in seconds.
errors
If specified then on failure error codes are written into here. See mi::neuraylib::IScene::create_render_context() for details.

Returns

The render context or NULL if no rendering context could be created for the given renderer.

virtual IRender_context* mi::​nservices::​IScene::get_render_context( const char* name) const [pure virtual]

Retrieves a render context by name. This method does not perform any checks that the render context is valid for this scene, it simply returns the named render context if it can be found in the cache.

Parameters

name
the name of the render context

Returns

The render context or NULL if no render context exists with the given name.

virtual const mi::IString* mi::​nservices::​IScene::get_rootgroup() const [pure virtual]

Returns the name of the root group object of this scene.

See also:

mi::neuraylib::IScene::get_rootgroup()

Returns

The name, or NULL if there is no root group.

virtual neuraylib::IScene* mi::​nservices::​IScene::get_scene() const [pure virtual]

Returns the underlying Neuray Library scene representation.

Returns

The scene or NULL if no neuray library scene is associated with this object.

virtual Sint32 mi::​nservices::​IScene::remove() [pure virtual]

Deletes the scene from the database regardless of any timers that may still exist. Calling this method will remove all the data associated with this scene including the scene graph. It should be noted however that this removal is dependent upon the neuray libraries internal garbage collection. Consequently, it may take sometime for the scene data to be flushed from the database.

See also:

mi::neuraylib::ITransaction::remove.

Returns

  • NRS_ERROR_NONE : success.
  • NRS_ERROR_FAILED : failure.

virtual mi::Sint32 mi::​nservices::​IScene::remove_render_context( const char* name) [pure virtual]

Removes a render context by name.

Parameters

name
the name of the render context

Returns

  • NRS_ERROR_NONE : success.
  • NRS_ERROR_NOT_FOUND : render context not found.
  • NRS_ERROR_INVALID_PARAMETERS : name is NULL or an empty string.

virtual Sint32 mi::​nservices::​IScene::set_camera_instance( const char* camera) [pure virtual]

Sets the camera instance used for rendering.

See also:

mi::neuraylib::IScene::set_camera_instance()

Parameters

camera
The name of the camera

Returns

NRS_ERROR_NONE success NRS_ERROR_FAILED failure

virtual Sint32 mi::​nservices::​IScene::set_dirty( mi::Uint32 flags = 0) [pure virtual]

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

Returns

  • NRS_ERROR_NONE : success.
  • NRS_ERROR_FAILED : failure.

virtual Sint32 mi::​nservices::​IScene::set_options( const char* options) [pure virtual]

Sets the options used for rendering.

See also:

mi::neuraylib::IScene::set_options()

Parameters

options
The name of the options object

Returns

NRS_ERROR_NONE success NRS_ERROR_FAILED failure

virtual Sint32 mi::​nservices::​IScene::set_rootgroup( const char* root) [pure virtual]

Sets the root group used for rendering.

See also:

mi::neuraylib::IScene::set_rootgroup()

Parameters

root
The root group

Returns

NRS_ERROR_NONE success NRS_ERROR_FAILED failure

virtual mi::Sint32 mi::​nservices::​IScene::start_expiry_timer( mi::Uint32 delay) [pure virtual]

starts the expiry timer for the scene

Parameters

delay
The time in seconds after which the scene will be removed if inactive.

Returns

  • NRS_ERROR_NONE : success.
  • NRS_ERROR_FAILED : Failed to start timer.

virtual mi::Sint32 mi::​nservices::​IScene::stop_expiry_timer() [pure virtual]

Stops the expiry timer for the scene.

Returns

  • NRS_ERROR_NONE : success.
  • NRS_ERROR_FAILED : Failed to stop timer.