omni::graph::exec::unstable::ITopology

Defined in omni/graph/exec/unstable/ITopology.h

class ITopology : public omni::core::Generated<omni::graph::exec::unstable::ITopology_abi>

The Topology of a graph is stored in this class.

omni::graph::exec::unstable::ITopology is a helper interface used to quickly invalidate the topology, quickly determine if the topology has been invalidated, assign each node in the topology a unique index (suitable for access in contiguous memory), and provide access to the root node.

Topologies play a large role in graph invalidation. See Graph Invalidation for details.

To better understand how this object relates to other objects in the Execution Framework, see Graph Concepts .

See omni::graph::exec::unstable::Topology for a concrete implementation of this interface.

Subclassed by omni::graph::exec::unstable::ImplementsCastWithoutAcquire< ITopology, Rest… >

Public Functions

inline bool isValid() noexcept

Check if the topology is valid.

A topology is considered valid if the topology’s root node stamp is in-sync with the topology (this usually happens during graph construction).

See Graph Invalidation for details about how this method is used during invalidation.

Thread Safety

This method is thread safe.

template<typename Fn>
inline void addInvalidationForwarder(InvalidationForwarderId owner, Fn &&fn)

Add a callback allowing to forward invalidation to other graphs.

At a minimum, the top-level omni::graph::exec::unstable::IGraph will register a invalidation callback with all topologies created within a pass pipeline. This allows tracking invalidation and triggering minimal graph rebuild.

In the future, override passes can generate new graphs and still track authoring invalidation by registering to the original graph topologies invalidation.

If owner has a current forwarder, it will be replaced with the given forwarder.

See Graph Invalidation for details about how this method is used during invalidation.

See omni::graph::exec::unstable::ITopology::removeInvalidationForwarder().

The supplied function should have the signature of void(ITopology*).

Thread Safety

This method is not thread safe.

inline uint64_t getMaxNodeIndex() noexcept

Returns the maximum node index in the topology.

The returned value may be greater than the current number of nodes associated with the topology. This may happen if a node has been deleted. EF avoid reassigning node indices when a node is deleted, meaning it’s possible for “holes” to show up in the index list.

The returned value may be greater than the number of nodes that are reachable from the root node. This may happen if a node has no parent that is either the root node or a node that has a path to the root node.

A common use of this method is seen when allocating an array of data that will be indexed by each node’s topology index (see omni::core::exec::unstable::INode::getIndexInTopology()).

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::INode *getRoot() noexcept

Returns the topology’s root node that allows reaching all of the valid nodes in the topology.

The returned omni::graph::exec::unstable::INode will not have omni::core::IObject::acquire() called before being returned.

The returned pointer will remain valid for the lifetime of this object.

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::Stamp getStamp() noexcept

Returns the topology stamp. This stamp is updated each time the topology is invalidated.

See omni::graph::exec::unstable::ITopology::invalidate() to invalidate the topology (and thereby update this Stamp).

Thread Safety

This method is thread safe.

inline void invalidate() noexcept

Invalidate topology. All edges of the graph will be dropped (lazily), nodes remain valid and can be used to build new topology.

See Graph Invalidation for details about how this method is used during invalidation.

It is not recommended to call this method during graph execution. Rather, defer invalidation until after execution.

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::NodeIndexInTopology acquireNodeIndex() noexcept

Returns a unique index for a node in this topology.

Users should not call this method. Only the constructors of implementations of omni::graph::exec::unstable::INode should call this method.

See omni::graph::exec::unstable::ITopology::releaseNodeIndex().

Thread Safety

This method is not thread safe.

inline void releaseNodeIndex(omni::graph::exec::unstable::NodeIndexInTopology index) noexcept

Release unique index of a node in this topology. Shouldn’t be used by anything else than a node’s destructor.

See omni::graph::exec::unstable::ITopology::acquireNodeIndex().

Thread Safety

This method is not thread safe.

inline void addInvalidationForwarder(omni::graph::exec::unstable::InvalidationForwarderId owner, omni::core::ObjectParam<omni::graph::exec::unstable::IInvalidationForwarder> callback) noexcept

Add a callback to forward invalidation to other entities.

At a minimum, the top-level omni::graph::exec::unstable::IGraph will register a invalidation callback with all topologies created within a pass pipeline. This allows tracking invalidation and triggering minimal graph rebuild.

In the future, override passes can generate new graphs and still track authoring invalidation by registering to the original graph topologies invalidation.

The given omni::graph::exec::unstable::IInvalidationForwarder will be stored and have omni::core::IObject::acquire() called.

If owner has a current forwarder, it will be replaced with the given forwarder.

The given callback must not be nullptr.

See Graph Invalidation for details about how this method is used during invalidation.

See omni::graph::exec::unstable::ITopology::removeInvalidationForwarder().

Thread Safety

This method is not thread safe.

inline void removeInvalidationForwarder(omni::graph::exec::unstable::InvalidationForwarderId owner) noexcept

Remove invalidation forwarding for a given owner.

If the given owner is not known, this method does nothing.

See omni::graph::exec::unstable::ITopology::addInvalidationForwarder().

Thread Safety

This method is not thread safe.

inline omni::graph::exec::unstable::SyncStamp getConstructionStamp() noexcept

Get construction version this topology is synchronized with.

Thread Safety

This method is thread safe.

inline void _setConstructionInSync(const omni::graph::exec::unstable::Stamp &toSync) noexcept

Private method only for IGraphBuilder, used to tag construction version.

Thread Safety

Calling this method concurrently is not recommended.

inline void *castWithoutAcquire(omni::core::TypeId id) noexcept

Casts this object to the type described the the given id.

Returns nullptr if the cast was not successful.

Unlike omni::core::IObject::cast(), this casting method does not call omni::core::IObject::acquire().

Thread Safety

This method is thread safe.

inline uint32_t getUseCount() noexcept

Returns the number of different instances (this included) referencing the current object.

Thread Safety

This method is thread safe.

inline void *cast(omni::core::TypeId id) noexcept

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety

This method is thread safe.

inline void acquire() noexcept

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.

inline void release() noexcept

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.

Protected Functions

virtual uint64_t getMaxNodeIndex_abi() noexcept = 0

Returns the maximum node index in the topology.

The returned value may be greater than the current number of nodes associated with the topology. This may happen if a node has been deleted. EF avoid reassigning node indices when a node is deleted, meaning it’s possible for “holes” to show up in the index list.

The returned value may be greater than the number of nodes that are reachable from the root node. This may happen if a node has no parent that is either the root node or a node that has a path to the root node.

A common use of this method is seen when allocating an array of data that will be indexed by each node’s topology index (see omni::core::exec::unstable::INode::getIndexInTopology()).

Thread Safety

This method is thread safe.

virtual INode *getRoot_abi() noexcept = 0

Returns the topology’s root node that allows reaching all of the valid nodes in the topology.

The returned omni::graph::exec::unstable::INode will not have omni::core::IObject::acquire() called before being returned.

The returned pointer will remain valid for the lifetime of this object.

Thread Safety

This method is thread safe.

virtual Stamp getStamp_abi() noexcept = 0

Returns the topology stamp. This stamp is updated each time the topology is invalidated.

See omni::graph::exec::unstable::ITopology::invalidate() to invalidate the topology (and thereby update this Stamp).

Thread Safety

This method is thread safe.

virtual void invalidate_abi() noexcept = 0

Invalidate topology. All edges of the graph will be dropped (lazily), nodes remain valid and can be used to build new topology.

See Graph Invalidation for details about how this method is used during invalidation.

It is not recommended to call this method during graph execution. Rather, defer invalidation until after execution.

Thread Safety

This method is thread safe.

virtual NodeIndexInTopology acquireNodeIndex_abi() noexcept = 0

Returns a unique index for a node in this topology.

Users should not call this method. Only the constructors of implementations of omni::graph::exec::unstable::INode should call this method.

See omni::graph::exec::unstable::ITopology::releaseNodeIndex().

Thread Safety

This method is not thread safe.

virtual void releaseNodeIndex_abi(NodeIndexInTopology index) noexcept = 0

Release unique index of a node in this topology. Shouldn’t be used by anything else than a node’s destructor.

See omni::graph::exec::unstable::ITopology::acquireNodeIndex().

Thread Safety

This method is not thread safe.

virtual void addInvalidationForwarder_abi(InvalidationForwarderId owner, IInvalidationForwarder *callback) noexcept = 0

Add a callback to forward invalidation to other entities.

At a minimum, the top-level omni::graph::exec::unstable::IGraph will register a invalidation callback with all topologies created within a pass pipeline. This allows tracking invalidation and triggering minimal graph rebuild.

In the future, override passes can generate new graphs and still track authoring invalidation by registering to the original graph topologies invalidation.

The given omni::graph::exec::unstable::IInvalidationForwarder will be stored and have omni::core::IObject::acquire() called.

If owner has a current forwarder, it will be replaced with the given forwarder.

The given callback must not be nullptr.

See Graph Invalidation for details about how this method is used during invalidation.

See omni::graph::exec::unstable::ITopology::removeInvalidationForwarder().

Thread Safety

This method is not thread safe.

virtual void removeInvalidationForwarder_abi(InvalidationForwarderId owner) noexcept = 0

Remove invalidation forwarding for a given owner.

If the given owner is not known, this method does nothing.

See omni::graph::exec::unstable::ITopology::addInvalidationForwarder().

Thread Safety

This method is not thread safe.

virtual SyncStamp getConstructionStamp_abi() noexcept = 0

Get construction version this topology is synchronized with.

Thread Safety

This method is thread safe.

virtual void _setConstructionInSync_abi(Stamp toSync) noexcept = 0

Private method only for IGraphBuilder, used to tag construction version.

Thread Safety

Calling this method concurrently is not recommended.

virtual void *castWithoutAcquire_abi(omni::core::TypeId id) noexcept = 0

Casts this object to the type described the the given id.

Returns nullptr if the cast was not successful.

Unlike omni::core::IObject::cast(), this casting method does not call omni::core::IObject::acquire().

Thread Safety

This method is thread safe.

virtual uint32_t getUseCount_abi() noexcept = 0

Returns the number of different instances (this included) referencing the current object.

Thread Safety

This method is thread safe.

virtual void *cast_abi(TypeId id) noexcept = 0

Returns a pointer to the interface defined by the given type id if this object implements the type id’s interface.

Objects can support multiple interfaces, even interfaces that are in different inheritance chains.

The returned object will have omni::core::IObject::acquire() called on it before it is returned, meaning it is up to the caller to call omni::core::IObject::release() on the returned pointer.

The returned pointer can be safely reinterpret_cast<> to the type id’s C++ class. For example, “omni.windowing.IWindow” can be cast to omni::windowing::IWindow.

Do not directly use this method, rather use a wrapper function like omni::core::cast() or omni::core::ObjectPtr::as().

Thread Safety

This method is thread safe.

virtual void acquire_abi() noexcept = 0

Increments the object’s reference count.

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.

virtual void release_abi() noexcept = 0

Decrements the objects reference count.

Most implementations will destroy the object if the reference count reaches 0 (though this is not a requirement).

Objects may have multiple reference counts (e.g. one per interface implemented). As such, it is important that you call omni::core::IObject::release() on the same pointer from which you called omni::core::IObject::acquire().

Do not directly use this method, rather use omni::core::ObjectPtr, which will manage calling omni::core::IObject::acquire() and omni::core::IObject::release() for you.

Thread Safety

This method is thread safe.