Iray SDK API nvidia_logo_transpbg.gif Up
Interface Framework Technology

The classes provided here support conventional modern C++ library design principles for component software to achieve binary compatibility across shared library boundaries and future extensibility. More...

Classes

class  mi::base::Handle<Interface>
 Handle class template for interfaces, automatizing the lifetime control via reference counting. More...
 
class  mi::base::IInterface
 The basic extensible interface. More...
 
class  mi::base::Interface_declare< id1, ... >
 Mixin class template for deriving new interface declarations. More...
 
class  mi::base::Interface_implement<I>
 Mixin class template for deriving interface implementations. More...
 
class  mi::base::Interface_implement_2<I1, I2>
 Mixin class template for deriving interface implementations from two interfaces. More...
 
class  mi::base::Interface_implement_singleton<I>
 Mixin class template for deriving singleton interface implementations, where the reference count is fixed to one. More...
 
class  mi::base::Interface_merger<MAJOR, MINOR>
 This mixin merges the implementation of one interface with a second interface. More...
 
struct  mi::base::Uuid
 A 128 bit representation of a universally unique identifier (UUID or GUID). More...
 
class  mi::base::Uuid_t< id1, ... >
 Class template for a compile-time representation of universally unique identifiers (UUIDs or GUIDs). More...
 

Typedefs

typedef const Dup_interface_helper * mi::base::Dup_interface
 Type for a symbolic constant to trigger a special constructor in the Handle class. More...
 
typedef Handle<Interface> mi::base::Handle<Interface>::Self
 Own type. More...
 
typedef Interface mi::base::Handle<Interface>::Interface_type
 Type of the underlying interface. More...
 
typedef Interface mi::base::Handle<Interface>::value_type
 Type of the underlying interface. More...
 
typedef Difference mi::base::Handle<Interface>::difference_type
 Difference type (signed integral type to hold pointer differences). More...
 
typedef Interface * mi::base::Handle<Interface>::pointer
 Mutable-pointer type to underlying interface. More...
 
typedef Interface & mi::base::Handle<Interface>::reference
 Mutable-reference type to underlying interface. More...
 
typedef bool(Handle::* mi::base::Handle<Interface>::bool_conversion_support) () const
 Helper typedef. More...
 
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0> mi::base::IInterface::IID
 Declares the interface ID (IID) of this interface. More...
 
typedef Interface_declare< id1, ... > mi::base::Interface_declare< id1, ... >::Self
 Own type. More...
 
typedef Uuid_t< id1, ... > mi::base::Interface_declare< id1, ... >::IID
 Declares the interface ID (IID) of this interface. More...
 
typedef MAJOR mi::base::Interface_merger<MAJOR, MINOR>::MAJOR_BASE
 Typedef for the MAJOR base class. More...
 
typedef MINOR mi::base::Interface_merger<MAJOR, MINOR>::MINOR_BASE
 Typedef for the MINOR base class. More...
 
typedef Interface_merger<MAJOR, MINOR> mi::base::Interface_merger<MAJOR, MINOR>::Self
 Typedef for this type. More...
 

Functions

 mi::base::Handle<Interface>::Handle ()
 Default constructor, initializes handle to hold an invalid interface. More...
 
 mi::base::Handle<Interface>::Handle (Interface *ptr)
 Constructor from interface pointer, takes ownership of interface. More...
 
 mi::base::Handle<Interface>::Handle (Interface *ptr, Dup_interface)
 Constructor from interface pointer, does not take ownership of interface but duplicates it. More...
 
 mi::base::Handle<Interface>::Handle (const Self &other)
 Copy constructor, increments reference count if interface is valid. More...
 
template<class Interface2>
 mi::base::Handle<Interface>::Handle (const Handle<Interface2> &other)
 Copy constructor template which allows the construction from assignment compatible interface pointers, increments reference count if interface is valid. More...
 
 mi::base::Handle<Interface>::Handle (Self &&other) noexcept
 Move constructor. More...
 
template<class Interface2>
 mi::base::Handle<Interface>::Handle (Handle<Interface2> &&other) noexcept
 Converting move constructor. More...
 
void mi::base::Handle<Interface>::swap (Self &other)
 Swap two interfaces. More...
 
Selfmi::base::Handle<Interface>::operator= (const Self &other)
 Assignment operator, releases old interface and increments reference count of the new interface if interface is valid. More...
 
template<class Interface2>
Selfmi::base::Handle<Interface>::operator= (const Handle<Interface2> &other)
 Assignment operator template, releases old interface and increments reference count of the new interface if interface is valid. More...
 
Selfmi::base::Handle<Interface>::operator= (Self &&other) noexcept
 Move assignment operator, releases old interface. More...
 
template<class Interface2>
Selfmi::base::Handle<Interface>::operator= (Handle<Interface2> &&other) noexcept
 Converting move assignment operator, releases old interface. More...
 
Selfmi::base::Handle<Interface>::operator= (Interface *ptr)
 Assignment operator from interface pointer, releases old interface and assigns new interface ptr, takes ownership of interface. More...
 
void mi::base::Handle<Interface>::reset ()
 Releases the current interface, decrementing the reference count. More...
 
 mi::base::Handle<Interface>::~Handle ()
 Destructor, releases the interface if it is valid, which decrements the reference count, and triggers thus the deletion of the interface implementation once the reference count reaches zero. More...
 
bool mi::base::Handle<Interface>::is_valid_interface () const
 Returns true if the interface is valid. More...
 
Interface * mi::base::Handle<Interface>::get () const
 Access to the interface. Returns 0 for an invalid interface. More...
 
Interface * mi::base::Handle<Interface>::extract ()
 Extracts the interface and releases the handle. More...
 
Interface & mi::base::Handle<Interface>::operator* () const
 The dereference operator accesses the interface. More...
 
Interface * mi::base::Handle<Interface>::operator-> () const
 The arrow operator accesses the interface. More...
 
template<class New_interface>
Handle<New_interface> mi::base::Handle<Interface>::get_interface () const
 Returns a new handle for a possibly different interface type, similar to a dynamic cast, but not necessarily restricted to derived interfaces, but also for otherwise related interfaces. More...
 
 mi::base::Handle<Interface>::operator bool_conversion_support () const
 Helper function for the conversion of a Handle<Interface> to a bool. More...
 
template<class Interface1 , class Interface2>
bool mi::base::operator== (const Handle<Interface1> &lhs, const Handle<Interface2> &rhs)
 Returns true if the underlying interface pointers are equal. More...
 
template<class Interface1 , class Interface2>
bool mi::base::operator!= (const Handle<Interface1> &lhs, const Handle<Interface2> &rhs)
 Returns true if the underlying interface pointers are not equal. More...
 
template<class Interface>
Handle<Interface> mi::base::make_handle (Interface *iptr)
 Returns a handle that holds the interface pointer passed in as argument. More...
 
template<class Interface>
Handle<Interface> mi::base::make_handle_dup (Interface *iptr)
 Converts passed-in interface pointer to a handle, without taking interface over. More...
 
static bool mi::base::IInterface::compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface. More...
 
virtual Uint32 mi::base::IInterface::retain () const =0
 Increments the reference count. More...
 
virtual Uint32 mi::base::IInterface::release () const =0
 Decrements the reference count. More...
 
virtual const IInterfacemi::base::IInterface::get_interface (const Uuid &interface_id) const =0
 Acquires a const interface from another. More...
 
template<class T>
const T * mi::base::IInterface::get_interface () const
 Acquires a const interface from another. More...
 
virtual IInterfacemi::base::IInterface::get_interface (const Uuid &interface_id)=0
 Acquires a mutable interface from another. More...
 
template<class T>
T * mi::base::IInterface::get_interface ()
 Acquires a mutable interface from another. More...
 
virtual Uuid mi::base::IInterface::get_iid () const =0
 Returns the interface ID of the most derived interface. More...
 
static bool mi::base::Interface_declare< id1, ... >::compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 
 mi::base::Interface_implement<I>::Interface_implement (Uint32 initial=1)
 Constructor. More...
 
 mi::base::Interface_implement<I>::Interface_implement (const Interface_implement<I> &other)
 Copy constructor. More...
 
Interface_implement<I> & mi::base::Interface_implement<I>::operator= (const Interface_implement<I> &other)
 Assignment operator. More...
 
 mi::base::Interface_implement<I>::Interface_implement (Interface_implement &&other)
 Move constructor. More...
 
Interface_implementmi::base::Interface_implement<I>::operator= (Interface_implement &&other)
 Move assignment. More...
 
virtual Uint32 mi::base::Interface_implement<I>::retain () const
 Increments the reference count. More...
 
virtual Uint32 mi::base::Interface_implement<I>::release () const
 Decrements the reference count. More...
 
virtual const IInterfacemi::base::Interface_implement<I>::get_interface (const Uuid &interface_id) const
 Acquires a const interface. More...
 
virtual IInterfacemi::base::Interface_implement<I>::get_interface (const Uuid &interface_id)
 Acquires a mutable interface. More...
 
Uuid mi::base::Interface_implement<I>::get_iid () const
 Returns the interface ID of the most derived interface. More...
 
Atom32mi::base::Interface_implement<I>::refcount () const
 Get the current refcount. More...
 
 mi::base::Interface_implement_2<I1, I2>::Interface_implement_2 (Uint32 initial=1)
 Constructor. More...
 
 mi::base::Interface_implement_2<I1, I2>::Interface_implement_2 (const Interface_implement_2<I1, I2> &other)
 Copy constructor. More...
 
Interface_implement_2<I1, I2> & mi::base::Interface_implement_2<I1, I2>::operator= (const Interface_implement_2<I1, I2> &other)
 Assignment operator. More...
 
virtual Uint32 mi::base::Interface_implement_2<I1, I2>::retain () const
 Increments the reference count. More...
 
virtual Uint32 mi::base::Interface_implement_2<I1, I2>::release () const
 Decrements the reference count. More...
 
virtual const IInterfacemi::base::Interface_implement_2<I1, I2>::get_interface (const Uuid &interface_id) const
 Acquires a const interface. More...
 
virtual IInterfacemi::base::Interface_implement_2<I1, I2>::get_interface (const Uuid &interface_id)
 Acquires a mutable interface. More...
 
Uuid mi::base::Interface_implement_2<I1, I2>::get_iid () const
 Returns the interface ID of the most derived interface. More...
 
virtual Uint32 mi::base::Interface_implement_singleton<I>::retain () const
 Returns the fixed reference count of one. More...
 
virtual Uint32 mi::base::Interface_implement_singleton<I>::release () const
 Returns the fixed reference count of one. More...
 
virtual const IInterfacemi::base::Interface_implement_singleton<I>::get_interface (const Uuid &interface_id) const
 Acquires a const interface. More...
 
virtual IInterfacemi::base::Interface_implement_singleton<I>::get_interface (const Uuid &interface_id)
 Acquires a mutable interface. More...
 
Uuid mi::base::Interface_implement_singleton<I>::get_iid () const
 Returns the interface ID of the most derived interface. More...
 
static bool mi::base::Interface_merger<MAJOR, MINOR>::compare_iid (const Uuid &iid)
 Reimplements mi::base::IInterface::compare_iid(). More...
 
const IInterfacemi::base::Interface_merger<MAJOR, MINOR>::get_interface (const Uuid &interface_id) const
 Reimplements mi::base::IInterface::get_interface(const Uuid&) const. More...
 
template<class T>
const T * mi::base::Interface_merger<MAJOR, MINOR>::get_interface () const
 Reimplements mi::base::IInterface::get_interface() const. More...
 
IInterfacemi::base::Interface_merger<MAJOR, MINOR>::get_interface (const Uuid &interface_id)
 Reimplements mi::base::IInterface::get_interface(const Uuid&). More...
 
template<class T>
T * mi::base::Interface_merger<MAJOR, MINOR>::get_interface ()
 Reimplements mi::base::IInterface::get_interface(). More...
 
Uuid mi::base::Interface_merger<MAJOR, MINOR>::get_iid () const
 Reimplements mi::base::IInterface::get_iid(). More...
 
mi::Uint32 mi::base::Interface_merger<MAJOR, MINOR>::retain () const
 Reimplements mi::base::IInterface::retain(). More...
 
mi::Uint32 mi::base::Interface_merger<MAJOR, MINOR>::release () const
 Reimplements mi::base::IInterface::release(). More...
 
const MAJOR * mi::base::Interface_merger<MAJOR, MINOR>::cast_to_major () const
 Returns a pointer to the MAJOR base class. More...
 
MAJOR * mi::base::Interface_merger<MAJOR, MINOR>::cast_to_major ()
 Returns a pointer to the MAJOR base class. More...
 
bool mi::base::operator== (const Uuid &id1, const Uuid &id2)
 Returns true if id1 is equal to id2. More...
 
bool mi::base::operator!= (const Uuid &id1, const Uuid &id2)
 Returns true if id1 is not equal to id2. More...
 
bool mi::base::operator< (const Uuid &id1, const Uuid &id2)
 Returns true if id1 is less than id2. More...
 
bool mi::base::operator> (const Uuid &id1, const Uuid &id2)
 Returns true if id1 is greater than id2. More...
 
bool mi::base::operator<= (const Uuid &id1, const Uuid &id2)
 Returns true if id1 is less than or equal to id2. More...
 
bool mi::base::operator>= (const Uuid &id1, const Uuid &id2)
 Returns true if id1 is greater than or equal to id2. More...
 
Uint32 mi::base::uuid_hash32 (const Uuid &id)
 Returns a 32 bit hash value by performing a bitwise xor of all four 32 bit values. More...
 
 mi::base::Uuid_t< id1, ... >::operator const Uuid & () const
 Conversion operator. More...
 

Variables

static const Dup_interface mi::base::DUP_INTERFACE = 0
 Symbolic constant to trigger a special constructor in the Handle class. More...
 
Uint32 mi::base::Uuid::m_id1
 First value. More...
 
Uint32 mi::base::Uuid::m_id2
 Second value. More...
 
Uint32 mi::base::Uuid::m_id3
 Third value. More...
 
Uint32 mi::base::Uuid::m_id4
 Fourth value. More...
 
static const Uint32 mi::base::Uuid_t< id1, ... >::m_id1 = id1
 First 32 bit out of four. More...
 
static const Uint32 mi::base::Uuid_t< id1, ... >::m_id2 = static_cast<Uint32>( id2 | (id3 << 16))
 Second 32 bit out of four. More...
 
static const Uint32 mi::base::Uuid_t< id1, ... >::m_id3 = static_cast<Uint32>( id4 | (id5 << 8) | (id6 << 16) | (id7 << 24))
 Third 32 bit out of four. More...
 
static const Uint32 mi::base::Uuid_t< id1, ... >::m_id4 = static_cast<Uint32>( id8 | (id9 << 8) | (id10 << 16) | (id11 << 24))
 Fourth 32 bit out of four. More...
 
static const Uint32 mi::base::Uuid_t< id1, ... >::hash32 = m_id1 ^ m_id2 ^ m_id3 ^ m_id4
 A 32 bit hash value from a bitwise xor of all four 32 bit values. More...
 

Detailed Description

The classes provided here support conventional modern C++ library design principles for component software to achieve binary compatibility across shared library boundaries and future extensibility.

The design provides access through interfaces, which are abstract base classes with pure virtual member functions.

Interfaces derived from mi::base::IInterface refer to reference-counted dynamic resources that need to be released. To avoid manual reference counting, you can use the provided handle class mi::base::Handle, which is a smart-pointer implementation with automatic reference counting. You can also use other handle class implementations, e.g., std::tr1::shared_ptr<T> (or boost::shared_ptr<T>).

Typedef Documentation

 bool_conversion_support

template<class Interface>
typedef bool(Handle::* mi::base::Handle<Interface>::bool_conversion_support) () const

Helper typedef.

This typedef represent the type of is_valid_interface() used by the bool_conversion_support() operator.

 difference_type

template<class Interface>
typedef Difference mi::base::Handle<Interface>::difference_type

Difference type (signed integral type to hold pointer differences).

 Dup_interface

typedef const Dup_interface_helper* mi::base::Dup_interface

Type for a symbolic constant to trigger a special constructor in the Handle class.

See also
mi::base::Handle::Handle(Interface* ptr,Dup_interface)

 IID [1/2]

typedef Uuid_t<0,0,0,0,0,0,0,0,0,0,0> mi::base::IInterface::IID

Declares the interface ID (IID) of this interface.

A local type in each interface type, which is distinct and unique for each interface. The type has a default constructor and the constructed value represents the universally unique identifier (UUID) for this interface. The local type is readily convertible to a mi::base::Uuid.

 IID [2/2]

template<Uint32 id1, Uint16 id2, Uint16 id3, Uint8 id4, Uint8 id5, Uint8 id6, Uint8 id7, Uint8 id8, Uint8 id9, Uint8 id10, Uint8 id11, class I = IInterface>
typedef Uuid_t<id1,id2,id3,id4,id5,id6,id7,id8,id9,id10,id11> mi::base::Interface_declare< id1, ... >::IID

Declares the interface ID (IID) of this interface.

 Interface_type

template<class Interface>
typedef Interface mi::base::Handle<Interface>::Interface_type

Type of the underlying interface.

 MAJOR_BASE

template<typename MAJOR , typename MINOR>
typedef MAJOR mi::base::Interface_merger<MAJOR, MINOR>::MAJOR_BASE

Typedef for the MAJOR base class.

 MINOR_BASE

template<typename MAJOR , typename MINOR>
typedef MINOR mi::base::Interface_merger<MAJOR, MINOR>::MINOR_BASE

Typedef for the MINOR base class.

 pointer

template<class Interface>
typedef Interface* mi::base::Handle<Interface>::pointer

Mutable-pointer type to underlying interface.

 reference

template<class Interface>
typedef Interface& mi::base::Handle<Interface>::reference

Mutable-reference type to underlying interface.

 Self [1/3]

template<class Interface>
typedef Handle<Interface> mi::base::Handle<Interface>::Self

Own type.

 Self [2/3]

template<Uint32 id1, Uint16 id2, Uint16 id3, Uint8 id4, Uint8 id5, Uint8 id6, Uint8 id7, Uint8 id8, Uint8 id9, Uint8 id10, Uint8 id11, class I = IInterface>
typedef Interface_declare<id1,id2,id3,id4,id5,id6,id7,id8,id9,id10,id11,I> mi::base::Interface_declare< id1, ... >::Self

Own type.

 Self [3/3]

template<typename MAJOR , typename MINOR>
typedef Interface_merger<MAJOR,MINOR> mi::base::Interface_merger<MAJOR, MINOR>::Self

Typedef for this type.

 value_type

template<class Interface>
typedef Interface mi::base::Handle<Interface>::value_type

Type of the underlying interface.

Function Documentation

 cast_to_major() [1/2]

template<typename MAJOR , typename MINOR>
MAJOR * mi::base::Interface_merger<MAJOR, MINOR>::cast_to_major ( )
inline

Returns a pointer to the MAJOR base class.

Note that mi::base::IInterface is an ambiguous base class. Often you just need a pointer to mi::base::IInterface but do not really care to which base class it actually points to. This method is intended to be used in these cases. It returns the pointer to the MAJOR base class, which can then be statically casted to mi::base::IInterface (unless Interface_merger is nested).

Note
The name cast_to_major() of this method emphasizes that it behaves similar to a static cast, in particular, it does not increase the reference count.

 cast_to_major() [2/2]

template<typename MAJOR , typename MINOR>
const MAJOR * mi::base::Interface_merger<MAJOR, MINOR>::cast_to_major ( ) const
inline

Returns a pointer to the MAJOR base class.

Note that mi::base::IInterface is an ambiguous base class. Often you just need a pointer to mi::base::IInterface but do not really care to which base class it actually points to. This method is intended to be used in these cases. It returns the pointer to the MAJOR base class, which can then be statically casted to mi::base::IInterface (unless Interface_merger is nested).

Note
The name cast_to_major() of this method emphasizes that it behaves similar to a static cast, in particular, it does not increase the reference count.

 compare_iid() [1/3]

static bool mi::base::IInterface::compare_iid ( const Uuid iid)
inlinestatic

Compares the interface ID iid against the interface ID of this interface.

Returns
true if iid == mi::base::IInterface::IID(), and false otherwise.

 compare_iid() [2/3]

template<Uint32 id1, Uint16 id2, Uint16 id3, Uint8 id4, Uint8 id5, Uint8 id6, Uint8 id7, Uint8 id8, Uint8 id9, Uint8 id10, Uint8 id11, class I = IInterface>
static bool mi::base::Interface_declare< id1, ... >::compare_iid ( const Uuid iid)
inlinestatic

Compares the interface ID iid against the interface ID of this interface and of its ancestors.

Returns
true if iid == IID() or is equal to one of the interface IDs of its ancestors, and false otherwise.

 compare_iid() [3/3]

template<typename MAJOR , typename MINOR>
static bool mi::base::Interface_merger<MAJOR, MINOR>::compare_iid ( const Uuid iid)
inlinestatic

Reimplements mi::base::IInterface::compare_iid().

Forwards the call to the MAJOR base class, and then, in case of failure, to the MINOR base class.

 extract()

template<class Interface>
Interface * mi::base::Handle<Interface>::extract ( )
inline

Extracts the interface and releases the handle.

Returns 0 for an invalid interface.

Note that the owner takes responsible for managing the lifetime of the interface.

 get()

template<class Interface>
Interface * mi::base::Handle<Interface>::get ( ) const
inline

Access to the interface. Returns 0 for an invalid interface.

 get_iid() [1/5]

template<class I>
Uuid mi::base::Interface_implement<I>::get_iid ( ) const
inline

Returns the interface ID of the most derived interface.

 get_iid() [2/5]

template<class I1 , class I2>
Uuid mi::base::Interface_implement_2<I1, I2>::get_iid ( ) const
inline

Returns the interface ID of the most derived interface.

 get_iid() [3/5]

template<class I>
Uuid mi::base::Interface_implement_singleton<I>::get_iid ( ) const
inline

Returns the interface ID of the most derived interface.

 get_iid() [4/5]

template<typename MAJOR , typename MINOR>
Uuid mi::base::Interface_merger<MAJOR, MINOR>::get_iid ( ) const
inline

Reimplements mi::base::IInterface::get_iid().

Forwards the call to the MAJOR base class.

 get_iid() [5/5]

 get_interface() [1/15]

template<class T>
T * mi::base::IInterface::get_interface ( )
inline

Acquires a mutable interface from another.

If this interface supports the interface T, then the method returns a non-NULL pointer to the interface T. Otherwise, the method returns NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to apply static_cast to the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Template Parameters
TThe requested interface type.

 get_interface() [2/15]

template<typename MAJOR , typename MINOR>
template<class T>
T * mi::base::Interface_merger<MAJOR, MINOR>::get_interface ( )
inline

Reimplements mi::base::IInterface::get_interface().

The implementation is identical, but needed for visibility reasons.

 get_interface() [3/15]

template<class Interface>
template<class New_interface>
Handle<New_interface> mi::base::Handle<Interface>::get_interface ( ) const
inline

Returns a new handle for a possibly different interface type, similar to a dynamic cast, but not necessarily restricted to derived interfaces, but also for otherwise related interfaces.

Returns a handle with an invalid interface if the requested interface type is not supported by the underlying interface implementation or if this interface is itself already invalid.

 get_interface() [4/15]

template<class T>
const T * mi::base::IInterface::get_interface ( ) const
inline

Acquires a const interface from another.

If this interface supports the interface T, then the method returns a non-NULL const pointer to the interface T. Otherwise, the method returns NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to apply static_cast to the returned pointer, since the return type already is a const pointer to the type T specified as template parameter.

Template Parameters
TThe requested interface type.

 get_interface() [5/15]

template<typename MAJOR , typename MINOR>
template<class T>
const T * mi::base::Interface_merger<MAJOR, MINOR>::get_interface ( ) const
inline

Reimplements mi::base::IInterface::get_interface() const.

The implementation is identical, but needed for visibility reasons.

 get_interface() [6/15]

template<class I>
virtual IInterface * mi::base::Interface_implement<I>::get_interface ( const Uuid interface_id)
inlinevirtual

Acquires a mutable interface.

If this interface is derived from or is the interface with the passed interface_id, then return a non-NULL mi::base::IInterface* that can be casted via static_cast to an interface pointer of the interface type corresponding to the passed interface_id. Otherwise return NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

Reimplemented in mi::bridge::Client_job<i_id1, i_id2, i_id3, i_id4, i_id5, i_id6, i_id7, i_id8, i_id9, i_id10, i_id11, I>, mi::bridge::Client_job< 0xf9b3c8e2, ... >, and mi::bridge::Server_job<i_id1, i_id2, i_id3, i_id4, i_id5, i_id6, i_id7, i_id8, i_id9, i_id10, i_id11, I>.

 get_interface() [7/15]

template<class I1 , class I2>
virtual IInterface * mi::base::Interface_implement_2<I1, I2>::get_interface ( const Uuid interface_id)
inlinevirtual

Acquires a mutable interface.

If this interface is derived from or is the interface with the passed interface_id, then return a non-NULL mi::base::IInterface* that can be casted via static_cast to an interface pointer of the interface type corresponding to the passed interface_id. Otherwise return NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

 get_interface() [8/15]

template<class I>
virtual IInterface * mi::base::Interface_implement_singleton<I>::get_interface ( const Uuid interface_id)
inlinevirtual

Acquires a mutable interface.

If this interface is derived from or is the interface with the passed interface_id, then return a non-NULL mi::base::IInterface* that can be casted via static_cast to an interface pointer of the interface type corresponding to the passed interface_id. Otherwise return NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

 get_interface() [9/15]

template<typename MAJOR , typename MINOR>
IInterface * mi::base::Interface_merger<MAJOR, MINOR>::get_interface ( const Uuid interface_id)

Reimplements mi::base::IInterface::get_interface(const Uuid&).

Forwards the call to the MAJOR base class, and then, in case of failure, to the MINOR base class.

 get_interface() [10/15]

template<class I>
virtual const IInterface * mi::base::Interface_implement<I>::get_interface ( const Uuid interface_id) const
inlinevirtual

Acquires a const interface.

If this interface is derived from or is the interface with the passed interface_id, then return a non-NULL const mi::base::IInterface* that can be casted via static_cast to an interface pointer of the interface type corresponding to the passed interface_id. Otherwise return NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

Reimplemented in mi::bridge::Client_job<i_id1, i_id2, i_id3, i_id4, i_id5, i_id6, i_id7, i_id8, i_id9, i_id10, i_id11, I>, mi::bridge::Client_job< 0xf9b3c8e2, ... >, and mi::bridge::Server_job<i_id1, i_id2, i_id3, i_id4, i_id5, i_id6, i_id7, i_id8, i_id9, i_id10, i_id11, I>.

 get_interface() [11/15]

template<class I1 , class I2>
virtual const IInterface * mi::base::Interface_implement_2<I1, I2>::get_interface ( const Uuid interface_id) const
inlinevirtual

Acquires a const interface.

If this interface is derived from or is the interface with the passed interface_id, then return a non-NULL const mi::base::IInterface* that can be casted via static_cast to an interface pointer of the interface type corresponding to the passed interface_id. Otherwise return NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

 get_interface() [12/15]

template<class I>
virtual const IInterface * mi::base::Interface_implement_singleton<I>::get_interface ( const Uuid interface_id) const
inlinevirtual

Acquires a const interface.

If this interface is derived from or is the interface with the passed interface_id, then return a non-NULL const mi::base::IInterface* that can be casted via static_cast to an interface pointer of the interface type corresponding to the passed interface_id. Otherwise return NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

 get_interface() [13/15]

template<typename MAJOR , typename MINOR>
const IInterface * mi::base::Interface_merger<MAJOR, MINOR>::get_interface ( const Uuid interface_id) const

Reimplements mi::base::IInterface::get_interface(const Uuid&) const.

Forwards the call to the MAJOR base class, and then, in case of failure, to the MINOR base class.

 get_interface() [14/15]

virtual const IInterface * mi::base::IInterface::get_interface ( const Uuid interface_id) const
pure virtual

Acquires a const interface from another.

If this interface supports the interface with the passed interface_id, then the method returns a non-NULL const mi::base::IInterface* that can be casted via static_cast to an interface pointer of the interface type corresponding to the passed interface_id. Otherwise, the method returns NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

Parameters
interface_idInterface ID of the interface to acquire.

Implemented in mi::base::Interface_implement< neuraylib::IBsdf_buffer >, mi::base::Interface_implement< neuraylib::IBsdf_isotropic_data >, mi::base::Interface_implement< neuraylib::ITimer_class_factory >, mi::base::Interface_implement< neuraylib::IUser_class_factory >, and mi::base::Interface_implement_singleton<IAllocator>.

 get_interface() [15/15]

virtual IInterface * mi::base::IInterface::get_interface ( const Uuid interface_id)
pure virtual

Acquires a mutable interface from another.

If this interface supports the interface with the passed interface_id, then the methods returns a non-NULL mi::base::IInterface* that can be casted via static_cast to an interface pointer of the interface type corresponding to the passed interface_id. Otherwise, the method returns NULL.

In the case of a non-NULL return value, the caller receives ownership of the new interface pointer, whose reference count has been retained once. The caller must release the returned interface pointer at the end to prevent a memory leak.

Parameters
interface_idInterface ID of the interface to acquire.

Implemented in mi::base::Interface_implement< neuraylib::IBsdf_buffer >, mi::base::Interface_implement< neuraylib::IBsdf_isotropic_data >, mi::base::Interface_implement< neuraylib::ITimer_class_factory >, mi::base::Interface_implement< neuraylib::IUser_class_factory >, and mi::base::Interface_implement_singleton<IAllocator>.

 Handle() [1/7]

template<class Interface>
mi::base::Handle<Interface>::Handle ( )
inline

Default constructor, initializes handle to hold an invalid interface.

 Handle() [2/7]

template<class Interface>
template<class Interface2>
mi::base::Handle<Interface>::Handle ( const Handle<Interface2> &  other)
inline

Copy constructor template which allows the construction from assignment compatible interface pointers, increments reference count if interface is valid.

This constructor allows specifically the construction of a Handle<const I> from a Handle<I> value, which corresponds to the assignment of a mutable pointer to a const pointer. In addition, promotion of derived interfaces to base interfaces is allowed.

 Handle() [3/7]

template<class Interface>
mi::base::Handle<Interface>::Handle ( const Self other)
inline

Copy constructor, increments reference count if interface is valid.

 Handle() [4/7]

template<class Interface>
template<class Interface2>
mi::base::Handle<Interface>::Handle ( Handle<Interface2> &&  other)
inlinenoexcept

Converting move constructor.

 Handle() [5/7]

template<class Interface>
mi::base::Handle<Interface>::Handle ( Interface *  ptr)
inlineexplicit

Constructor from interface pointer, takes ownership of interface.

The constructor does not increment the reference count of ptr assuming it is already set properly, e.g., by a corresponding get_interface() call. It therefore takes over the ownership of the interface pointer.

 Handle() [6/7]

template<class Interface>
mi::base::Handle<Interface>::Handle ( Interface *  ptr,
Dup_interface   
)
inline

Constructor from interface pointer, does not take ownership of interface but duplicates it.

The constructor increments the reference count of ptr so that it does not influence the interface when it decrements the reference count later on. You can use this constructor for example to hold interfaces that are passed into functions as parameters because by convention they are owned by the function caller. You can pass the constant DUP_INTERFACE as the second argument.

 Handle() [7/7]

template<class Interface>
mi::base::Handle<Interface>::Handle ( Self &&  other)
inlinenoexcept

Move constructor.

 Interface_implement() [1/3]

template<class I>
mi::base::Interface_implement<I>::Interface_implement ( const Interface_implement<I> &  other)
inline

Copy constructor.

Initializes the reference count to 1.

 Interface_implement() [2/3]

template<class I>
mi::base::Interface_implement<I>::Interface_implement ( Interface_implement<I> &&  other)
inline

Move constructor.

 Interface_implement() [3/3]

template<class I>
mi::base::Interface_implement<I>::Interface_implement ( Uint32  initial = 1)
inline

Constructor.

Parameters
initialThe initial reference count (defaults to 1).

 Interface_implement_2() [1/2]

template<class I1 , class I2>
mi::base::Interface_implement_2<I1, I2>::Interface_implement_2 ( const Interface_implement_2<I1, I2> &  other)
inline

Copy constructor.

Initializes the reference count to 1.

 Interface_implement_2() [2/2]

template<class I1 , class I2>
mi::base::Interface_implement_2<I1, I2>::Interface_implement_2 ( Uint32  initial = 1)
inline

Constructor.

Parameters
initialThe initial reference count (defaults to 1).

 is_valid_interface()

template<class Interface>
bool mi::base::Handle<Interface>::is_valid_interface ( ) const
inline

Returns true if the interface is valid.

 make_handle()

template<class Interface>
Handle<Interface> mi::base::make_handle ( Interface *  iptr)
inline

Returns a handle that holds the interface pointer passed in as argument.

This helper function template simplifies the creation of handles with an interface type that matches the type of the interface argument. In contrast to make_handle_dup(), the handle takes ownership of the interface.

 make_handle_dup()

template<class Interface>
Handle<Interface> mi::base::make_handle_dup ( Interface *  iptr)
inline

Converts passed-in interface pointer to a handle, without taking interface over.

This helper function template simplifies the creation of handles with an interface type that matches the type of the interface argument. In contrast to make_handle(), the handle does not take ownership of the interface.

 operator bool_conversion_support()

template<class Interface>
mi::base::Handle<Interface>::operator bool_conversion_support ( ) const
inline

Helper function for the conversion of a Handle<Interface> to a bool.

This helper function allows to write

Handle<T> h(...);
if( h) ...
Handle class template for interfaces, automatizing the lifetime control via reference counting.
Definition: handle.h:113

instead of

Handle<T> h(...);
if( h.is_valid_interface()) ...

 operator const Uuid &()

template<Uint32 id1, Uint16 id2, Uint16 id3, Uint8 id4, Uint8 id5, Uint8 id6, Uint8 id7, Uint8 id8, Uint8 id9, Uint8 id10, Uint8 id11>
mi::base::Uuid_t< id1, ... >::operator const Uuid & ( ) const
inline

Conversion operator.

The conversion to mi::base::Uuid initializes the UUID to (m_id1, m_id2, m_id3, m_id4).

 operator!=() [1/2]

template<class Interface1 , class Interface2>
bool mi::base::operator!= ( const Handle<Interface1> &  lhs,
const Handle<Interface2> &  rhs 
)
inline

Returns true if the underlying interface pointers are not equal.

 operator!=() [2/2]

bool mi::base::operator!= ( const Uuid id1,
const Uuid id2 
)
inline

Returns true if id1 is not equal to id2.

 operator*()

template<class Interface>
Interface & mi::base::Handle<Interface>::operator* ( ) const
inline

The dereference operator accesses the interface.

Precondition
is_valid_interface().

 operator->()

template<class Interface>
Interface * mi::base::Handle<Interface>::operator-> ( ) const
inline

The arrow operator accesses the interface.

Precondition
is_valid_interface().

 operator<()

bool mi::base::operator< ( const Uuid id1,
const Uuid id2 
)
inline

Returns true if id1 is less than id2.

 operator<=()

bool mi::base::operator<= ( const Uuid id1,
const Uuid id2 
)
inline

Returns true if id1 is less than or equal to id2.

 operator=() [1/8]

template<class Interface>
template<class Interface2>
Self & mi::base::Handle<Interface>::operator= ( const Handle<Interface2> &  other)
inline

Assignment operator template, releases old interface and increments reference count of the new interface if interface is valid.

This assignment operator allows specifically the assignment of a Handle<I> to a Handle<const I> value, which corresponds to the assignment of a mutable pointer to a const pointer. In addition, promotion of derived interfaces to base interfaces is allowed.

 operator=() [2/8]

template<class I>
Interface_implement<I> & mi::base::Interface_implement<I>::operator= ( const Interface_implement<I> &  other)
inline

Assignment operator.

The reference count of *this and other remain unchanged.

 operator=() [3/8]

template<class I1 , class I2>
Interface_implement_2<I1, I2> & mi::base::Interface_implement_2<I1, I2>::operator= ( const Interface_implement_2<I1, I2> &  other)
inline

Assignment operator.

The reference count of *this and other remain unchanged.

 operator=() [4/8]

template<class Interface>
Self & mi::base::Handle<Interface>::operator= ( const Self other)
inline

Assignment operator, releases old interface and increments reference count of the new interface if interface is valid.

 operator=() [5/8]

template<class Interface>
template<class Interface2>
Self & mi::base::Handle<Interface>::operator= ( Handle<Interface2> &&  other)
inlinenoexcept

Converting move assignment operator, releases old interface.

 operator=() [6/8]

template<class Interface>
Self & mi::base::Handle<Interface>::operator= ( Interface *  ptr)
inline

Assignment operator from interface pointer, releases old interface and assigns new interface ptr, takes ownership of interface.

Does not increment reference count of ptr assuming it is already set properly, e.g., by a corresponding get_interface() call.

 operator=() [7/8]

template<class I>
Interface_implement & mi::base::Interface_implement<I>::operator= ( Interface_implement<I> &&  other)
inline

Move assignment.

 operator=() [8/8]

template<class Interface>
Self & mi::base::Handle<Interface>::operator= ( Self &&  other)
inlinenoexcept

Move assignment operator, releases old interface.

 operator==() [1/2]

template<class Interface1 , class Interface2>
bool mi::base::operator== ( const Handle<Interface1> &  lhs,
const Handle<Interface2> &  rhs 
)
inline

Returns true if the underlying interface pointers are equal.

 operator==() [2/2]

bool mi::base::operator== ( const Uuid id1,
const Uuid id2 
)
inline

Returns true if id1 is equal to id2.

 operator>()

bool mi::base::operator> ( const Uuid id1,
const Uuid id2 
)
inline

Returns true if id1 is greater than id2.

 operator>=()

bool mi::base::operator>= ( const Uuid id1,
const Uuid id2 
)
inline

Returns true if id1 is greater than or equal to id2.

 refcount()

template<class I>
Atom32 & mi::base::Interface_implement<I>::refcount ( ) const
inlineprotected

Get the current refcount.

 release() [1/5]

template<class I>
virtual Uint32 mi::base::Interface_implement<I>::release ( ) const
inlinevirtual

Decrements the reference count.

Decrements the reference count of the object referenced through this interface and returns the new reference count. If the reference count dropped to zero, the object will be deleted. The operation is thread-safe.

Reimplemented in mi::neuraylib::User_class< id1, ... >.

 release() [2/5]

template<class I1 , class I2>
virtual Uint32 mi::base::Interface_implement_2<I1, I2>::release ( ) const
inlinevirtual

Decrements the reference count.

Decrements the reference count of the object referenced through this interface and returns the new reference count. If the reference count dropped to zero, the object will be deleted. The operation is thread-safe.

 release() [3/5]

template<class I>
virtual Uint32 mi::base::Interface_implement_singleton<I>::release ( ) const
inlinevirtual

Returns the fixed reference count of one.

Implements mi::base::IInterface::release() with a constant reference count of one. The object will never be deleted through a release call.

 release() [4/5]

template<typename MAJOR , typename MINOR>
mi::Uint32 mi::base::Interface_merger<MAJOR, MINOR>::release ( ) const
inline

Reimplements mi::base::IInterface::release().

Forwards the call to the MAJOR base class.

 release() [5/5]

virtual Uint32 mi::base::IInterface::release ( ) const
pure virtual

Decrements the reference count.

Decrements the reference count of the object referenced through this interface and returns the new reference count. If the reference count dropped to zero, the object will be deleted. The operation is thread-safe.

Returns
The new, decremented reference count.

Implemented in mi::base::Interface_implement< neuraylib::IBsdf_buffer >, mi::base::Interface_implement< neuraylib::IBsdf_isotropic_data >, mi::base::Interface_implement< neuraylib::ITimer_class_factory >, mi::base::Interface_implement< neuraylib::IUser_class_factory >, and mi::base::Interface_implement_singleton<IAllocator>.

 reset()

template<class Interface>
void mi::base::Handle<Interface>::reset ( )
inline

Releases the current interface, decrementing the reference count.

 retain() [1/5]

template<class I>
virtual Uint32 mi::base::Interface_implement<I>::retain ( ) const
inlinevirtual

Increments the reference count.

Increments the reference count of the object referenced through this interface and returns the new reference count. The operation is thread-safe.

 retain() [2/5]

template<class I1 , class I2>
virtual Uint32 mi::base::Interface_implement_2<I1, I2>::retain ( ) const
inlinevirtual

Increments the reference count.

Increments the reference count of the object referenced through this interface and returns the new reference count. The operation is thread-safe.

 retain() [3/5]

template<class I>
virtual Uint32 mi::base::Interface_implement_singleton<I>::retain ( ) const
inlinevirtual

Returns the fixed reference count of one.

Implements mi::base::IInterface::retain() with a constant reference count of one.

 retain() [4/5]

template<typename MAJOR , typename MINOR>
mi::Uint32 mi::base::Interface_merger<MAJOR, MINOR>::retain ( ) const
inline

Reimplements mi::base::IInterface::retain().

Forwards the call to the MAJOR base class.

 retain() [5/5]

virtual Uint32 mi::base::IInterface::retain ( ) const
pure virtual

Increments the reference count.

Increments the reference count of the object referenced through this interface and returns the new reference count. The operation is thread-safe.

Returns
The new, incremented reference count.

Implemented in mi::base::Interface_implement< neuraylib::IBsdf_buffer >, mi::base::Interface_implement< neuraylib::IBsdf_isotropic_data >, mi::base::Interface_implement< neuraylib::ITimer_class_factory >, mi::base::Interface_implement< neuraylib::IUser_class_factory >, and mi::base::Interface_implement_singleton<IAllocator>.

 swap()

template<class Interface>
void mi::base::Handle<Interface>::swap ( Self other)
inline

Swap two interfaces.

 uuid_hash32()

Uint32 mi::base::uuid_hash32 ( const Uuid id)
inline

Returns a 32 bit hash value by performing a bitwise xor of all four 32 bit values.

 ~Handle()

template<class Interface>
mi::base::Handle<Interface>::~Handle ( )
inline

Destructor, releases the interface if it is valid, which decrements the reference count, and triggers thus the deletion of the interface implementation once the reference count reaches zero.

Variable Documentation

 DUP_INTERFACE

const Dup_interface mi::base::DUP_INTERFACE = 0
static

Symbolic constant to trigger a special constructor in the Handle class.

See also
mi::base::Handle::Handle(Interface* ptr,Dup_interface)

 hash32

template<Uint32 id1, Uint16 id2, Uint16 id3, Uint8 id4, Uint8 id5, Uint8 id6, Uint8 id7, Uint8 id8, Uint8 id9, Uint8 id10, Uint8 id11>
const Uint32 mi::base::Uuid_t< id1, ... >::hash32 = m_id1 ^ m_id2 ^ m_id3 ^ m_id4
static

A 32 bit hash value from a bitwise xor of all four 32 bit values.

 m_id1 [1/2]

Uint32 mi::base::Uuid::m_id1

First value.

 m_id1 [2/2]

template<Uint32 id1, Uint16 id2, Uint16 id3, Uint8 id4, Uint8 id5, Uint8 id6, Uint8 id7, Uint8 id8, Uint8 id9, Uint8 id10, Uint8 id11>
const Uint32 mi::base::Uuid_t< id1, ... >::m_id1 = id1
static

First 32 bit out of four.

 m_id2 [1/2]

Uint32 mi::base::Uuid::m_id2

Second value.

 m_id2 [2/2]

template<Uint32 id1, Uint16 id2, Uint16 id3, Uint8 id4, Uint8 id5, Uint8 id6, Uint8 id7, Uint8 id8, Uint8 id9, Uint8 id10, Uint8 id11>
const Uint32 mi::base::Uuid_t< id1, ... >::m_id2 = static_cast<Uint32>( id2 | (id3 << 16))
static

Second 32 bit out of four.

 m_id3 [1/2]

Uint32 mi::base::Uuid::m_id3

Third value.

 m_id3 [2/2]

template<Uint32 id1, Uint16 id2, Uint16 id3, Uint8 id4, Uint8 id5, Uint8 id6, Uint8 id7, Uint8 id8, Uint8 id9, Uint8 id10, Uint8 id11>
const Uint32 mi::base::Uuid_t< id1, ... >::m_id3 = static_cast<Uint32>( id4 | (id5 << 8) | (id6 << 16) | (id7 << 24))
static

Third 32 bit out of four.

 m_id4 [1/2]

Uint32 mi::base::Uuid::m_id4

Fourth value.

 m_id4 [2/2]

template<Uint32 id1, Uint16 id2, Uint16 id3, Uint8 id4, Uint8 id5, Uint8 id6, Uint8 id7, Uint8 id8, Uint8 id9, Uint8 id10, Uint8 id11>
const Uint32 mi::base::Uuid_t< id1, ... >::m_id4 = static_cast<Uint32>( id8 | (id9 << 8) | (id10 << 16) | (id11 << 24))
static

Fourth 32 bit out of four.