omni::graph::core::IAttribute

Defined in omni/graph/core/iComputeGraph.h

struct IAttribute

Interface to provide functionality to access and modify properties of an OmniGraph attribute.

Public Members

const char *(*getName)(const AttributeObj &attr)

Returns the name of the attribute.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Return: The name of the attribute

const char *(*getTypeName)(const AttributeObj &attr)

Returns the type name of the attribute.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Return: The type name of the attribute

ExtendedAttributeType (*getExtendedType)(const AttributeObj &attr)

Returns the extended type, if any, of the attribute.

Extended types are things like “union” and “any” types that aren’t in the explicit list of types in USD. kExtendedAttributeType_Regular means that the attribute is not one of these extended types.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Return: The extended type of the attribute

Type (*getResolvedType)(const AttributeObj &attr)

Returns the resolved type an extended type like union actually turns out to be, by inferring it from the connection.

If the type is still not resolved, the BaseDataType of the returned type will have eNone as its value.

If the attribute type is just a Regular one then this method will return its permanent type.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Return: The resolved type of the attribute, based on the connection

bool (*isArray)(const AttributeObj &attr)

Returns whether the attribute is an array.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Return: Whether or not the attribute is an array

bool (*connectPrim)(const AttributeObj &attrObj, const char *pathToPrim, bool modifyInUsd, bool isBundleConnection)

Connects an attribute using a relationship to some other prim.

This could be for a bundle connection or a pure relationship to a prim. In the case of a pure relationship to a prim, some meta-data will be added to mark the relationship as not being used for a bundle

Param attrObj: [in] The attr that represents the relationship
Param pathToPrim: [in] The path to the prim to connect to
Param modifyInUsd: [in] Whether the connection is also modified in the underlying USD representation
Param isBundleConnection: [in] Whether the connection is to be used for bundles or just a pure relationship to a prim
Return: true if connection is successful, false otherwise

bool (*disconnectPrim)(const AttributeObj &attrObj, const char *pathToPrim, bool modifyInUsd, bool isBundleConnection)

Disconnects an attribute using a relationship to some other prim.

This could be for a bundle connection or a pure relationship to a prim.

Param attrObj: [in] The attr that represents the relationship
Param pathToPrim: [in] The path to the prim to disconnect
Param modifyInUsd: [in] Whether the connection is also modified in the underlying USD representation
Param isBundleConnection: [in] Whether the connection is to be used for bundles or just a pure relationship to a prim
Return: true if disconnection is successful, false otherwise

bool (*connectAttrs)(const AttributeObj &srcAttr, const AttributeObj &destAttr, bool modifyInUsd)

Connects two attributes together to add an edge to the graph.

This is a legacy version of the connection API. Calling this is equivalent to setting kConnectionType_Regular type connections. Please use connectAttrsEx to have fuller control over the kind of connections created.

Param srcAttr: [in] The attr that is the source of the directed connection
Param destAttr: [in] The attr that is the destination of the directed connection
Param modifyInUsd: [in] Whether the connection is also modified in the underlying USD representation
Return: true if connection is successful, false otherwise

bool (*connectAttrsEx)(const AttributeObj &srcAttr, const ConnectionInfo &destAttr, bool modifyInUsd)

Connects two attributes together to add an edge to the graph.

This is an extended version with more information about the connection, such as the type of connection.

Param srcAttr: [in] The attr that is the source of the directed connection
Param destAttrInfo: [in] A ConnectionInfo struct describing the connection
Param modifyInUsd: [in] Whether the connection is also modified in the underlying USD representation
Return: true if connection is successful, false otherwise

bool (*disconnectAttrs)(const AttributeObj &srcAttr, const AttributeObj &destAttr, bool modifyInUsd)

Disconnects two attributes that are connected.

Param srcAttr: [in] The attribute that is the source of the directed connection
Param destAttr: [in] The attribute that is the destination of the directed connection
Param modifyInUsd: [in] Whether the connection is also modified in the underlying USD representation
Return: true if connection is successfully broken, false otherwise (if no connections existed)

bool (*areAttrsConnected)(const AttributeObj &srcAttr, const AttributeObj &destAttr)

Queries whether two attributes are connected.

Param srcAttr: [in] The attribute that is the source of the directed connection
Param destAttr: [in] The attribute that is the destination of the directed connection
Return: true if the two attributes are connected, false otherwise

bool (*areAttrsCompatible)(const AttributeObj &srcAttr, const AttributeObj &destAttr)

Queries whether two attributes are connection compatible.

Param srcAttr: [in] The attribute that would be the source of the directed connection
Param destAttr: [in] The attribute that would be the destination of the directed connection
Return: true if the two attributes are compatible, false otherwise

size_t (*getUpstreamConnectionCount)(const AttributeObj &attrObj)

Retrieves the number of upstream connections to the attribute of a node.

Param attrObj: [in] The attribute object for which to retrieve the connection count
Return: The number of upstream connections to that attribute

bool (*getUpstreamConnections)(const AttributeObj &attrObj, AttributeObj *attrsBuf, size_t bufferSize)

Retrieves the upstream connections of the attribute of a node.

Param attrObj: [in] The attribute object for which to retrieve the connections
Param attrsBuf: [out] Buffer to hold the return AttributeObj
Param bufferSize: [in] the number of AttributeObj structures the buffer is able to hold
Return: true on success, false on failure

bool (*getUpstreamConnectionsInfo)(const AttributeObj &attrObj, ConnectionInfo *connectionInfoBuf, size_t bufferSize)

Retrieves the detailed upstream connection info of an attribute.

Includes information like type of connections.

Param attrObj: [in] The attribute object for which to retrieve the connections
Param connectionInfoBif: [out] Buffer to hold the return ConnectionInfo
Param bufferSize: [in] the number of AttributeObj structures the buffer is able to hold
Return: true on success, false on failure

size_t (*getDownstreamConnectionCount)(const AttributeObj &attrObj)

Retrieves the number of downstream connections to the attribute of a node.

Param attrObj: [in] The attribute object for which to retrieve the connection count
Return: The number of downstream connections to that attribute

bool (*getDownstreamConnections)(const AttributeObj &attrObj, AttributeObj *attrsBuf, size_t bufferSize)

Retrieves the down connections of the attribute of a node.

Param attrObj: [in] The attribute object for which to retrieve the connections
Param attrsBuf: [out] Buffer to hold the return AttributeObj
Param bufferSize: [in] the number of AttributeObj structures the buffer is able to hold
Return: true on success, false on failure

bool (*getDownstreamConnectionsInfo)(const AttributeObj &attrObj, ConnectionInfo *connectionInfoBuf, size_t bufferSize)

Retrieves the detailed upstream connection info of an attribute.

Includes information like type of connections.

Param attrObj: [in] The attribute object for which to retrieve the connections
Param connectionInfoBif: [out] Buffer to hold the return ConnectionInfo
Param bufferSize: [in] the number of AttributeObj structures the buffer is able to hold
Return: true on success, false on failure

NodeObj (*getNode)(const AttributeObj &attrObj)

Retrieves the node associated with this attribute.

Param attrObj: [in] The attribute object for which to retrieve the node
Return: The NodeObj representing the node. In case of failure, the node handle will be kInvalidNodeHandle

bool (*updateAttributeValue)(const AttributeObj &attrObj, bool updateImmediately)

Ensures the attribute’s value is updated, before reading it.

For push graphs this does nothing, as the push graph is always evaluating and considered up to date. For pull graphs, this generates the true “pull” on the attribute, that will cause whatever is upstream and is dirty to evaluate.

Param attrObj: [in] The attribute object for which to update the value for
Param updateImmediately: [in] Whether to cause the graph to update immediately (synchronously)
Return: Whether the update was successful

void (*registerValueChangedCallback)(const AttributeObj &attrObj, void (*onValueChanged)(const AttributeObj &attr, const void *value), bool triggerOnConnected)

Registers a callback to be invoked when the value of the current attribute changes.

An attribute only permits a single callback and when called, the previously set callback is replaced. Passing nullptr as the callback will remove any existing callback.

Param thisAttribute: [in] Reference to the AttributeObj struct representing the current attribute object
Param onValueChanged: [in] The callback to trigger. Parameters are the attribute involved, and the new value
Param triggerOnConnected: [in] Whether to trigger the callback on connected attributes.

size_t (*getAllMetadata)(const AttributeObj &thisAttribute, const char **keyBuf, const char **valueBuf, size_t bufferSize)

Returns the set of all metadata on this attribute.

The keyBuf and valueBuf arrays preallocated by the caller, and contain at least “getMetadataCount()” entries in them. All returned strings are owned by the node type and not to be destroyed. The returned keyBuf and valueBuf must have exactly the same size with corresponding index values; that is keyBuf[i] is the metadata name for the string in valueBuf[i].

Param thisAttribute: [in] Reference to the AttributeObj struct representing the current attribute object
Param keyBuf: [out] Buffer in which to put the list of metadata keys
Param valueBuf: [out] Buffer in which to put the list of metadata values
Param bufferSize: [in] the number of strings each of the two buffers is able to hold
Return: Number of metadata items successfully populated

const char *(*getMetadata)(const AttributeObj &thisAttribute, const char *key)

Retrieves a metadata value from this attribute.

Param thisAttribute: [in] Reference to the AttributeObj struct representing the current attribute object
Param key: [in] The name of the metadata to be retrieved
Return: The value of the metadata, or nullptr if the named metadata was not set on this attribute

size_t (*getMetadataCount)(const AttributeObj &thisAttribute)

Returns the number of metadata entries on this attribute.

Param thisAttribute: [in] Reference to the AttributeObj struct representing the current attribute object
Return: the number of metadata key/value pairs on this attribute

void (*setMetadata)(const AttributeObj &attrObj, const char *key, const char *value)

Sets a metadata value on this attribute.

Certain metadata keywords have special meaning internally: uiName: The name of the attribute in a longer, human-readable format

Note: The main way for metadata to be set is through the .ogn format files. If you call this directly the metadata will not persist across sessions. If you wish to define metadata outside of the .ogn file the best method is to override the initializeType() method in your attribute definition and set it there.

Param attrObj: [in] Reference to the AttributeObj struct representing the current attribute object
Param key: [in] The keyword, used as the name of the metadata
Param value: [in] The value of the metadata. Metadata can be parsed later if non-string values are desired.

bool (*getDisableDynamicDownstreamWork)(const AttributeObj &attrObj)

Where we have dynamic scheduling, downstream nodes can have their execution disabled by turning on the flag in the upstream attribute.

Note you also have to call setDynamicDownstreamControl on the node to enable this feature. See setDynamicDownstreamControl on INode for further information.

Param attrObj: [in] Reference to the AttributeObj struct representing the current attribute object
Return: Whether downstream nodes connected to this attribute should be disabled from further work

void (*setDisableDynamicDownstreamWork)(const AttributeObj &attrObj, bool value)

Where we have dynamic scheduling, downstream nodes can have their execution disabled by turning on the flag in the upstream attribute.

Note you also have to call setDynamicDownstreamControl on the node to enable this feature. This function allows you to set the flag on the attribute that will disable the downstream node. See setDynamicDownstreamControl on INode for further information.

Param attrObj: [in] Reference to the AttributeObj struct representing the current attribute object
Param value: [in] Whether to disable the downstream connected nodes or not.

void (*setResolvedType)(const AttributeObj &attr, const Type &type)

Sets the resolved type of an extended type.

This should be called by a node from the onConnectionTypeResolve() callback when it determines that an extended-type attribute can be resolved to a specific type. For example a generic 2-input “Add” node could resolve input B and its output attribute type to float when input A is connected to a float. Passing omni::fabric::Type() will reset the attribute type to “unresolved”.

Note

This operation is asynchronous because it is considered as part of a whole-graph type resolution algorithm. It also may not succeed because there could be constraints in the graph that prevent the type from being resolved as requested.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Param type: [in] The new type of the attribute

AttributePortType (*getPortType)(const AttributeObj &attrObj)

Retrieves the port type (such as input, output, state) associated with this attribute.

Param attrObj: [in] The attribute object for which to retrieve the connections
Return: the AttributePortType of this attribute

bool (*isDynamic)(const AttributeObj &attrObj)

Returns whether the attribute is a dynamic attribute (not in the node definition) or not.

Param attrObj: [in] The attribute object for which to query
Return: Whether the attribute is a dynamic one

const char *(*getPath)(const AttributeObj &attrObj)

Returns the full path to the attribute, including the node path.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Return: The full path to the attribute

const char *(*getUnionTypes)(const AttributeObj &attribute)

Return: The string representing the extended union types, nullptr if the attribute is not a union type

bool (*isValid)(const AttributeObj &attrObj)

Returns whether the attribute is still valid or not.

Param attrObj: [in] The attribute object for which to query
Return: Whether the attribute is still valid

NameToken (*ensurePortTypeInName)(NameToken name, AttributePortType portType, bool isBundle)

Return the attribute name with the port type prepended if it isn’t already present.

Param name: [in] The attribute name, with or without the port prefix
Param portType: [in] The port type of the attribute
Param isBundle: [in] true if the attribute name is to be used in a bundle. Note that colon is an illegal character in bundled attributes so an underscore is used instead.
Return: The name with the proper prefix for the given port type

AttributePortType (*getPortTypeFromName)(NameToken name)

Parse the port type from the given attribute name if present.

The port type is indicated by a prefix separated by a colon or underscore in the case of bundled attributes.

Param name: [in] The attribute name
Return: The port type indicated by the attribute prefix if present. AttributePortType::kAttributePortType_Unknown if there is no recognized prefix.

NameToken (*removePortTypeFromName)(NameToken name, bool isBundle)

Return the attribute name with the port type removed if it is present.

For example “inputs:attr” becomes “attr”

Param name: [in] The attribute name, with or without the port prefix
Param isBundle: [in] true if the attribute name is to be used in a bundle. Note that colon is an illegal character in bundled attributes so an underscore is used instead.
Return: The name with the port type prefix removed

bool (*getIsOptionalForCompute)(const AttributeObj &attrObj)

Get the optional compute flag from the attribute.

When true this flag indicates that the attribute does not need to be valid in order for the compute() function to be called. Note that “valid” does not necessarily mean the attribute data is up to date, it only means that everything required to locate the attribute data is available and valid (otherwise outputs would always be invalid).

Param attrObj: [in] The attribute object being queried
Return: True if the attribute is optional for compute

void (*setIsOptionalForCompute)(const AttributeObj &attrObj, bool isOptional)

Set whether the attribute is optional for compute or not; mostly used by generated code.

This flag would be set on attributes that the compute() method may not look at. It would then be up to the compute() method to check validity if it ends up requiring the attribute’s value. You might use this when an attribute value is not used in all compute paths, like a “choice” node that selects exactly one of its inputs to send to the output - only the selected input would need to be valid for compute to succeed.

Param attrObj: [in] The attribute object being modified
Param isOptional: [in] New value for the optional flag on the attribute

bool (*isDeprecated)(const AttributeObj &attrObj)

Get the deprecated flag from the attribute.

When true this flag indicates that the attribute has been deprecated and will be removed in a future version of the node.

Param attrObj: [in] The attribute object being queried
Return: True if the attribute is deprecated

char const *(*deprecationMessage)(const AttributeObj &attributeObj)

Return the deprecation message for an attribute.

Param attributeObj: [in] Attribute to which this function applies
Return: String containing the attribute deprecation message (nullptr if the attribute is not deprecated)

AttributeDataHandle (*getAttributeDataHandle)(const AttributeObj &attrObj, InstanceIndex instanceIdx)

Returns an AttributeDataHandle to access the data on this attribute.

Param attrObj: [in] The attribute object for which to retrieve the data accessor
Param instanceIdx: [in] The instance index relative to the current active instance for which you want to retrieve the data.
Return: The AttributeDataHandle associated with this attribute, to mutate data in the FC

ConstAttributeDataHandle (*getConstAttributeDataHandle)(const AttributeObj &attrObj, InstanceIndex instanceIdx)

Returns a ConstAttributeDataHandle to access the data on this attribute.

Param attrObj: [in] The attribute object for which to retrieve the data accessor
Param instanceIdx: [in] The instance index relative to the current active instance for which you want to retrieve the data.
Return: The ConstAttributeDataHandle associated with this attribute, to read data in the FC

bool (*isRuntimeConstant)(const AttributeObj &attrObj)

Returns whether or not this attribute is a runtime constant or not.

Runtime constant will keep the same value every frame, for every instances This property can be taken advantage in vectorized compute

Param attrObj: [in] The attribute object to query
Return: true if the attribute is a runtime constant, false otherwise

void (*writeComplete)(const AttributeObj *attrObjs, size_t attrObjCount)

Warn the framework that writing to the provided attributes is done, so it can trigger callbacks attached to them.

Param attrObjs: [in] A pointer to an array of attribute objects for which to call change callbacks
Param attrObjCount: [in] The number of object(s) in that array

NameToken (*getNameToken)(const AttributeObj &attr)

Returns the name of the attribute as a token.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Return: The name of the attribute as a token

bool (*setDefaultValue)(AttributeObj const &attr, Type type, void const *value, size_t size)

Set the default value that needs to be used for this attribute This function won’t work on extended attributes This function will write to USD if the owning graph is backed by USD The new value will be immediately propagated to all existing instances.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Param type: [in] The type of the value pointed by “value”. The function will fail is this type is incompatible with the attribute
Param value: [in] A pointer to a value of type “type”. In case the type is an array, value should be a pointer to the base address of the storage
Param size: [in] In case the pointed type is an array, the size of the pointed array. Parameter ignored otherwise.
Return: Whether the value was successfully set or not

FunctionResult (*mapToTarget)(AttributeObj const &attr, NameToken targetAttribName)

Maps a node attribute to an attribute on the owning graph target.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Param targetAttribName: [in] The name of the attribute on the graph target to map to
Return: Whether the attribute was successfully mapped or not. In certain cases, the mapping is deferred until instances are added to the graph, and the return value will reflect this.

NameToken (*getTargetMapping)(AttributeObj const &attr)

Returns the attribute name on the graph target this node attribute maps to.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Return: The target attribute name if mapped, invalid token else (omni::fabric::kUninitializedToken)

bool (*isPassthrough)(AttributeObj const &attr)

Checks if this attribute is a pass through attribute.

Pass through attributes do not own any data.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Return: Returns true if this is a pass through attribute, otherwise returns false.

AttributeObj (*getDataOwningAttribute)(AttributeObj const &attr)

Returns the attribute that will be the owner of the data for runtime taking into account its connections.

Param attr: [in] Reference to the AttributeObj struct representing the attribute object
Return: Returns the attribute that will be the owner of the data for runtime.

bool (*setFabricBackingForMappedAttribute)(AttributeObj const &attr, omni::fabric::FabricId fabricId)

Experimental feature that let you specify that a mapped attribute lives in another fabric cache than the one used by the graph.

This is mandatory that the graph targets are layed out in the exact same way in all fabrics caches referenced by the graph (the main fabric as well as any others referenced through this call)

Param attr: [in] Reference to the AttributeObj struct representing an already mapped attribute object
Param fabricId: [in] The Id representing the fabric cache backing the target data. Passing kInvalidFabricId will restore the default backing.
Return: Returns true if the backing has been successfully changed, false otherwise and an error has been logged