PrimvarData

Fully qualified name: usdex::core::PrimvarData

template<typename T>
class PrimvarData

A templated read-only class to manage the components of UsdGeomPrimvar data as a single object without risk of detaching (copying) arrays.

All of the USD authoring “define” functions in this library accept optional PrimvarData to define e.g normals, display colors, etc.

Public Functions

PrimvarData(

const pxr::TfToken &interpolation,

const pxr::VtArray<T> &values,

int elementSize = -1,

)

Construct non-indexed PrimvarData.

Note

To avoid immediate array iteration, validation does not occur during construction, and is deferred until isValid() is called. This may be counter-intuitive as PrimvarData provides read-only access, but full validation is often only possible within the context of specific surface topology, so premature validation would be redundant.

Parameters:

• interpolation – The primvar interpolation. Must match UsdGeomPrimvar::IsValidInterpolation() to be considered valid.

• values – Read-only accessor to the values array.

• elementSize – Optional element size. This should be fairly uncommon. See GetElementSize for details.

Returns:

The read-only PrimvarData.

PrimvarData(

const pxr::TfToken &interpolation,

const pxr::VtArray<T> &values,

const pxr::VtArray<int> &indices,

int elementSize = -1,

)

Construct indexed PrimvarData.

Note

To avoid immediate array iteration, validation does not occur during construction, and is deferred until isValid() is called. This may be counter-intuitive as PrimvarData provides read-only access, but full validation is often only possible within the context of specific surface topology, so premature validation would be redundant.

Parameters:

• interpolation – The primvar interpolation. Must match UsdGeomPrimvar::IsValidInterpolation() to be considered valid.

• values – Read-only accessor to the values array.

• indices – Read-only accessor to the indices array.

• elementSize – Optional element size. This should be fairly uncommon. See GetElementSize for details.

Returns:

The read-only PrimvarData.

bool setPrimvar(

pxr::UsdGeomPrimvar &primvar,

pxr::UsdTimeCode time = pxr::UsdTimeCode::Default(),

) const

Set data on an existing UsdGeomPrimvar from a PrimvarData that has already been authored.

Any existing authored data on the primvar will be overwritten or blocked with the PrimvarData members.

To copy data from one UsdGeomPrimvar to another, use PrimvarData::get(UsdGeomPrimvar&) to gather the data, then use setPrimvar(UsdGeomPrimvar&) to author it.

Parameters:

• primvar – The previously authored UsdGeomPrimvar.

• time – The time at which the attribute values are written.

Returns:

Whether the UsdGeomPrimvar was completely authored from the member data. Any failure to author may leave the primvar in an unknown state (e.g. it may have been partially authored).

const pxr::TfToken &interpolation() const

The geometric interpolation.

It may be an invalid interpolation. Use PrimvarData::isValid() or UsdGeomPrimvar::IsValidInterpolation() to confirm.

Returns:

The geometric interpolation.

const pxr::VtArray<T> &values() const

Read-only access to the values array.

Bear in mind the values may need to be accessed via indices() or using an elementSize() stride.

It may contain an empty or invalid values array.

Returns:

The primvar values.

bool hasIndices() const

Whether this is indexed or non-indexed PrimvarData

Returns:

Whether this is indexed or non-indexed PrimvarData.

const pxr::VtArray<int> &indices() const

Read-only access to the indices array.

This method throws a runtime error if the PrimvarData is not indexed. For exception-free access, check hasIndices() before calling this.

Note

It may contain an empty or invalid indices array. Use PrimvarData::isValid() to validate that the indices are not out-of-range.

Returns:

The primvar indices.

int elementSize() const

The element size.

Any value less than 1 is considered “non authored” and indicates no element size. This should be the most common case, as element size is a fairly esoteric extension of UsdGeomPrimvar data to account for non-typed array strides such as spherical harmonics float[9] arrays.

See GetElementSize for more details.

Returns:

The primvar element size.

size_t effectiveSize() const

The effective size of the data, having accounted for values, indices, and element size.

This is the number of variable values that “really” exist, as far as a consumer is concerned. The indices & elementSize are used as a storage optimization, but the consumer should consider the effective size as the number of “deduplicated” individual values.

Returns:

The effective size of the data.

bool isValid() const

Whether the data is valid or invalid.

This is a validation check with respect to the PrimvarData itself & the requirements of UsdGeomPrim. It does not validate with respect to specific surface topology data, as no such data is available or consistant across UsdGeomPointBased prim types.

This validation checks the following, in this order, and returns false if any condition fails:

• The interpolation matches UsdGeomPrimvar::IsValidInterpolation().

• The values are not empty. Note that individual values may be invalid (e.g NaN values on a VtFloatArray) but this will not be considered a failure, as some workflows allow for NaN to indicate non-authored elements or “holes” within the data.

• If it is non-indexed, and has elements, that the values divide evenly by elementSize.

• If it is indexed, and has elements, that the indices divide evenly by elementSize.

• If it is indexed, that the indices are all within the expected range of the values array.

Returns:

Whether the data is valid or invalid.

bool isIdentical(const PrimvarData &other) const

Check that all data between two PrimvarData objects is identical.

This differs from the equality operator in that it ensures the VtArray values and indices have not detached.

Parameters:

other – The other PrimvarData.

Returns:

True if all the member data is equal and arrays are identical.

bool index()

Update the values and indices of this PrimvarData object to avoid duplicate values.

Updates will not be made in the following conditions:

• If element size is greater than one.

• If the existing indexing is efficient.

• If there are no duplicate values.

• If the existing indices are invalid

Returns:

True if the values and/or indices were modified.

bool operator==(const PrimvarData &other) const

Check for equality between two PrimvarData objects.

Parameters:

other – The other PrimvarData.

Returns:

True if all the member data is equal (but not necessarily identical arrays).

bool operator!=(const PrimvarData &other) const

Check for in-equality between two PrimvarData objects.

Parameters:

other – The other PrimvarData.

Returns:

True if any member data is not equal (but does not check for identical arrays).

Public Static Functions

static PrimvarData getPrimvarData(

const pxr::UsdGeomPrimvar &primvar,

pxr::UsdTimeCode time = pxr::UsdTimeCode::Default(),

)

Construct a PrimvarData from a UsdGeomPrimvar that has already been authored.

The primvar may be indexed, non-indexed, with or without elements, or it may not even be validly authored scene description. Use isValid() to confirm that valid data has been gathered.

Parameters:

• primvar – The previously authored UsdGeomPrimvar.

• time – The time at which the attribute values are read.

Returns:

The read-only PrimvarData.