omni::graph::exec::unstable::IGraphBuilder

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

class IGraphBuilder : public omni::core::Generated<omni::graph::exec::unstable::IGraphBuilder_abi>

Graph builder is the only class that has the ability to modify topology of a graph.

Topological edits of the graph are only allowed during graph transformation and should never be performed during execution of the graph. Construction of the builder will automatically drop all the connections between nodes.

Thread Safety

Methods on this class mutating a graph topology are not thread-safe (unless documented otherwise)

Public Functions

inline INode *getRoot() noexcept

Return the root node of the graph definition this builder is modifying.

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

This method always returns a valid pointer.

Thread Safety

This method is thread safe.

inline INode *createNode(const std::string &name, omni::core::ObjectParam<IDef> def) noexcept

Create a new node in the builder’s node graph definition.

The given node name must not be nullptr.

The given definition can be nullptr.

Node creation can return nullptr when the builder’s node graph definition doesn’t allow node construction outside of the pass that created it (i.e. omni::graph::exec::unstable::INodeGraphDef::getNodeFactory() returns nullptr).

The returned omni::graph::exec::unstable::INode will not have omni::core::IObject::acquire() called on it. It is assumed the returned node will be owned by the builder’s graph definition.

Thread Safety

This method is not thread safe.

inline omni::graph::exec::unstable::IGraph *getGraph() noexcept

Return the top-level execution graph who owns the graph definition this builder is modifying.

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

This method always returns a valid pointer.

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::ITopology *getTopology() noexcept

Returns the topology this builder can modify.

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

This method always returns a valid pointer.

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::IGraphBuilderContext *getContext() noexcept

Returns the context in which this builder works.

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

This method always returns a valid pointer.

Thread Safety

This method is thread safe.

inline omni::graph::exec::unstable::INodeGraphDef *getNodeGraphDef() noexcept

Returns omni::graph::exec::unstable::INodeGraphDef this builder is modifying.

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

This method always returns a valid pointer.

Thread Safety

This method is thread safe.

inline void connect(omni::core::ObjectParam<omni::graph::exec::unstable::INode> upstreamNode, omni::core::ObjectParam<omni::graph::exec::unstable::INode> downstreamNode) noexcept

Connects two given nodes in the graph definition.

The given nodes must be in the builder’s graph definition topology.

The given nodes must not be nullptr.

The upstream and downstream nodes can be the same node, essentially forming a connection between a node and itself.

Neither omni::graph::exec::unstable::INode have omni::core::IObject::acquire() called during the connection process.

Thread Safety

This method is not thread safe.

inline void disconnect(omni::core::ObjectParam<omni::graph::exec::unstable::INode> upstreamNode, omni::core::ObjectParam<omni::graph::exec::unstable::INode> downstreamNode) noexcept

Disconnect two given nodes.

The given nodes must be in the builder’s graph definition topology.

The given nodes must not be nullptr.

It is not an error if the two nodes are not connected.

Neither omni::graph::exec::unstable::INode have omni::core::IObject::acquire() called during the disconnection process.

Thread Safety

This method is not thread safe.

inline void remove(omni::core::ObjectParam<omni::graph::exec::unstable::INode> node) noexcept

Remove a node from topology.

The given node must be in the builder’s graph definition topology.

The given node can be nullptr.

Thread Safety

This method is not thread safe.

inline void setNodeDef(omni::core::ObjectParam<omni::graph::exec::unstable::INode> node, omni::core::ObjectParam<omni::graph::exec::unstable::INodeDef> nodeDef) noexcept

Sets the definition for the given node.

If a definition is already set, it will be replaced by the given definition.

The given node must be in the builder’s graph definition topology.

The given node must not be nullptr.

The given definition may be nullptr.

omni::core::IObject::acquire() is called on the given definition pointer.

See also omni::graph::exec::unstable::IGraphBuilder::setNodeGraphDef().

Thread Safety

This method is not thread safe.

inline void setNodeGraphDef(omni::core::ObjectParam<omni::graph::exec::unstable::INode> node, omni::core::ObjectParam<omni::graph::exec::unstable::INodeGraphDef> nodeGraphDef) noexcept

Sets the graph definition for give node.

If a definition is already set, it will be replaced by the given definition.

The given node must be in the builder’s graph definition topology.

The given node must not be nullptr.

The given definition may be nullptr.

omni::core::IObject::acquire() is called on the given definition pointer.

See also omni::graph::exec::unstable::IGraphBuilder::setNodeDef().

Thread Safety

This method is not thread safe.

inline void clearDef(omni::core::ObjectParam<omni::graph::exec::unstable::INode> node) noexcept

Removes the given node’s definition.

The given node must be in the builder’s graph definition topology.

The given node must not be nullptr.

If the definition is already nullptr, this method does nothing.

Thread Safety

This method is not thread safe.

inline void replacePartition(const omni::graph::exec::unstable::NodePartition &partition, omni::core::ObjectParam<omni::graph::exec::unstable::IDef> definition) noexcept

Replace a well formed cluster of nodes with a single node and the given definition.

All nodes in the partition must by in the builder’s graph definition topology.

All nodes in the partition must not be nullptr.

The given partition pointer must not be nullptr.

The given definition may be nullptr.

If the given partition is empty, this method does nothing.

The node graph definition this builder is modifying must support node creation (e.g. omni::graph::exec::unstable::INodeGraphDef::getNodeFactory() must return a valid factory).

omni::core::IObject::acquire() is called on the given definition pointer.

Thread Safety

This method is not thread safe.

inline omni::graph::exec::unstable::INode *createNode(const char *name, omni::core::ObjectParam<omni::graph::exec::unstable::IDef> def) noexcept

Create a new node in the builder’s node graph definition.

The given node name must not be nullptr.

The given definition can be nullptr.

Node creation can return nullptr when the builder’s node graph definition doesn’t allow node construction outside of the pass that created it (i.e. omni::graph::exec::unstable::INodeGraphDef::getNodeFactory() returns nullptr).

The returned omni::graph::exec::unstable::INode will not have omni::core::IObject::acquire() called on it. It is assumed the returned node will be owned by the builder’s graph definition.

Thread Safety

This method is not thread safe.

inline omni::graph::exec::unstable::Span<omni::graph::exec::unstable::INode*const> getCreatedNodes() noexcept

Access nodes created by this builder.

The returned span is no longer valid when the topology of the builder’s graph changes.

Nodes returned in this list may not be valid in the builder’s graph definition topology. This can happen if a previously created node was removed by a subsequent pass. Users can check if a returned node is valid within the topology with omni::graph::exec::unstable::INode::isValidTopology().

The pointers in the span are non-owning, i.e. each omni::graph::exec::unstable::INode will not have omni::core::IObject::acquire() called on it before returning.

Thread Safety

This method is not thread safe.

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 IGraph *getGraph_abi() noexcept = 0

Return the top-level execution graph who owns the graph definition this builder is modifying.

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

This method always returns a valid pointer.

Thread Safety

This method is thread safe.

virtual ITopology *getTopology_abi() noexcept = 0

Returns the topology this builder can modify.

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

This method always returns a valid pointer.

Thread Safety

This method is thread safe.

virtual IGraphBuilderContext *getContext_abi() noexcept = 0

Returns the context in which this builder works.

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

This method always returns a valid pointer.

Thread Safety

This method is thread safe.

virtual INodeGraphDef *getNodeGraphDef_abi() noexcept = 0

Returns omni::graph::exec::unstable::INodeGraphDef this builder is modifying.

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

This method always returns a valid pointer.

Thread Safety

This method is thread safe.

virtual void connect_abi(INode *upstreamNode, INode *downstreamNode) noexcept = 0

Connects two given nodes in the graph definition.

The given nodes must be in the builder’s graph definition topology.

The given nodes must not be nullptr.

The upstream and downstream nodes can be the same node, essentially forming a connection between a node and itself.

Neither omni::graph::exec::unstable::INode have omni::core::IObject::acquire() called during the connection process.

Thread Safety

This method is not thread safe.

virtual void disconnect_abi(INode *upstreamNode, INode *downstreamNode) noexcept = 0

Disconnect two given nodes.

The given nodes must be in the builder’s graph definition topology.

The given nodes must not be nullptr.

It is not an error if the two nodes are not connected.

Neither omni::graph::exec::unstable::INode have omni::core::IObject::acquire() called during the disconnection process.

Thread Safety

This method is not thread safe.

virtual void remove_abi(INode *node) noexcept = 0

Remove a node from topology.

The given node must be in the builder’s graph definition topology.

The given node can be nullptr.

Thread Safety

This method is not thread safe.

virtual void setNodeDef_abi(INode *node, INodeDef *nodeDef) noexcept = 0

Sets the definition for the given node.

If a definition is already set, it will be replaced by the given definition.

The given node must be in the builder’s graph definition topology.

The given node must not be nullptr.

The given definition may be nullptr.

omni::core::IObject::acquire() is called on the given definition pointer.

See also omni::graph::exec::unstable::IGraphBuilder::setNodeGraphDef().

Thread Safety

This method is not thread safe.

virtual void setNodeGraphDef_abi(INode *node, INodeGraphDef *nodeGraphDef) noexcept = 0

Sets the graph definition for give node.

If a definition is already set, it will be replaced by the given definition.

The given node must be in the builder’s graph definition topology.

The given node must not be nullptr.

The given definition may be nullptr.

omni::core::IObject::acquire() is called on the given definition pointer.

See also omni::graph::exec::unstable::IGraphBuilder::setNodeDef().

Thread Safety

This method is not thread safe.

virtual void clearDef_abi(INode *node) noexcept = 0

Removes the given node’s definition.

The given node must be in the builder’s graph definition topology.

The given node must not be nullptr.

If the definition is already nullptr, this method does nothing.

Thread Safety

This method is not thread safe.

virtual void replacePartition_abi(const NodePartition *partition, IDef *definition) noexcept = 0

Replace a well formed cluster of nodes with a single node and the given definition.

All nodes in the partition must by in the builder’s graph definition topology.

All nodes in the partition must not be nullptr.

The given partition pointer must not be nullptr.

The given definition may be nullptr.

If the given partition is empty, this method does nothing.

The node graph definition this builder is modifying must support node creation (e.g. omni::graph::exec::unstable::INodeGraphDef::getNodeFactory() must return a valid factory).

omni::core::IObject::acquire() is called on the given definition pointer.

Thread Safety

This method is not thread safe.

virtual INode *createNode_abi(const char *name, IDef *def) noexcept = 0

Create a new node in the builder’s node graph definition.

The given node name must not be nullptr.

The given definition can be nullptr.

Node creation can return nullptr when the builder’s node graph definition doesn’t allow node construction outside of the pass that created it (i.e. omni::graph::exec::unstable::INodeGraphDef::getNodeFactory() returns nullptr).

The returned omni::graph::exec::unstable::INode will not have omni::core::IObject::acquire() called on it. It is assumed the returned node will be owned by the builder’s graph definition.

Thread Safety

This method is not thread safe.

virtual Span<INode*const> getCreatedNodes_abi() noexcept = 0

Access nodes created by this builder.

The returned span is no longer valid when the topology of the builder’s graph changes.

Nodes returned in this list may not be valid in the builder’s graph definition topology. This can happen if a previously created node was removed by a subsequent pass. Users can check if a returned node is valid within the topology with omni::graph::exec::unstable::INode::isValidTopology().

The pointers in the span are non-owning, i.e. each omni::graph::exec::unstable::INode will not have omni::core::IObject::acquire() called on it before returning.

Thread Safety

This method is not thread safe.

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.