omni::graph::core::IGraph

Defined in omni/graph/core/iComputeGraph.h

struct IGraph

Interface to an OmniGraph, several of which may be present in a scene.

Public Members

size_t (*getNodeCount)(const GraphObj &graphObj)

Returns the number of nodes in the graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: The number of nodes in the graph

bool (*getNodes)(const GraphObj &graphObj, NodeObj *nodesBuf, size_t bufferSize)

Get the nodes in the graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param nodesBuf: [out] Buffer to hold the return NodeObjs
Param bufferSize: [in] the number of NodeObj structures the buffer is able to hold
Return: true on success, false on failure

size_t (*getSubgraphCount)(const GraphObj &graphObj)

Returns the number of subgraphs in the graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: The number of subgraphs in the graph

bool (*getSubgraphs)(const GraphObj &graphObj, GraphObj *graphsBuf, size_t bufferSize)

Get the subgraphs in the graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param graphsBuf: [out] Buffer to hold the return GraphObjs
Param bufferSize: [in] the number of GraphObjs structures the buffer is able to hold
Return: true on success, false on failure

GraphObj (*getSubgraph)(const GraphObj &graphObj, const char *subgraphPath)

Get a particular subgraph in the graph given its path.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param subgraphPath: [in] the path to the subgraph in question
Return: The GraphObj representing the graph. In case of failure, the graph handle will be kInvalidGraphHandle

const char *(*getPathToGraph)(const GraphObj &graphObj)

Returns the path to the graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: The path to the graph (may be empty)

bool (*isDisabled)(const GraphObj &graphObj)

Returns whether the current graph is disabled.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: true if the current graph is disabled false otherwise

void (*setDisabled)(const GraphObj &graphObj, bool disable)

Sets the disabled state of the graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param disable: [in] Whether or not to disable the current graph

GraphContextObj (*getDefaultGraphContext)(const GraphObj &graphObj)

Get the default graph context associated with the graph.

Each graph has a default context - it’s usually one that gives you evaluation of the graph on the current time, for example.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: The GraphContextObj representing the default graph context associated with the node.

NodeObj (*getNode)(const GraphObj &graphObj, const char *nodePath)

Get a particular node in the graph given its path.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param nodePath: [in] the path to the node in question
Return: The NodeObj representing the node. In case of failure, the node handle will be kInvalidNodeHandle

NodeObj (*createNode)(GraphObj &graphObj, const char *nodePath, const char *nodeType, bool createUsd)

Create a node in the graph at a given path with a given type.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param nodePath: [in] the path to where the node will be added
Param nodeType: [in] the type name of the node to add
Param createUsd: [in] Whether to create USD backing for the node being created
Return: The NodeObj representing the node. In case of failure, the node handle will be kInvalidNodeHandle

bool (*destroyNode)(GraphObj &graphObj, const char *nodePath, bool destroyUsd)

Destroy the node in the graph at a given path.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param nodePath: [in] the path of the node to destroy
Param destroyUsd: [in] Whether to destroy USD backing for the node being destroyed
Return: True, if the node was successfully destroyed. False otherwise.

bool (*renameNode)(GraphObj &graphObj, const char *oldPath, const char *newPath)

Rename the node in the graph at a given path.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param nodePath: [in] the path of the node to rename
Param newPath: [in] the new path of the node
Return: True, if the node was successfully renamed. False otherwise.

GraphObj (*createSubgraph)(GraphObj &graphObj, const char *subgraphPath, const char *evaluator, bool createUsd)

Create a subgraph in the graph at a given path with a given type.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param subgraphPath: [in] the path to where the subgraph will be added
Param evaluator: [in] the evaluator type to use for the subgraph being created
Param createUsd: [in] whether to create USD backing for the subgraph being created
Return: The GraphObj representing the subgraph. In case of failure, the graph handle will be kInvalidGraphHandle

void (*reloadGraphSettings)(GraphObj &graphObj)

reload the graph settings based on ComputeGraphSettings

Param graphObj: [in] Reference to the GraphObj struct representing the graph object

bool (*renameSubgraph)(GraphObj &graphObj, const char *oldPath, const char *newPath)

Rename the subgraph in the graph at a given path.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param subgraphPath: [in] the path of the subgraph to rename
Param newPath: [in] the new path of the subgraph
Return: True, if the subgraph was successfully renamed. False otherwise.

void (*onAttributeChanged)(const GraphObj &graphObj, const AttributeObj &attrObj)

Notifies the graph that some attribute has changed on a node.

This will trigger updates from things like lazy evaluation graphs, for example.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param Reference: [in] to the AttributeObj struct representing the attribute object

void (*registerPreLoadFileFormatUpgradeCallback)(FileFormatUpgrade fileFormatUpgrade)

Register a callback to be invoked when a legacy file with an older file format version is detected.

This callback is invoked before stage attach happens.

Param fileFormatUpgrade: [in] - structure containing the callback and a piece of user data to be passed back to the callback when invoked.

void (*registerPostLoadFileFormatUpgradeCallback)(FileFormatUpgrade fileFormatUpgrade)

Register a callback to be invoked when a legacy file with an older file format version is detected.

This callback is invoked after stage attach happens.

Param fileFormatUpgrade: [in] - structure containing the callback and a piece of user data to be passed back to the callback when invoked.

void (*deregisterPreLoadFileFormatUpgradeCallback)(FileFormatUpgrade fileFormatUpgrade)

Deregisters the pre-load callback to be invoked when a legacy file with an older file format version is detected.

Param fileFormatUpgrade: [in] - structure containing the callback and a piece of user data to be passed back to the callback when invoked.

void (*deregisterPostLoadFileFormatUpgradeCallback)(FileFormatUpgrade fileFormatUpgrade)

Deregisters the post-load callback to be invoked when a legacy file with an older file format version is detected.

Param fileFormatUpgrade: [in] - structure containing the callback and a piece of user data to be passed back to the callback when invoked.

bool (*usdNoticeHandlingEnabled)(const GraphObj &graphObj)

Returns whether USD notice handling is enabled for the graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: true if the current graph has USD notice handling enabled

void (*setUSDNoticeHandlingEnabled)(const GraphObj &graphObj, bool enable)

Sets whether the USD notice handling is enabled for this graph.

This is an advanced operation - do not use this method unless you know what you’re doing.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param enable: [in] Whether or not to enable USD notice handling for this graph

bool (*inspect)(const GraphObj &graphObj, inspect::IInspector *inspector)

Runs the inspector on the data in the given graph.

Param graphObj: [in] The graph on which the inspector runs
Param inspector: [in] The inspector class
Return: true if the inspection ran successfully, false if the inspection type is not supported

NodeObj (*createGraphAsNode)(GraphObj &graphObj, const char *nodeName, const char *graphPath, const char *evaluatorName, bool isGlobalGraph, bool backByUSD, GraphBackingType backingType, GraphPipelineStage graphPipelineStage)

Create a new graph, wrapped as a node, at the given location.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param nodeName: [in] the name of the node that wraps the graph
Param graphPath: [in] the path to where the graph that the node will wrap will be added
Param evaluatorName: [in] the evaluator to use for the new graph
Param isGlobalGraph: [in] Whether this graph is a top level global graph
Param backByUSD: [in] Whether to back this graph by USD
Param backingType: [in] What kind of FC backs this graph
Param graphPipelineStage: [in] What pipeline stage this graph occupies
Return: The NodeObj representing the node that wraps the graph. The newly created graph can be retrieved from the node. In case of failure, the NodeObj will contain kInvalidNodeHandle

void (*reloadFromStage)(const GraphObj &graphObj)

Reloads the graph from the stage by deleting the current graph and creating a new one to attach to the stage.

Note: this is a complete reset - any stateful nodes will lose their state.

Param graphObj: [in] The graph to reload

GraphBackingType (*getGraphBackingType)(const GraphObj &graphObj)

Returns the Fabric backing type for this graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: Fabric backing type. See GraphBackingType definition for details.

GraphPipelineStage (*getPipelineStage)(const GraphObj &graphObj)

Returns the graph pipeline stage (eg.

simulation, pre-render, post-render) for this graph

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: Graph pipeline stage. See GraphPipelineStage definition for details.

bool (*isValid)(const GraphObj &graphObj)

Returns whether the GraphObj’s handle is still valid.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: true if valid, false otherwise

bool (*getFabricId)(const GraphObj &graphObj, omni::fabric::FabricId &fabricId)

Returns the FabricId for this Graph.

This id can be used with the Fabric API, but should only be required for advanced use cases.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param fabricId: [out] The output user id
Return: true on success, false on failure

void (*evaluate)(const GraphObj &graphObj)

Warning: this is an advanced function - do not call unless you know exactly what is involved here.

This allows a graph to be “ticked” independently of the normal graph evaluation process, where graphs are ordered into different pipeline stages (simulation, pre-render, post-render), and all graphs of each stage are evaluated according to the order described in the orchestration graph in each stage.

Instead, this function allows graphs in the custom pipeline stage to be evaluated on its own. If this function is being called from a different thread, it is the caller’s responsibility to ensure that the Fabric backing the graph is independent (stage without history), otherwise data races will ensue. If this function is being called from the simulation / main thread, the the Fabric backing the graph may be a shared one.

It is illegal to call this function for any graph other than those setup with the custom pipeline stage.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object

GraphObj (*getParentGraph)(const GraphObj &graphObj)

Returns the parent of this graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: The parent graph (may be invalid)

bool (*isGlobalGraphPrim)(const char *path)

Returns whether the path points to a top level graph prim.

Param path: [in] to the prim in question
Return: True if the path points to a prim that is a top level graph

void (*registerErrorStatusChangeCallback)(const GraphObj &graphObj, ErrorStatusChangeCallback errorStatusChangeCallback)

Registers a callback to be invoked at the end of graph evaluation for all of the nodes whose error status changed during that evaluation.

This is provided primarily for UI purposes. E.g. highlighting nodes with compute errors

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param errorStatusChangeCallback: [in] - structure containing the callback and a piece of user data to be passed back to the callback when invoked.

void (*deregisterErrorStatusChangeCallback)(const GraphObj &graphObj, ErrorStatusChangeCallback errorStatusChangeCallback)

Deregisters a callback to be invoked at the end of graph evaluation for all of the nodes whose error status changed during that evaluation.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param errorStatusChangeCallback: [in] - structure containing the callback and a piece of user data to be passed back to the callback when invoked.

size_t (*getVariableCount)(const GraphObj &graphObj)

Returns the number of variables in the graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: The number of variables in the graph.

bool (*getVariables)(const GraphObj &graphObj, IVariablePtr *variableBuf, size_t bufferSize)

Get the variables defined in the graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param variableBuf: [out] Buffer to hold the returned IVariable objects
Param bufferSize: [in] The number of IVariable objects the buffer is able to hold
Return: true on success, false on failure

IVariablePtr (*createVariable)(const GraphObj &graphObj, const char *name, Type variableType)

Create a new variable on the graph with the given name.

The name must be unique among variables on the graph, even if the type is different.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param name: [in] The name to give the variable.
Param variableType: [in] the data type used to create the variable.
Return: The newly created variable, or null if the variable could not be created.

bool (*removeVariable)(const GraphObj &graphObj, const IVariablePtr &variable)

Removes the given variable from the graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param variable: [in] The variable to remove from the graph.
Return: True if the variable was successfully removed, false otherwise.

IVariablePtr (*findVariable)(const GraphObj &graphObj, const char *name)

Retrieves a variable with the given name.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param name: [in] The name of the variable to search for.
Return: The variable with the given name on the graph, or null if the variable does not exist.

void (*changePipelineStage)(const GraphObj &graphObj, GraphPipelineStage newPipelineStage)

Change the pipeline stage (eg.

simulation, pre-render, post-render) that this graph is in

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param newPipelineStage: [in] The new pipeline stage that this graph will be moved into

carb::events::IEventStreamPtr (*getEventStream)(const GraphObj &graphObj)

Returns the interface for the event stream generated by changes to this graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: The IEventStreamPtr that pumps events when graph changes happen

GraphEvaluationMode (*getEvaluationMode)(const GraphObj &graphObj)

Returns the evaluation mode of the graph.

The evaluation mode determines how the graph will be evaluated standalone or when referenced from an OmniGraphAPI component.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: The evaluation mode of the graph

void (*setEvaluationMode)(const GraphObj &graphObj, GraphEvaluationMode evaluationMode)

Sets the evaluation mode of the graph.

The evaluation mode determines if the graph will be evaluated standalone or when referenced from an OmniGraphAPI component.

Param graphObj: [in] Reference to the graph object
Param evaluationMode: [in] the evaluation mode of the graph to set

NodeObj (*createGraphAsNodeV2)(GraphObj &graphObj, const CreateGraphAsNodeOptions &options)

Create a new graph, wrapped as a node, at the given location.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Param options: [in] Options relating to creating a graph as a node.
Return: The NodeObj representing the node that wraps the graph. The newly created graph can be retrieved from the node. In case of failure, the NodeObj will contain kInvalidNodeHandle

const char *(*getEvaluatorName)(const GraphObj &graphObj)

Returns the name of the evaluator for the specified graph.

Param graphObj: [in] Reference to the GraphObj struct representing the graph object
Return: The name of the evaluator, or the empty string if it isn’t set.

bool (*isCompoundGraph)(const GraphObj &graphObj)

Returns whether this graph is a compound graph instance.

A compound graph is a subgraph that is parented to a compound node

Return: True if this graph is a compound graph, false otherwise.

size_t (*getInstanceCount)(const GraphObj &graphObj)

Returns the number of instance currently allocated for this graph.

Return: The number of instances registered in the graph, 0 if the graph is standalone

bool (*isAutoInstanced)(const GraphObj &graphObj)

Returns whether this graph is an auto instance.

An auto instance is a graph that got merged as an instance with all other similar graphs in the stage.

Return: True if this graph is an auto instance, false otherwise.

bool (*setAutoInstancingAllowed)(const GraphObj &graphObj, bool allowed)

Set whether or not this graph can be candidate for auto-instance merging (true by default)

Return: The old value of the allowed flag

NodeObj (*getOwningCompoundNode)(const GraphObj &graphObj)

Returns the compound node for which this graph is the compound subgraph of.

Return: If this graph is a compound graph, the owning compound node. Otherwise, an invalid node is returned.

bool (*setPrimView)(const GraphObj &graphObj, IPrimViewPtr view)

Apply a prim view to a graph.

A view is a way to dynamically and automatically manage the list of instances for a graph

Return: Whether the view has been successfully applied (could fail if graph already have instances for example)

bool (*canEvaluate)(const GraphObj &graphObj): Returns whether or not a graph meets all the required condition in order to run For example, a graph cannot run if it is disabled, or has invalid/unresolved mappings.

FileFormatVersion (*getCurrentFileFormatVersion)()

Returns the file format version for any new OmniGraphs created.

Return: The file format structure containing the current major and minor version.