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

#include <screenSizeHeuristicQuery.h>

Inheritance diagram for UsdLodScreenSizeHeuristicQuery:

Public Types
using	Parent = UsdLodHeuristicQuery

Public Member Functions
	UsdLodScreenSizeHeuristicQuery (const UsdLodScreenSizeHeuristicQuery &)=default

	UsdLodScreenSizeHeuristicQuery (UsdLodScreenSizeHeuristicQuery &&)=default

	UsdLodScreenSizeHeuristicQuery (const TfToken &domainIn, const GfRange3d extentIn=GfRange3d(), const TfToken &projectionMethodIn=UsdLodTokens->projectedSphere, const VtFloatArray &thresholdsIn=VtFloatArray(), const VtFloatArray &blendThresholdsIn=VtFloatArray())

virtual USDLOD_API	~UsdLodScreenSizeHeuristicQuery ()
	Destructor.

USDLOD_API double	ComputeScreenSize (const GfFrustum &frustum, const GfMatrix4d &transform) const
	Calculate the screen size given a `frustum` and a `transform`.

double	ComputeScreenSize (const GfFrustum &frustum, const GfMatrix4d &transform, double prevSize, 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 screen size applying hysteresis to the result.

USDLOD_API float	ComputeLOD (double size) const
	Calculate an LOD index given a screen size.

float	ComputeLOD (const GfFrustum &frustum, 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. Calculate an LOD index given a `frustum` and a `transform`.

float	ComputeLOD (const GfFrustum &frustum, const GfMatrix4d &transform, double prevSize, double hysteresis, double *sizeOut) 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 UsdLodHeuristicQuery
	UsdLodHeuristicQuery (const TfToken &lodDomainIn)
	Construct with an explicit domain.

virtual USDLOD_API	~UsdLodHeuristicQuery ()
	Destructor.

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

TfToken	projectionMethod = UsdLodTokens->projectedSphere
	Defines how screen size is calculated.

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

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

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

Detailed Description

This class implements the internals of an LOD screenSize 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 UsdLodScreenSizeHeuristic prim type: a center point or an extent, and one or two sets of screen size thresholds. See the documentation for UsdLodScreenSizeHeuristic for full details.

Definition at line 39 of file screenSizeHeuristicQuery.h.

Member Typedef Documentation

◆ Parent

using Parent = UsdLodHeuristicQuery

Definition at line 42 of file screenSizeHeuristicQuery.h.

Constructor & Destructor Documentation

◆ UsdLodScreenSizeHeuristicQuery()

UsdLodScreenSizeHeuristicQuery	(	const TfToken &	domainIn,
		const GfRange3d	extentIn = GfRange3d(),
		const TfToken &	projectionMethodIn = UsdLodTokens->projectedSphere,
		const VtFloatArray &	thresholdsIn = VtFloatArray(),
		const VtFloatArray &	blendThresholdsIn = VtFloatArray() )

inline

Definition at line 132 of file screenSizeHeuristicQuery.h.

◆ ~UsdLodScreenSizeHeuristicQuery()

virtual USDLOD_API ~UsdLodScreenSizeHeuristicQuery ( )

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

◆ ComputeLOD() [1/3]

float ComputeLOD	(	const GfFrustum &	frustum,
		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. Calculate an LOD index given a frustum and a transform.

See ComputeScreenSize

Definition at line 235 of file screenSizeHeuristicQuery.h.

◆ ComputeLOD() [2/3]

float ComputeLOD	(	const GfFrustum &	frustum,
		const GfMatrix4d &	transform,
		double	prevSize,
		double	hysteresis,
		double *	sizeOut ) 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 sizeOut so it can be used in next call to ComputeLOD.

Definition at line 254 of file screenSizeHeuristicQuery.h.

◆ ComputeLOD() [3/3]

USDLOD_API float ComputeLOD ( double size ) const

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.

◆ ComputeScreenSize() [1/2]

USDLOD_API double ComputeScreenSize	(	const GfFrustum &	frustum,
		const GfMatrix4d &	transform ) const

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.

◆ ComputeScreenSize() [2/2]

double ComputeScreenSize	(	const GfFrustum &	frustum,
		const GfMatrix4d &	transform,
		double	prevSize,
		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 screen size applying hysteresis to the result.

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 181 of file screenSizeHeuristicQuery.h.

Member Data Documentation

◆ blendThresholds

VtFloatArray blendThresholds

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% (from thresholds)
Blend LOD 0 and LOD 1 when 25% >= size > 20% (min to max)
Use LOD 1 when 20% >= size > 10% (max to min)
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.

This field is advisory and not strongly interoperable.

See also: UsdLodScreenSizeHeuristicQuery::thresholds and UsdLodScreenSizeHeuristicQuery::ComputeLOD

Definition at line 125 of file screenSizeHeuristicQuery.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 screenSize, otherwise the value of center will be used. The value is empty by default.

Definition at line 48 of file screenSizeHeuristicQuery.h.

◆ projectionMethod

TfToken projectionMethod = UsdLodTokens->projectedSphere

Defines how screen size is calculated.

projectedExtent: Project the extent to the view plane
projectedSphere: Project the extent bounding sphere to the view plane

If projectionMethod is projectedSphere, a very quick approximation of the extent area is used.

The extent is transformed to world space.
A sphere's center and diameter are computed from the extent's diagonal.
If the entire sphere is clipped by the frustum, the area is 0.0.
If the frustum uses perspective then the diameter is scaled down by the distance from the view point to the center. The diameter is unchanged for orthographic frustums.
The area of a circle with that diameter is divided by the area of the view window to calculate the fraction of the view window that the sphere could cover.

If projectionMethod is projectedExtent, a more expensive but more accurate computation is used.

The extent box is transformed into the frustum's clip space.
If the extent is entirely clipped, the area is 0.0
The extent is clipped against the near clip plane, possibly generating new vertices.
The convex hull of the remaining vertices is found.
The area of the convex hull polygon is computed and divided by the area of the screen to calculate the fraction of the view window that the extent could cover.

Definition at line 87 of file screenSizeHeuristicQuery.h.

◆ thresholds

VtFloatArray thresholds

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

For example, the values {0.25, 0.10, 0.025} would mean:

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

See also: UsdLodScreenSizeHeuristicQuery::blendThresholds

Definition at line 99 of file screenSizeHeuristicQuery.h.

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

pxr/usd/usdLod/screenSizeHeuristicQuery.h

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ Parent

Constructor & Destructor Documentation

◆ UsdLodScreenSizeHeuristicQuery()

◆ ~UsdLodScreenSizeHeuristicQuery()

Member Function Documentation

◆ ComputeLOD() [1/3]

◆ ComputeLOD() [2/3]

◆ ComputeLOD() [3/3]

◆ ComputeScreenSize() [1/2]

◆ ComputeScreenSize() [2/2]

Member Data Documentation

◆ blendThresholds

◆ extent

◆ projectionMethod

◆ thresholds