NameCache#

Fully qualified name: usdex::core::NameCache

class NameCache#

The NameCache class provides a mechanism for generating unique and valid names for UsdPrims and their UsdProperties.

The class ensures that generated names are valid according to OpenUSD name requirements and are unique within the context of sibling Prim and Property names.

The cache provides a performant alternative to repeated queries by caching generated names and managing reserved names for Prims and Properties.

Because reserved names are held in the cache, collisions can be avoided in cases where the Prim or Property has not been authored in the Stage. Names can be requested individually or in bulk, supporting a range of authoring patterns. Cache entries are based on prim path and are not unique between stages or layers.

The name cache can be used in several authoring contexts, by providing a particular parent type:

• SdfPath: Useful when generating names before authoring anything in USD.

• UsdPrim: Useful when authoring in a UsdStage.

• SdfPrimSpec: Useful when authoring in an SdfLayer

When a cache entry is first created it will be populated with existing names depending on the scope of the supplied parent.

• Given an SdfPath no names will be reserved

• Given a UsdPrim it’s existing child Prim and Property names (after composition) will be reserved

• Given an SdfPrimSpec it’s existing child Prim and Property names (before composition) will be reserved

The parent must be stable to be useable as a cache key.

• An SdfPath must be an absolute prim path containing no variant selections.

• A UsdPrim must be valid.

• An SdfPrimSpec must not be NULL or dormant.

The pseudo root cannot have properties, therefore it is not useable as a parent for property related functions.

Warning

This class does not automatically invalidate cached values based on changes to the prims from which values were cached. Additionally, a separate instance of this class should be used per-thread, calling methods from multiple threads is not safe.

Public Functions

NameCache()#

~NameCache()#

pxr::TfToken getPrimName(

const pxr::SdfPath &parent,

const std::string &name,

)#

Make a name valid and unique for use as the name of a child of the given prim.

An invalid token is returned on failure.

Parameters:

• parent – The parent path

• name – Preferred name

Returns:

Valid and unique name token

pxr::TfToken getPrimName(

const pxr::UsdPrim &parent,

const std::string &name,

)#

Make a name valid and unique for use as the name of a child of the given prim.

An invalid token is returned on failure.

Parameters:

• parent – The parent prim

• name – Preferred name

Returns:

Valid and unique name token

pxr::TfToken getPrimName(

const pxr::SdfPrimSpecHandle parent,

const std::string &name,

)#

Make a name valid and unique for use as the name of a child of the given prim.

An invalid token is returned on failure.

Parameters:

• parent – The parent prim spec

• name – Preferred name

Returns:

Valid and unique name token

pxr::TfTokenVector getPrimNames(

const pxr::SdfPath &parent,

const std::vector<std::string> &names,

)#

Make a list of names valid and unique for use as the names of a children of the given prim.

Parameters:

• parent – The parent path

• names – Preferred names

Returns:

A vector of Valid and unique name tokens ordered to match the preferred names

pxr::TfTokenVector getPrimNames(

const pxr::UsdPrim &parent,

const std::vector<std::string> &names,

)#

Make a list of names valid and unique for use as the names of a children of the given prim.

Parameters:

• parent – The parent prim

• names – Preferred names

Returns:

A vector of Valid and unique name tokens ordered to match the preferred names

pxr::TfTokenVector getPrimNames(

const pxr::SdfPrimSpecHandle parent,

const std::vector<std::string> &names,

)#

Make a list of names valid and unique for use as the names of a children of the given prim.

Parameters:

• parent – The parent prim spec

• names – Preferred names

Returns:

A vector of Valid and unique name tokens ordered to match the preferred names

pxr::TfToken getPropertyName(

const pxr::SdfPath &parent,

const std::string &name,

)#

Make a name valid and unique for use as the name of a property on the given prim.

An invalid token is returned on failure.

Parameters:

• parent – The prim path

• name – Preferred name

Returns:

Valid and unique name token

pxr::TfToken getPropertyName(

const pxr::UsdPrim &parent,

const std::string &name,

)#

Make a name valid and unique for use as the name of a property on the given prim.

An invalid token is returned on failure.

Parameters:

• parent – The parent prim

• name – Preferred name

Returns:

Valid and unique name token

pxr::TfToken getPropertyName(

const pxr::SdfPrimSpecHandle parent,

const std::string &name,

)#

Make a name valid and unique for use as the name of a property on the given prim.

An invalid token is returned on failure.

Parameters:

• parent – The parent prim spec

• name – Preferred name

Returns:

Valid and unique name token

pxr::TfTokenVector getPropertyNames(

const pxr::SdfPath &parent,

const std::vector<std::string> &names,

)#

Make a list of names valid and unique for use as the names of properties on the given prim.

Parameters:

• parent – The parent path

• names – Preferred names

Returns:

A vector of Valid and unique name tokens ordered to match the preferred names

pxr::TfTokenVector getPropertyNames(

const pxr::UsdPrim &parent,

const std::vector<std::string> &names,

)#

Make a list of names valid and unique for use as the names of properties on the given prim.

Parameters:

• parent – The parent prim

• names – Preferred names

Returns:

A vector of Valid and unique name tokens ordered to match the preferred names

pxr::TfTokenVector getPropertyNames(

const pxr::SdfPrimSpecHandle parent,

const std::vector<std::string> &names,

)#

Make a list of names valid and unique for use as the names of properties on the given prim.

Parameters:

• parent – The parent prim spec

• names – Preferred names

Returns:

A vector of Valid and unique name tokens ordered to match the preferred names

void updatePrimNames(const pxr::UsdPrim &parent)#

Update the reserved child names for a prim to include existing children.

Parameters:

parent – The parent prim.

void updatePrimNames(const pxr::SdfPrimSpecHandle parent)#

Update the reserved child names for a prim to include existing children.

Parameters:

parent – The parent prim spec.

void updatePropertyNames(const pxr::UsdPrim &parent)#

Update the reserved property names for a prim to include existing properties.

Parameters:

parent – The parent prim.

void updatePropertyNames(const pxr::SdfPrimSpecHandle parent)#

Update the reserved property names for a prim to include existing properties.

Parameters:

parent – The parent prim spec.

void update(const pxr::UsdPrim &parent)#

Update the reserved child and property names for a prim to include existing children and properties.

Parameters:

parent – The parent prim.

void update(const pxr::SdfPrimSpecHandle parent)#

Update the reserved child and property names for a prim to include existing children and properties.

Parameters:

parent – The parent prim spec.

void clearPrimNames(const pxr::SdfPath &parent)#

Clear the reserved child names for a prim.

Parameters:

parent – The parent prim path

void clearPrimNames(const pxr::UsdPrim &parent)#

Clear the reserved child names for a prim.

Parameters:

parent – The parent prim

void clearPrimNames(const pxr::SdfPrimSpecHandle parent)#

Clear the reserved child names for a prim.

Parameters:

parent – The parent prim spec

void clearPropertyNames(const pxr::SdfPath &parent)#

Clear the reserved property names for a prim.

Parameters:

parent – The parent prim path

void clearPropertyNames(const pxr::UsdPrim &parent)#

Clear the reserved property names for a prim.

Parameters:

parent – The parent prim

void clearPropertyNames(const pxr::SdfPrimSpecHandle parent)#

Clear the reserved property names for a prim.

Parameters:

parent – The parent prim spec

void clear(const pxr::SdfPath &parent)#

Clear the reserved prim and property names for a prim.

Parameters:

parent – The parent prim path

void clear(const pxr::UsdPrim &parent)#

Clear the reserved prim and property names for a prim.

Parameters:

parent – The parent prim

void clear(const pxr::SdfPrimSpecHandle parent)#

Clear the reserved prim and property names for a prim.

Parameters:

parent – The parent prim spec