Iray Programmer's Manual

Database scopes

While transactions allow to run multiple operations at the same time without affecting each other for multi-user operation a second concept is important: the database scopes. A scope is basically a container for database elements. Each database element is stored in a specific scope. Scopes can be nested, each scopes can have an arbitrary number of child scopes and an arbitrary number of database elements. Each scope except the "global" scope has exactly one parent scope. In that aspect the database is analogous to a file system with directories and files. A scope is analogous to a directory, while a database element corresponds to a file. The "global" scope corresponds to the "root" directory of a file system.

Scopes allow to have different database elements stored using the same key. This can for example be used to have different versions of the same database element for different users. An example where this is useful is, if two different users would like to view the same model of a car but have different colors on the paint. The usage of scopes is not limited to different users, they can also be used to have different variants of a model and let a user switch between them.

Each transaction is started within one specific scope. To carry the file system analogy further, the scope in which a transaction is started corresponds to the current working directory in a file system.

When some operation accesses a key for which multiple versions exist in different scopes the database needs to decide which version to return. This is done by first looking inside the current transaction's scope. If the key is found there the database element stored in that scope is returned. Otherwise the scope's parent scope is searched for the key. This continues until the "global" scope has been searched. If the key was not found in that scope the key does not exist or is not accessible from the current transaction's scope.

The sketched mechanism allows to overwrite a shared version of some scene element individually for different scopes.

Scopes can be created and removed using API functions. Removing a scope will automatically remove all contained scene elements.

Scopes are created from the database. A scope is represented with the mi::neuraylib::IScope interface in the API, which allows you to create transactions.