omni::graph::core::INode

Defined in omni/graph/core/iComputeGraph.h

struct INode

Interface to a single node in a graph.

Public Members

size_t (*getAttributeCount)(const NodeObj &node)

Returns the number of attributes on this node.

Param node: [in] Reference to the NodeObj struct representing the node object
Return: the number of attributes on this node

bool (*getAttributes)(const NodeObj &node, AttributeObj *attrsBuf, size_t bufferSize)

Returns the attributes on this node.

Param node: [in] Reference to the NodeObj struct representing the node object
Param attrsBuf: [out] Buffer to hold the return attribute objects
Param bufferSize: [in] the number of AttributeObj structures the buffer is able to hold
Return: true if successful, false otherwise

bool (*getAttributeExists)(const NodeObj &node, const char *attrName)

Retrieves whether the attribute in question exists or not.

Param node: [in] Reference to the NodeObj struct representing the node object
Param attrName: [in] Name of the attribute on the node
Return: true if the attribute exists on the node, false if not

AttributeObj (*getAttribute)(const NodeObj &node, const char *attrName)

Retrieves an attribute that points to the attribute on the current node.

Param node: [in] Reference to the NodeObj struct representing the node object
Param attrName: [in] Name of the attribute on the node
Return: the attribute object requested

AttributeObj (*getAttributeByToken)(const NodeObj &node, NameToken attrName)

Retrieves an attribute that points to the attribute on the current node.

Param node: [in] Reference to the NodeObj struct representing the node object
Param attrName: [in] Name of the attribute on the node
Return: the attribute object requested

const char *(*getPrimPath)(const NodeObj &node)

Retrieves the prim path to the node.

Param node: [in] Reference to the NodeObj struct representing the node object
Return: the prim path to the node

void *(*getUserData)(const NodeObj &node)

Retrieves the user data set on the node.

Param node: [in] Reference to the NodeObj struct representing the node object

void (*setUserData)(const NodeObj &node, void *userData)

Retrieves the user data set on the node.

Param node: [in] Reference to the NodeObj struct representing the node object

GraphObj (*getGraph)(const NodeObj &node)

Returns the graph that this node belongs to.

Param node: [in] Reference to the NodeObj struct representing the node object
Return: GraphObj structure containing the graph this node belongs to

bool (*isDisabled)(const NodeObj &node)

Returns the node is disabled.

Param node: [in] Reference to the NodeObj struct representing the node object
Return: true if disabled, false otherwise

void (*setDisabled)(const NodeObj &node, bool disable)

Sets the disabled state on the node.

Param node: [in] Reference to the NodeObj struct representing the node object
Param disable: [in] Whether to disable the node

void (*setComputeIncomplete)(const NodeObj &node)

Lets the evaluation system know that the compute for this node is complete for this frame but not completed overall.

For example, once an animation is triggered, we want the animation to play until completion - on a particular frame, the animation for that frame may be complete, but we’re not done until the overall animation is completed. This method is only meaningful for evaluators that implement standard flow graph semantics.

Param node: [in] Reference to the NodeObj struct representing the node object

bool (*isBackedByUsd)(const NodeObj &node)

Returns whether the node has an USD representation on the stage.

Param node: [in] Reference to the NodeObj struct representing the node object
Return: true if the node is backed by USD, false otherwise

bool (*createAttribute)(const NodeObj &node, const char *name, Type attributeType, const void *value, const size_t *elemCount, AttributePortType portType, ExtendedAttributeType extendedAttrType, const char *unionTypes)

Creates a dynamic attribute on the node.

Param node: [in] Reference to the NodeObj struct representing the node object
Param name: [in] Name of the attribute
Param attributeType: [in] The Type of the attribute. Extended attributes are Token types.
Param value: [in] Pointer to the location containing the initial value of the attribute
Param elemCount: [in] Number of elements in the attribute — nullptr if the attribute is a scalar
Param portType: [in] Whether this attribute is an input, output, or state
Param extendedAttrType: [in] The type of extended attribute to create, if any (see definition of ExtendedAttributeType)
Param unionTypes: [in] In case the extendedAttrType is union, unionTypes is a comma separated string that lists the allowable concrete types in the union
Return: true if the attribute was created, false otherwise

bool (*removeAttribute)(const NodeObj &node, const char *name)

Removes a dynamic attribute from the node.

Param node: [in] Reference to the NodeObj struct representing the node object
Param name: [in] Name of the attribute
Return: true if the attribute was removed, false if the attribute was not found

bool (*registerConnectedCallback)(const NodeObj &node, ConnectionCallback connectionCallback)

Registers a callback to be invoked when any attribute of the current node is connected.

Param node: [in] Reference to the NodeObj struct representing the node object
Param connectionCallback: [in] The struct containing the callback to trigger, and a piece of user data. The parameters are the attributes of this and the other node being connected, and a void* of user data
Return: true for success, false for failure

bool (*registerDisconnectedCallback)(const NodeObj &node, ConnectionCallback connectionCallback)

Registers a callback to be invoked when any attribute of the current node is disconnected.

Param node: [in] Reference to the NodeObj struct representing the node object
Param connectionCallback: [in] The struct containing the callback to trigger, and a piece of user data. The parameters are the attributes of this and the other node being disconnected, and a void* of user data
Return: true for success, false for failure

void (*deregisterConnectedCallback)(const NodeObj &node, ConnectionCallback connectionCallback)

Deregisters the callback to be invoked when any attribute of the current node is connected.

Param node: [in] Reference to the NodeObj struct representing the node object
Param connectionCallback: [in] The struct containing the callback to trigger, and a piece of user data.

void (*deregisterDisconnectedCallback)(const NodeObj &node, ConnectionCallback connectionCallback)

Deregisters the callback to be invoked when any attribute of the current node is disconnected.

Param node: [in] Reference to the NodeObj struct representing the node object
Param connectionCallback: [in] The struct containing the callback to trigger, and a piece of user data.

bool (*retired_6)(const NodeObj&): retired - do not use

void (*retired_7)(const NodeObj&, bool): retired - do not use

NodeTypeObj (*getNodeTypeObj)(const NodeObj &node)

Returns the NodeTypeObj structure associated with this node.

Param node: [in] Reference to the NodeObj struct representing the node object
Return: NodeTypeObj encapsulating the node type from which this node was created

bool (*resolveCoupledAttributes)(const NodeObj &node, AttributeObj *attrsBuf, size_t bufferSize)

Resolves attribute types given a set of attributes which are fully type coupled.

For example if node ‘Increment’ has one input attribute ‘a’ and one output attribute ‘b’ and the types of ‘a’ and ‘b’ should always match. If the input is resolved then this function will resolve the output to the same type. It will also take into consideration available conversions on the input side. The type of the first (resolved) provided attribute will be used to resolve others or select appropriate conversions

Note that input attribute types are never inferred from output attribute types.

This function should only be called from the INodeType function onConnectionTypeResolve

Param node: [in] Reference to the NodeObj struct representing the node object
Param attrsBuf: [out] Buffer that holds the attributes to be resolved as a coupled group
Param bufferSize: [in] the number of AttributeObj structures the buffer is able to hold
Return: true if successful, false otherwise, usually due to mismatched or missing resolved types

bool (*resolvePartiallyCoupledAttributes)(const NodeObj &node, const AttributeObj *attrsBuf, const uint8_t *tuplesBuf, const uint8_t *arrayDepthsBuf, const AttributeRole *rolesBuf, size_t bufferSize)

Resolves attribute types given a set of attributes, that can have differing tuple counts and/or array depth, and differing but convertible base data type.

The three input buffers are tied together, holding the attribute, the tuple count, and the array depth of the types to be coupled. This function will solve base type conversion by targeting the first provided type in the list, for all other ones that require it.

For example if node ‘makeTuple2’ has two input attributes ‘a’ and ‘b’ and one output ‘c’ and we want to resolve any float connection to the types ‘a’:float, ‘b’:float, ‘c’:float[2] (convertible base types and different tuple counts) then the input buffers would contain: attrsBuf = [a, b, c] tuplesBuf = [1, 1, 2] arrayDepthsBuf = [0, 0, 0] rolesBuf = [AttributeRole::eNone, AttributeRole::eNone, AttributeRole::eNone]

This is worth noting that ‘b’ could be of any type convertible to float. But since the first provided attribute is ‘a’, the type of ‘a’ will be used to propagate the type resolution.

Note that input attribute types are never inferred from output attribute types.

This function should only be called from the INodeType function onConnectionTypeResolve

Param node: [in] Reference to the NodeObj struct representing the node object
Param attrsBuf: [in] Buffer that holds the attributes to be resolved as a coupled group
Param tuplesBuf: [in] Buffer that holds the tuple count desired for each corresponding attribute. Any value of kUninitializedTypeCount indicates the found tuple count is to be used when resolving.
Param arrayDepthsBuf: [in] Buffer that holds the array depth desired for each corresponding attribute. Any value of kUninitializedTypeCount indicates the found array depth is to be used when resolving.
Param rolesBuf: [in] Buffer that holds the role desired for each corresponding attribute. Any value of AttributeRole::eUnknown indicates the found role is to be used when resolving.
Param bufferSize: [in] the number of AttributeObj structures the buffer is able to hold
Return: true if successful, false otherwise, usually due to mismatched or missing resolved types

GraphObj (*getWrappedGraph)(const NodeObj &node)

Returns the graph wrapped by this node, if any (as opposed to the graph this node belongs to)

Param node: [in] Reference to the NodeObj struct representing the node object
Return: GraphObj structure containing the graph wrapped by this node

carb::events::IEventStreamPtr (*getEventStream)(const NodeObj &node)

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

Return: The IEventStreamPtr that pumps events when node changes happen

bool (*isValid)(const NodeObj &node)

Returns whether the NodeObj’s handle is still valid.

Param node: [in] Reference to the NodeObj struct representing the node object
Return: true if valid, false otherwise

bool (*requestCompute)(const NodeObj &node)

Requests that the given node be computed at the next graph evaluation.

This is for use with nodes that are marked as being RequestDrivenCompute.

Param node: [in] Reference to the NodeObj struct representing the node object
Return: true if the request was successful, false if there was an error

NodeObj (*getNodeFromHandle)(const NodeHandle nodeHandle)

Returns a NodeObj for the given NodeHandle if the referenced node is valid.

Param nodeHandle: [in] The NodeHandle for the compute node
Return: The NodeObj representing the node. In case of failure, the node handle will be kInvalidNodeHandle

size_t (*getComputeCount)(const NodeObj &node)

Returns the number of instances on which computation has been invoked for this node since the counter last rolled over to 0.

Param node: [in] Reference to the NodeObj struct representing the node object.
Return: The count.

size_t (*getComputeMessageCount)(const NodeObj &node, ogn::Severity severity)

Returns the number of compute messages of the given severity logged for the node.

Compute messages are cleared at the start of each evaluation, so the count will be only for the most recent evaluation.

Param node: [in] Reference to the NodeObj struct representing the node object.
Param severity: [in] Severity level of the messages.
Return: The number of compute messages of the specified severity.

const char *(*getComputeMessage)(const NodeObj &node, ogn::Severity severity, size_t index)

Returns a specified compute message of the given severity logged for the node.

Use getComputeMessageCount() to determine the number of messages currently available.

Param node: [in] Reference to the NodeObj struct representing the node object.
Param severity: [in] Severity level of the message to return.
Param index: [in] Index of the message to return, starting at 0.
Return: The requested message or nullptr if ‘index’ was out of range.

size_t (*clearOldComputeMessages)(const NodeObj &node)

Clears all compute messages logged for the node prior to its most recent evaluation.

Messages from its most recent evaluation are left untouched.

Param node: [in] Reference to the NodeObj struct representing the node object.
Return: The number of messages that were deleted.

ogn::OmniGraphDatabase *(*getOgnDatabase)(const NodeObj &node, CreateDbFunc ognCreate)

Retrieve the OGN database for the current active instance of this node.

The DB is maintained up2date internally by the framework. If it does not exists the provided ognCreate callback will be invoked to instantiate it

Param node: [in] Reference to the NodeObj struct representing the node object.
Param ognCreate: [in] A callback that allocates and returns the DB associated to the current active instance of this node. Ownership is transferred to the node

bool (*isCompoundNode)(const NodeObj &node)

Returns whether this node is a compound node.

A compound node is a node whose node type is defined by a subgraph instead of a built-in type.

Param node: [in] Reference to the NodeObj struct representing the node object.
Return: True if the provided node is a compound node, false otherwise

GraphInstanceID (*getGraphInstanceID)(NodeHandle node, InstanceIndex instanceOffset)

Retrieve a persistent ID for the current active graph associated to this node, optionally offsetted.

UPGRADE NOTE: if you end up here because of a compile error, the previously returned token is now wrapped into the GraphInstanceID. Everything remains binary compatible, but code at call site needs to be adapted by adding “.id” to the returned value.

Param node: [in] Handle representing the node object.
Param instanceOffset: [in] In vectorized context, the instance index relative to the currently targeted graph
Return: A unique and process-persistent ID that represents the current active instance of this node

exec::unstable::Stamp (*getAttributeChangeStamp)(const NodeObj &node)

Returns a Stamp that is incremented any time an input or state attribute is changed outside of graph evaluation.

For example, interactively or through a script.

Param node: [in] Reference to the NodeObj struct representing the node object.
Return: The stamp value

GraphObj (*getCompoundGraphInstance)(const NodeObj &node)

Returns a handle to the associated sub-graph, if the given node is a compound node.

Param node: [in] Handle representing the node object.
Return: The GraphObj representing the graph. In case of failure, the graph handle will be kInvalidGraphHandle.

size_t (*getAutoInstances)(const NodeObj &node, GraphContextObj const *&graphContexts, NodeObj const *&nodeObjects)

Query all the node and context handles that the provided node emulate when used in an auto instancing scenario.

Param node: [in] Handle representing the “master” node object, the one that handle the execution.
Param graphContexts: [out] A pointer reference that will be set to an array of all the emulated auto-instanced graph contexts
Param nodeObjects: [out] A pointer reference that will be set to an array of all the emulated auto-instanced nodes
Return: The number of elements in the returned arrays, 1 if there is not auto instancing associated to the provided node (itself)

bool (*logComputeMessageOnInstance)(const NodeObj &node, InstanceIndex inst, ogn::Severity severity, const char *message)

Logs a compute message of a given severity for the node.

This method is intended to be used from within the compute() method of a node to alert the user to any problems or issues with the node’s most recent evaluation. They are accumulated until the start of the next compute, at which point they are cleared.

If duplicate messages are logged, with the same severity level, only one is stored.

Param node: [in] Reference to the NodeObj struct representing the node object.
Param inst: [in] In vectorized context, the instance index relative to the currently targeted graph
Param severity: [in] Severity level of the message.
Param message: [in] The message.
Return: Returns true if the message has already been logged, false otherwise.

size_t (*increaseComputeCount)(const NodeObj &node, size_t count)

Increase the node’s compute counter by the provided amount.

This method is provided primarily for debugging and experimental uses and should not normally be used by end-users.

Param node: [in] Reference to the NodeObj struct representing the node object
Param count: [in] the number to be added to the compute count.
Return: The new count.

size_t (*getComputeVectorizedCount)(const NodeObj &node)

Returns the number of vectorized segments on which computation has been invoked on this node since the counter last rolled over to 0.

Param node: [in] Reference to the NodeObj struct representing the node object.
Return: The count.

bool (*validateCompute)(const NodeObj &node)

Validates that a node can be evaluated.

This is intended to be called prior to compute to validate that the node does not contain any errors that should prevent computation, such as invalid connections.

Param node: [in] Reference to the NodeObj struct representing the node object.
Return: True if the node is eligible for validation, false if it contains an error that should prevent evaluation.