UsdColorSpaceAPI is an API schema that introduces a colorSpace property for authoring scene referred color space opinions. More...

#include <colorSpaceAPI.h>

Inheritance diagram for UsdColorSpaceAPI:

Classes
class	ColorSpaceCache
	A minimalistic cache for color space lookups. More...

class	ColorSpaceHashCache
	This is a simple example of a color space cache implementation. More...

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

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

virtual USD_API	~UsdColorSpaceAPI ()
	Destructor.

USD_API UsdAttribute	GetColorSpaceNameAttr () const
	The color space that applies to attributes with unauthored color spaces on this prim and its descendents.

USD_API UsdAttribute	CreateColorSpaceNameAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
	See GetColorSpaceNameAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

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 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 USD_API UsdColorSpaceAPI	Get (const UsdStagePtr &stage, const SdfPath &path)
	Return a UsdColorSpaceAPI holding the prim adhering to this schema at `path` on `stage`.

static USD_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 USD_API UsdColorSpaceAPI	Apply (const UsdPrim &prim)
	Applies this single-apply API schema to the given `prim`.

static USD_API TfToken	ComputeColorSpaceName (const UsdAttribute &attribute, ColorSpaceCache *cache=nullptr)
	Computes the color space name for the given attribute.

static USD_API GfColorSpace	ComputeColorSpace (const UsdAttribute &attribute, ColorSpaceCache *cache=nullptr)
	Computes the color space for the given attribute on this prim, using the same algorithm as `ComputeColorSpaceName`.

static USD_API TfToken	ComputeColorSpaceName (UsdPrim prim, ColorSpaceCache *cache=nullptr)
	Computes the color space name for the given prim.

static USD_API GfColorSpace	ComputeColorSpace (UsdPrim prim, const TfToken &colorSpace, ColorSpaceCache *cache=nullptr)
	Creates a color space object for the named color space if it built in, defined on the prim or on an ancestor.

static USD_API GfColorSpace	ComputeColorSpace (UsdPrim prim, ColorSpaceCache *cache=nullptr)
	Computes the color space for this prim, using the same algorithm as `ComputeColorSpaceName()`.

static USD_API bool	IsValidColorSpaceName (UsdPrim prim, const TfToken &colorSpace, ColorSpaceCache *cache=nullptr)
	Returns true if the named color space is built in, defined on the supplied prim, or on one of the prim's ancestors.

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
USD_API UsdSchemaKind	_GetSchemaKind () const override
	Returns the kind of schema this class belongs to.

Protected Member Functions inherited from UsdAPISchemaBase
USD_API UsdSchemaKind	_GetSchemaKind () const override
	Returns the kind of schema this class belongs to.

	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

UsdColorSpaceAPI is an API schema that introduces a colorSpace property for authoring scene referred color space opinions.

It also provides a mechanism to determine the applicable color space within a scope through inheritance. Accordingly, this schema may be applied to any prim to introduce a color space at any point in a compositional hierarchy.

Color space resolution involves determining the color space authored on an attribute by first examining the attribute itself for a color space which may have been authored via UsdAttribute::SetColorSpace(). If none is found, the attribute's prim is checked for the existence of the UsdColorSpaceAPI, and any color space authored there. If none is found on the attribute's prim, the prim's ancestors are examined up the hierarchy until an authored color space is found. If no color space is found, an empty TfToken is returned. When no color space is found, the default color space is linear, with Rec709 primaries and D65 white point, corresponding to the GfColorSpace token LinearRec709.

For a list of built in color space token values, see GfColorSpaceNames.

Use a pattern like this when determining an attribute's resolved color space:

TfToken attrCs = attr.GetColorSpace();
if (!attrCs.IsEmpty()) { 
return attrCs; 
}
auto csAPI = UsdColorSpaceAPI(attr.GetPrim());
return UsdColorSpaceAPI::ComputeColorSpaceName(attr);

GfColorSpace and its associated utilities can be used to perform color transformations; some examples:

srcSpace = GfColorSpace(ComputeColorSpaceName(attr))
targetSpace = GfColorSpace(targetSpaceName)
targetColor = srcSpace.Convert(targetSpace, srcColor)
srcSpace.ConvertRGBSpan(targetSpace, colorSpan)

It is recommended that in situations where performance is a concern, an application should perform conversions infrequently and cache results wherever possible.

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdTokens. So to set an attribute to the value "rightHanded", use UsdTokens->rightHanded as the value.

Definition at line 93 of file colorSpaceAPI.h.

Constructor & Destructor Documentation

◆ UsdColorSpaceAPI() [1/2]

UsdColorSpaceAPI ( const UsdPrim & prim = UsdPrim() )

inlineexplicit

Construct a UsdColorSpaceAPI on UsdPrim prim .

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

Definition at line 105 of file colorSpaceAPI.h.

◆ UsdColorSpaceAPI() [2/2]

UsdColorSpaceAPI ( const UsdSchemaBase & schemaObj )

inlineexplicit

Construct a UsdColorSpaceAPI on the prim held by schemaObj .

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

Definition at line 113 of file colorSpaceAPI.h.

◆ ~UsdColorSpaceAPI()

virtual USD_API ~UsdColorSpaceAPI ( )

virtual

Destructor.

Member Function Documentation

◆ _GetSchemaKind()

USD_API UsdSchemaKind _GetSchemaKind ( ) const

overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See also: UsdSchemaKind

Reimplemented from UsdAPISchemaBase.

◆ Apply()

static USD_API UsdColorSpaceAPI Apply ( const UsdPrim & prim )

static

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

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

Returns: A valid UsdColorSpaceAPI object is returned upon success. An invalid (or empty) UsdColorSpaceAPI 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 USD_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()

◆ ComputeColorSpace() [1/3]

static USD_API GfColorSpace ComputeColorSpace	(	const UsdAttribute &	attribute,
		ColorSpaceCache *	cache = `nullptr`
	)

static

Computes the color space for the given attribute on this prim, using the same algorithm as ComputeColorSpaceName.

The same performance caveat applies.

Parameters

attribute	The attribute to compute the color space for.
cache	A cache object for accelerating color space lookups.

◆ ComputeColorSpace() [2/3]

static USD_API GfColorSpace ComputeColorSpace	(	UsdPrim	prim,
		ColorSpaceCache *	cache = `nullptr`
	)

static

Computes the color space for this prim, using the same algorithm as ComputeColorSpaceName().

The same performance caveat applies.

Parameters

prim	The prim to check for the color space.
cache	A cache object for accelerating color space lookups.

◆ ComputeColorSpace() [3/3]

static USD_API GfColorSpace ComputeColorSpace	(	UsdPrim	prim,
		const TfToken &	colorSpace,
		ColorSpaceCache *	cache = `nullptr`
	)

static

Creates a color space object for the named color space if it built in, defined on the prim or on an ancestor.

Parameters

prim	The prim from which a search for a defined color space begins.
colorSpace	The name of the color space.
cache	A cache object for accelerating color space lookups.

◆ ComputeColorSpaceName() [1/2]

static USD_API TfToken ComputeColorSpaceName	(	const UsdAttribute &	attribute,
		ColorSpaceCache *	cache = `nullptr`
	)

static

Computes the color space name for the given attribute.

The attribute is first checked for an authored color space; if one exists, it's returned. Otherwise, the attribute's prim is consulted, following the inheritance rules for color space determination on a prim. If one is found, it's returned. Otherwise, the value on the attribute's prim definition is returned if there is one. Otherwise, an empty TfToken is returned.

This function may be considered a reference implementation for determining the color space of an attribute. Since the algorithm is implemented as an exhaustive search performed through the prim hierarchy, applications may want to implement a caching mechanism to avoid redundant searches.

See also: UsdColorSpaceAPI::Apply; UsdColorSpaceAPI::GetColorSpaceAttr

Parameters

attribute	The attribute to compute the color space for.
cache	An optional cache for accelerating color space lookups.

◆ ComputeColorSpaceName() [2/2]

static USD_API TfToken ComputeColorSpaceName	(	UsdPrim	prim,
		ColorSpaceCache *	cache = `nullptr`
	)

static

Computes the color space name for the given prim.

The color space is determined by checking this prim for a colorSpace property. If no colorSpaceproperty is authored, the search continues up the prim's hierarchy until a colorSpace property is found or the root prim is reached. If no colorSpace property is found, an empty TfToken is returned.

If a colorSpace name is found, but does not match one of the standard color spaces or a user defined color space, an empty TfToken is returned.

This function should be considered as a reference implementation, and applications may want to implement a caching mechanism for performance.

See also: UsdColorSpaceAPI::Apply; UsdColorSpaceAPI::GetColorSpaceAttr

Parameters

prim	The prim to compute the color space for.
cache	A cache object for accelerating color space lookups.

◆ CreateColorSpaceNameAttr()

USD_API UsdAttribute CreateColorSpaceNameAttr	(	VtValue const &	defaultValue = `VtValue()`,
		bool	writeSparsely = `false`
	)		const

See GetColorSpaceNameAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ Get()

static USD_API UsdColorSpaceAPI Get	(	const UsdStagePtr &	stage,
		const SdfPath &	path
	)

static

Return a UsdColorSpaceAPI 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:

UsdColorSpaceAPI(stage->GetPrimAtPath(path));

◆ GetColorSpaceNameAttr()

USD_API UsdAttribute GetColorSpaceNameAttr ( ) const

The color space that applies to attributes with unauthored color spaces on this prim and its descendents.


Declaration	`uniform token colorSpace:name`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Variability	SdfVariabilityUniform

◆ GetSchemaAttributeNames()

static USD_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.

◆ IsValidColorSpaceName()

static USD_API bool IsValidColorSpaceName	(	UsdPrim	prim,
		const TfToken &	colorSpace,
		ColorSpaceCache *	cache = `nullptr`
	)

static

Returns true if the named color space is built in, defined on the supplied prim, or on one of the prim's ancestors.

Parameters

prim	The prim from which a search for a defined color space begins.
colorSpace	The name of the color space to verify.
cache	A cache object for accelerating color space lookups.

Friends And Related Function Documentation

◆ UsdSchemaRegistry

friend class UsdSchemaRegistry

friend

Definition at line 191 of file colorSpaceAPI.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 99 of file colorSpaceAPI.h.

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

pxr/usd/usd/colorSpaceAPI.h

Classes

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ UsdColorSpaceAPI() [1/2]

◆ UsdColorSpaceAPI() [2/2]

◆ ~UsdColorSpaceAPI()

Member Function Documentation

◆ _GetSchemaKind()

◆ Apply()

◆ CanApply()

◆ ComputeColorSpace() [1/3]

◆ ComputeColorSpace() [2/3]

◆ ComputeColorSpace() [3/3]

◆ ComputeColorSpaceName() [1/2]

◆ ComputeColorSpaceName() [2/2]

◆ CreateColorSpaceNameAttr()

◆ Get()

◆ GetColorSpaceNameAttr()

◆ GetSchemaAttributeNames()

◆ IsValidColorSpaceName()

Friends And Related Function Documentation

◆ UsdSchemaRegistry

Member Data Documentation

◆ schemaKind