UsdAttributeLimits Class Reference

Provides API for retrieving and authoring values within a particular sub-dictionary of the limits dictionary metadata field on a UsdAttribute instance. More...

#include <attributeLimits.h>

Classes
class	ValidationResult
	Validation information for a limits sub-dictionary. More...

Public Member Functions
	UsdAttributeLimits ()=default
	Construct an invalid limits object.
USD_API	UsdAttributeLimits (const UsdAttribute &attr, const TfToken &subDictKey)
	Construct a limits object for the sub-dictionary given by subDictKey in attr's limits dictionary.
	operator bool () const
	Return true if this limits object is valid.
bool	operator== (const UsdAttributeLimits &rhs) const
	Equality operator.
bool	operator!= (const UsdAttributeLimits &rhs) const
	Inequality operator.
Object Information
Information about the limits object itself.
USD_API bool	IsValid () const
	Return whether the limits object is valid.
USD_API UsdAttribute	GetAttribute () const
	Return the limits object's attribute.
USD_API TfToken	GetSubDictKey () const
	Return the sub-dictionary key the limits object is using.
Opinions API
API for determining whether authored opinions exist, and clearing them.
USD_API bool	HasAuthored () const
	Return whether any authored opinions exist for the limits sub-dictionary.
USD_API bool	Clear ()
	Clear all authored opinions for the limits sub-dictionary at the current edit target.
USD_API bool	HasAuthored (const TfToken &key) const
	Return whether an authored opinion for key exists in the limits sub-dictionary.
USD_API bool	Clear (const TfToken &key)
	Clear the authored opinion for key in the limits sub-dictionary.
USD_API bool	HasAuthoredMinimum () const
	Return whether an authored minimum value opinion exists in the limits sub-dictionary.
USD_API bool	ClearMinimum ()
	Clear the authored minimum value opinion in the limits sub-dictionary.
USD_API bool	HasAuthoredMaximum () const
	Return whether an authored maximum value opinion exists in the limits sub-dictionary.
USD_API bool	ClearMaximum ()
	Clear the authored maximum value opinion in the limits sub-dictionary.
Sub-dictionary Operations
Operations related to the entire limits sub-dictionary.
USD_API bool	Validate (const VtDictionary &subDict, ValidationResult *result=nullptr) const
	Return whether subDict is a valid limits sub-dictionary.
USD_API bool	Set (const VtDictionary &subDict)
	Set the entire limits sub-dictionary to subDict.
Typed Value API
Templated API for retrieving and authoring individual limits values.
template<typename T >
std::optional< T >	Get (const TfToken &key) const
	Return the value encoded under key in the limits sub-dictionary.
template<typename T >
T	GetOr (const TfToken &key, const T &defaultValue) const
	Return the value encoded under key in the limits sub-dictionary.
template<typename T >
bool	Set (const TfToken &key, const T &value)
	Set the value encoded under key in the limits sub-dictionary to value.
template<typename T >
std::optional< T >	GetMinimum () const
	Return the minimum value from the limits sub-dictionary.
template<typename T >
T	GetMinimumOr (const T &defaultValue) const
	Return the minimum value from the limits sub-dictionary.
template<typename T >
bool	SetMinimum (const T &value)
	Set the minimum value in the limits sub-dictionary.
template<typename T >
std::optional< T >	GetMaximum () const
	Return the maximum value from the limits sub-dictionary.
template<typename T >
T	GetMaximumOr (const T &defaultValue) const
	Return the maximum value from the limits sub-dictionary.
template<typename T >
bool	SetMaximum (const T &value)
	Set the maximum value in the limits sub-dictionary.
Type-erased Value API
VtValue-based overloads, mainly for use by the Python wrapping.
USD_API VtValue	Get (const TfToken &key) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
USD_API bool	Set (const TfToken &key, const VtValue &value)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
USD_API VtValue	GetMinimum () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
USD_API bool	SetMinimum (const VtValue &value)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
USD_API VtValue	GetMaximum () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
USD_API bool	SetMaximum (const VtValue &value)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Detailed Description

Provides API for retrieving and authoring values within a particular sub-dictionary of the limits dictionary metadata field on a UsdAttribute instance.

Within a given sub-dictionary, minimum and maximum values are encoded under the UsdLimitsKeys->Minimum and UsdLimitsKeys->Maximum keys, respectively.

For example, to express that an attribute's typical useful value range is between 5 and 10 (the "soft limits"), but that it must be between 0 and 15 (the "hard limits"), a typical limits dictionary might look like the following:

def "MyPrim"
{
    int attr = 7 (
        limits = {
            dictionary soft = {
                int minimum = 5
                int maximum = 10
            }
            dictionary hard = {
                int minimum = 0
                int maximum = 15
            }
        }
    )
}

To work with these values, use the UsdAttributeLimits objects returned by UsdAttribute::GetSoftLimits() and UsdAttribute::GetHardLimits(), which edit and interpret the "soft" and "hard" sub-dictionaries, respectively.

UsdAttributeLimits softLimits = attr.GetSoftLimits();
if (x >= softLimits.GetMinimumOr(0) && x <= softLimits.GetMaximumOr(100)) {
    // x is within the soft limits, 5 and 10. The passed-in defaults
    // (0 and 100) are ignored since both min and max values are authored
}

You can also create custom sub-dictionaries:

UsdAttributeLimits customLimits = attr.GetLimits(TfToken("myCustomSubDict"));
customLimits.SetMinimum(50);
customLimits.SetMaximum(100);
customLimits.Set(TfToken("customKey"), 42.5));

Combined with the starting limits dictionary above, this would produce:

def "MyPrim"
{
    int attr = 7 (
        limits = {
            dictionary soft = {
                int minimum = 5
                int maximum = 10
            }
            dictionary hard = {
                int minimum = 0
                int maximum = 15
            }
            dictionary myCustomSubDict = {
                int minimum = 50,
                int maximum = 100,
                double customKey = 42.5
            }
        }
    )
}

Definition at line 107 of file attributeLimits.h.

Constructor & Destructor Documentation

UsdAttributeLimits() [1/2]

UsdAttributeLimits ( )

default

Construct an invalid limits object.

Calling "set" operations on an invalid limits object will post errors. "Get" operations will return empty.

UsdAttributeLimits() [2/2]

USD_API UsdAttributeLimits	(	const UsdAttribute &	attr,
		const TfToken &	subDictKey
	)

Construct a limits object for the sub-dictionary given by subDictKey in attr's limits dictionary.

Member Function Documentation

Clear() [1/2]

USD_API bool Clear

(

)

Clear all authored opinions for the limits sub-dictionary at the current edit target.

Return true if successful.

Clear() [2/2]

USD_API bool Clear

(

const TfToken &

key

)

Clear the authored opinion for key in the limits sub-dictionary.

Return true if successful.

ClearMaximum()

USD_API bool ClearMaximum

(

)

Clear the authored maximum value opinion in the limits sub-dictionary.

Return true if successful.

ClearMinimum()

USD_API bool ClearMinimum

(

)

Clear the authored minimum value opinion in the limits sub-dictionary.

Return true if successful.

Get() [1/2]

std::optional< T > Get ( const TfToken &  key ) const

inline

Return the value encoded under key in the limits sub-dictionary.

Return an empty std::optional if no authored or fallback value is present, or if the template type T does not match the type of the stored value.

Definition at line 430 of file attributeLimits.h.

Get() [2/2]

USD_API VtValue Get

(

const TfToken &

key

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

GetAttribute()

USD_API UsdAttribute GetAttribute

(

)

const

Return the limits object's attribute.

GetMaximum() [1/2]

std::optional< T > GetMaximum

inline

Return the maximum value from the limits sub-dictionary.

Return an empty std::optional if no authored or fallback value is present, or if the template type T does not match the type of the stored value.

Definition at line 498 of file attributeLimits.h.

GetMaximum() [2/2]

USD_API VtValue GetMaximum

(

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

GetMaximumOr()

T GetMaximumOr ( const T &  defaultValue ) const

inline

Return the maximum value from the limits sub-dictionary.

Return defaultValue if no authored or fallback value is present, or if the template type T does not match the type of the stored value.

Definition at line 505 of file attributeLimits.h.

GetMinimum() [1/2]

std::optional< T > GetMinimum

inline

Return the minimum value from the limits sub-dictionary.

Return an empty std::optional if no authored or fallback value is present, or if the template type T does not match the type of the stored value.

Definition at line 477 of file attributeLimits.h.

GetMinimum() [2/2]

USD_API VtValue GetMinimum

(

)

const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

GetMinimumOr()

T GetMinimumOr ( const T &  defaultValue ) const

inline

Return the minimum value from the limits sub-dictionary.

Return defaultValue if no authored or fallback value is present, or if the template type T does not match the type of the stored value.

Definition at line 484 of file attributeLimits.h.

GetOr()

T GetOr ( const TfToken &  key, const T &  defaultValue  ) const

inline

Return the value encoded under key in the limits sub-dictionary.

Return defaultValue if no authored or fallback value is present, or if the template type T does not match the type of the stored value.

Definition at line 448 of file attributeLimits.h.

GetSubDictKey()

USD_API TfToken GetSubDictKey

(

)

const

Return the sub-dictionary key the limits object is using.

HasAuthored() [1/2]

USD_API bool HasAuthored

(

)

const

Return whether any authored opinions exist for the limits sub-dictionary.

HasAuthored() [2/2]

USD_API bool HasAuthored

(

const TfToken &

key

)

const

Return whether an authored opinion for key exists in the limits sub-dictionary.

HasAuthoredMaximum()

USD_API bool HasAuthoredMaximum

(

)

const

Return whether an authored maximum value opinion exists in the limits sub-dictionary.

HasAuthoredMinimum()

USD_API bool HasAuthoredMinimum

(

)

const

Return whether an authored minimum value opinion exists in the limits sub-dictionary.

IsValid()

USD_API bool IsValid

(

)

const

Return whether the limits object is valid.

Calling "set" operations on an invalid limits object will post errors. "Get" operations will return empty.

operator bool()

operator bool ( ) const

inlineexplicit

Return true if this limits object is valid.

See also

IsValid()

Definition at line 405 of file attributeLimits.h.

operator!=()

bool operator!= ( const UsdAttributeLimits &  rhs ) const

inline

Inequality operator.

Definition at line 415 of file attributeLimits.h.

operator==()

bool operator== ( const UsdAttributeLimits &  rhs ) const

inline

Equality operator.

Definition at line 410 of file attributeLimits.h.

Set() [1/3]

bool Set ( const TfToken &  key, const T &  value  )

inline

Set the value encoded under key in the limits sub-dictionary to value.

Return true if successful.

Definition at line 468 of file attributeLimits.h.

Set() [2/3]

USD_API bool Set	(	const TfToken &	key,
		const VtValue &	value
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Set() [3/3]

USD_API bool Set

(

const VtDictionary &

subDict

)

Set the entire limits sub-dictionary to subDict.

Return true if successful.

The types of encoded minimum and maximum values must match the value type of the attribute.

SetMaximum() [1/2]

bool SetMaximum ( const T &  value )

inline

Set the maximum value in the limits sub-dictionary.

Return true if successful.

The type of value must match the attribute's value type.

Definition at line 512 of file attributeLimits.h.

SetMaximum() [2/2]

USD_API bool SetMaximum

(

const VtValue &

value

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SetMinimum() [1/2]

bool SetMinimum ( const T &  value )

inline

Set the minimum value in the limits sub-dictionary.

Return true if successful.

The type of value must match the attribute's value type.

Definition at line 491 of file attributeLimits.h.

SetMinimum() [2/2]

USD_API bool SetMinimum

(

const VtValue &

value

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Validate()

USD_API bool Validate	(	const VtDictionary &	subDict,
		ValidationResult *	result = nullptr
	)		const

Return whether subDict is a valid limits sub-dictionary.

If result is provided, fill it in. To be valid, the types of encoded minimum and maximum values must match the value type of the attribute.

See also

ValidationResult

---

The documentation for this class was generated from the following file:

• pxr/usd/usd/attributeLimits.h