MDL SDK API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IExpression_factory Class Referenceabstract

The interface for creating expressions. More...

Inheritance diagram for mi::neuraylib::IExpression_factory:
mi::base::Interface_declare< 0x9fd3b2d4, 0xb5b8, 0x4ccd, 0x9b, 0x5f, 0x7b, 0xd9, 0x9d, 0xeb, 0x62, 0x64 > mi::base::IInterface

Public Types

enum  Comparison_options {
  DEFAULT_COMPARISON_OPTIONS = 0,
  DEEP_CALL_COMPARISONS = 1,
  SKIP_TYPE_ALIASES = 2
}
 Various options for the comparison of expressions or expression lists. More...
 
- Public Types inherited from mi::base::Interface_declare< 0x9fd3b2d4, 0xb5b8, 0x4ccd, 0x9b, 0x5f, 0x7b, 0xd9, 0x9d, 0xeb, 0x62, 0x64 >
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 IValue_factoryget_value_factory () const =0
 Returns the value factory associated with this expression factory. More...
 
virtual IExpression_constantcreate_constant (IValue *value) const =0
 Creates a constant (mutable). More...
 
virtual const
IExpression_constant
create_constant (const IValue *value) const =0
 Creates a constant (const). More...
 
virtual IExpression_callcreate_call (const char *name) const =0
 Creates a call. More...
 
virtual IExpression_parametercreate_parameter (const IType *type, Size index) const =0
 Creates a parameter reference. More...
 
virtual IExpression_direct_callcreate_direct_call (const char *name, IExpression_list *arguments, Sint32 *errors=0) const =0
 Creates a direct call. More...
 
virtual IExpression_listcreate_expression_list () const =0
 Creates a new expression list. More...
 
virtual IAnnotationcreate_annotation (const char *name, const IExpression_list *arguments) const =0
 Creates a new annotation. More...
 
virtual IAnnotation_blockcreate_annotation_block () const =0
 Creates a new annotation block. More...
 
virtual IAnnotation_listcreate_annotation_list () const =0
 Creates a new annotation list. More...
 
virtual IExpressionclone (const IExpression *expr) const =0
 Clones the given expression. More...
 
template<class T >
T * clone (const T *expr) const
 Clones the given expression. More...
 
virtual IExpression_listclone (const IExpression_list *expression_list) const =0
 Clones the given expression list. More...
 
virtual Sint32 compare (const IExpression *lhs, const IExpression *rhs, Uint32 flags=0, Float64 epsilon=0.0) const =0
 Compares two instances of mi::neuraylib::IExpression. More...
 
virtual Sint32 compare (const IExpression_list *lhs, const IExpression_list *rhs, Uint32 flags=0, Float64 epsilon=0.0) const =0
 Compares two instances of mi::neuraylib::IExpression_list. More...
 
virtual const IStringdump (const IExpression *expr, const char *name, Size depth=0) const =0
 Returns a textual representation of an expression. More...
 
virtual const IStringdump (const IExpression_list *list, const char *name, Size depth=0) const =0
 Returns a textual representation of an expression list. More...
 
virtual const IStringdump (const IAnnotation *annotation, const char *name, Size depth=0) const =0
 Returns a textual representation of an annotation. More...
 
virtual const IStringdump (const IAnnotation_block *block, const char *name, Size depth=0) const =0
 Returns a textual representation of an annotation block. More...
 
virtual const IStringdump (const IAnnotation_list *list, const char *name, Size depth=0) const =0
 Returns a textual representation of an annotation list. More...
 
virtual IExpressioncreate_cast (IExpression *src_expr, const IType *target_type, const char *cast_db_name, bool force_cast, Sint32 *errors=0) const =0
 Returns an expression which casts the source expression to the target_type. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from mi::base::Interface_declare< 0x9fd3b2d4, 0xb5b8, 0x4ccd, 0x9b, 0x5f, 0x7b, 0xd9, 0x9d, 0xeb, 0x62, 0x64 >
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

The interface for creating expressions.

An expression factory can be obtained from mi::neuraylib::IMdl_factory::create_expression_factory().

Member Enumeration Documentation

Various options for the comparison of expressions or expression lists.

See Also
The flags parameter of compare()
Enumerator
DEFAULT_COMPARISON_OPTIONS 

Default comparison options.

DEEP_CALL_COMPARISONS 

This option indicates that call expressions should be compared for equality, not for identity.

That is, the comparison is not done via mi::neuraylib::IExpression::get_value(), but by traversing into the referenced function call, i.e., comparing the function definition reference and the arguments. This option is useful if you want to decide whether an argument is semantically equal to the corresponding default parameter.

SKIP_TYPE_ALIASES 

This option indicates that all type aliases should be skipped before types of expression are compared.

Defaults and argument might sometimes differ in explicit type modifiers, therefore this option is useful if you want to decide whether an argument is semantically equal to the corresponding default parameter.

Member Function Documentation

virtual IExpression* mi::neuraylib::IExpression_factory::clone ( const IExpression expr) const
pure virtual

Clones the given expression.

Note that referenced DB elements, e.g., resources in constant expressions, or function calls and material instances in call expressions, are not copied, but shared. Function calls and material instances that serve as default arguments, are copied, though.

template<class T >
T* mi::neuraylib::IExpression_factory::clone ( const T *  expr) const
inline

Clones the given expression.

Note that referenced DB elements, e.g., resources in constant expressions, or function calls and material instances in call expressions, are not copied, but shared. Function calls and material instances that serve as default arguments, are copied, though.

virtual IExpression_list* mi::neuraylib::IExpression_factory::clone ( const IExpression_list expression_list) const
pure virtual

Clones the given expression list.

Note that referenced DB elements, e.g., resources in constant expressions, or function calls and material instances in call expressions, are not copied, but shared.

virtual Sint32 mi::neuraylib::IExpression_factory::compare ( const IExpression lhs,
const IExpression rhs,
Uint32  flags = 0,
Float64  epsilon = 0.0 
) const
pure virtual

Compares two instances of mi::neuraylib::IExpression.

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

  • If lhs or rhs is NULL, the result is the lexicographic comparison of the pointer addresses themselves.
  • Otherwise, the types of lhs and rhs are compared. If they are different, the result is determined by that comparison.
  • Next, the kind of the expressions are compared. If they are different, the result is determined by operator< on the mi::neuraylib::IExpression::Kind values. Note that setting SKIP_TYPE_ALIASES in flags modifies this behavior.
  • Finally, the expressions are compared as follows:
    • For constants the results is defined by comparing their values.
    • For calls, the result is defined by comparison of the call reference (unless DEEP_CALL_COMPARISONS is set in flags). Note that the representation of this call reference is an internal implementation detail, and the comparison result might have the opposite sign as strcmp() on the strings returned by mi::neuraylib::IExpression_call::get_call().
    • For parameter and temporary references, the results is defined by operator<() on the indices.
    • For indirect calls, first the definition reference is compared. Note that the representation of this definition reference is an internal implementation detail, and the comparison result might have the opposite sign as strcmp() on the strings returned by mi::neuraylib::IExpression_direct_call::get_definition(). If both indirect call reference the same definition, then the result is defined by comparison of the arguments.
Parameters
lhsThe left-hand side operand for the comparison.
rhsThe right-hand side operand for the comparison.
flagsA bitmask of flags of type Comparison_options.
epsilonMaximum difference for floating point values to consider them as equal.
Returns
-1 if lhs < rhs, 0 if lhs == rhs, and +1 if lhs > rhs.
virtual Sint32 mi::neuraylib::IExpression_factory::compare ( const IExpression_list lhs,
const IExpression_list rhs,
Uint32  flags = 0,
Float64  epsilon = 0.0 
) const
pure virtual

Compares two instances of mi::neuraylib::IExpression_list.

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

  • If lhs or rhs is NULL, the result is the lexicographic comparison of the pointer addresses themselves.
  • Next, the list sizes are compared using operator<().
  • Next, the lists are traversed by increasing index and the names are compared using strcmp().
  • Finally, the list elements are enumerated by increasing index and the expressions are compared.
Parameters
lhsThe left-hand side operand for the comparison.
rhsThe right-hand side operand for the comparison.
flagsA bitmask of flags of type Comparison_options.
epsilonMaximum difference for floating point values to consider them as equal.
Returns
-1 if lhs < rhs, 0 if lhs == rhs, and +1 if lhs > rhs.
virtual IAnnotation* mi::neuraylib::IExpression_factory::create_annotation ( const char *  name,
const IExpression_list arguments 
) const
pure virtual

Creates a new annotation.

Returns NULL if one of the arguments is not a constant expression.

virtual IAnnotation_block* mi::neuraylib::IExpression_factory::create_annotation_block ( ) const
pure virtual

Creates a new annotation block.

virtual IAnnotation_list* mi::neuraylib::IExpression_factory::create_annotation_list ( ) const
pure virtual

Creates a new annotation list.

virtual IExpression_call* mi::neuraylib::IExpression_factory::create_call ( const char *  name) const
pure virtual

Creates a call.

Parameters
nameThe DB name of the referenced function call or material instance.
Returns
The created call, or NULL in case of errors.
virtual IExpression* mi::neuraylib::IExpression_factory::create_cast ( IExpression src_expr,
const IType target_type,
const char *  cast_db_name,
bool  force_cast,
Sint32 errors = 0 
) const
pure virtual

Returns an expression which casts the source expression to the target_type.

This is a convenience function that creates an instance of the cast operator with the necessary arguments, stores it in the database and creates and returns an mi::neuraylib::IExpression_call using the just created function. If force_cast is set to true, the cast will always be inserted, even if the types match. If force_cast is set to false, the original expression is returned for identical types. If the type of src_expr and target_type are not compatible, NULL is returned.

Parameters
src_exprThe expression whose type is supposed to be casted.
target_typeThe result type of the cast. Note that the inserted cast operator acts on types without qualifiers, i.e., modifiers on target_type are ignored.
cast_db_nameThis name is used when storing the instance of the cast-operator function into the database. If the name is already taken by another DB element, this string will be used as the base for generating a unique name. If NULL, a unique name is generated.
force_castIf true, the cast will be created even if the types are identical. Please note that a cast cannot be forced for incompatible types.
errorsAn optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning:
  • 0: Success.
  • 1: Invalid parameters (NULL pointer).
  • 2: The type of src_expr cannot be cast to target_type.
Returns
The resulting expression or NULL in case of failure.
virtual IExpression_constant* mi::neuraylib::IExpression_factory::create_constant ( IValue value) const
pure virtual

Creates a constant (mutable).

Parameters
valueThe value of the constant.
Returns
The created constant, or NULL in case of errors.
virtual const IExpression_constant* mi::neuraylib::IExpression_factory::create_constant ( const IValue value) const
pure virtual

Creates a constant (const).

Parameters
valueThe value of the constant.
Returns
The created constant.
virtual IExpression_direct_call* mi::neuraylib::IExpression_factory::create_direct_call ( const char *  name,
IExpression_list arguments,
Sint32 errors = 0 
) const
pure virtual

Creates a direct call.

Parameters
nameThe DB name of the referenced function or material definition.
argumentsThe arguments of the created direct call.
Arguments for parameters without default are mandatory, otherwise optional. The type of an argument must match the corresponding parameter type. Any argument missing in arguments will be set to the default of the corresponding parameter.
Note that the expressions in arguments are copied. Valid subexpressions are constants, direct calls, and parameter references. operation is a deep copy, e.g., DB elements referenced in call expressions are also copied.
NULL is a valid argument which is handled like an empty expression list.
[out]errorsAn optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning:
  • 0: Success.
  • -1: An argument for a non-existing parameter was provided in arguments.
  • -2: The type of an argument in arguments does not have the correct type.
  • -3: A parameter that has no default was not provided with an argument value.
  • -4: The function or material definition can not be instantiated because it is not exported.
  • -5: A parameter type is uniform, but the corresponding argument has a varying return type.
  • -6: An argument expression is not a constant, a direct call, nor a parameter.
  • -7: Invalid parameters (NULL pointer) or name is not a valid DB name of a function or material definition.
  • -8: One of the parameter types is uniform, but the corresponding argument or default is a call expression and the return type of the called function or material definition is effectively varying since the function or material definition itself is varying.
  • -9: The function or material definition is invalid due to a module reload.
Returns
The created call, or NULL in case of errors.
virtual IExpression_list* mi::neuraylib::IExpression_factory::create_expression_list ( ) const
pure virtual

Creates a new expression list.

virtual IExpression_parameter* mi::neuraylib::IExpression_factory::create_parameter ( const IType type,
Size  index 
) const
pure virtual

Creates a parameter reference.

Parameters
typeThe type of the parameter.
indexThe index of the parameter.
Returns
The created parameter reference, or NULL in case of errors.
virtual const IString* mi::neuraylib::IExpression_factory::dump ( const IExpression expr,
const char *  name,
Size  depth = 0 
) const
pure virtual

Returns a textual representation of an expression.

The parameter depth is only relevant for constants, where the argument is passed to mi::neuraylib::IValue_factory::dump().

Note
The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.
virtual const IString* mi::neuraylib::IExpression_factory::dump ( const IExpression_list list,
const char *  name,
Size  depth = 0 
) const
pure virtual

Returns a textual representation of an expression list.

The representation of the expression list will contain line breaks. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note
The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.
virtual const IString* mi::neuraylib::IExpression_factory::dump ( const IAnnotation annotation,
const char *  name,
Size  depth = 0 
) const
pure virtual

Returns a textual representation of an annotation.

The representation of the annotation will contain line breaks. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note
The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.
virtual const IString* mi::neuraylib::IExpression_factory::dump ( const IAnnotation_block block,
const char *  name,
Size  depth = 0 
) const
pure virtual

Returns a textual representation of an annotation block.

The representation of the annotation block will contain line breaks. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note
The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.
virtual const IString* mi::neuraylib::IExpression_factory::dump ( const IAnnotation_list list,
const char *  name,
Size  depth = 0 
) const
pure virtual

Returns a textual representation of an annotation list.

The representation of the annotation list will contain line breaks. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note
The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.
virtual IValue_factory* mi::neuraylib::IExpression_factory::get_value_factory ( ) const
pure virtual

Returns the value factory associated with this expression factory.