omni::graph::exec::unstable::IPopulatePass

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

class IPopulatePass : public omni::core::Generated<omni::graph::exec::unstable::IPopulatePass_abi>

Base class for populate passes.

See Pass Concepts for an in-depth guide on how this object is used during graph construction.

The purpose of a populate pass is to populate a node with a definition. That definition can be an existing defintion, shared definition, or a new definition. Likewise, the definition may be either opaque or a graph.

Population passes are the main avenue to translate data in the authoring layer to the core Execution Framework.

Register a populate pass with OMNI_GRAPH_EXEC_REGISTER_POPULATE_PASS()

. When registering a pass, a “name to

match” is also specified. This name is the name of a node or definition on which the registered pass should populate.

Populate passes are typically the first pass type to run in the pass pipeline. When a node is encountered during construction, only a single populate pass will get a chance to populate the newly discovered node. If no pass is registered against the node’s name, the node definition’s name is used to find a population pass to run.

Minimal rebuild of the execution graph topology should be considered by the pass each time it runs. Pass pipeline leaves the responsibility of deciding if pass needs to run to the implementation. At minimum it can rely on verifying that the topology of the omni::graph::exec::unstable::NodeGraphDef it generated before is still valid or omni::graph::exec::unstable::NodeDef has not changed.

See Passes for more pass related functionality.

Thread Safety

Only a single population pass is run on a node at a time. However, many threads may be concurrently populating the overall execution graph and care must be taken if a population pass accesses shared state outside of the node’s state.

Public Functions

inline void run(omni::core::ObjectParam<omni::graph::exec::unstable::IGraphBuilder> builder, omni::core::ObjectParam<omni::graph::exec::unstable::INode> node) noexcept

Called from a pass pipeline to apply graph transformations on a given node (definition or topology).

The given builder supplies the graph definition in which the node resides. builder must not be nullptr.

node is the node to populate. Either the node’s name matches the name of this population pass or the name of the currently attached definition to the node matches. node must not be nullptr.

This method is expected to do one of the follow:

  • Set the node’s definition to a new definition, shared definition, or nullptr.

  • If the node has an attached graph definition, update the graph definition.

  • Do nothing if the definition is up-to-date. It is up to this method to determine if the definition is up-to-date.

When updating a definition, implementers should strive to perform the minimal amount of work. This means instead of tearing down a definition and rebuilding it from scratch, try to detect what has changed and only update that part of the definition.

Thread Safety

See thread safety information in interface description.

Protected Functions

virtual void run_abi(IGraphBuilder *builder, INode *node) noexcept = 0

Called from a pass pipeline to apply graph transformations on a given node (definition or topology).

The given builder supplies the graph definition in which the node resides. builder must not be nullptr.

node is the node to populate. Either the node’s name matches the name of this population pass or the name of the currently attached definition to the node matches. node must not be nullptr.

This method is expected to do one of the follow:

  • Set the node’s definition to a new definition, shared definition, or nullptr.

  • If the node has an attached graph definition, update the graph definition.

  • Do nothing if the definition is up-to-date. It is up to this method to determine if the definition is up-to-date.

When updating a definition, implementers should strive to perform the minimal amount of work. This means instead of tearing down a definition and rebuilding it from scratch, try to detect what has changed and only update that part of the definition.

Thread Safety

See thread safety information in interface description.