#include <Prim.h>

Inheritance diagram for usg::Prim:

Classes
class	FlagsSet

Public Types
enum	{ ActiveFlag = 0 , LoadedFlag , ModelFlag , GroupFlag , AbstractFlag , DefinedFlag , HasDefiningSpecifierFlag , InstanceFlag , PayloadFlag , ClipsFlag , DeadFlag , PrototypeFlag , InstanceProxyFlag , PseudoRootFlag , NumFlags }

using	FlagMask = uint32_t

using	FlagsPredicate = FlagsSet

Public Member Functions
	Prim ()
	Abstraction handle for casting to UsdPrim.

	Prim (const Prim &)

Prim &	operator= (const Prim &)

bool	operator== (const Prim &b) const
	Equality - are the two Prims the same object or not? Compares the underlying Prim::Impls.

bool	operator!= (const Prim &b) const

bool	operator< (const Prim &b) const

bool	isValid () const
	Returns true if Prim::Impl is valid (has a valid object binding.)

	operator bool () const

bool	isSdfPrim () const

bool	isUsdPrim () const

virtual bool	validate ()

class Prim::SpecPrimHandle *	getSdfPrimSpec (int usd_version)

const class Prim::SpecPrimHandle *	getSdfPrimSpec (int usd_version) const

class Prim::UsdPrimHandle *	getUsdPrim (int usd_version)

const class Prim::UsdPrimHandle *	getUsdPrim (int usd_version) const

const std::string &	getName () const
	Returns the name of the prim.

Token	getNameToken () const
	Returns the name of the prim as a token.

Path	getPath () const
	Returns the path of the prim.

Token	getTypeName () const
	Returns the name of the type of the prim.

Prim	getParent () const
	Return this prim's parent prim. Returns an invalid prim if this is a root prim.

bool	isA (const Token &typeName) const
	Returns true if the prim is an instance of the given type.

bool	isA (const Type &type) const
	Returns true if the prim is an instance of the given type. This is faster than the isA method which takes a Token as it avoids a type name lookup.

template<class T >
bool	isA () const
	Returns true if the prim is an instance of a schema.

bool	hasApi (const Token &typeName) const
	Returns true if the prim has the given API.

bool	hasApi (const Token &typeName, const Token &instanceName) const
	Returns true if the prim has the given multiple-apply schema API.

void	setActive (bool active)

bool	isActive () const

bool	clearActive ()

bool	clearTypeName ()

bool	isDefined () const

bool	isModel () const

bool	isGroup () const

bool	isAbstract () const

bool	hasDefiningSpecifier () const

bool	hasOverSpecifier () const

bool	hasClassSpecifier () const

bool	hasArcs () const

bool	isPseudoRoot () const
	Returns true if the prim is the pseudo root - ie '/'.

void	setKind (const Token &kind)

Token	getKind () const

void	setInstanceable (bool instanceable)

bool	getInstanceable () const

bool	isInstanceable () const

bool	isInstance () const

bool	isInstanceProxy () const

bool	isPrototype () const

bool	isInPrototype () const

bool	hasPayload () const

bool	isLoaded () const

void	load (bool loadWithDescendants=true) const

void	unload () const

void	setVisibility (bool active, fdk::TimeValue time=fdk::defaultTimeValue())

bool	visibility (fdk::TimeValue time=fdk::defaultTimeValue()) const

void	setVisible (bool active, fdk::TimeValue time=fdk::defaultTimeValue())

bool	isVisible (fdk::TimeValue time=fdk::defaultTimeValue()) const

bool	addAppliedSchema (const Token &schemaName, ListPosition position=ListPosition::PrependBack)

bool	removeAppliedSchema (const Token &schemaName)

void	setCreator (const Token &creator)
	Sets the name of the app that created this prim.

Token	creatorApp () const
	Gets the name of the app that created this prim.

bool	isCreator (const Token &creator) const
	True if creator is the prim's creator app.

void	setMetadata (const std::string &key, const Value &value)
	Sets the metadata (or field for sdfPrim) value of given key.

bool	setMetadataByDictKey (const Token &key, const Token &keyPath, const Value &value)
	Sets the dictionary metadata (or field for sdfPrim) value of given key.and keyPath.

bool	getMetadataByDictKey (const Token &key, const Token &keyPath, Value &value) const
	Gets the dictionary metadata (or field for sdfPrim) value of given key.and keyPath.

void	setCustomData (const std::string &key, const Value &value)
	Sets the custom data value of given key.

bool	getCustomData (const std::string &key, Value &value) const
	Retrieves the custom data value for the key. Returns true if it exists.

Value	getCustomData (const std::string &key) const
	Returns a valid value if the custom data exists for the key.

CustomDataRef	getCustomData () const
	Returns the prim's custom data.

bool	hasCustomData (const std::string &key) const
	Checks whether the prim has custom data for the key.

void	removeCustomData (const std::string &key)
	Erases the custom data for the key.

bool	getMetadata (const Token &key, Value &value) const
	Return this prim's metadata given a key token.

TokenArray	getMetadataFieldNames () const
	Returns the list field names of the prim's metadata.

std::vector< Token >	getAuthoredMetadata () const

Attribute	createIntrinsicAttr (const Token &name, Value::Type type, TimeVariability variability_hint=TimeVariability::Uniform)

Attribute	createCustomAttr (const Token &name, Value::Type type, TimeVariability variability_hint=TimeVariability::Uniform)

Attribute	createAttr (const Token &name, Value::Type type, bool is_custom=false, TimeVariability variability_hint=TimeVariability::Varying, const Value &defaultValue=Value())

template<typename T >
Attribute	setAttr (const Token &name, const T &v, const fdk::TimeValue &time=fdk::defaultTimeValue())

Attribute	getAttr (const Token &name) const
	If the named attribute exists on the Prim returns it otherwise return an empty (invalid) Attribute object.

bool	getAttr (const Token &name, Attribute &attr) const

Value	getValueAt (const Token &attributeName, const fdk::TimeValue &time=fdk::earliestTimeValue()) const

std::vector< Token >	getAttributes () const
	Returns the list of attributes.

std::vector< Token >	getAuthoredAttributes () const
	Returns the list of authored attributes.

std::vector< Token >	getAuthoredRelationships () const
	Returns the list of authored relationships.

std::vector< Token >	getAuthoredProperties () const
	Returns the list of authored properties. This includes attributes and relationships.

void	removeProperty (const Token &propertyName)
	Removes a property if this prim is an SDF representation.

Attribute	copyAttr (const Prim &fromPrim, const Token &name, fdk::TimeValue time)
	Copy the attribute from another prim at the given time.

Relationship	createRelationship (const Token &name, bool custom=false)
	Creates and returns an empty relationship.

Relationship	getRelationship (const Token &name) const

bool	getRelationship (const Token &name, Relationship &rel) const

size_t	getRelationships (std::vector< const char * > &relationships) const
	Fills in the list of relationship names, returning the number of relationship.

void	addInherit (const Path &path, ListPosition position=ListPosition::PrependBack)
	Adds a inherit path to the prim's inherits list.

PathArray	getInherits ()
	Return the prim's inherits list.

void	removeInherit (const Path &path)
	Removes a inherit path to the prim's inherits list.

void	setInherits (const PathArray &paths)
	Sets inherits to the prim's inherits list. If empty list is given, clears the inherits list.

void	addReference (const std::string &identifier, const Path &path, ListPosition position=ListPosition::PrependBack, double offset=0.0, double scale=1.0)
	Adds a reference to the prim's reference list.

void	removeReference (const std::string &identifier, const Path &path, double offset=0.0, double scale=1.0)
	Removes a reference to the prim's reference list.

void	setReferences (const std::vector< std::pair< std::string, Path > > &identifierAndPaths, double offset=0.0, double scale=1.0)
	Sets references to the prim's reference list. If empty list is given, clears the reference list.

void	addPayload (const std::string &identifier, const Path &path, ListPosition position=ListPosition::PrependBack, double offset=0.0, double scale=1.0)
	Adds a payload to the prim's payload list.

void	removePayload (const std::string &identifier, const Path &path, double offset=0.0, double scale=1.0)
	Removes a payload to the prim's payload list.

void	setPayloads (const std::vector< std::pair< std::string, Path > > &identifierAndPaths, double offset=0.0, double scale=1.0)
	Sets payloads to the prim's payload list. If empty list is given, clears the payload list.

void	addSpecialize (const Path &path, ListPosition position=ListPosition::PrependBack)
	Adds a specialize path to the prim's specializes list.

void	removeSpecialize (const Path &path)
	Removes a specialize path to the prim's specializes list.

void	setSpecializes (const PathArray &paths)
	Sets specializes to the prim's specializes list. If empty list is given, clears the specializes list.

void	addVariantSet (const std::string &variantSetName, ListPosition position=ListPosition::PrependBack)
	Adds a variant set to the prim.

void	addVariant (const std::string &variantSetName, const std::string &variantName)
	Adds a variant to a variant set.

void	setVariantSelection (const std::string &variantSetName, const std::string &selection)
	Sets the variant selection for a variant set.

std::vector< std::string >	getVariantSets () const
	Returns the list of variant sets authored on the prim.

std::vector< std::string >	getVariants (const std::string &variantSetName) const
	Returns the list of variants for a variant set on this prim.

std::string	getVariantSelection (const std::string &variantSetName) const
	Returns the variant selection for a given variant set.

size_t	getChildren (std::vector< Prim > &children, bool activeOnly=true, bool includeClasses=false, bool includeOverrides=true) const

LayerRef	getDefiningLayer () const
	Returns a possible layer which defined this prim. This returns the layer containing the first "def" for the prim.

virtual void	print (const char *prefix, std::ostream &o, bool printAttribContents=false) const
	Debugging - prints some key info about the prim to a stream.

	Prim (const Prim::Impl &)

Prim::Impl *	impl ()

const Prim::Impl *	impl () const

void	invalidate ()
	Remove the binding making the Prim invalid. For internal use only!

virtual bool	applyAttributeOverrides (const ShaderDesc &, bool v=true)

Static Public Member Functions
static Prim	defineInLayer (const LayerRef &layer, const Path &path, const Token &typeName)

static Prim	overrideInLayer (const LayerRef &layer, const Path &path, const Token &typeName)

static void	createMissingParents (const StageRef &referenceStage, const LayerRef &layer, const Path &path, const Token &parentPrimType=GeomTokens.types.Scope)

Static Public Attributes
static constexpr FlagMask	IsActiveMask = 0x0001

static constexpr FlagMask	IsLoadedMask = 0x0002

static constexpr FlagMask	IsModelMask = 0x0004

static constexpr FlagMask	IsGroupMask = 0x0008

static constexpr FlagMask	IsAbstractMask = 0x0010

static constexpr FlagMask	IsDefinedMask = 0x0020

static constexpr FlagMask	HasDefiningSpecifierMask = 0x0040

static constexpr FlagMask	IsInstanceMask = 0x0080

static constexpr FlagMask	PayloadMask = 0x0100

static constexpr FlagMask	ClipsMask = 0x0200

static constexpr FlagMask	DeadMask = 0x0400

static constexpr FlagMask	PrototypeMask = 0x0800

static constexpr FlagMask	InstanceProxyMask = 0x1000

static constexpr FlagMask	PseudoRootMask = 0x2000

static const FlagsPredicate	IsActive

static const FlagsPredicate	IsLoaded

static const FlagsPredicate	IsModel

static const FlagsPredicate	IsGroup

static const FlagsPredicate	IsAbstract

static const FlagsPredicate	IsDefined

static const FlagsPredicate	HasDefiningSpecifier

static const FlagsPredicate	IsInstance

static const FlagsPredicate	IncludeInstanceProxies

static const FlagsPredicate	DefaultPredicate
	Default filtering mask. Same as (IsActive && IsDefined && IsLoaded && -IsAbstract)

static const FlagsPredicate	AllPrimsPredicate
	No filtering mask (no flags enabled.) Same as FlagsSet().

Protected Member Functions
void	initialize (const Prim &prim)

Protected Attributes
std::unique_ptr< Prim::Impl, void()(Prim::Impl )>	_pImpl

Detailed Description

class Prim Polymorphic wrapper class for SdfPrimSpec or UsdPrim

Constructor & Destructor Documentation

◆ Prim()

usg::Prim::Prim ( )

Abstraction handle for casting to UsdPrim.

Constructs an empty (invalid) Prim.

Member Function Documentation

◆ validate()

virtual bool usg::Prim::validate ( )

virtual

Returns true if we're holding a valid type of prim for our class. If not, returns false and invalidates this prim so that furutre.calls to isValid will return false;

Reimplemented in usg::BasisCurvesPrim, usg::BoundablePrim, usg::CameraPrim, usg::CapsulePrim, usg::ConePrim, usg::CubePrim, usg::CurvesPrim, usg::CylinderPrim, usg::GeomSubsetPrim, usg::GprimPrim, usg::HermiteCurvesPrim, usg::MeshPrim, usg::NurbsCurvesPrim, usg::NurbsPatchPrim, usg::PointBasedPrim, usg::PointInstancerPrim, usg::PointsPrim, usg::ScopePrim, usg::SpherePrim, usg::XformPrim, usg::lux::BoundableLightBasePrim, usg::lux::CylinderLightPrim, usg::lux::DiskLightPrim, usg::lux::DistantLightPrim, usg::lux::DomeLightPrim, usg::lux::GeometryLightPrim, usg::lux::LightFilterPrim, usg::lux::NonboundableLightBasePrim, usg::lux::PluginLightFilterPrim, usg::lux::PluginLightPrim, usg::lux::PortalLightPrim, usg::lux::RectLightPrim, usg::lux::SphereLightPrim, usg::skel::SkelRootPrim, usg::ui::BackdropPrim, usg::ImageablePrim, usg::LightPrim, usg::MaterialPrim, usg::ShaderPrim, and usg::XformablePrim.

◆ getSdfPrimSpec()

class Prim::SpecPrimHandle * usg::Prim::getSdfPrimSpec ( int usd_version )

If the Prim is bound to an SdfPrimSpec return a pointer to the underlying SdfPrimSpec object if the usd_version passed in matches the Usd version this library was built with, otherwise return null.

The version must match the one returned by usg::usdAPIVersion().

Caller should cast the returned pointer to an SdfPrimSpec* and possibly double-check its validity since a Prim can be created without a valid binding. However, if Prim::isValid() returns true then the underlying binding will also be valid.

◆ getUsdPrim()

class Prim::UsdPrimHandle * usg::Prim::getUsdPrim ( int usd_version )

If the Prim is bound to a UsdPrim return a pointer to the underlying UsdPrim object if the usd_version passed in matches the Usd version this library was built with, otherwise return null.

The version must match the one returned by usg::usdAPIVersion().

Caller should cast the returned pointer to an UsdPrim* and possibly double-check its validity since a Prim can be created without a valid binding. However, if Prim::isValid() returns true then the underlying binding will also be valid.

◆ setVisibility()

void usg::Prim::setVisibility	(	bool	active,
		fdk::TimeValue	time = `fdk::defaultTimeValue()`
	)

If active is false the prim's visibility attribute is set to 'invisible', otherwise it is set to 'inherited' which means the prim's actual visibility is determined by its parent's visibility state.

◆ visibility()

bool usg::Prim::visibility ( fdk::TimeValue time = fdk::defaultTimeValue() ) const

Returns the state of the prim's local visibility attribute, if authored. If authored and the value is 'invisible' then false is returned, otherwise true is returned if value is 'inherited' or was not authored (default is 'inherited'.) Warning, a returned value of true does not mean this prim must be visible! You must walk up the graph checking for any parents explicitly set 'invisible', and if no more parents left then this prim is -by default- visible.

◆ getAuthoredMetadata()

std::vector< Token > usg::Prim::getAuthoredMetadata ( ) const

Returns the list of authored metadata. This method does not return field keys for composition arcs.

◆ defineInLayer()

static Prim usg::Prim::defineInLayer	(	const LayerRef &	layer,
		const Path &	path,
		const Token &	typeName
	)

static

Creates a Prim definition in the owner Layer, returning a constructed reference. Convenience function that calls Layer::definePrim().

◆ overrideInLayer()

static Prim usg::Prim::overrideInLayer	(	const LayerRef &	layer,
		const Path &	path,
		const Token &	typeName
	)

static

Creates a Prim override in the owner Layer, returning a constructed reference. Convenience function that calls Layer::overridePrim().

◆ createMissingParents()

static void usg::Prim::createMissingParents	(	const StageRef &	referenceStage,
		const LayerRef &	layer,
		const Path &	path,
		const Token &	parentPrimType = `GeomTokens.types.Scope`
	)

static

Creates the missing parent prims in a Prim path with a specific type.

Other define and override prim methods default to creating missing parent prims as untyped pure overs, which may cause the prim to act as if they doesn't exist.

Be careful with this method as it requires a composed source stage to determine whether a prim is 'missing' from the path or not, and this may lead to unexpected overhead costs when defining prims.

◆ createIntrinsicAttr()

Attribute usg::Prim::createIntrinsicAttr	(	const Token &	name,
		Value::Type	type,
		TimeVariability	variability_hint = `TimeVariability::Uniform`
	)

Creates and attaches an intrinsic(non-custom) attribute to this Prim. If the named Attribute object already exists returns it at its current value.

If this Prim has just been defined on a Layer then the new attribute will be defined on that Layer.

If this Prim is being edited then the attribute will be created on the editable Stage and saved to the Stage's current edit target Layer.

variability_hint is only declaring the expected time-variance of the new attribute. In practice this does not do much as setting time samples later on is not prohibited if the attribute is declared here as uniform.

◆ createCustomAttr()

Attribute usg::Prim::createCustomAttr	(	const Token &	name,
		Value::Type	type,
		TimeVariability	variability_hint = `TimeVariability::Uniform`
	)

Creates and attaches a custom(arbitrary) attribute to this Prim. If the named Attribute object already exists returns it at its current value.

If this Prim has just been defined on a Layer then the new attribute will be defined on that Layer.

If this Prim is being edited then the attribute will be created on the editable Stage and saved to the Stage's current edit target Layer.

variability_hint is only declaring the expected time-variance of the new attribute. In practice this does not do much as setting time samples later on is not prohibited if the attribute is declared here as uniform.

◆ createAttr()

Attribute usg::Prim::createAttr	(	const Token &	name,
		Value::Type	type,
		bool	is_custom = `false`,
		TimeVariability	variability_hint = `TimeVariability::Varying`,
		const Value &	defaultValue = `Value()`
	)

Creates an attribute with the given name, type, temporal variability, and optionally setting the default value.

If the named Attribute object already exists the default value will still be set if provided.

variability_hint is only declaring the expected time-variance of the new attribute. In practice this does not do much as setting time samples later on is not prohibited if the attribute is declared here as uniform.

◆ setAttr()

template<typename T >

Attribute usg::Prim::setAttr	(	const Token &	name,
		const T &	v,
		const fdk::TimeValue &	time = `fdk::defaultTimeValue()`
	)

Sets an existing attribute's value at a specific time. Returns a valid Attribute if successful otherwise an invalid one on failure.

This templated method does not support custom user data types, only the common ones found in the Value::Type 'Base data types' list.

Assumes the attrib has already been created and configured for the correct Value::Type and interpolation rate. Use createAttr() for this prior to calling setAttr().

If the attribute does not already exist setAttr() will create it as a custom uniform attribute using the default Value::Type corresponding to the data type passed in. For example if setting UVs you would likely want the attribute to be a TexCoord2fArray Value::Type, but this method will create it as a Float2Array.

To set array-variant types (FloatArray, Color3fArray, etc) pass in a std::vector. Many of the common array types are already defined in geo/scene/Array.h or in the vec/mat/box math types. For example to set an array of normals: Vec3fArray normalsArray; prim.setAttr(GeomTokens.primvars.normals, normalsArray, 100.0);

◆ getAttr()

bool usg::Prim::getAttr	(	const Token &	name,
		Attribute &	attr
	)		const

If the named attribute exists on the Prim fills in the provided Attribute object and returns true, otherwise returns false.

◆ getValueAt()

Value usg::Prim::getValueAt	(	const Token &	attributeName,
		const fdk::TimeValue &	time = `fdk::earliestTimeValue()`
	)		const

Return the value of the named attribute at a specific time. If the attribute does not exist an invalid Value is returned.

◆ getRelationship() [1/2]

Relationship usg::Prim::getRelationship ( const Token & name ) const

If the named relationship exists on the Prim returns it otherwise returns an empty (invalid) Relationship object.

◆ getRelationship() [2/2]

bool usg::Prim::getRelationship	(	const Token &	name,
		Relationship &	rel
	)		const

If the named relationship exists on the Prim fills in the provided Relationship object and return true, otherwise return false.

◆ getChildren()

size_t usg::Prim::getChildren	(	std::vector< Prim > &	children,
		bool	activeOnly = `true`,
		bool	includeClasses = `false`,
		bool	includeOverrides = `true`
	)		const

Fills in a list of child Prims directly underneath this one (ie does not include any children of the children) and returns the list size.

This only functions if Prim is resident on a valid stage.

◆ applyAttributeOverrides()

virtual bool usg::Prim::applyAttributeOverrides	(	const ShaderDesc &	,
		bool	v = `true`
	)

inlinevirtual

Reimplemented in usg::ShaderPrim.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Prim()

Member Function Documentation

◆ validate()

◆ getSdfPrimSpec()

◆ getUsdPrim()

◆ setVisibility()

◆ visibility()

◆ getAuthoredMetadata()

◆ defineInLayer()

◆ overrideInLayer()

◆ createMissingParents()

◆ createIntrinsicAttr()

◆ createCustomAttr()

◆ createAttr()

◆ setAttr()

◆ getAttr()

◆ getValueAt()

◆ getRelationship() [1/2]

◆ getRelationship() [2/2]

◆ getChildren()

◆ applyAttributeOverrides()