#include <colorSpaceAPI.h>

Inheritance diagram for UsdColorSpaceAPI:

Classes
class	ColorSpaceCache

class	ColorSpaceHashCache

Public Member Functions
	UsdColorSpaceAPI (const UsdPrim &prim=UsdPrim())

	UsdColorSpaceAPI (const UsdSchemaBase &schemaObj)

virtual USD_API	~UsdColorSpaceAPI ()
	Destructor. More...

USD_API UsdAttribute	GetColorSpaceNameAttr () const

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

Public Member Functions inherited from UsdAPISchemaBase
	UsdAPISchemaBase (const UsdPrim &prim=UsdPrim())

	UsdAPISchemaBase (const UsdSchemaBase &schemaObj)

virtual USD_API	~UsdAPISchemaBase ()=0
	Destructor. More...

Public Member Functions inherited from UsdSchemaBase
bool	IsConcrete () const

bool	IsTyped () const

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

bool	IsAppliedAPISchema () const

bool	IsMultipleApplyAPISchema () const

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

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

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

virtual USD_API	~UsdSchemaBase ()
	Destructor. More...

USD_API	operator bool () const

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

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

USD_API const UsdPrimDefinition *	GetSchemaClassPrimDefinition () const

Static Public Member Functions
static USD_API const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)

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

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

static USD_API UsdColorSpaceAPI	Apply (const UsdPrim &prim)

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

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

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

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

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

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

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

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

Static Public Attributes
static const UsdSchemaKind	schemaKind = UsdSchemaKind::SingleApplyAPI

Static Public Attributes inherited from UsdAPISchemaBase
static const UsdSchemaKind	schemaKind = UsdSchemaKind::AbstractBase

Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind	schemaKind = UsdSchemaKind::AbstractBase

Protected Member Functions
USD_API UsdSchemaKind	_GetSchemaKind () const override

Protected Member Functions inherited from UsdAPISchemaBase
	UsdAPISchemaBase (const UsdPrim &prim, const TfToken &instanceName)

	UsdAPISchemaBase (const UsdSchemaBase &schemaObj, const TfToken &instanceName)

const TfToken &	_GetInstanceName () const

USD_API bool	_IsCompatible () const override

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)

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::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::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.

virtual USD_API UsdColorSpaceAPI::~UsdColorSpaceAPI ( )

virtual

Destructor.

Member Function Documentation

USD_API UsdSchemaKind UsdColorSpaceAPI::_GetSchemaKind ( ) const

overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See Also: UsdSchemaKind

Reimplemented from UsdAPISchemaBase.

static USD_API UsdColorSpaceAPI 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()

static USD_API bool UsdColorSpaceAPI::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()

static USD_API GfColorSpace UsdColorSpaceAPI::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.

static USD_API GfColorSpace UsdColorSpaceAPI::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.

static USD_API GfColorSpace UsdColorSpaceAPI::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.

static USD_API TfToken UsdColorSpaceAPI::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.

static USD_API TfToken UsdColorSpaceAPI::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.

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

See GetColorSpaceNameAttr(), and also Usd_Create_Or_Get_Property 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.

static USD_API UsdColorSpaceAPI 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));

USD_API UsdAttribute UsdColorSpaceAPI::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

static USD_API const TfTokenVector& UsdColorSpaceAPI::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.

static USD_API bool UsdColorSpaceAPI::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.