neuray API Programmer's Manual

mi::neuraylib::INeuray Class Reference

[MainneurayAdjectiveName Interface and C access function]

Description

This is an object representing the . Only one object of this type will exist at a time. It is used for configuration, startup and shutdown of the .

mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

Public Enumerations

enum Status{ PRE_STARTING = 0, STARTING = 1, STARTED = 2, SHUTTINGDOWN = 3, SHUTDOWN = 4, FAILURE = 5, FORCE_32_BIT = 0xffffffffU}
The operational status of the library .

Public Member Functions

virtual base::​IInterface* get_api_component( const base::​Uuid& uuid) const =0
Returns an API component from the neuray API. More...
template< class T>T* get_api_component() const
Returns an API component from the neuray API. More...
virtual Uint32 get_interface_version() const =0
Returns the interface version of the . More...
virtual Status get_status() const =0
Returns the status of the library. More...
virtual const char* get_version() const =0
Returns the product version of the . More...
virtual Sint32 register_api_component( const base::​Uuid& uuid, base::​IInterface* api_component) =0
Registers an API component with the neuray API. More...
template< class T>Sint32 register_api_component( T* api_component)
Registers an API component with the neuray API. More...
virtual Sint32 shutdown( bool blocking = true) =0
Shuts down the library. More...
virtual Sint32 start( bool blocking = true) =0
Starts the operation of the . More...
virtual Sint32 unregister_api_component( const base::​Uuid& uuid) =0
Unregisters an API component with the neuray API. More...
template< class T>Sint32 unregister_api_component()
Unregisters an API component with the neuray API. More...

Enums

enum mi::​neuraylib::​INeuray::Status

The operational status of the library .

Enumerator:

PRE_STARTING = 0
The library or the cluster has not yet been started.
STARTING = 1
The library or the cluster is starting.
STARTED = 2
The library or the cluster is ready for operation.
SHUTTINGDOWN = 3
The library or the cluster is shutting down.
SHUTDOWN = 4
The library or the cluster has been shut down.
FAILURE = 5
There was a failure during operation.
FORCE_32_BIT = 0xffffffffU

Member Functions

virtual base::​IInterface* mi::​neuraylib::​INeuray::get_api_component( const base::​Uuid& uuid) const [pure virtual]

Returns an API component from the neuray API.

See also:

mi_neuray_api_components for a list of built-in API components.

register_api_component(), unregister_api_component()

Parameters

uuid
The UUID under which the API components was registered. For built-in API components this is the interface ID of the corresponding interface.

Returns

A pointer to the API component or NULL if the API component is not supported or currently not available.

template< class T>

T* mi::​neuraylib::​INeuray::get_api_component() const [inline]

Returns an API component from the neuray API. This template variant requires that the API component is registered under the interface ID of the corresponding interface (which is the case for built-in API components).

See also:

mi_neuray_api_components for a list of built-in API components.

register_api_component(), unregister_api_component()

Returns

A pointer to the API component or NULL if the API component is not supported or currently not available.

virtual Uint32 mi::​neuraylib::​INeuray::get_interface_version() const [pure virtual]

Returns the interface version of the . This number changes whenever the abstract interfaces of the neuray API change.

virtual Status mi::​neuraylib::​INeuray::get_status() const [pure virtual]

Returns the status of the library.

Returns

The status

virtual const char* mi::​neuraylib::​INeuray::get_version() const [pure virtual]

Returns the product version of the . This string contains the product version, build number, build date, etc. of the current library.

virtual Sint32 mi::​neuraylib::​INeuray::register_api_component( const base::​Uuid& uuid, base::​IInterface* api_component) [pure virtual]

Registers an API component with the neuray API. API components are a way for plugins to provide access to their functionality. The registration makes the API component available for subsequent calls of get_api_component().

Parameters

uuid
The ID of the API component to register, e.g., the interface ID of the corresponding interface.
api_component
The API component to register.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: There is already an API component registered under the ID uuid.

template< class T>

Sint32 mi::​neuraylib::​INeuray::register_api_component( T* api_component) [inline]

Registers an API component with the neuray API. API components are a way for plugins to provide access to their functionality. The registration makes the API component available for subsequent calls of get_api_component().

This template variant registers the API component under the interface ID of the corresponding interface.

Parameters

api_component
The API component to register.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: There is already an API component registered under the ID T::IID().
virtual Sint32 mi::​neuraylib::​INeuray::shutdown( bool blocking = true) [pure virtual]

Shuts down the library. For proper shutdown this may only be called after all transactions have been committed and all rendering is finished.

You also need to release all interface pointers related to functionality obtained after startup before calling this method. In case you use the mi::base::Handle class (or another handle class), you need to make sure that all such handles have been reset or destroyed.

Parameters

blocking
Indicates whether the shutdown should be done in blocking mode. If true the method will not return before shutdown has completed. If false the method will return immediately and the shutdown is done in a separate thread. The status of the shutdown sequence can be checked via get_status().

Returns

0, in case of success, -1 in case of failure

virtual Sint32 mi::​neuraylib::​INeuray::start( bool blocking = true) [pure virtual]

Starts the operation of the . All configuration which is marked to be done before the start of the library must be done before calling this function. When calling this function will start threads and start network operations etc. The may not be ready for operation after the call returned if blocking mode is not used.

Parameters

blocking
Indicates whether the startup should be done in blocking mode. If true the method will not return before all initialization was done. If false the method will return immediately and the startup is done in a separate thread. The status of the startup sequence can be checked via get_status().

Returns

  • 0: Success
  • -1: Unspecified failure.
  • -2: Authentication failure (challenge-response).
  • -3: Authentication failure (SPM).
  • -4: Provided license expired.
  • -5: No professional GPU as required by the license in use was found.
  • -6: Authentication failure (FLEXlm).
  • -7: No NVIDIA VCA as required by the license in use was found.
virtual Sint32 mi::​neuraylib::​INeuray::unregister_api_component( const base::​Uuid& uuid) [pure virtual]

Unregisters an API component with the neuray API. The API component will no longer be accessible via get_api_component().

Parameters

uuid
The ID of the API component to unregister.

Returns

  • 0: Success.
  • -1: There is no API component registered under the ID uuid.

template< class T>

Sint32 mi::​neuraylib::​INeuray::unregister_api_component() [inline]

Unregisters an API component with the neuray API. The API component will no longer be accessible via get_api_component().

This template variant requires that the API component was registered under the interface ID of the corresponding interface (which is the case for the template variant of register_api_component()).

Returns

  • 0: Success.
  • -1: There is no API component registered under the ID T::IID().