This schema specifies a back plate i.e. More...

#include <backPlateAPI.h>

Inheritance diagram for UsdGeomBackPlateAPI:

Public Member Functions
	UsdGeomBackPlateAPI (const UsdPrim &prim=UsdPrim(), const TfToken &name=TfToken())
	Construct a UsdGeomBackPlateAPI on UsdPrim `prim` with name `name` .

	UsdGeomBackPlateAPI (const UsdSchemaBase &schemaObj, const TfToken &name)
	Construct a UsdGeomBackPlateAPI on the prim held by `schemaObj` with name `name`.

virtual USDGEOM_API	~UsdGeomBackPlateAPI ()
	Destructor.

TfToken	GetName () const
	Returns the name of this multiple-apply schema instance.

USDGEOM_API UsdAttribute	GetScaleTweakAttr () const
	The (X,Y) scale of the plate about its center.

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

USDGEOM_API UsdAttribute	GetRotateXYZTweakAttr () const
	The (X,Y,Z) rotation of the plate about its center in degrees.

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

USDGEOM_API UsdAttribute	GetTranslateTweakAttr () const
	The (X,Y,Z) translation of the plate about its center after it has been translated by the focus distance and scaled accordingly.

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

USDGEOM_API UsdAttribute	GetImageAttr () const
	Asset path to the file containing a texture or sequence of textures.

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

USDGEOM_API UsdAttribute	GetAlphaImageAttr () const
	Asset path to channel representing the opacity of the back plate.

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

USDGEOM_API UsdAttribute	GetDepthImageAttr () const
	File path to a single-channel texture that describes the depth associated with the image if one exists.

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

USDGEOM_API UsdAttribute	GetDepthMinOffsetAttr () const
	Offset to shift the depth values if minimum value of current range is not set at 0 if needed.

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

USDGEOM_API UsdAttribute	GetDepthNormalizingFactorAttr () const
	Value to scale the texture depth value if needed.

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

USDGEOM_API UsdAttribute	GetDepthCameraSpaceOffsetAttr () const
	Offset to shift the depth into camera space if needed.

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

USDGEOM_API UsdAttribute	GetLumaGainAttr () const
	Scales the per-channel upper bound of the normalized signal before gamma, analogous to per-channel exposure or slope.

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

USDGEOM_API UsdAttribute	GetLumaLiftAttr () const
	Raises or lowers the signal floor (black level) of the normalized value prior to the gain and gamma stages.

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

USDGEOM_API UsdAttribute	GetLumaGammaAttr () const
	Per-channel power applied to the normalized RGB signal after lift and gain.

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

USDGEOM_API UsdAttribute	GetPlateVisibilityAttr () const
	Toggles the visibility of the back plate to all cameras, only the owning camera, or no cameras.

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

USDGEOM_API float	ComputeEffectiveDimension (bool computeWidth, UsdTimeCode time) const
	Returns the height of the plate.

USDGEOM_API void	SetAspectRatio (float width, float height, UsdTimeCode time) const
	Computes and sets backplate tweak::scale such that the back plate will have the desired `width` and `height`.

USDGEOM_API void	SetCameraSpacePosition (GfVec3f pos, UsdTimeCode time) const
	Computes and sets backplate tweak::translate such that the back plate will be positioned at the desired coordinates in camera space.

USDGEOM_API GfVec3f	GetCameraSpacePosition (UsdTimeCode time) const
	Computes and returns the position of the backplate in camera space.

USDGEOM_API void	SetWorldSpacePosition (GfVec3f pos, UsdTimeCode time) const
	Computes and sets backplate tweak::translate such that the back plate will be positioned at the desired coordinates in world space.

USDGEOM_API GfVec3f	GetWorldSpacePosition (UsdTimeCode time) const
	Computes and returns the position of the backplate in world space.

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 USDGEOM_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 USDGEOM_API TfTokenVector	GetSchemaAttributeNames (bool includeInherited, const TfToken &instanceName)
	Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes for a given instance name.

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

static USDGEOM_API UsdGeomBackPlateAPI	Get (const UsdPrim &prim, const TfToken &name)
	Return a UsdGeomBackPlateAPI with name `name` holding the prim `prim`.

static USDGEOM_API std::vector< UsdGeomBackPlateAPI >	GetAll (const UsdPrim &prim)
	Return a vector of all named instances of UsdGeomBackPlateAPI on the given `prim`.

static USDGEOM_API bool	IsSchemaPropertyBaseName (const TfToken &baseName)
	Checks if the given name `baseName` is the base name of a property of BackPlateAPI.

static USDGEOM_API bool	IsBackPlateAPIPath (const SdfPath &path, TfToken *name)
	Checks if the given path `path` is of an API schema of type BackPlateAPI.

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

static USDGEOM_API UsdGeomBackPlateAPI	Apply (const UsdPrim &prim, const TfToken &name)
	Applies this multiple-apply API schema to the given `prim` along with the given instance name, `name`.

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::MultipleApplyAPI
	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
USDGEOM_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

This schema specifies a back plate i.e.

a camera-constrained but not always camera-facing texture card, that exists in scene space. Multiple back plates can be applied to a single camera and each plate can independently specify its own overall visibility, as well as its own opacity and depth varying over the plate.

UsdGeomBackplateAPI is designed to work with UsdGeomCamera, and thus specifically builds off of the camera model that the Camera schema defines, adding the ability to incorporate separately imaged or captured images into a synthetic 3D scene where the UsdGeomCamera can correspond to the camera from which the images were taken.

Auto-Focus

By default, back plates are placed at the focus distance and scaled to fit the camera frustum such that the plate is always in focus. If the focus distance changes, then the back plate will also shift along the optical axis to remain at focus distance and scale accordingly. This auto-focus setup is tailored for match moving and assumes that the captured photos are intended to be shown as is without any additional camera-based-depth blurring.

This schema provides additional rotation, translation, and scale controls, suffixed with 'tweak', that are intended for local adjustments to the plate. These are applied to the center of the plate after it has been autofocused i.e. moved by the focus distance and scaled accordingly. It also has a subset of color grading controls for modifying gain, gamma, and lift values, as well as offset and normalization factors for modifying texture-refered depth information.

Cameral Model

Back plates use a Gaussian thin lens model, whose origin is defined at the point where the optical axis intersects the focal plane. Note that the focus distance used for back plate computations is assumed to be UsdGeomCamera::focusDistance + UsdGeomCamera::focalLength such that our model aligns with film-production on-set practices.

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

Definition at line 83 of file backPlateAPI.h.

Constructor & Destructor Documentation

◆ UsdGeomBackPlateAPI() [1/2]

UsdGeomBackPlateAPI	(	const UsdPrim &	prim = UsdPrim(),
		const TfToken &	name = TfToken() )

inlineexplicit

Construct a UsdGeomBackPlateAPI on UsdPrim prim with name name .

Equivalent to UsdGeomBackPlateAPI::Get( prim.GetStage(), prim.GetPath().AppendProperty( "backPlate:name"));

for a valid prim, but will not immediately throw an error for an invalid prim

Definition at line 100 of file backPlateAPI.h.

◆ UsdGeomBackPlateAPI() [2/2]

UsdGeomBackPlateAPI	(	const UsdSchemaBase &	schemaObj,
		const TfToken &	name )

inlineexplicit

Construct a UsdGeomBackPlateAPI on the prim held by schemaObj with name name.

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

Definition at line 109 of file backPlateAPI.h.

◆ ~UsdGeomBackPlateAPI()

virtual USDGEOM_API ~UsdGeomBackPlateAPI ( )

virtual

Destructor.

Member Function Documentation

◆ _GetSchemaKind()

USDGEOM_API UsdSchemaKind _GetSchemaKind ( ) const

overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See also: UsdSchemaKind

Reimplemented from UsdAPISchemaBase.

◆ Apply()

static USDGEOM_API UsdGeomBackPlateAPI Apply	(	const UsdPrim &	prim,
		const TfToken &	name )

static

Applies this multiple-apply API schema to the given prim along with the given instance name, name.

This information is stored by adding "BackPlateAPI:<i>name</i>" to the token-valued, listOp metadata apiSchemas on the prim. For example, if name is 'instance1', the token 'BackPlateAPI:instance1' is added to 'apiSchemas'.

Returns: A valid UsdGeomBackPlateAPI object is returned upon success. An invalid (or empty) UsdGeomBackPlateAPI 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 USDGEOM_API bool CanApply	(	const UsdPrim &	prim,
		const TfToken &	name,
		std::string *	whyNot = nullptr )

static

Returns true if this multiple-apply API schema can be applied, with the given instance name, name, to the given prim.

If this schema can not be a applied 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()

◆ ComputeEffectiveDimension()

USDGEOM_API float ComputeEffectiveDimension	(	bool	computeWidth,
		UsdTimeCode	time ) const

Returns the height of the plate.

Calculated by the scale and the size of the camera frustum at a focus distance away from the intrinsic camera origin. Note if the focus distance is less than or equal to the focal length then the dimensions of the plate will be 0.