HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | List of all members
UsdUtilsSparseAttrValueWriter Class Reference

#include <sparseValueWriter.h>

Public Member Functions

USDUTILS_API UsdUtilsSparseAttrValueWriter (const UsdAttribute &attr, const VtValue &defaultValue=VtValue())
 
USDUTILS_API UsdUtilsSparseAttrValueWriter (const UsdAttribute &attr, VtValue *defaultValue)
 
USDUTILS_API bool SetTimeSample (const VtValue &value, const UsdTimeCode time)
 
USDUTILS_API bool SetTimeSample (VtValue *value, const UsdTimeCode time)
 
const UsdAttribute & GetAttr () const
 Returns the attribute that's held in the sparse value writer. More...
 

Detailed Description

A utility class for authoring time-varying attribute values with simple run-length encoding, by skipping any redundant time-samples. Time-samples that are close enough to each other, with relative difference smaller than a fixed epsilon value are considered to be equivalent. This is to avoid unnecessary authoring of time-samples caused by numerical fuzz in certain computations.

For vectors, matrices, and other composite types (like quaternions and arrays), each component is compared with the corresponding component for closeness. The chosen epsilon value for double precision floating point numbers is 1e-12. For single-precision, it is 1e-6 and for half-precision, it is 1e-2.

Example c++ usage:

UsdGeomSphere sphere = UsdGeomSphere::Define(stage, SdfPath("/Sphere"));
UsdAttribute radius = sphere.CreateRadiusAttr();
UsdUtilsSparseAttrValueWriter attrValueWriter(radius,
/*defaultValue*/ VtValue(1.0));
attrValueWriter.SetTimeSample(VtValue(10.0), UsdTimeCode(1.0));
attrValueWriter.SetTimeSample(VtValue(10.0), UsdTimeCode(2.0));
attrValueWriter.SetTimeSample(VtValue(10.0), UsdTimeCode(3.0));
attrValueWriter.SetTimeSample(VtValue(20.0), UsdTimeCode(4.0));

Equivalent python example:

sphere = UsdGeom.Sphere.Define(stage, Sdf.Path("/Sphere"))
radius = sphere.CreateRadiusAttr()
attrValueWriter = UsdUtils.SparseAttrValueWriter(radius, defaultValue=1.0)
attrValueWriter.SetTimeSample(10.0, 1.0)
attrValueWriter.SetTimeSample(10.0, 2.0)
attrValueWriter.SetTimeSample(10.0, 3.0)
attrValueWriter.SetTimeSample(20.0, 4.0)

In the above examples, the specified default value of radius (1.0) will not be authored into scene description since it matches the fallback value. Additionally, the time-sample authored at time=2.0 will be skipped since it is redundant. Also note that for correct behavior, the calls to SetTimeSample() must be made with sequentially increasing time values. If not, a coding error is issued and the authored animation may be incorrect.

Definition at line 88 of file sparseValueWriter.h.

Constructor & Destructor Documentation

USDUTILS_API UsdUtilsSparseAttrValueWriter::UsdUtilsSparseAttrValueWriter ( const UsdAttribute &  attr,
const VtValue &  defaultValue = VtValue() 
)

The constructor initializes the data required for run-length encoding of time-samples. It also sets the default value of attr to defaultValue, if defaultValue is non-empty and different from the existing default value of attr.

defaultValue can be unspecified (or left empty) if you don't care about authoring a default value. In this case, the sparse authoring logic is initialized with the existing authored default value or the fallback value, if attr has one.

USDUTILS_API UsdUtilsSparseAttrValueWriter::UsdUtilsSparseAttrValueWriter ( const UsdAttribute &  attr,
VtValue *  defaultValue 
)

The constructor initializes the data required for run-length encoding of time-samples. It also sets the default value of attr to defaultValue, if defaultValue is non-empty and different from the existing default value of attr.

It defaultValue is null or points to an empty VtValue, the sparse authoring logic is initialized with the existing authored default value or the fallback value, if attr has one.

For efficiency, this function swaps out the given defaultValue, leaving it empty.

Member Function Documentation

const UsdAttribute& UsdUtilsSparseAttrValueWriter::GetAttr ( ) const
inline

Returns the attribute that's held in the sparse value writer.

Definition at line 139 of file sparseValueWriter.h.

USDUTILS_API bool UsdUtilsSparseAttrValueWriter::SetTimeSample ( const VtValue &  value,
const UsdTimeCode  time 
)

Sets a new time-sample on the attribute with given value at the given time. The time-sample is only authored if it's different from the previously set time-sample, in which case the previous time-sample is also authored, in order to to end the previous run of contiguous identical values and start a new run.

This incurs a copy of value. Also, the value will be held in memory at least until the next time-sample is written or until the SparseAttrValueWriter instance is destroyed.

USDUTILS_API bool UsdUtilsSparseAttrValueWriter::SetTimeSample ( VtValue *  value,
const UsdTimeCode  time 
)

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

For efficiency, this function swaps out the given value, leaving it empty. The value will be held in memory at least until the next time-sample is written or until the SparseAttrValueWriter instance is destroyed.

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