GraphBuilderT

Fully qualified name: omni::graph::exec::unstable::GraphBuilderT

template<typename ...Bases>
class GraphBuilderT : public omni::graph::exec::unstable::Implements<Bases...>

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 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<GraphBuilderT> create(

omni::core::ObjectParam<IGraphBuilderContext> context,

)

Construct a graph builder for the root INodeGraphDef of the IGraph in the given IGraphBuilderContext.

Construction of this graph builder will invalidate the underlying topology.

context must not be nullptr.

This method always returns a valid pointer.

static inline omni::core::ObjectPtr<GraphBuilderT> create(

omni::core::ObjectParam<IGraphBuilder> parentBuilder,

omni::core::ObjectParam<INodeGraphDef> nodeGraphDef,

)

Construct a graph builder for the given INodeGraphDef.

Construction of this graph builder will invalidate the underlying topology.

context must not be nullptr.

nodeGraphDef must not be nullptr.

This method always returns a valid pointer.

static inline omni::core::ObjectPtr<GraphBuilderT> createForPass(

omni::core::ObjectParam<IGraphBuilderContext> context,

omni::core::ObjectParam<INodeGraphDef> nodeGraphDef,

)

Construct graph builder for a given INodeGraphDef without causing topology invalidation.

This method creates a builder that can be used by the pass pipeline when operations to the graph will alter existing topology.

context must not be nullptr.

nodeGraphDef must not be nullptr.

This method always returns a valid pointer.

Protected Functions

inline IGraph *getGraph_abi() noexcept override

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 ITopology *getTopology_abi() noexcept override

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 IGraphBuilderContext *getContext_abi() noexcept override

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 INodeGraphDef *getNodeGraphDef_abi() noexcept override

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_abi(

INode *upstreamNode,

INode *downstreamNode,

) noexcept override

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_abi(

INode *upstreamNode,

INode *downstreamNode,

) noexcept override

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

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_abi(

INode *node,

INodeDef *nodeDef,

) noexcept override

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_abi(

INode *node,

INodeGraphDef *nodeGraphDef,

) noexcept override

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

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_abi(

const NodePartition *partition,

IDef *definition,

) noexcept override

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 INode *createNode_abi(

const char *name,

IDef *def,

) noexcept override

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 Span<INode*const> getCreatedNodes_abi() noexcept override

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 GraphBuilderT(

IGraphBuilderContext *context,

INodeGraphDef *nodeGraphDef,

) noexcept

Constructor.

inline ~GraphBuilderT() 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.