This class implements the internals of an LOD distance heuristic, but without any dependencies on USD scene data or any USD data types. More...

#include <distanceHeuristicQuery.h>

Inheritance diagram for UsdLodDistanceHeuristicQuery:

Public Types
using	Parent = UsdLodHeuristicQuery

Public Member Functions
	UsdLodDistanceHeuristicQuery (const UsdLodDistanceHeuristicQuery &)=default

	UsdLodDistanceHeuristicQuery (UsdLodDistanceHeuristicQuery &&)=default

	UsdLodDistanceHeuristicQuery (const TfToken &domainIn, const GfVec3f &centerIn=GfVec3f(0.0, 0.0, 0.0), const GfRange3d &extentIn=GfRange3d(), const VtFloatArray &thresholdsIn=VtFloatArray(), const VtFloatArray &blendThresholdsIn=VtFloatArray())

virtual USDLOD_API	~UsdLodDistanceHeuristicQuery ()
	Destructor.

USDLOD_API double	ComputeDistance (const GfVec3d &viewpoint, const GfMatrix4d &transform) const
	Compute a distance given a `viewpoint` and a `transform`.

double	ComputeDistance (const GfVec3d &viewpoint, const GfMatrix4d &transform, double prevDistance, double hysteresis) 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 distance applying hysteresis to the result.

USDLOD_API float	ComputeLOD (double distance) const
	Compute an LOD index given a distance.

float	ComputeLOD (const GfVec3d &viewpoint, const GfMatrix4d &transform) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Compute an LOD index given a `viewpoint` and a `transform`.

float	ComputeLOD (const GfVec3d &viewpoint, const GfMatrix4d &transform, double prevDistance, double hysteresis, double *distanceOut) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Compute an LOD index given a `viewpoint,` a `transform`, a `prevDistance,` and a `hysteresis` value.

Public Member Functions inherited from UsdLodHeuristicQuery
	UsdLodHeuristicQuery (const TfToken &lodDomainIn)
	Construct with an explicit domain.

virtual USDLOD_API	~UsdLodHeuristicQuery ()
	Destructor.

Public Attributes
GfVec3f	center = {0.0, 0.0, 0.0}
	The `center` point of the LOD root in the local coordinates.

GfRange3d	extent
	The bounding box of the geometry, stored in a GfRange3d.

VtFloatArray	thresholds
	The distance thresholds for LOD transitions in ascending order.

VtFloatArray	blendThresholds
	This defines distance thresholds for LOD transitions in ascending order.

Public Attributes inherited from UsdLodHeuristicQuery
TfToken	lodDomain
	The LOD domain of this heuristic.

Detailed Description

This class implements the internals of an LOD distance heuristic, but without any dependencies on USD scene data or any USD data types.

It is intended to be usable inside a renderer to make fast, run-time LOD decisions without requiring access back to the original USD layers or prims.

The data types match the UsdLodDistanceHeuristic prim type: a center point or an extent, and one or two sets of distance thresholds. See the documentation for UsdLodDistanceHeuristic for full details.

Definition at line 38 of file distanceHeuristicQuery.h.

Member Typedef Documentation

◆ Parent

using Parent = UsdLodHeuristicQuery

Definition at line 41 of file distanceHeuristicQuery.h.

Constructor & Destructor Documentation

◆ UsdLodDistanceHeuristicQuery()

UsdLodDistanceHeuristicQuery	(	const TfToken &	domainIn,
		const GfVec3f &	centerIn = GfVec3f(0.0, 0.0, 0.0),
		const GfRange3d &	extentIn = GfRange3d(),
		const VtFloatArray &	thresholdsIn = VtFloatArray(),
		const VtFloatArray &	blendThresholdsIn = VtFloatArray() )

inline

Definition at line 97 of file distanceHeuristicQuery.h.

◆ ~UsdLodDistanceHeuristicQuery()

virtual USDLOD_API ~UsdLodDistanceHeuristicQuery ( )

virtual

Destructor.

The destructor is virtual to support RTTI and allow the object to be safely held as a pointer to UsdLodHeuristicQuery.

Member Function Documentation

◆ ComputeDistance() [1/2]

USDLOD_API double ComputeDistance	(	const GfVec3d &	viewpoint,
		const GfMatrix4d &	transform ) const

Compute a distance given a viewpoint and a transform.

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

If transform is close to singular then any extent is ignored and the distance is calculated from viewpoint to center.

See also: UsdLodDistanceHeuristicQuery::ComputeLOD

◆ ComputeDistance() [2/2]

double ComputeDistance	(	const GfVec3d &	viewpoint,
		const GfMatrix4d &	transform,
		double	prevDistance,
		double	hysteresis ) 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 distance applying hysteresis to the result.

The arguments prevDistance and hysteresis should contain the most recently calculated distance and a hysteresis threshold respectively. If the actual distance is within hysteresis distance of prevDistance then prevDistance is returned. If the actual distance is outside the hysteresis window then the returned value lags behind the actual value by hysteresis. Specifically, if the actual distance is greater than prevDistance + hysteresis then the calculated distance - hysteresis is returned and if it is less than prevDistance - hysteresis then the calculated distance + hysteresis is returned. This helps prevent flickering between LOD levels when the computed size is very close to a threshold value.

Definition at line 145 of file distanceHeuristicQuery.h.

◆ ComputeLOD() [1/3]

float ComputeLOD	(	const GfVec3d &	viewpoint,
		const GfMatrix4d &	transform ) const

inline

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

Compute the distance given viewpoint and transform, then compute the LOD index from that distance.

Definition at line 198 of file distanceHeuristicQuery.h.

◆ ComputeLOD() [2/3]

float ComputeLOD	(	const GfVec3d &	viewpoint,
		const GfMatrix4d &	transform,
		double	prevDistance,
		double	hysteresis,
		double *	distanceOut ) const

inline

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

Compute the distance given the input arguments, then compute the LOD index from that distance. The computed distance is stored in the double pointed to by distanceOut.

The computed distance will be stored in distanceOut so it can be used in the next call to ComputeLOD with hysteresis.

See also: ComputeDistance for details on the hysteresis calculation.

Definition at line 217 of file distanceHeuristicQuery.h.

◆ ComputeLOD() [3/3]

USDLOD_API float ComputeLOD ( double distance ) const

Compute an LOD index given a distance.

Compare the distance against the values in thresholds to determine an LOD index. If blendThresholds has values and distance 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(distance);
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]
}

Member Data Documentation

◆ blendThresholds

VtFloatArray blendThresholds

This defines distance thresholds for LOD transitions in ascending order.

If blendThresholds values are defined, then the calculation can return a result between two levels of detail that can be used to blend or combine two LOD items.

For example if:

thresholds is [10.0, 50.0, 100.0]
blendThresholds is [11.0, 55.0, 110.0]

then:

Use LOD 0 when distance < 10.0 (from thresholds)
Blend LOD 0 and LOD 1 when 10.0 <= distance < 11.0 (min to max)
Use LOD 1 when 11.0 <= distance < 50.0 (max to min)
Blend LOD 1 and LOD 2 when 50 <= distance < 55.0
Use LOD 2 when 55.0 <= distance < 100.0
Blend LOD 2 and LOD 3 when 100 <= distance < 110.0
Use LOD 3 when 110.0 <= distance

The blend amount should be computed linearly between the corresponding thresholds and blendThresholds values.

This field is advisory and not strongly interoperable.

See also: UsdLodDistanceHeuristicQuery::thresholds and UsdLodDistanceHeuristicQuery::ComputeLOD

Definition at line 90 of file distanceHeuristicQuery.h.

◆ center

GfVec3f center = {0.0, 0.0, 0.0}

The center point of the LOD root in the local coordinates.

If extent is empty then this center point is used to compute the distance. If extent is not empty, center is ignored.

Definition at line 47 of file distanceHeuristicQuery.h.

◆ extent

GfRange3d extent

The bounding box of the geometry, stored in a GfRange3d.

If the value is not empty, it will be used to compute the distance, otherwise the value of center will be used. The value is empty by default.

Definition at line 52 of file distanceHeuristicQuery.h.

◆ thresholds

VtFloatArray thresholds

The distance thresholds for LOD transitions in ascending order.

For example, the values {10.0, 50.0, 100.0} would mean:

Use LOD 0 when distance < 10.0
Use LOD 1 when 10.0 <= distance < 50.0
Use LOD 2 when 50.0 <= distance < 100.0
Use LOD 3 when 100.0 <= distance

See also: UsdLodDistanceHeuristicQuery::blendThresholds

Definition at line 63 of file distanceHeuristicQuery.h.

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

pxr/usd/usdLod/distanceHeuristicQuery.h

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ Parent

Constructor & Destructor Documentation

◆ UsdLodDistanceHeuristicQuery()

◆ ~UsdLodDistanceHeuristicQuery()

Member Function Documentation

◆ ComputeDistance() [1/2]

◆ ComputeDistance() [2/2]

◆ ComputeLOD() [1/3]

◆ ComputeLOD() [2/3]

◆ ComputeLOD() [3/3]

Member Data Documentation

◆ blendThresholds

◆ center

◆ extent

◆ thresholds