A transaction provides a consistent view on the database. More...
Public Member Functions | |
virtual Sint32 | commit ()=0 |
Commits the transaction. More... |
|
virtual void | abort ()=0 |
Aborts the transaction. More... |
|
virtual bool | is_open () const =0 |
Indicates whether the transaction is open. More... |
|
virtual base::IInterface * | create (const char *type_name, Uint32 argc=0, const base::IInterface *argv[]=0)=0 |
Creates an object of the type type_name . More... |
|
template<class T > | |
T * | create (const char *type_name, Uint32 argc=0, const base::IInterface *argv[]=0) |
Creates an object of the type type_name . More... |
|
template<class T > | |
T * | create () |
Creates an object of the type T . More... |
|
virtual Sint32 | store (base::IInterface *db_element, const char *name, Uint8 privacy=LOCAL_SCOPE)=0 |
Stores the element db_element in the database under the name name and with the privacy level privacy . More... |
|
virtual const base::IInterface * | access (const char *name)=0 |
Retrieves an element from the database. More... |
|
template<class T > | |
const T * | access (const char *name) |
Retrieves an element from the database. More... |
|
virtual base::IInterface * | edit (const char *name)=0 |
Retrieves an element from the database and returns it ready for editing. More... |
|
template<class T > | |
T * | edit (const char *name) |
Retrieves an element from the database and returns it ready for editing. More... |
|
virtual Sint32 | copy (const char *source, const char *target, Uint8 privacy=0)=0 |
Creates a copy of a database element. More... |
|
virtual Sint32 | remove (const char *name, bool only_localized=false)=0 |
Removes the element with the name name from the database. More... |
|
virtual const char * | name_of (const base::IInterface *db_element) const =0 |
Returns the name of a database element. More... |
|
virtual const char * | get_time_stamp () const =0 |
Returns the time stamp describing the current "time". More... |
|
virtual const char * | get_time_stamp (const char *element) const =0 |
Returns the time stamp of the last change of a database element. More... |
|
virtual bool | has_changed_since_time_stamp (const char *element, const char *time_stamp) const =0 |
Checks whether an element has been stored or changed in the database since a given time stamp. More... |
|
virtual const char * | get_id () const =0 |
Returns the ID of this transaction. More... |
|
virtual IScope * | get_scope () const =0 |
Returns the scope of this transaction. More... |
|
virtual IArray * | list_elements (const char *root_element, const char *name_pattern=0, const IArray *type_names=0) const =0 |
Returns scene elements of a subgraph originating at a given scene element. More... |
|
virtual Sint32 | get_privacy_level (const char *name) const =0 |
Returns the privacy level of the element with the name name . More... |
|
Static Public Attributes | |
static const mi::Uint8 | LOCAL_SCOPE = 255 |
Symbolic privacy level for the privacy level of the scope of this transaction. More... |
|
Additional Inherited Members | |
Public Types inherited from mi::base::Interface_declare< 0x6ca1f0c2, 0xb262, 0x4f09, 0xa6, 0xa5, 0x05, 0xae, 0x14, 0x45, 0xed, 0xfa > | |
typedef Interface_declare< id1, id2, id3, id4, id5, id6, id7, id8, id9, id10, id11, IInterface > |
Self |
Own type. More... |
|
typedef Uuid_t< id1, id2, id3, id4, id5, id6, id7, id8, id9, id10, id11 > |
IID |
Declares the interface ID (IID) of this interface. More... |
|
Static Public Member Functions inherited from mi::base::Interface_declare< 0x6ca1f0c2, 0xb262, 0x4f09, 0xa6, 0xa5, 0x05, 0xae, 0x14, 0x45, 0xed, 0xfa > | |
static bool | compare_iid (const Uuid &iid) |
Compares the interface ID iid against the interface ID of this interface and of its ancestors. More... |
|
A transaction provides a consistent view on the database.
This view on the database is isolated from changes by other (parallel) transactions. Eventually, each transaction must be either committed or aborted, i.e., all changes become either atomically visible to transaction started afterwards, or not at all.
Transaction are associated with a scope of the database and can be created with mi::neuraylib::IScope::create_transaction().
|
pure virtual |
Aborts the transaction.
Note that an abort() implicitly closes the transaction. A closed transaction does not allow any future operations and needs to be released.
|
pure virtual |
Retrieves an element from the database.
The database searches for the most recent version of the named DB element visible for the current transaction. That version will be returned.
name | The name of the element to retrieve. |
NULL
if name
is invalid, no DB element with that name exists, or the transaction is already closed.
|
inline |
Retrieves an element from the database.
The database searches for the most recent version of the named DB element visible for the current transaction. That version will be returned.
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 const pointer to the type T
specified as template parameter.
name | The name of the element to retrieve. |
T | The interface type of the element to retrieve. |
NULL
if name
is invalid, no DB element with that name exists, the transaction is already closed, or the element is not of type T
.
|
pure virtual |
Commits the transaction.
Note that a commit() implicitly closes the transaction. A closed transaction does not allow any future operations and needs to be released.
|
pure virtual |
Creates a copy of a database element.
Note that DB elements of type mi::IMdl_module, mi::IMdl_material_definition, and mi::IMdl_function_definition can not be copied.
source | The name of the element to be copied. |
target | The desired name of the copy. |
privacy | The desired privacy level of the copy (in the range from 0 to the privacy level of the scope of this transaction). In addition, the constant LOCAL_SCOPE can be used as a shortcut to indicate the privacy level of the scope of this transaction without supplying the actual value itself. Note that DB elements of type mi::IShader_class, mi::IShader_graph_class, and mi::ICompound_shader_class can only be stored in privacy level 0. |
NULL
pointer).source
visible in this transaction.name
and overwriting elements of that type is not supported. This applies to elements of type mi::IMdl_module, mi::IMdl_material_definition, and mi::IMdl_function_definition.
|
pure virtual |
Creates an object of the type type_name
.
Objects created with this methods are typically Types, Scene elements and Functors. It is also possible to create instances of user-defined classes. Note that most types can also be created via the API component mi::neuraylib::IFactory which does not require the context of a transaction.
This method can not be used to create MDL definitions, material instances, or function calls. To create instances of mi::IMdl_material_instance and mi::IMdl_function_call, use the methods mi::IMdl_material_definition::create_material_instance() or mi::IMdl_function_definition::create_function_call(), respectively.
This method can not be used to create instances of mi::IShader_class, mi::IShader, or mi::IShader_graph. To create an instance of the latter two these interfaces, use the methods mi::IShader_class::create_shader() or mi::IShader_graph_class::create_shader_graph(), respectively.
The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.
type_name | The type name of the object to create. See Types for possible type names. In addition, Scene elements and Functors can be created by passing the name of the requested interfaces without namespace qualifiers and the leading "I" , e.g., "Camera" for mi::ICamera. Names of user-defined classes are also valid arguments. Note that you can not create instances of mi::IAttribute_set or mi::IScene_element, only instances of the derived interfaces (see also mi::IAttribute_container). |
argc | The number of elements in argv . Passed to the constructor of factory of the object to create. |
argv | The array of arguments passed to the constructor. Passed to the constructor of factory of the object to create. |
NULL
if type_name
is invalid (NULL
pointer) or not a valid type name.
|
inline |
Creates an object of the type type_name
.
Objects created with this method are typically Types, Scene elements and Functors. It is also possible to create instances of user-defined classes. Note that most types can also be created via the API component mi::neuraylib::IFactory which does not require the context of a transaction.
This method can not be used to create MDL definitions, material instances, or function calls. To create instances of mi::IMdl_material_instance and mi::IMdl_function_call, use the methods mi::IMdl_material_definition::create_material_instance() or mi::IMdl_function_definition::create_function_call(), respectively.
This method can not be used to create instances of mi::IShader_class, mi::IShader, or mi::IShader_graph. To create an instance of the latter two these interfaces, use the methods mi::IShader_class::create_shader() or mi::IShader_graph_class::create_shader_graph(), respectively.
The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.
Note that there are two versions of this templated member function, one that takes no arguments, and another one that takes one or three arguments (the type name, and two optional arguments passed to the constructor or factory). The version with no arguments can only be used to create a subset of supported types derived from mi::IData: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays, structures, maps, pointers, attachables, and calls.The version with one or three arguments can be used to create any type (but requires the type name as parameter, which is redundant for many types). Attempts to use the version with no arguments with a template parameter where the type name can not be deduced results in compiler errors.
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.
type_name | The type name of the object to create. See Types for possible type names. In addition, Scene elements and Functors can be created by passing the name of the requested interfaces without namespace qualifiers and the leading "I" , e.g., "Camera" for mi::ICamera. Names of user-defined classes are also valid arguments. Note that you can not create instances of mi::IAttribute_set or mi::IScene_element, only instances of the derived interfaces (see also mi::IAttribute_container). |
argc | The number of elements in argv . Passed to the constructor of factory of the object to create. |
argv | The array of arguments passed to the constructor. Passed to the constructor of factory of the object to create. |
T | The interface type of the class to create. |
NULL
if type_name
is invalid (NULL
pointer), not a valid type name, or does not create an object of type T
.
|
inline |
Creates an object of the type T
.
Objects created with this method are typically Types. Note that most types can also be created via the API component mi::neuraylib::IFactory which does not require the context of a transaction.
The created object will be initialized in a manner dependent upon the passed type name. Each class has its own policy on initialization. So, one should not make any assumptions on the values of the various class members.
Note that there are two versions of this templated member function, one that takes no arguments, and another one that takes one or three arguments (the type name, and two optional arguments passed to the constructor or factory). The version with no arguments can only be used to create a subset of supported types derived from mi::IData: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays, structures, maps, pointers, attachables, and calls.The version with one or three arguments can be used to create any type (but requires the type name as parameter, which is redundant for many types). Attempts to use the version with no arguments with a template parameter where the type name can not be deduced results in compiler errors.
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.
T | The interface type of the class to create. |
|
pure virtual |
Retrieves an element from the database and returns it ready for editing.
The database searches for the most recent version of the named DB element visible for the current transaction. It will then make a copy of that version and return the copy. The edited DB element will be committed to the database automatically, when the obtained interface is released. It is neither necessary nor possible to store the edited element manually in the database using the store() method.
Note that it is not possible to edit instances of mi::IShader_graph_class or mi::ICompound_shader_class.
name | The name of the element to retrieve. |
NULL
if name
is invalid, no DB element with that name exists, or the transaction is already closed.
|
inline |
Retrieves an element from the database and returns it ready for editing.
The database searches for the most recent version of the named database element visible for the current transaction. It will then make a copy of that version and return the copy. The edited DB element will be committed to the database automatically, when the obtained interface is released. It is neither necessary nor possible to store the edited element manually in the database using the store() method.
Note that it is not possible to edit instances of mi::IShader_graph_class or mi::ICompound_shader_class. 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.
name | The name of the element to retrieve. |
T | The interface type of the element to retrieve. |
NULL
if name
is invalid, no DB element with that name exists, the transaction is already closed, or the element is not of type T
.
|
pure virtual |
Returns the ID of this transaction.
The transaction ID is of most use when debugging an application as the value returned allows one to correlate log messages and admin HTTP server output with the API actions.
|
pure virtual |
Returns the privacy level of the element with the name name
.
name | The name of the element. |
NULL
pointer).name
visible in this transaction.
|
pure virtual |
Returns the scope of this transaction.
|
pure virtual |
Returns the time stamp describing the current "time".
|
pure virtual |
Returns the time stamp of the last change of a database element.
|
pure virtual |
Checks whether an element has been stored or changed in the database since a given time stamp.
time
stamp should not stem from another concurrent transaction. Such changes will never be visible in this transaction, but the method might still return true
depending on the start order of the two transactions.element | The name of the element. |
time_stamp | The time stamp obtained from get_time_stamp() or get_time_stamp(const char*)const. |
true
if the element has been stored or changed since the time stamp (or if element
or time_stamp
is invalid, or there is no element with that name), false
otherwise.
|
pure virtual |
Indicates whether the transaction is open.
true
if the transaction is still open, or false
if the transaction is closed, i.e., it has been committed or aborted.
|
pure virtual |
Returns scene elements of a subgraph originating at a given scene element.
The method iterates over all elements of a subgraph originating at the given scene element and returns their names. Optionally, the results can be filtered by a regular expression for the element names and a list for type names.
Note that the runtime of the method depends on the number of elements in the subgraph. It might be expensive to call this method for large subgraphs.
The returned scene elements are in such an order that all elements referenced by a given element are listed before that element (before in the sense of smaller array indices).
root_element | The root of the subgraph to traverse. |
name_pattern | A regular expression that acts as filter on the names of returned scene elements. The regular expression must be compliant to extended regular expressions as defined in POSIX 1003.2. The value NULL is handled as ".*" . |
type_names | A list of type names that acts as filter on the names of returned scene elements. Only scene elements with a matching type name pass the filter. The value NULL lets all scene elements pass the filter irrespective of their type name. |
NULL
in case of an invalid root element name or an invalid regular expression.
|
pure virtual |
Returns the name of a database element.
db_element | The DB element. |
NULL
if db_element
is invalid (NULL
pointer), the object is not in the database, or the transaction is already closed.
|
pure virtual |
Removes the element with the name name
from the database.
Note that the element continues to be stored in the database as long as it is referenced by other elements. If it is no longer referenced, it will be lazily removed by the garbage collection of the DB. There is no guarantee when this will happen. This implies that a remove() call might actually remove an element that was stored later under the same name. This can potentially lead to invalid tag accesses. Those cases can be fixed by using mi::neuraylib::IDatabase::garbage_collection() after a transaction was committed and before starting the next one to force garbage collection of all possible elements.
Be careful with the removal of elements of type mi::IMdl_material_definition and mi::IMdl_function_definition. As long as the corresponding MDL module still exists in the DB it is not possible to recreate the material and/or function definition.
name | The name of the element in the database to remove. |
only_localized | If true , the element is only removed if it exists in the scope of the transaction; parent scopes are not considered. |
name
visible in this transaction (only_localize
is false
) or there is no DB element named name
in the scope of this transaction (only_localized
is true
).NULL
pointer).
|
pure virtual |
Stores the element db_element
in the database under the name name
and with the privacy level privacy
.
After a successful store operation the passed interface pointer must no longer be used, except for releasing it. This is due to the fact that after a store() the database retains ownership of the stored data. You can obtain the stored version from the database using the access() or edit() methods.
db_element | The mi::base::IInterface to store. |
name | The name under which to store db_element . If there exists already a DB element with that name then it will be overwritten (but see also return code -9 below) . |
privacy | The privacy level under which to store db_element (in the range from 0 to the privacy level of the scope of this transaction). In addition, the constant LOCAL_SCOPE can be used as a shortcut to indicate the privacy level of the scope of this transaction without supplying the actual value itself. Note that DB elements of type mi::IShader_class, mi::IShader_graph_class, and mi::ICompound_shader_class can only be stored in privacy level 0. |
NULL
pointer).db_element
is not a DB element.db_element
has already been stored previously.name
and overwriting elements of that type is not supported. This applies to elements of type mi::IMdl_module, mi::IMdl_material_definition, and mi::IMdl_function_definition.
|
static |
Symbolic privacy level for the privacy level of the scope of this transaction.
This symbolic constant can be passed to store() and copy() to indicate the privacy level of the scope of this transaction. It has the same affect as passing the result of mi::neuraylib::IScope::get_privacy_level(), but is more convenient.