|
HDK
|
#include <attribute.h>
Inheritance diagram for UsdAttribute:Friends | |
| class | UsdAttributeQuery |
| class | UsdObject |
| class | UsdPrim |
| class | UsdSchemaBase |
| class | Usd_PrimData |
| struct | UsdPrim_AttrConnectionFinder |
Additional Inherited Members | |
| Static Public Member Functions inherited from UsdObject | |
| static char | GetNamespaceDelimiter () |
| Protected Member Functions inherited from UsdProperty | |
| template<class Derived > | |
| UsdProperty (_Null< Derived >) | |
| bool | _GetTargets (SdfSpecType specType, SdfPathVector *out, bool *foundErrors=nullptr) const |
| Protected Member Functions inherited from UsdObject | |
| template<class Derived > | |
| UsdObject (_Null< Derived >) | |
| UsdObject (const Usd_PrimDataHandle &prim, const SdfPath &proxyPrimPath) | |
| UsdObject (UsdObjType objType, const Usd_PrimDataHandle &prim, const SdfPath &proxyPrimPath, const TfToken &propName) | |
| UsdStage * | _GetStage () const |
| USD_API SdfSpecType | _GetDefiningSpecType () const |
| const Usd_PrimDataHandle & | _Prim () const |
| const TfToken & | _PropName () const |
| const SdfPath & | _ProxyPrimPath () const |
Scenegraph object for authoring and retrieving numeric, string, and array valued data, sampled over time.
The allowed value types for UsdAttribute are dictated by the Sdf ("Scene Description Foundations") core's data model, which we summarize in Usd_Page_Datatypes .
In addition to its value type, an Attribute has two other defining qualities:
SdfVariabilityVarying), or only a default (GetVariability() == SdfVariabilityUniform). For more on reasoning about time samples, see Value & Time-Sample Accessors.false), or is a user-defined, custom attribute. schema attributes will always be defined on a prim of the schema type, ans may possess fallback values from the schema, whereas custom attributes must always first be authored in order to be defined. Note that custom is actually an aspect of UsdProperty, as UsdRelationship can also be custom or provided by a schema.One can always create an attribute generically via UsdPrim::CreateAttribute(), which ensures that an attribute "is defined" in the current UsdEditTarget . In order to author any metadata or a default or timesample for an attribute, it must first be defined. It is sufficient that the attribute be defined in any one of the layers participating in the stage's current composition; for builtin attributes (those belonging to the owning prim's defining schema, i.e. the most specific subclass of UsdTypedSchema for which prim.IsA<schema>() will evaluate to true) there need be no authored scene description, because a definition is provided by the prim's schema definition.
Creating an attribute does not imply that the attribute has a value. More broadly, in the following code:
The UsdAttribute passes the bool test, because it is defined; however, inside the clause, we have no guarantee that attr has a value.
UsdAttribute supports two interpolation behaviors when retrieving attribute values at times where no value is explicitly authored. The desired behavior may be specified via UsdStage::SetInterpolationType. That behavior will be used for all calls to UsdAttribute::Get.
The supported interpolation types are:
Linear interpolation is only supported for certain data types. See USD_LINEAR_INTERPOLATION_TYPES for the list of these types. Types that do not support linear interpolation will use held interpolation instead.
Linear interpolation is done element-by-element for array, vector, and matrix data types. If linear interpolation is requested for two array values with different sizes, held interpolation will be used instead.
While prims can effectively be removed from a scene by deactivating them, properties cannot. However, it is possible to block an attribute's value, thus making the attribute behave as if it has a definition (and possibly metadata), but no authored value.
One blocks an attribute using UsdAttribute::Block(), which will block the attribute in the stage's current UsdEditTarget, by authoring an SdfValueBlock in the attribute's default, and only values authored in weaker layers than the editTarget will be blocked. If the value block is the strongest authored opinion for the attribute, the HasAuthoredValue() method will return false, and the HasValue() and Get() methods will only return true if the attribute possesses a fallback value from the prim's schema. "Unblocking" a blocked attribute is as simple as setting a default or timeSample value for the attribute in the same or stronger layer.
The semantics of Value Clips necessitate the ability to selectively block an attribute's value for only some intervals in its authored range of samples. One can block an attribute's value at time t by calling attr.Set(SdfValueBlock, t) When an attribute is thusly "partially blocked", UsdAttribute::Get() will succeed only for those time intervals whose left/earlier bracketing timeSample is not SdfValueBlock.
Due to this time-varying potential of value blocking, it may be the case that an attribute's HasAuthoredValue() and HasValue() methods both return true (because they do not and cannot consider time-varying blocks), but Get() may yet return false over some intervals.
If an attribute's value type is SdfAssetPath or SdfAssetPathArray, Get() performs extra work to compute the resolved asset paths, using the layer that has the strongest value opinion as the anchor for "relative" asset paths. Both the unresolved and resolved results are available through SdfAssetPath::GetAssetPath() and SdfAssetPath::GetResolvedPath(), respectively.
Clients that call Get() on many asset-path-valued attributes may wish to employ an ArResolverScopedCache to improve asset path resolution performance.
Definition at line 176 of file attribute.h.
|
inline |
Construct an invalid attribute.
Definition at line 179 of file attribute.h.
| USD_API bool UsdAttribute::AddConnection | ( | const SdfPath & | source, |
| UsdListPosition | position = UsdListPositionBackOfPrependList |
||
| ) | const |
Adds source to the list of connections, in the position specified by position.
Issue an error if source identifies a prototype prim or an object descendant to a prototype prim. It is not valid to author connections to these objects.
What data this actually authors depends on what data is currently authored in the authoring layer, with respect to list-editing semantics, which we will document soon
Remove all time samples on an attribute and author a block default value. This causes the attribute to resolve as if there were no authored value opinions in weaker layers.
See Attribute Value Blocking for more information, including information on time-varying blocking.
| USD_API bool UsdAttribute::Clear | ( | ) | const |
Clears the authored default value and all time samples for this attribute at the current EditTarget and returns true on success.
Calling clear when either no value is authored or no spec is present, is a silent no-op returning true.
This method does not affect any other data authored on this attribute.
| USD_API bool UsdAttribute::ClearAtTime | ( | UsdTimeCode | time | ) | const |
Clear the authored value for this attribute at the given time, at the current EditTarget and return true on success. UsdTimeCode::Default() can be used to clear the default value.
Calling clear when either no value is authored or no spec is present, is a silent no-op returning true.
| USD_API bool UsdAttribute::ClearColorSpace | ( | ) | const |
Clears authored color-space value on the attribute.
| USD_API bool UsdAttribute::ClearConnections | ( | ) | const |
Remove all opinions about the connections list from the current edit target.
| USD_API bool UsdAttribute::ClearDefault | ( | ) | const |
Shorthand for ClearAtTime(UsdTimeCode::Default()).
|
inline |
Perform value resolution to fetch the value of this attribute at the requested UsdTimeCode time, which defaults to default.
If no value is authored at time but values are authored at other times, this function will return an interpolated value based on the stage's interpolation type. See Attribute Value Interpolation.
If no value is authored and no fallback value is provided by the schema for this attribute, this function will return false. If the consumer's use-case requires a default value, the consumer will need to provide one, possibly using GetTypeName().GetDefaultValue().
This templated accessor is designed for high performance data-streaming applications, allowing one to fetch data into the same container repeatedly, avoiding memory allocations when possible (VtArray containers will be resized as necessary to conform to the size of data being read).
This template is only instantiated for the valid scene description value types and their corresponding VtArray containers. See Usd_Page_Datatypes for the complete list of types.
Values are retrieved without regard to this attribute's variability. For example, a uniform attribute may retrieve time sample values if any are authored. However, the USD_VALIDATE_VARIABILITY TF_DEBUG code will cause debug information to be output if values that are inconsistent with this attribute's variability are retrieved. See UsdAttribute::GetVariability for more details.
For more details, see Usd_ValueResolution , and also Attributes of type SdfAssetPath and UsdAttribute::Get() for information on how to retrieve resolved asset paths from SdfAssetPath-valued attributes.
Definition at line 436 of file attribute.h.
| USD_API bool UsdAttribute::Get | ( | VtValue * | value, |
| UsdTimeCode | time = UsdTimeCode::Default() |
||
| ) | const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Type-erased access, often not as efficient as typed access.
| USD_API bool UsdAttribute::GetBracketingTimeSamples | ( | double | desiredTime, |
| double * | lower, | ||
| double * | upper, | ||
| bool * | hasTimeSamples | ||
| ) | const |
Populate lower and upper with the next greater and lesser value relative to the desiredTime. Return false if no value exists or an error occurs, true if either a default value or timeSamples exist.
Use standard resolution semantics: if a stronger default value is authored over weaker time samples, the default value hides the underlying timeSamples.
1) If a sample exists at the desiredTime, set both upper and lower to desiredTime.
2) If samples exist surrounding, but not equal to the desiredTime, set lower and upper to the bracketing samples nearest to the desiredTime.
3) If the desiredTime is outside of the range of authored samples, clamp upper and lower to the nearest time sample.
4) If no samples exist, do not modify upper and lower and set hasTimeSamples to false.
In cases (1), (2) and (3), set hasTimeSamples to true.
All four cases above are considered to be successful, thus the return value will be true and no error message will be emitted.
Gets the color space in which the attribute is authored.
| USD_API bool UsdAttribute::GetConnections | ( | SdfPathVector * | sources | ) | const |
Compose this attribute's connections and fill sources with the result. All preexisting elements in sources are lost.
Returns true if any connection path opinions have been authored and no composition errors were encountered, returns false otherwise. Note that authored opinions may include opinions that clear the connections and a return value of true does not necessarily indicate that sources will contain any connection paths.
See Usd_ScenegraphInstancing_TargetsAndConnections for details on behavior when targets point to objects beneath instance prims.
The result is not cached, and thus recomputed on each query.
| USD_API size_t UsdAttribute::GetNumTimeSamples | ( | ) | const |
Returns the number of time samples that have been authored.
This method uses the standard resolution semantics, so if a stronger default value is authored over weaker time samples, the default value will hide the underlying timesamples.
| USD_API UsdResolveInfo UsdAttribute::GetResolveInfo | ( | UsdTimeCode | time | ) | const |
Perform value resolution to determine the source of the resolved value of this attribute at the requested UsdTimeCode time.
| USD_API UsdResolveInfo UsdAttribute::GetResolveInfo | ( | ) | const |
Perform value resolution to determine the source of the resolved value of this attribute at any non-default time.
Often (i.e. unless the attribute is affected by Value Clips) the source of the resolved value does not vary over time. See UsdAttributeQuery as an example that takes advantage of this quality of value resolution.
Return the roleName for this attribute's typeName.
| USD_API bool UsdAttribute::GetTimeSamples | ( | std::vector< double > * | times | ) | const |
Populates a vector with authored sample times. Returns false only on error.
This method uses the standard resolution semantics, so if a stronger default value is authored over weaker time samples, the default value will hide the underlying timesamples.
| times | - on return, will contain the sorted, ascending timeSample ordinates. Any data in times will be lost, as this method clears times. |
| USD_API bool UsdAttribute::GetTimeSamplesInInterval | ( | const GfInterval & | interval, |
| std::vector< double > * | times | ||
| ) | const |
Populates a vector with authored sample times in interval. Returns false only on an error.
| interval | - the GfInterval on which to gather time samples. |
| times | - on return, will contain the sorted, ascending timeSample ordinates. Any data in times will be lost, as this method clears times. |
| USD_API SdfValueTypeName UsdAttribute::GetTypeName | ( | ) | const |
Return the "scene description" value type name for this attribute.
|
static |
Populates the given vector, times with the union of all the authored sample times on all of the given attributes, attrs.
attrs, opening them if needed. This may be expensive, especially if many clips are involved.The accumulated sample times will be in sorted (increasing) order and will not contain any duplicates.
This clears any existing values in the times vector before accumulating sample times of the given attributes.
attr are invalid or if there's an error when fetching time-samples for any of the attributes.
|
static |
Populates the given vector, times with the union of all the authored sample times in the GfInterval, interval on all of the given attributes, attrs.
attrs, in the given interval, opening them if necessary.The accumulated sample times will be in sorted (increasing) order and will not contain any duplicates.
This clears any existing values in the times vector before accumulating sample times of the given attributes.
attr are invalid or if there's an error fetching time-samples for any of the attributes.| USD_API SdfVariability UsdAttribute::GetVariability | ( | ) | const |
An attribute's variability expresses whether it is intended to have time-samples (SdfVariabilityVarying), or only a single default value (SdfVariabilityUniform).
Variability is required meta-data of all attributes, and its fallback value is SdfVariabilityVarying.
| USD_API bool UsdAttribute::HasAuthoredConnections | ( | ) | const |
Return true if this attribute has any authored opinions regarding connections. Note that this includes opinions that remove connections, so a true return does not necessarily indicate that this attribute has connections.
| USD_API bool UsdAttribute::HasAuthoredValue | ( | ) | const |
Return true if this attribute has either an authored default value or authored time samples. If the attribute has been blocked, then return false
| USD_API bool UsdAttribute::HasAuthoredValueOpinion | ( | ) | const |
true even when an attribute is blocked. Please use HasAuthoredValue() instead. If you truly need to know whether the attribute has any authored value opinions, including blocks, you can make the following query: attr.GetResolveInfo().HasAuthoredValueOpinion()Return true if this attribute has either an authored default value or authored time samples.
| USD_API bool UsdAttribute::HasColorSpace | ( | ) | const |
Returns whether color-space is authored on the attribute.
| USD_API bool UsdAttribute::HasFallbackValue | ( | ) | const |
Return true if this attribute has a fallback value provided by a registered schema.
| USD_API bool UsdAttribute::HasValue | ( | ) | const |
Return true if this attribute has an authored default value, authored time samples or a fallback value provided by a registered schema. If the attribute has been blocked, then return true if and only if it has a fallback value.
Removes target from the list of targets.
Issue an error if source identifies a prototype prim or an object descendant to a prototype prim. It is not valid to author connections to these objects.
|
inline |
Set the value of this attribute in the current UsdEditTarget to value at UsdTimeCode time, which defaults to default.
Values are authored without regard to this attribute's variability. For example, time sample values may be authored on a uniform attribute. However, the USD_VALIDATE_VARIABILITY TF_DEBUG code will cause debug information to be output if values that are inconsistent with this attribute's variability are authored. See UsdAttribute::GetVariability for more details.
T does not match this attribute's defined scene description type exactly, or if there is no existing definition for the attribute. Definition at line 477 of file attribute.h.
| USD_API bool UsdAttribute::Set | ( | const char * | value, |
| UsdTimeCode | time = UsdTimeCode::Default() |
||
| ) | const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. As a convenience, we allow the setting of string value typed attributes via a C string value.
| USD_API bool UsdAttribute::Set | ( | const VtValue & | value, |
| UsdTimeCode | time = UsdTimeCode::Default() |
||
| ) | const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Sets the color space of the attribute to colorSpace.
| USD_API bool UsdAttribute::SetConnections | ( | const SdfPathVector & | sources | ) | const |
Make the authoring layer's opinion of the connection list explicit, and set exactly to sources.
Issue an error if source identifies a prototype prim or an object descendant to a prototype prim. It is not valid to author connections to these objects.
If any path in sources is invalid, issue an error and return false.
| USD_API bool UsdAttribute::SetTypeName | ( | const SdfValueTypeName & | typeName | ) | const |
Set the value for typeName at the current EditTarget, return true on success, false if the value can not be written.
Note that this value should not be changed as it is typically either automatically authored or provided by a property definition. This method is provided primarily for fixing invalid scene description.
| USD_API bool UsdAttribute::SetVariability | ( | SdfVariability | variability | ) | const |
Set the value for variability at the current EditTarget, return true on success, false if the value can not be written.
Note that this value should not be changed as it is typically either automatically authored or provided by a property definition. This method is provided primarily for fixing invalid scene description.
| USD_API bool UsdAttribute::ValueMightBeTimeVarying | ( | ) | const |
Return true if it is possible, but not certain, that this attribute's value changes over time, false otherwise.
If this function returns false, it is certain that this attribute's value remains constant over time.
This function is equivalent to checking if GetNumTimeSamples() > 1, but may be more efficient since it does not actually need to get a full count of all time samples.
|
friend |
Definition at line 639 of file attribute.h.
|
friend |
Definition at line 635 of file attribute.h.
Definition at line 636 of file attribute.h.
Definition at line 637 of file attribute.h.
|
friend |
Definition at line 640 of file attribute.h.
|
friend |
Definition at line 638 of file attribute.h.
1.8.6