UsdClaimsAPI records a prim's profile compatibility claims and per-capability usage declarations. More...

#include <claimsAPI.h>

Inheritance diagram for UsdProfilesClaimsAPI:

Public Member Functions
	UsdProfilesClaimsAPI (const UsdPrim &prim=UsdPrim())
	Construct a UsdProfilesClaimsAPI on UsdPrim `prim` .

	UsdProfilesClaimsAPI (const UsdSchemaBase &schemaObj)
	Construct a UsdProfilesClaimsAPI on the prim held by `schemaObj` .

virtual USDPROFILES_API	~UsdProfilesClaimsAPI ()
	Destructor.

Claims API
All profile data is stored in the prim-level `customData` dictionary under the key `profilesInfo`, using two sub-dictionaries: `capabilityUsages` — maps capability token → degradation class string (`"hard"`, `"soft"`, or `"enhancement"`). Written by the DCC. `profileCompatibility` — maps profile token → array of excepted capability tokens (empty array = fully compatible). Written by the pipeline audit step.
USDPROFILES_API VtDictionary	GetProfilesInfo () const
	Returns the composed `profilesInfo` dictionary, or an empty dictionary if none has been authored.

USDPROFILES_API void	SetProfilesInfo (const VtDictionary &info) const
	Replaces the entire `profilesInfo` dictionary on the current edit target.

USDPROFILES_API VtDictionary	GetCapabilityUsages () const
	Returns the capability usage map as a `VtDictionary` whose keys are capability token strings and whose values are degradation class strings (`"hard"`, `"soft"`, or `"enhancement"`).

USDPROFILES_API void	SetCapabilityUsages (const VtDictionary &usages) const
	Replaces the entire capability usage map.

USDPROFILES_API void	SetCapabilityUsage (const TfToken &capability, const TfToken &degradationClass) const
	Sets the degradation class for a single capability.

USDPROFILES_API TfToken	GetCapabilityUsage (const TfToken &capability) const
	Returns the degradation class string for `capability`, or an empty `TfToken` if `capability` has not been recorded.

USDPROFILES_API VtArray< TfToken >	GetCompatibleProfiles () const
	Returns all profiles that this prim has been declared compatible with, as an unordered array of profile tokens.

USDPROFILES_API void	SetProfileCompatible (const TfToken &profile) const
	Declares this prim fully compatible with `profile` (no exceptions).

USDPROFILES_API void	SetProfileCompatibleWithExceptions (const TfToken &profile, const VtArray< TfToken > &exceptions) const
	Declares this prim compatible with `profile` subject to the given `exceptions` — capabilities that are intentionally unsupported.

USDPROFILES_API VtArray< TfToken >	GetProfileExceptions (const TfToken &profile) const
	Returns the exception set for `profile` — the capabilities that are intentionally unsupported in the context of that profile.

USDPROFILES_API void	ClearProfileCompatibility (const TfToken &profile) const
	Removes the compatibility entry for `profile` entirely.

USDPROFILES_API UsdProfileRegistry::QueryStatus	IsCompatibleWith (const TfToken &profile, std::vector< UsdProfileRegistry::CapabilityResult > *results=nullptr) const
	Returns the `QueryStatus` representing how well this prim satisfies `profile`, taking into account any exception set stored for that profile via `SetProfileCompatibleWithExceptions`.

Public Member Functions inherited from UsdAPISchemaBase
	UsdAPISchemaBase (const UsdPrim &prim=UsdPrim())
	Construct a UsdAPISchemaBase on UsdPrim `prim` .

	UsdAPISchemaBase (const UsdSchemaBase &schemaObj)
	Construct a UsdAPISchemaBase on the prim held by `schemaObj` .

virtual USD_API	~UsdAPISchemaBase ()=0
	Destructor.

Public Member Functions inherited from UsdSchemaBase
bool	IsConcrete () const
	Returns whether or not this class corresponds to a concrete instantiable prim type in scene description.

bool	IsTyped () const
	Returns whether or not this class inherits from UsdTyped.

bool	IsAPISchema () const
	Returns whether this is an API schema or not.

bool	IsAppliedAPISchema () const
	Returns whether this is an applied API schema or not.

bool	IsMultipleApplyAPISchema () const
	Returns whether this is an applied API schema or not.

UsdSchemaKind	GetSchemaKind () const
	Returns the kind of schema this class is.

USD_API	UsdSchemaBase (const UsdPrim &prim=UsdPrim())
	Construct and store `prim` as the held prim.

USD_API	UsdSchemaBase (const UsdSchemaBase &otherSchema)
	Construct and store for the same prim held by `otherSchema`.

virtual USD_API	~UsdSchemaBase ()
	Destructor.

UsdPrim	GetPrim () const
	Return this schema object's held prim.

SdfPath	GetPath () const
	Shorthand for GetPrim()->GetPath().

USD_API const UsdPrimDefinition *	GetSchemaClassPrimDefinition () const
	Return the prim definition associated with this schema instance if one exists, otherwise return null.

USD_API	operator bool () const
	Return true if this schema object is compatible with its held prim, false otherwise.

Static Public Member Functions
static USDPROFILES_API const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)
	Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.

static USDPROFILES_API UsdProfilesClaimsAPI	Get (const UsdStagePtr &stage, const SdfPath &path)
	Return a UsdProfilesClaimsAPI holding the prim adhering to this schema at `path` on `stage`.

static USDPROFILES_API bool	CanApply (const UsdPrim &prim, std::string *whyNot=nullptr)
	Returns true if this single-apply API schema can be applied to the given `prim`.

static USDPROFILES_API UsdProfilesClaimsAPI	Apply (const UsdPrim &prim)
	Applies this single-apply API schema to the given `prim`.

Static Public Member Functions inherited from UsdAPISchemaBase
static USD_API const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)
	Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.

Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)

Static Public Attributes
static const UsdSchemaKind	schemaKind = UsdSchemaKind::SingleApplyAPI
	Compile time constant representing what kind of schema this class is.

Static Public Attributes inherited from UsdAPISchemaBase
static const UsdSchemaKind	schemaKind = UsdSchemaKind::AbstractBase
	Compile time constant representing what kind of schema this class is.

Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind	schemaKind = UsdSchemaKind::AbstractBase
	Compile time constant representing what kind of schema this class is.

Protected Member Functions
USDPROFILES_API UsdSchemaKind	_GetSchemaKind () const override
	Returns the kind of schema this class belongs to.

Protected Member Functions inherited from UsdAPISchemaBase
	UsdAPISchemaBase (const UsdPrim &prim, const TfToken &instanceName)
	Construct a multiple-apply UsdAPISchemaBase on UsdPrim `prim` with the specified `instanceName`.

	UsdAPISchemaBase (const UsdSchemaBase &schemaObj, const TfToken &instanceName)
	Construct a multiple-apply UsdAPISchemaBase on the prim held by `schemaObj` with the given `instanceName`.

const TfToken &	_GetInstanceName () const
	Returns the instance name of the API schema object belonging to a multiple-apply API schema.

USD_API bool	_IsCompatible () const override
	Check whether this APISchema object is valid for the currently held prim.

Protected Member Functions inherited from UsdSchemaBase
virtual UsdSchemaKind	_GetSchemaType () const

const TfType &	_GetType () const

USD_API UsdAttribute	_CreateAttr (TfToken const &attrName, SdfValueTypeName const &typeName, bool custom, SdfVariability variability, VtValue const &defaultValue, bool writeSparsely) const

Friends
class	UsdSchemaRegistry

Additional Inherited Members
Static Protected Member Functions inherited from UsdAPISchemaBase
static USD_API TfTokenVector	_GetMultipleApplyInstanceNames (const UsdPrim &prim, const TfType &schemaType)
	Returns a vector of names of API schema objects belonging to a multiple-apply API schema applied to a given prim.

Detailed Description

UsdClaimsAPI records a prim's profile compatibility claims and per-capability usage declarations.

It provides two tiers of data, stored as sub-dictionaries within the prim's profilesInfo metadata dictionary (analogous to assetInfo):

Capability Usage (DCC-authored)

The capability usage tier records which USD capabilities this prim actually uses, together with a degradation class for each:

hard — the capability is load-bearing; a consumer that does not support it will produce incorrect results.
soft — it is acceptable that the prim degrades gracefully if the capability is absent (e.g. although the capability may be absent, an application has a fallback representation).
enhancement — the capability improves quality but its absence is allowable.

This tier is intended to be written automatically by the DCC tool that saved the prim, or during a tool-based post-process that traverses a stage aggregating capabilities.

Profile Compatibility (pipeline-authored)

The profile compatibility tier records which named profiles (nodes in the UsdProfileRegistry DAG) this prim is compatible with, together with an optional per-profile exception set listing capabilities that are present but known to be out of compliance. As an example, a low-end mobile profile may be able to display a particular material, but the performance is known to be poor. So, while the prim has a hard capability declared, the specific embodiment of that prim fails the profile's constraints.

A compatibility claim without exceptions is an unqualified assertion: "this prim satisfies every capability in the profile's transitive closure." A claim with exceptions is an audited, signed degradation declaration: "this prim satisfies the profile except for the listed capabilities, which are present but failing audit."

This tier is appropriate for publishable deliverables. It is authored by a pipeline conformance step or when performing a platform-compatibility audit.

Querying Compatibility

Use IsCompatibleWith() for the common single-profile check. It calls UsdProfileRegistry::CoversCapabilities() under the hood, passing the stored exception set, and returns the aggregate QueryStatus.

For bulk access, GetProfilesInfo() / SetProfilesInfo() expose the raw VtDictionary so callers can read or write the full record at once.

Data Layout

All data lives in the prim-level profilesInfo metadata dictionary:

profilesInfo = {
dictionary capabilityUsages = {
string "usd.geom.mesh"    = "hard"
string "usd.geom.hairAndFur" = "soft"
string "usd.shading.mtlx" = "hard"
}
dictionary profileCompatibility = {
# profile token and list of present capabilities that 
# don't pass audit. (may be empty)
string[] "profile.studio.vfx.25.08" = []
string[] "vnd.apple.visionos_v1"    = ["usd.geom.hairAndFur"]
}
}

Definition at line 116 of file claimsAPI.h.

Constructor & Destructor Documentation

◆ UsdProfilesClaimsAPI() [1/2]

UsdProfilesClaimsAPI ( const UsdPrim & prim = UsdPrim() )

inlineexplicit

Construct a UsdProfilesClaimsAPI on UsdPrim prim .

Equivalent to UsdProfilesClaimsAPI::Get(prim.GetStage(), prim.GetPath()) for a valid prim, but will not immediately throw an error for an invalid prim

Definition at line 128 of file claimsAPI.h.

◆ UsdProfilesClaimsAPI() [2/2]

UsdProfilesClaimsAPI ( const UsdSchemaBase & schemaObj )

inlineexplicit

Construct a UsdProfilesClaimsAPI on the prim held by schemaObj .

Should be preferred over UsdProfilesClaimsAPI(schemaObj.GetPrim()), as it preserves SchemaBase state.

Definition at line 136 of file claimsAPI.h.

◆ ~UsdProfilesClaimsAPI()

virtual USDPROFILES_API ~UsdProfilesClaimsAPI ( )

virtual

Destructor.

Member Function Documentation

◆ _GetSchemaKind()

USDPROFILES_API UsdSchemaKind _GetSchemaKind ( ) const

overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See also: UsdSchemaKind

Reimplemented from UsdAPISchemaBase.

◆ Apply()

static USDPROFILES_API UsdProfilesClaimsAPI Apply ( const UsdPrim & prim )

static

Applies this single-apply API schema to the given prim.

This information is stored by adding "ClaimsAPI" to the token-valued, listOp metadata apiSchemas on the prim.

Returns: A valid UsdProfilesClaimsAPI object is returned upon success. An invalid (or empty) UsdProfilesClaimsAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

See also: UsdPrim::GetAppliedSchemas(); UsdPrim::HasAPI(); UsdPrim::CanApplyAPI(); UsdPrim::ApplyAPI(); UsdPrim::RemoveAPI()

◆ CanApply()

static USDPROFILES_API bool CanApply	(	const UsdPrim &	prim,
		std::string *	whyNot = nullptr )

static

Returns true if this single-apply API schema can be applied to the given prim.

If this schema can not be a applied to the prim, this returns false and, if provided, populates whyNot with the reason it can not be applied.

Note that if CanApply returns false, that does not necessarily imply that calling Apply will fail. Callers are expected to call CanApply before calling Apply if they want to ensure that it is valid to apply a schema.

See also: UsdPrim::GetAppliedSchemas(); UsdPrim::HasAPI(); UsdPrim::CanApplyAPI(); UsdPrim::ApplyAPI(); UsdPrim::RemoveAPI()

◆ ClearProfileCompatibility()

USDPROFILES_API void ClearProfileCompatibility ( const TfToken & profile ) const

Removes the compatibility entry for profile entirely.

After this call, profile will not appear in GetCompatibleProfiles.

◆ Get()

static USDPROFILES_API UsdProfilesClaimsAPI Get	(	const UsdStagePtr &	stage,
		const SdfPath &	path )

static

Return a UsdProfilesClaimsAPI holding the prim adhering to this schema at path on stage.

If no prim exists at path on stage, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdProfilesClaimsAPI(stage->GetPrimAtPath(path));

UsdProfilesClaimsAPI::UsdProfilesClaimsAPI

UsdProfilesClaimsAPI(const UsdPrim &prim=UsdPrim())

Construct a UsdProfilesClaimsAPI on UsdPrim prim .

Definition claimsAPI.h:128

◆ GetCapabilityUsage()

USDPROFILES_API TfToken GetCapabilityUsage ( const TfToken & capability ) const

Returns the degradation class string for capability, or an empty TfToken if capability has not been recorded.

◆ GetCapabilityUsages()

USDPROFILES_API VtDictionary GetCapabilityUsages ( ) const

Returns the capability usage map as a VtDictionary whose keys are capability token strings and whose values are degradation class strings ("hard", "soft", or "enhancement").

Returns an empty dictionary if no capability usages have been authored.

◆ GetCompatibleProfiles()

USDPROFILES_API VtArray< TfToken > GetCompatibleProfiles ( ) const

Returns all profiles that this prim has been declared compatible with, as an unordered array of profile tokens.

This includes both fully-compatible profiles (no exceptions) and those with a non-empty exception set.

◆ GetProfileExceptions()

USDPROFILES_API VtArray< TfToken > GetProfileExceptions ( const TfToken & profile ) const

Returns the exception set for profile — the capabilities that are intentionally unsupported in the context of that profile.

Returns an empty array if profile is not a declared compatible profile, or if it is compatible with no exceptions.

◆ GetProfilesInfo()

USDPROFILES_API VtDictionary GetProfilesInfo ( ) const

Returns the composed profilesInfo dictionary, or an empty dictionary if none has been authored.

◆ GetSchemaAttributeNames()

static USDPROFILES_API const TfTokenVector & GetSchemaAttributeNames ( bool includeInherited = true )

static

Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.

Does not include attributes that may be authored by custom/extended methods of the schemas involved.

◆ IsCompatibleWith()

USDPROFILES_API UsdProfileRegistry::QueryStatus IsCompatibleWith	(	const TfToken &	profile,
		std::vector< UsdProfileRegistry::CapabilityResult > *	results = nullptr ) const

Returns the QueryStatus representing how well this prim satisfies profile, taking into account any exception set stored for that profile via SetProfileCompatibleWithExceptions.

This is a convenience that calls UsdProfileRegistry::CoversCapabilities() with:

profile as the perspective
the capability tokens from GetCapabilityUsages() as required
the stored exception set (from GetProfileExceptions()) as excepted

If results is non-null it is populated with per-capability detail, following the same contract as CoversCapabilities.

Returns QueryStatus::NoPath if profile is not a declared compatible profile on this prim, or if no capability usages have been recorded.

◆ SetCapabilityUsage()

USDPROFILES_API void SetCapabilityUsage	(	const TfToken &	capability,
		const TfToken &	degradationClass ) const

Sets the degradation class for a single capability.

degradationClass must be "hard", "soft", or "enhancement". Replaces any previously authored value for capability.

◆ SetCapabilityUsages()

USDPROFILES_API void SetCapabilityUsages ( const VtDictionary & usages ) const

Replaces the entire capability usage map.

usages must be a dictionary mapping capability token strings to one of "hard", "soft", or "enhancement".

◆ SetProfileCompatible()

USDPROFILES_API void SetProfileCompatible ( const TfToken & profile ) const

Declares this prim fully compatible with profile (no exceptions).

Replaces any previously authored compatibility entry for profile.

◆ SetProfileCompatibleWithExceptions()

USDPROFILES_API void SetProfileCompatibleWithExceptions	(	const TfToken &	profile,
		const VtArray< TfToken > &	exceptions ) const

Declares this prim compatible with profile subject to the given exceptions — capabilities that are intentionally unsupported.

Replaces any previously authored compatibility entry for profile.

◆ SetProfilesInfo()

USDPROFILES_API void SetProfilesInfo ( const VtDictionary & info ) const

Replaces the entire profilesInfo dictionary on the current edit target.

Friends And Related Symbol Documentation

◆ UsdSchemaRegistry

friend class UsdSchemaRegistry

friend

Definition at line 214 of file claimsAPI.h.

Member Data Documentation

◆ schemaKind

const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI

static

Compile time constant representing what kind of schema this class is.

See also: UsdSchemaKind

Definition at line 122 of file claimsAPI.h.

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

pxr/usd/usdProfiles/claimsAPI.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Capability Usage (DCC-authored)

Profile Compatibility (pipeline-authored)

Querying Compatibility

Data Layout

Constructor & Destructor Documentation

◆ UsdProfilesClaimsAPI() [1/2]

◆ UsdProfilesClaimsAPI() [2/2]

◆ ~UsdProfilesClaimsAPI()

Member Function Documentation

◆ _GetSchemaKind()

◆ Apply()

◆ CanApply()

◆ ClearProfileCompatibility()

◆ Get()

◆ GetCapabilityUsage()

◆ GetCapabilityUsages()

◆ GetCompatibleProfiles()

◆ GetProfileExceptions()

◆ GetProfilesInfo()

◆ GetSchemaAttributeNames()

◆ IsCompatibleWith()

◆ SetCapabilityUsage()

◆ SetCapabilityUsages()

◆ SetProfileCompatible()

◆ SetProfileCompatibleWithExceptions()

◆ SetProfilesInfo()

Friends And Related Symbol Documentation

◆ UsdSchemaRegistry

Member Data Documentation

◆ schemaKind