omni::graph::exec::unstable::Topology

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

class Topology : public omni::graph::exec::unstable::Implements<ITopology>

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.

Public Functions

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.

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

See omni::core::IObject::cast.

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

See omni::graph::exec::unstable::IBase_abi::castWithoutAcquire_abi.

Public Static Functions

static inline omni::core::ObjectPtr<Topology> create(const carb::cpp::string_view &rootDebugName) noexcept

Creates a new topology.

The given name must not be nullptr.

This method always returns a valid object.

Protected Functions

inline uint64_t getMaxNodeIndex_abi() noexcept override

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 INode *getRoot_abi() noexcept override

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 Stamp getStamp_abi() noexcept override

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_abi() noexcept override

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 NodeIndexInTopology acquireNodeIndex_abi() noexcept override

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_abi(NodeIndexInTopology index) noexcept override

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 virtual void addInvalidationForwarder_abi(InvalidationForwarderId owner, IInvalidationForwarder *callback) noexcept override

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_abi(InvalidationForwarderId owner) noexcept override

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 SyncStamp getConstructionStamp_abi() noexcept override

Get construction version this topology is synchronized with.

Thread Safety

This method is thread safe.

inline void _setConstructionInSync_abi(Stamp toSync) noexcept override

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

Thread Safety

Calling this method concurrently is not recommended.

inline explicit Topology(const carb::cpp::string_view &rootDebugName) noexcept

Constructor.

inline virtual ~Topology() noexcept

Destructor.

inline void acquire_abi() noexcept override

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_abi() noexcept override

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.

inline uint32_t getUseCount_abi() noexcept override

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

inline void *cast_abi(omni::core::TypeId id) noexcept override

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 *castWithoutAcquire_abi(omni::core::TypeId id) noexcept override

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.

Protected Attributes

std::atomic<uint32_t> m_refCount

Reference count.