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
-
const char *(*getName)(const AttributeObj &attr)