Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IFactory Class Referenceabstract

This API component allows the creation, assignment, and cloning of instances of types. It also provides a comparison function for types. More...

Inheritance diagram for mi::neuraylib::IFactory:
mi::base::Interface_declare< 0x8afad838, 0xe597, 0x4a81, 0x92, 0x34, 0x51, 0xfe, 0xa4, 0xff, 0x04, 0x31 > mi::base::IInterface

Public Types

enum  Assign_result {
  NULL_POINTER = 1,
  STRUCTURAL_MISMATCH = 2,
  NO_CONVERSION = 4,
  TARGET_KEY_MISSING = 8,
  SOURCE_KEY_MISSING = 16,
  DIFFERENT_COLLECTIONS = 32,
  NON_IDATA_VALUES = 64,
  INCOMPATIBLE_POINTER_TYPES = 128,
  DEEP_ASSIGNMENT_TO_CONST_POINTER = 256,
  INCOMPATIBLE_PRIVACY_LEVELS = 1024,
  INCOMPATIBLE_ENUM_TYPES = 2048,
  INCOMPATIBLE_OPTIONS = 4096
}
 This enum represents possible events that can happen during assignment of types. More...
 
enum  Assign_clone_options {
  DEEP_ASSIGNMENT_OR_CLONE = 1,
  FIX_SET_OF_TARGET_KEYS = 4
}
 This enum represents various options for the assignment or cloning of types. More...
 
- Public Types inherited from mi::base::Interface_declare< 0x8afad838, 0xe597, 0x4a81, 0x92, 0x34, 0x51, 0xfe, 0xa4, 0xff, 0x04, 0x31 >
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...
 
- Public Types inherited from mi::base::IInterface
typedef Uuid_t< 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 > IID
 Declares the interface ID (IID) of this interface. More...
 

Public Member Functions

virtual base::IInterfacecreate (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 Uint32 assign_from_to (const IData *source, IData *target, Uint32 options=0)=0
 Assigns the value(s) of source to target. More...
 
virtual IDataclone (const IData *source, Uint32 options=0)=0
 Creates a clone of a type. More...
 
template<class T >
T * clone (const IData *source, Uint32 options=0)
 Creates a clone of a type. More...
 
virtual Sint32 compare (const IData *lhs, const IData *rhs)=0
 Compares two instances of mi::IData. More...
 
virtual const IStringdump (const IData *data, const char *name=0, Size depth=0)=0
 Returns a textual representation of a type. More...
 
virtual const IStringdump (neuraylib::ITransaction *transaction, const IData *data, const char *name=0, Size depth=0)=0
 Returns a textual representation of a type. More...
 
virtual const IStructure_declget_structure_decl (const char *structure_name) const =0
 Returns a registered structure declaration. More...
 
virtual const IEnum_declget_enum_decl (const char *enum_name) const =0
 Returns a registered enum declaration. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from mi::base::Interface_declare< 0x8afad838, 0xe597, 0x4a81, 0x92, 0x34, 0x51, 0xfe, 0xa4, 0xff, 0x04, 0x31 >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 

Detailed Description

This API component allows the creation, assignment, and cloning of instances of types. It also provides a comparison function for types.

Types are interfaces derived from mi::IData. See Types for an explanation of the type system.

Member Enumeration Documentation

This enum represents various options for the assignment or cloning of types.

The enum values are powers of two such that they can be combined in a bitmask. Such a bitmask van be is passed to assign_from_to() and clone().

Enumerator
DEEP_ASSIGNMENT_OR_CLONE 

By default, assignment or cloning of instances of mi::IPointer and mi::IConst_pointer is shallow, i.e., the pointer represented by these interfaces is assigned or cloned as a plain value and both pointers point to the same interface afterwards. If this option is given the assignment or cloning is deep, i.e., the operations happens on the wrapped pointers themselves.

FIX_SET_OF_TARGET_KEYS 

By default, assignment might change the set of keys if the for target is a dynamic array or map. If this option is given the set of keys in the target remains fixed.

This enum represents possible events that can happen during assignment of types.

The enum values are powers of two such that they can be combined in a bitmask. Such a bitmask is returned by assign_from_to().

Enumerator
NULL_POINTER 

One of the arguments source or target is NULL. Alternatively, a deep assignment to an instance of mi::IPointer failed due to a NULL value.

STRUCTURAL_MISMATCH 

There is a structural mismatch between source and target. One of the two arguments is of type mi::IData_simple and the other one is of mi::IData_collection, or alternatively, both arguments are of type mi::IData_collection and there is at least one key which is of type mi::IData_simple in one argument, and of type mi::IData_collection in the other argument.

NO_CONVERSION 

Both arguments (or at least one key thereof) are of different interfaces derived from mi::IData_simple and there is no conversion between them. This happens for example if an instance of mi::ISint32 is assigned to an instance of mi::IString).

TARGET_KEY_MISSING 

There is at least one key in source which does not exist in target.

SOURCE_KEY_MISSING 

There is at least one key in target which does not exist in source.

DIFFERENT_COLLECTIONS 

Both arguments source and target (or the types of at least one key thereof) are collections, but of different type. For example, this flag is set when assigning from static to dynamic arrays, from arrays to maps, or from arrays or maps to compounds, or vice versa.

NON_IDATA_VALUES 

The argument source is a collection and contains at least one key which is not of type mi::IData, e.g., in untyped arrays or maps. Or source is a pointer or contains a key that is a pointer that wraps an instance not derived from mi::IData. Such types cannot get assigned with this method.

INCOMPATIBLE_POINTER_TYPES 

Shallow assignment (the default) was requested and the assignment failed due to incompatible pointer types, e.g., assigning from mi::IConst_pointer to mi::IPointer, or between different typed pointers (mi::IPointer::set_pointer() or mi::IConst_pointer::set_pointer() failed).

DEEP_ASSIGNMENT_TO_CONST_POINTER 

Deep assignment was requested and target is an instance of mi::IConst_pointer (or a key of target is an instance of mi::IConst_pointer).

INCOMPATIBLE_PRIVACY_LEVELS 

The assignment failed due to incompatible privacy levels, i.e., mi::IRef::set_reference() returned error code -4.

INCOMPATIBLE_ENUM_TYPES 

The assignment failed due to incompatible enum types.

INCOMPATIBLE_OPTIONS 

The assignment failed due to incompatible options.

Member Function Documentation

virtual Uint32 mi::neuraylib::IFactory::assign_from_to ( const IData source,
IData target,
Uint32  options = 0 
)
pure virtual

Assigns the value(s) of source to target.

Assignment succeeds if both source and target are of the same type. If not, the method tries to perform an assignment on a best effort basis. For example, an assignment between interfaces derived from mi::INumber might require a conversion as defined in the C/C++ standard. If both arguments are of type mi::IData_collection, assignment happens for all keys existing in both parameters.

Parameters
sourceThe instance to assign from.
targetThe instance to assign to.
optionsSee Assign_clone_options for possible options.
Returns
The return value is a bit field that indicates which events occurred during assignment. See Assign_result for possible events.
The value 0 indicates that the assignment took place without any problems. Note that a non-zero value is not necessarily an error, it is up to the caller to interpret the result according to the context. For example, assigning from an instance of mi::IFloat32_3 to an instance of mi::IFloat32_2 will result in TARGET_KEY_MISSING because there is no key named "z" in mi::IFloat32_2. It is up to the caller to decide whether this is the intended behavior or not.
virtual IData* mi::neuraylib::IFactory::clone ( const IData source,
Uint32  options = 0 
)
pure virtual

Creates a clone of a type.

It is not possible to clone untyped pointers and collections that wrap/contain interface pointers that are not of type mi::IData.

Parameters
sourceThe instance to clone.
optionsSee Assign_clone_options for possible options.
template<class T >
T* mi::neuraylib::IFactory::clone ( const IData source,
Uint32  options = 0 
)
inline

Creates a clone of a type.

It is not possible to clone untyped pointers and collections that wrap/contain interface pointers that are not of type mi::IData.

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.

Parameters
sourceThe instance to clone.
optionsSee Assign_clone_options for possible options.
Template Parameters
TThe interface type of the class to create
virtual Sint32 mi::neuraylib::IFactory::compare ( const IData lhs,
const IData rhs 
)
pure virtual

Compares two instances of mi::IData.

The comparison operator for instances of mi::IData is defined as follows:

  • If lhs or rhs is NULL, the result is the lexicographic comparison of the pointer addresses themselves.
  • Otherwise, the type names of lhs and rhs are considered. If they are different, the result is determined by strcmp() on the type names. For example, this method never returns 0 if you compare a dynamic array and a static array, even if they have the same element type, length, and equal element values.
  • Finally, the values of the elements are compared lexicographically, as defined by operator< or strcmp() with the following special cases for selected interfaces:
    • mi::IRef: If mi::IRef::get_reference_name() returns NULL for at least one operand, the result is the lexicographic comparison of the pointer addresses. Otherwise, the result is determined by strcmp() on the names of the referenced DB elements.
    • mi::IPointer and mi::IConst_pointer: If mi::IPointer::get_pointer() or mi::IConst_pointer::get_pointer() returns NULL for at least one operand, the result is the lexicographic comparison of the pointer addresses. Otherwise, if at least one pointer is not of the type mi::IData, the result is the lexicographic comparison of the pointer addresses. Finally (both pointers are of type mi::IData), the result is determined by the recursive invocation of this method on these pointers.
    • mi::IData_collection: First, if the collections have different length, this decides the comparison. Next, the elements are compared pairwise in lexicographic order of the element index. If the element keys are different, strcmp() on the element keys determines the result. Otherwise, the element values are compared by recursive invocation of this method (or lexicographic comparison of the pointer addresses if one element is not of type mi::IData). If they are different, this decides the result, otherwise the comparison continues with the next element. If all elements are equal, the result is 0.
Parameters
lhsThe left-hand side operand for the comparison.
rhsThe right-hand side operand for the comparison.
Returns
-1 if lhs < rhs, 0 if lhs == rhs, and +1 if lhs > rhs.
virtual base::IInterface* mi::neuraylib::IFactory::create ( const char *  type_name,
Uint32  argc = 0,
const base::IInterface argv[] = 0 
)
pure virtual

Creates an object of the type type_name.

The arguments passed to this method are passed to the constructor of the created object.

This factory allows the creation of instances of mi::IData and derived interfaces. For other kind of objects like DB elements use mi::neuraylib::ITransaction::create(). It is not possible to create instances of mi::IRef or collections of references. Use::mi::neuraylib::ITransaction::create()instead.

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.

See Also
mi::neuraylib::ITransaction::create()
Parameters
type_nameThe type name of the object to create. See Types for possible type names.
argcThe number of elements in argv.
argvThe array of arguments passed to the constructor.
Returns
A pointer to the created object on success, or NULL on failure (e.g., invalid type name).
template<class T >
T* mi::neuraylib::IFactory::create ( const char *  type_name,
Uint32  argc = 0,
const base::IInterface argv[] = 0 
)
inline

Creates an object of the type type_name.

The arguments passed to this method are passed to the constructor of the created object.

This factory allows the creation of instances of mi::IData and derived interfaces. For other kind of objects like DB elements use mi::neuraylib::ITransaction::create(). It is not possible to create instances of mi::IRef or collections of references. Use::mi::neuraylib::ITransaction::create()instead.

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 factory class). The version with no arguments can only be used to create a subset of supported types: 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, and pointers. 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.

See Also
mi::neuraylib::ITransaction::create()
Parameters
type_nameThe type name of the object to create
argcThe number of elements in argv
argvThe array of arguments passed to the constructor
Template Parameters
TThe interface type of the class to create
Returns
A pointer to the created object on success, or NULL on failure (e.g., invalid type name).
template<class T >
T* mi::neuraylib::IFactory::create ( )
inline

Creates an object of the type T.

This factory allows the creation of instances of mi::IData and derived interfaces. For other kind of objects like DB elements use mi::neuraylib::ITransaction::create(). It is not possible to create instances of mi::IRef or collections of references. Use::mi::neuraylib::ITransaction::create()instead.

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 factory class). The version with no arguments can only be used to create a subset of supported types: 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, and pointers. 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.

See Also
mi::neuraylib::ITransaction::create()
Template Parameters
TThe interface type of the class to create
Returns
A pointer to the created object on success, or NULL on failure (e.g., invalid type name).
virtual const IString* mi::neuraylib::IFactory::dump ( const IData data,
const char *  name = 0,
Size  depth = 0 
)
pure virtual

Returns a textual representation of a type.

The textual representation is of the form "type name = value" if name is not NULL, and of the form "value" if name is NULL. The representation of the value might contain line breaks, for example for structures and arrays. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

See Also
mi::neuraylib::IFactory::dump(ITransaction*,const IData*,const char*,Size)
virtual const IString* mi::neuraylib::IFactory::dump ( neuraylib::ITransaction transaction,
const IData data,
const char *  name = 0,
Size  depth = 0 
)
pure virtual

Returns a textual representation of a type.

This overload of mi::neuraylib::IFactory::dump(const IData*,const char*,Size) requires an additional transaction pointer. This is necessary to support the dumping of possibly nested non-mi::IData types.

virtual const IEnum_decl* mi::neuraylib::IFactory::get_enum_decl ( const char *  enum_name) const
pure virtual

Returns a registered enum declaration.

Parameters
enum_nameThe name of the enum declaration to return.
Returns
The enum declaration for name, or NULL if there is no enum declaration for that name.
virtual const IStructure_decl* mi::neuraylib::IFactory::get_structure_decl ( const char *  structure_name) const
pure virtual

Returns a registered structure declaration.

Parameters
structure_nameThe name of the structure declaration to return.
Returns
The structure declaration for name, or NULL if there is no structure declaration for that name.