omni::graph::exec::unstable::NodeT
Defined in omni/graph/exec/unstable/Node.h
-
template<typename ...Bases>
class NodeT : public omni::graph::exec::unstable::Implements<Bases...> Concrete implementation of omni::graph::exec::unstable::INode.
This template is a concrete implementation of omni::graph::exec::unstable::INode. In most cases, instantiating omni::graph::exec::unstable::Node (which is instance of this template) will suffice.
See omni::graph::exec::unstable::INode for documentation on the purpose of nodes in the Execution Framework.
This class can be seen as a way to provide a reasonable, default implementation of both omni::graph::exec::unstable::INode and omni::graph::exec::unstable::IGraphBuilderNode. The template arguments allow the developer to further customize the interfaces this class implements. A common pattern seen in the Execution Framework is to define a private interface to attach authoring data to a node. See Private Interfaces for details.
During graph construction, authoring data can be stored in omni::graph::exec::unstable::NodeT. When storing data in omni::graph::exec::unstable::NodeT, the user must be mindful that a node may be a part of a definition that is shared.
Storing authoring data in omni::graph::exec::unstable::NodeGraphDefT during graph construction is another way to link authoring data and the Execution Framework. Again, the user must be mindful that definitions can be shared across multiple nodes in the execution graph.
omni::graph::exec::unstable::IExecutionContext is another place to store data. Rather than storing authoring data, omni::graph::exec::unstable::IExecutionContext is designed to store execution/evaluation data keyed on each node’s unique omni::graph::exec::unstable::ExecutionPath. Since definitions can be shared between nodes, each node’s omni::graph::exec::unstable::ExecutionPath is necessary to uniquely identify the “instance” of any given node.
Public Functions
-
inline virtual ~NodeT()
Destructor.
-
inline bool hasChild(omni::core::ObjectParam<INode> child) noexcept
Check if a given node is a child of this node.
The given node may be
nullptr
.- Thread Safety
This method makes no guarantees on thread safety. However, in practice, accessing the children during execution is safe as the list of children is not expected to change during execution. Accessing the children during graph construction requires coordination with the passes building the graph.
-
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 *castWithoutAcquire(omni::core::TypeId id) noexcept
See omni::graph::exec::unstable::IBase_abi::castWithoutAcquire_abi.
Public Static Functions
-
template<typename T>
static inline omni::core::ObjectPtr<NodeT> create(T &&graphOrTopology, const carb::cpp::string_view &idName) Constructor of a node with an empty definition.
The given graph or topology must not be
nullptr
.The given name must not be
nullptr
.A valid pointer is always returned.
-
template<typename T, typename D>
static inline omni::core::ObjectPtr<NodeT> create(T &&graphOrTopology, D &&def, const carb::cpp::string_view &idName) Constructor of a node with a definition (can be a base definition
IDef
, an opaque node definitionINodeDef
, or a node graph definitionINodeGraphDef
).The given graph or topology must not be
nullptr
.The given name must not be
nullptr
.A valid pointer is always returned.
Protected Functions
-
inline ITopology *getTopology_abi() noexcept override
Access topology owning this node.
The returned pointer will not be
nullptr
.The returned omni::graph::exec::unstable::ITopology will not have omni::core::IObject::acquire() called before being returned.
- Thread Safety
This method is thread safe.
-
inline const ConstName *getName_abi() noexcept override
Access node’s unique identifier name.
The lifetime of the returned object is tied to this node.
- Thread Safety
This method is thread safe.
-
inline NodeIndexInTopology getIndexInTopology_abi() noexcept override
Access nodes unique index withing owning topology. Index will be always smaller than topology size.
- Thread Safety
This method is thread safe.
-
inline Span<INode*const> getParents_abi() noexcept override
Access parents.
The returned omni::graph::exec::unstable::INode objects will not have omni::core::IObject::acquire() called before being returned.
- Thread Safety
This method makes no guarantees on thread safety. However, in practice, accessing the parents during execution is safe as the list of parents is not expected to change during execution. Accessing the parents during graph construction requires coordination with the passes building the graph.
-
inline Span<INode*const> getChildren_abi() noexcept override
Access children.
The returned omni::graph::exec::unstable::INode objects will not have omni::core::IObject::acquire() called before being returned.
- Thread Safety
This method makes no guarantees on thread safety. However, in practice, accessing the children during execution is safe as the list of children is not expected to change during execution. Accessing the children during graph construction requires coordination with the passes building the graph.
-
inline uint32_t getCycleParentCount_abi() noexcept override
Return number of parents that cause cycles within the graph during traversal over this node.
- Thread Safety
This method makes no guarantees on thread safety. However, in practice, accessing this count during execution is safe as the cycle count is expected to be computed during graph construction. Accessing the count during graph construction requires coordination with the passes building the graph.
-
inline bool isValidTopology_abi() noexcept final override
Check if topology/connectivity of nodes is valid within current topology version.
See Graph Invalidation for details on invalidation.
- Thread Safety
This method is not thread safe.
Note
This method is called in the destructor and therefore must be marked as final
-
inline virtual void validateOrResetTopology_abi() noexcept
Check if this node is valid in the topology, dropping all connections if it is not.
This method checks if the node is valid in the topology (i.e. checks the node’s topology stamp with the topology). If it is not valid, all parent and child connections are removed and the cycle count is set back to zero.
If the node is valid in the topology, this method does nothing.
See Graph Invalidation to better understand stamps, topologies, and invalidation.
- Thread Safety
This method is not thread safe.
-
inline IDef *getDef_abi() noexcept override
Access the node’s definition (can be empty).
When you wish to determine if the attached definition is either opaque or a graph, consider calling omni::graph::exec::unstable::INode::getNodeDef() or omni::graph::exec::unstable::INode::getNodeGraphDef() rather than this method.
The returned omni::graph::exec::unstable::IDef will not have omni::core::IObject::acquire() called before being returned.
- Thread Safety
This method is thread safe during execution since the definition is not expected to change during execution. During construction, access to this method must be coordinated between the passes building the graph.
-
inline INodeDef *getNodeDef_abi() noexcept override
Access node definition (can be empty).
If the returned pointer is
nullptr
, either the definition does not implement omni::graph::exec::unstable::INodeDef or there is no definition attached to the node.The returned omni::graph::exec::unstable::INodeDef will not have omni::core::IObject::acquire() called before being returned.
Also see omni::graph::exec::unstable::INode::getDef() and omni::graph::exec::unstable::INode::getNodeGraphDef().
- Thread Safety
This method is thread safe during execution since the definition is not expected to change during execution. During construction, access to this method must be coordinated between the passes building the graph.
-
inline INodeGraphDef *getNodeGraphDef_abi() noexcept override
Access node’s graph definition (can be empty)
The returned graph definition pointer is the graph definition which defines the work this node represents. The returned pointer is not the graph definition that contains this node.
If the returned pointer is
nullptr
, either the definition does not implement omni::graph::exec::unstable::INodeGraphDef or there is no definition attached to the node.The returned omni::graph::exec::unstable::INodeGraphDef will not have omni::core::IObject::acquire() called before being returned.
Also see omni::graph::exec::unstable::INode::getDef() and omni::graph::exec::unstable::INode::getNodeDef().
- Thread Safety
This method is thread safe during execution since the definition is not expected to change during execution. During construction, access to this method must be coordinated between the passes building the graph.
-
inline void _addParent_abi(IGraphBuilderNode *parent) noexcept override
Adds the given node as a parent (i.e. upstream) of this node.
omni::core::IObject::acquire() is not called on the given node. It is up to the calling code to ensure the node persists while in use by this interface.
parent
must not benullptr
.It is undefined behavior to add a parent multiple times to a node.
Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::connect().
- Thread Safety
This method is not thread safe.
-
inline void _removeParent_abi(IGraphBuilderNode *parent) noexcept override
Removes the given node as a parent.
It is not an error if the given node is not a parent.
The given node may be
nullptr
.Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::disconnect().
- Thread Safety
This method is not thread safe.
-
inline void _addChild_abi(IGraphBuilderNode *child) noexcept override
Adds the given node as a child (i.e. downstream) of this node.
omni::core::IObject::acquire() is not called on the given node. It is up to the calling code to ensure the node persists while in use by this interface.
child
must not benullptr
.It is undefined behavior to add a child multiple times to a node.
Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::connect().
- Thread Safety
This method is not thread safe.
-
inline void _removeChild_abi(IGraphBuilderNode *child) noexcept override
Removes the given node as a child.
It is not an error if the given node is not a parent.
The given node may not be
nullptr
.Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::disconnect().
- Thread Safety
This method is not thread safe.
-
inline void _removeInvalidParents_abi() noexcept override
Remove from this node’s parent list any nodes that no longer exist in current topology, i.e are invalid.
omni::core::IObject::release() is not called on the invalid nodes.
Do not directly call this method. It is used internally by omni::graph::exec::unstable::IGraphBuilder.
- Thread Safety
This method is not thread safe.
-
inline void _removeInvalidChildren_abi() noexcept override
Remove from this node’s children list any nodes that no longer exist in current topology, i.e are invalid.
omni::core::IObject::release() is not called on the invalid nodes.
Do not directly call this method. It is used internally by omni::graph::exec::unstable::IGraphBuilder.
- Thread Safety
This method is not thread safe.
-
inline void _invalidateConnections_abi() noexcept override
Invalidate all children and parents connections by invalidating the topology stamp this node is synchronized with.
Do not directly call this method. It is used internally by omni::graph::exec::unstable::IGraphBuilder.
- Thread Safety
This method is thread safe.
Warning
This only removes connections on a single node. The topology has bi-directional connections for every node with the exception of the connection with the root node.
-
inline void setCycleParentCount_abi(uint32_t count) noexcept override
Sets the number of parents who are a part of cycle.
- Thread Safety
This method is not thread safe.
-
inline void _setNodeDef_abi(INodeDef *nodeDef) noexcept override
Sets the definition for this node.
If a definition is already set, it will be replaced by the given definition.
The given definition may be
nullptr
.omni::core::IObject::acquire() is called on the given pointer.
See also omni::graph::exec::unstable::IGraphBuilderNode::_setNodeGraphDef().
Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::setNodeDef().
- Thread Safety
This method is not thread safe.
-
inline void _setNodeGraphDef_abi(INodeGraphDef *nodeGraphDef) noexcept override
Sets the definition for this node.
If a definition is already set, it will be replaced by the given definition.
The given definition may be
nullptr
.omni::core::IObject::acquire() is called on the given pointer.
See also omni::graph::exec::unstable::IGraphBuilderNode::_setNodeDef().
Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::setNodeGraphDef().
- Thread Safety
This method is not thread safe.
-
inline void _clearDef_abi() noexcept override
Unsets this node’s definition.
If the definition is already
nullptr
, this method does nothing.Do not directly call this method. Instead, call omni::graph::exec::unstable::IGraphBuilder::clearDef().
- Thread Safety
This method is not thread safe.
-
inline IGraphBuilderNode *getParentAt_abi(uint64_t index) noexcept override
Access the parent at the given index.
It is an error if the the given index is greater than the parent count.
See omni::graph::exec::unstable::IGraphBuilderNode::getParentCount().
Consider using omni::graph::exec::unstable::IGraphBuilderNode::getParents() for a modern C++ wrapper to this method.
The returned omni::graph::exec::unstable::IGraphBuilderNode will not have omni::core::IObject::acquire() called before being returned.
The returned pointer will not be
nullptr
.- Thread Safety
This method is not thread safe.
-
inline uint64_t getParentCount_abi() noexcept override
Returns the number of parents.
- Thread Safety
This method is not thread safe.
-
inline IGraphBuilderNode *getChildAt_abi(uint64_t index) noexcept override
Access the child at the given index.
It is an error if the the given index is greater than the child count.
See omni::graph::exec::unstable::IGraphBuilderNode::getChildCount().
Consider using omni::graph::exec::unstable::IGraphBuilderNode::getChildren() for a modern C++ wrapper to this method.
The returned omni::graph::exec::unstable::IGraphBuilderNode will not have omni::core::IObject::acquire() called before being returned.
The returned pointer will not be
nullptr
.- Thread Safety
This method is not thread safe.
-
inline uint64_t getChildCount_abi() noexcept override
Returns the number of children.
- Thread Safety
This method is not thread safe.
-
inline bool hasChild_abi(IGraphBuilderNode *node) noexcept override
Returns
true
if the given node is an immediate child of this node.node
may benullptr
.- Thread Safety
This method is not thread safe.
-
inline bool isRoot_abi() noexcept override
Returns
true
if this node is the root of the topology.- Thread Safety
This method is not thread safe.
-
inline IGraphBuilderNode *getRoot_abi() noexcept override
Returns the root node of the topology of which this node is a part.
The returned omni::graph::exec::unstable::IGraphBuilderNode will not have omni::core::IObject::acquire() called before being returned.
The returned pointer will not be
nullptr
.- Thread Safety
This method is not thread safe.
-
inline NodeT(ITopology *topology, const carb::cpp::string_view &idName) noexcept
Constructor.
-
inline NodeT(ITopology *topology, INodeGraphDef *nodeGraphDef, const carb::cpp::string_view &idName) noexcept
Constructor.
-
inline NodeT(ITopology *topology, INodeDef *nodeDef, const carb::cpp::string_view &idName) noexcept
Constructor.
-
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 toomni::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.
-
inline virtual ~NodeT()