Loading...
Searching...
No Matches
UsdLodScreenSizeHeuristic Class Reference

This LOD heuristic selects LOD children on the basis of the fraction of the viewplane would be covered by the extent. More...

#include <screenSizeHeuristic.h>

+ Inheritance diagram for UsdLodScreenSizeHeuristic:

Public Member Functions

 UsdLodScreenSizeHeuristic (const UsdPrim &prim=UsdPrim())
 Construct a UsdLodScreenSizeHeuristic on UsdPrim prim .
 
 UsdLodScreenSizeHeuristic (const UsdSchemaBase &schemaObj)
 Construct a UsdLodScreenSizeHeuristic on the prim held by schemaObj .
 
virtual USDLOD_API ~UsdLodScreenSizeHeuristic ()
 Destructor.
 
USDLOD_API UsdAttribute GetExtentAttr () const
 The extent of this LOD Root in local coordinates.
 
USDLOD_API UsdAttribute CreateExtentAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetExtentAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLOD_API UsdAttribute GetProjectionMethodAttr () const
 Defines how screen size is calculated.
 
USDLOD_API UsdAttribute CreateProjectionMethodAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetProjectionMethodAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLOD_API UsdAttribute GetThresholdsAttr () const
 The screen size thresholds for LOD transitions in descending order as a fraction of the viewport size.
 
USDLOD_API UsdAttribute CreateThresholdsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetThresholdsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLOD_API UsdAttribute GetBlendThresholdsAttr () const
 This defines screen size thresholds for LOD transitions in descending order.
 
USDLOD_API UsdAttribute CreateBlendThresholdsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetBlendThresholdsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLOD_API UsdRelationship GetBoundingVolumeRel () const
 Optional relationship to a Boundable prim that defines the bounding volume for this LOD Root, used for size calculation if the referenced prim has a valid extent.
 
USDLOD_API UsdRelationship CreateBoundingVolumeRel () const
 See GetBoundingVolumeRel(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDLOD_API UsdLodScreenSizeHeuristicQuery CreateScreenSizeHeuristicQuery (UsdTimeCode time=UsdTimeCode::Default()) const
 Return a UsdLodScreenSizeHeuristicQuery that matches the current attribute values of this UsdLodScreenSizeHeuristic.
 
USDLOD_API double ComputeScreenSize (const GfFrustum &frustum, const GfMatrix4d &transform, UsdTimeCode time=UsdTimeCode::Default()) const
 Calculate the screen size given a frustum and a transform.
 
USDLOD_API double ComputeScreenSize (const GfFrustum &frustum, const GfMatrix4d &transform, double prevSize, double hysteresis, UsdTimeCode time=UsdTimeCode::Default()) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Calculate the screen size given a frustum and a transform with hysteresis.
 
USDLOD_API float ComputeLOD (double size, UsdTimeCode time=UsdTimeCode::Default()) const
 Calculate an LOD index given a screen size.
 
USDLOD_API float ComputeLOD (const GfFrustum &frustum, const GfMatrix4d &transform, UsdTimeCode time=UsdTimeCode::Default()) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Calculate an LOD index given a frustum and a transform.
 
USDLOD_API float ComputeLOD (const GfFrustum &frustum, const GfMatrix4d &transform, double prevSize, double hysteresis, double *screenSizeOut, UsdTimeCode time=UsdTimeCode::Default()) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Calculate an LOD index given a frustum and a transform with hysteresis.
 
- Public Member Functions inherited from UsdLodHeuristic
 UsdLodHeuristic (const UsdPrim &prim=UsdPrim())
 Construct a UsdLodHeuristic on UsdPrim prim .
 
 UsdLodHeuristic (const UsdSchemaBase &schemaObj)
 Construct a UsdLodHeuristic on the prim held by schemaObj .
 
virtual USDLOD_API ~UsdLodHeuristic ()
 Destructor.
 
USDLOD_API UsdAttribute GetLodDomainAttr () const
 The "domain" of this heuristic.
 
USDLOD_API UsdAttribute CreateLodDomainAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetLodDomainAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
- Public Member Functions inherited from UsdTyped
 UsdTyped (const UsdPrim &prim=UsdPrim())
 Construct a UsdTyped on UsdPrim prim .
 
 UsdTyped (const UsdSchemaBase &schemaObj)
 Construct a UsdTyped on the prim held by schemaObj .
 
virtual USD_API ~UsdTyped ()
 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 UsdPrimDefinitionGetSchemaClassPrimDefinition () 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 USDLOD_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USDLOD_API UsdLodScreenSizeHeuristic Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdLodScreenSizeHeuristic holding the prim adhering to this schema at path on stage.
 
static USDLOD_API UsdLodScreenSizeHeuristic Define (const UsdStagePtr &stage, const SdfPath &path)
 Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined()) on this stage.
 
- Static Public Member Functions inherited from UsdLodHeuristic
static USDLOD_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USDLOD_API UsdLodHeuristic Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdLodHeuristic holding the prim adhering to this schema at path on stage.
 
- Static Public Member Functions inherited from UsdTyped
static USD_API const TfTokenVectorGetSchemaAttributeNames (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 UsdTyped Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdTyped holding the prim adhering to this schema at path on stage.
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Static Public Attributes

static const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdLodHeuristic
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractTyped
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdTyped
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

USDLOD_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
- Protected Member Functions inherited from UsdLodHeuristic
- Protected Member Functions inherited from UsdTyped
USD_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
USD_API bool _IsCompatible () const override
 Subclasses may override _IsCompatible to do specific compatibility checking with the given prim, such as type compatibility or value compatibility.
 
- 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
 

Detailed Description

This LOD heuristic selects LOD children on the basis of the fraction of the viewplane would be covered by the extent.

The LOD child selected is determined by the comparing the computed screen size with the values in thresholds and blendThresholds. Providing values in blendThresholds can allow the renderer to blend between different LOD children which can be useful to avoid flickering between two LODs. Alternatively, hysteresis can be employed to avoid changing the LOD when the distance changes by just a small amount.

The extent and boundingVolume properties describe geometric information for the Root prim that informs the distance calculation. If boundingVolume is authored and targets a prim with a valid extent, the targeted prim's extent should govern the heuristic; otherwise, the extent holds. Both extent and boundingVolume coordinates are assumed to be in the local coordinate system of the LOD root. (Note that this heuristic prim may have a completely different coordinate system than the root does.)

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

Definition at line 66 of file screenSizeHeuristic.h.

Constructor & Destructor Documentation

◆ UsdLodScreenSizeHeuristic() [1/2]

UsdLodScreenSizeHeuristic ( const UsdPrim & prim = UsdPrim())
inlineexplicit

Construct a UsdLodScreenSizeHeuristic on UsdPrim prim .

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

Definition at line 78 of file screenSizeHeuristic.h.

◆ UsdLodScreenSizeHeuristic() [2/2]

UsdLodScreenSizeHeuristic ( const UsdSchemaBase & schemaObj)
inlineexplicit

Construct a UsdLodScreenSizeHeuristic on the prim held by schemaObj .

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

Definition at line 86 of file screenSizeHeuristic.h.

◆ ~UsdLodScreenSizeHeuristic()

virtual USDLOD_API ~UsdLodScreenSizeHeuristic ( )
virtual

Destructor.

Member Function Documentation

◆ _GetSchemaKind()

USDLOD_API UsdSchemaKind _GetSchemaKind ( ) const
overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See also
UsdSchemaKind

Reimplemented from UsdLodHeuristic.

◆ ComputeLOD() [1/3]

USDLOD_API float ComputeLOD ( const GfFrustum & frustum,
const GfMatrix4d & transform,
double prevSize,
double hysteresis,
double * screenSizeOut,
UsdTimeCode time = UsdTimeCode::Default() ) const
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Calculate an LOD index given a frustum and a transform with hysteresis.

The arguments prevSize and hysteresis should contain the most recently calculated screen size and a hysteresis threshold respectively. If the computed screen size differs from prevSize by less than hysteresis, then prevSize is used, otherwise the computed screen size is used. This helps prevent flickering between LOD levels when the computed size is very close to a threshold value. The size used (either prevSize or the newly computed size) will be returned in screenSizeOut so it can be used in next call to ComputeLOD.

Definition at line 443 of file screenSizeHeuristic.h.

◆ ComputeLOD() [2/3]

USDLOD_API float ComputeLOD ( const GfFrustum & frustum,
const GfMatrix4d & transform,
UsdTimeCode time = UsdTimeCode::Default() ) const
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Calculate an LOD index given a frustum and a transform.

See ComputeScreenSize

Definition at line 420 of file screenSizeHeuristic.h.

◆ ComputeLOD() [3/3]

USDLOD_API float ComputeLOD ( double size,
UsdTimeCode time = UsdTimeCode::Default() ) const
inline

Calculate an LOD index given a screen size.

Compare the size against the values in thresholds to determine an LOD index. If blendThresholds has values and size is between a thresholds value and its corresponding blendThresholds value, then the returned value will be non-integral. If the renderer can blend between 2 LOD item children then it should use the returned index as follows:

float index = heuristic.ComputeLOD(size);
if (blending_between_LOD_levels_is_active) {
int lowIndex = int(std::floor(index));
int highIndex = int(std::ceil(index));
float alpha = index - lowIndex;
// Display a linear interpolation using:
// (1-alpha) * item[lowIndex] + alpha * item[highIndex]
} else {
int index = int(std::round(index))
// Display item[index]
}

If blendThresholds is not set then only integral valued LOD indices will ever be returned.

Definition at line 407 of file screenSizeHeuristic.h.

◆ ComputeScreenSize() [1/2]

USDLOD_API double ComputeScreenSize ( const GfFrustum & frustum,
const GfMatrix4d & transform,
double prevSize,
double hysteresis,
UsdTimeCode time = UsdTimeCode::Default() ) const
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Calculate the screen size given a frustum and a transform with hysteresis.

The arguments prevSize and hysteresis should contain the most recently calculated screen size and a hysteresis threshold respectively. If the computed screen size differs from prevSize by less than hysteresis, then prevSize is returned, otherwise the computed screen size is returned. This helps prevent flickering between LOD levels when the computed size is very close to a threshold value.

Definition at line 368 of file screenSizeHeuristic.h.

◆ ComputeScreenSize() [2/2]

USDLOD_API double ComputeScreenSize ( const GfFrustum & frustum,
const GfMatrix4d & transform,
UsdTimeCode time = UsdTimeCode::Default() ) const
inline

Calculate the screen size given a frustum and a transform.

The matrix transform should convert from the root's local coordinate system to the viewpoint's coordinate system. Typically, the viewpoint will be specified in world coordinates and transform will convert from the root's coordinate system to world coordinates.

The returned screen size is measured as the projection of the extent (or its bounding sphere) onto the viewplane and converted to a fraction of the visible window. The projected shape is not clipped by the viewing frustum as we do not want the computed size of an extent to change simply because it is moving off the side of the screen.

If the extent crosses the near plane, then the calculated size will be 1.0 (i.e., 100%). If the extent is entirely in front of the near plane or entirely behind the far plane (would be clipped by near or far plane clipping) then the calculated size will be 0.0.

Definition at line 348 of file screenSizeHeuristic.h.

◆ CreateBlendThresholdsAttr()

USDLOD_API UsdAttribute CreateBlendThresholdsAttr ( VtValue const & defaultValue = VtValue(),
bool writeSparsely = false ) const

See GetBlendThresholdsAttr(), 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.

◆ CreateBoundingVolumeRel()

USDLOD_API UsdRelationship CreateBoundingVolumeRel ( ) const

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

◆ CreateExtentAttr()

USDLOD_API UsdAttribute CreateExtentAttr ( VtValue const & defaultValue = VtValue(),
bool writeSparsely = false ) const

See GetExtentAttr(), 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.

◆ CreateProjectionMethodAttr()

USDLOD_API UsdAttribute CreateProjectionMethodAttr ( VtValue const & defaultValue = VtValue(),
bool writeSparsely = false ) const

See GetProjectionMethodAttr(), 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.

◆ CreateScreenSizeHeuristicQuery()

USDLOD_API UsdLodScreenSizeHeuristicQuery CreateScreenSizeHeuristicQuery ( UsdTimeCode time = UsdTimeCode::Default()) const

Return a UsdLodScreenSizeHeuristicQuery that matches the current attribute values of this UsdLodScreenSizeHeuristic.

The UsdLodScreenSizeHeuristicQuery can be used to perform LOD calculations in a renderer without referencing back to the original USD data.

◆ CreateThresholdsAttr()

USDLOD_API UsdAttribute CreateThresholdsAttr ( VtValue const & defaultValue = VtValue(),
bool writeSparsely = false ) const

See GetThresholdsAttr(), 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.

◆ Define()

static USDLOD_API UsdLodScreenSizeHeuristic Define ( const UsdStagePtr & stage,
const SdfPath & path )
static

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined()) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema's prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget's namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

◆ Get()

static USDLOD_API UsdLodScreenSizeHeuristic Get ( const UsdStagePtr & stage,
const SdfPath & path )
static

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

UsdLodScreenSizeHeuristic(stage->GetPrimAtPath(path));
UsdLodScreenSizeHeuristic(const UsdPrim &prim=UsdPrim())
Construct a UsdLodScreenSizeHeuristic on UsdPrim prim .

◆ GetBlendThresholdsAttr()

USDLOD_API UsdAttribute GetBlendThresholdsAttr ( ) const

This defines screen size thresholds for LOD transitions in descending order.

The blend threshold is consulted for transitions that blend or combine multiple LOD items.

For example if:

  • thresholds is [0.25, 0.10, 0.025]
  • blendThresholds is [0.20, 0.08, 0.020]

then:

  • Use LOD 0 when size > 25%
  • Blend LOD 0 and LOD 1 when 25% >= size > 20%
  • Use LOD 1 when 20% >= size > 10%
  • Blend LOD 1 and LOD 2 when 10% >= size > 8%
  • Use LOD 2 when 8% >= size > 2.5%
  • Blend LOD 2 and LOD 3 when 2.5 >= size > 2%
  • Use LOD 3 when 2% >= size

The blend amount should be computed linearly between the corresponding thresholds and blendThresholds values. See thresholds for complementary information.

Declaration uniform float[] blendThresholds = []
C++ Type VtArray<float>
Usd Type SdfValueTypeNames->FloatArray
Variability SdfVariabilityUniform

◆ GetBoundingVolumeRel()

USDLOD_API UsdRelationship GetBoundingVolumeRel ( ) const

Optional relationship to a Boundable prim that defines the bounding volume for this LOD Root, used for size calculation if the referenced prim has a valid extent.

◆ GetExtentAttr()

USDLOD_API UsdAttribute GetExtentAttr ( ) const

The extent of this LOD Root in local coordinates.

This value is used to calculate the screen size from the camera if the boundingVolume relationship does not target a Boundable prim with a valid extent.

Declaration float3[] extent = [(-1, -1, -1), (1, 1, 1)]
C++ Type VtArray<GfVec3f>
Usd Type SdfValueTypeNames->Float3Array

◆ GetProjectionMethodAttr()

USDLOD_API UsdAttribute GetProjectionMethodAttr ( ) const

Defines how screen size is calculated.

  • projectedExtent: Project the extent to the view plane
  • projectedSphere: Project the extent bounding sphere to the view plane
Declaration uniform token projectionMethod = "projectedSphere"
C++ Type TfToken
Usd Type SdfValueTypeNames->Token
Variability SdfVariabilityUniform
Allowed Values projectedExtent, projectedSphere

◆ GetSchemaAttributeNames()

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

◆ GetThresholdsAttr()

USDLOD_API UsdAttribute GetThresholdsAttr ( ) const

The screen size thresholds for LOD transitions in descending order as a fraction of the viewport size.

For example, [0.25, 0.10, 0.025] means:

  • Use LOD 0 when the bounds cover more than 25% of the screen
  • Use LOD 1 when the bounds cover 25% or less but more than 10%
  • Use LOD 2 when the bounds cover 10% or less but more than 2.5%
  • Use LOD 3 when the bounds cover 2.5% or less of the screen

This field is advisory and not strongly interoperable.

Declaration uniform float[] thresholds = []
C++ Type VtArray<float>
Usd Type SdfValueTypeNames->FloatArray
Variability SdfVariabilityUniform

Friends And Related Symbol Documentation

◆ UsdSchemaRegistry

friend class UsdSchemaRegistry
friend

Definition at line 150 of file screenSizeHeuristic.h.

Member Data Documentation

◆ schemaKind

const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped
static

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

See also
UsdSchemaKind

Definition at line 72 of file screenSizeHeuristic.h.


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