Represents a group of views that collectively select tiles from a particular Tileset. More...

#include <Cesium3DTilesSelection/TilesetViewGroup.h>

Inheritance diagram for Cesium3DTilesSelection::TilesetViewGroup:

Classes
struct	LoadQueueCheckpoint
	A checkpoint within this view group's load queue. More...

Public Types
using	TraversalState
	The type of the `CesiumUtility::TreeTraversalState` used to track tile selection states for this view group.

Public Member Functions
	TilesetViewGroup () noexcept
	Constructs a new instance.

	TilesetViewGroup (const TilesetViewGroup &rhs) noexcept
	Constructs a new instance as a copy of an existing one.

	TilesetViewGroup (TilesetViewGroup &&rhs) noexcept
	Moves an existing view group into a new one.

const ViewUpdateResult &	getViewUpdateResult () const
	Gets the result from the last time this view group was updated by calling `Tileset::updateViewGroup`.

ViewUpdateResult &	getViewUpdateResult ()
	Gets the result from the last time this view group was updated by calling `Tileset::updateViewGroup`.

TraversalState &	getTraversalState () noexcept
	Gets an object used to track the selection state of tiles as they are traversed for this view group.

const TraversalState &	getTraversalState () const noexcept
	Gets an object used to track the selection state of tiles as they are traversed for this view group.

void	addToLoadQueue (const TileLoadTask &task)
	Adds a tile load task to this view group's load queue.

LoadQueueCheckpoint	saveTileLoadQueueCheckpoint ()
	Saves a checkpoint of the tile load queue associated with this view group.

size_t	restoreTileLoadQueueCheckpoint (const LoadQueueCheckpoint &checkpoint)
	Restores a previously-saved checkpoint of the tile load queue associated with this view group.

size_t	getWorkerThreadLoadQueueLength () const
	Gets the number of tiles that are currently in the queue waiting to be loaded in the worker thread.

size_t	getMainThreadLoadQueueLength () const
	Gets the number of tiles that are currently in the queue waiting to be loaded in the main thread.

void	startNewFrame (const Tileset &tileset, const TilesetFrameState &frameState)
	Starts a new frame, clearing the set of tiles to be loaded so that a new set can be selected.

void	finishFrame (const Tileset &tileset, const TilesetFrameState &frameState)
	Finishes the current frame by making the current tile selection state the previous one and releasing references to tiles in the old previous one.

float	getPreviousLoadProgressPercentage () const
	Gets the previous load progress percentage for this view group as of the last time it was updated.

double	getWeight () const override

void	setWeight (double weight) noexcept
	Sets the weight of this view group relative to other tile requesters.

bool	hasMoreTilesToLoadInWorkerThread () const override

Tile *	getNextTileToLoadInWorkerThread () override

bool	hasMoreTilesToLoadInMainThread () const override

Tile *	getNextTileToLoadInMainThread () override

Public Member Functions inherited from Cesium3DTilesSelection::TileLoadRequester
void	unregister () noexcept
	Unregister this requester with the {link Tileset} with which it is currently registered. Once unregistered, it will not influence tile loads until registered again.

Additional Inherited Members
Protected Member Functions inherited from Cesium3DTilesSelection::TileLoadRequester
	TileLoadRequester () noexcept
	Constructs a new instance.

	TileLoadRequester (const TileLoadRequester &rhs) noexcept
	Constructs a new instance as a copy of an existing one.

	TileLoadRequester (TileLoadRequester &&rhs) noexcept
	Moves an existing instance into a new one.

virtual	~TileLoadRequester () noexcept
	Destroys this instance.

Detailed Description

Represents a group of views that collectively select tiles from a particular Tileset.

Create an instance of this class and pass it repeatedly to Tileset::updateViewGroup to select tiles suitable for rendering the tileset from a given view or set of views.

This class is intentionally decoupled from ViewState, such that clients are responsible for managing which views are represented by any particular group.

Definition at line 34 of file TilesetViewGroup.h.

Member Typedef Documentation

◆ TraversalState

using Cesium3DTilesSelection::TilesetViewGroup::TraversalState

Initial value:

CesiumUtility::TreeTraversalState<Tile::Pointer, TileSelectionState>

CesiumUtility::TreeTraversalState

Associates state (arbitrary data) with each node during partial, depth-first traversal of a tree....

Definition TreeTraversalState.h:35

The type of the CesiumUtility::TreeTraversalState used to track tile selection states for this view group.

Definition at line 41 of file TilesetViewGroup.h.

Constructor & Destructor Documentation

◆ TilesetViewGroup() [1/2]

Cesium3DTilesSelection::TilesetViewGroup::TilesetViewGroup ( const TilesetViewGroup & rhs )

noexcept

Constructs a new instance as a copy of an existing one.

The new instance will be equivalent to the existing one, but it will not be registered with the Cesium3DTilesSelection::Tileset.

Parameters

rhs	The view group to copy.

◆ TilesetViewGroup() [2/2]

Cesium3DTilesSelection::TilesetViewGroup::TilesetViewGroup ( TilesetViewGroup && rhs )

noexcept

Moves an existing view group into a new one.

The new instance will be registered with the Cesium3DTilesSelection::Tileset, and the old one will be unregistered.

Parameters

rhs	The view group to move from.

Member Function Documentation

◆ addToLoadQueue()

void Cesium3DTilesSelection::TilesetViewGroup::addToLoadQueue ( const TileLoadTask & task )

Adds a tile load task to this view group's load queue.

Each tile may only be added once per call to startNewFrame. Adding a tile multiple times will lead to an assertion in debug builds and undefined behavior in release builds.

Parameters

task	The tile load task to add to the queue.

◆ finishFrame()

void Cesium3DTilesSelection::TilesetViewGroup::finishFrame	(	const Tileset &	tileset,
		const TilesetFrameState &	frameState )

Finishes the current frame by making the current tile selection state the previous one and releasing references to tiles in the old previous one.

This method also updates the load progress percentage returned by getPreviousLoadProgressPercentage and makes sure credits used by this view group have been referenced on the CesiumUtility::CreditSystem.

Parameters

tileset	The tileset that is finishing the current frame.
frameState	The state of the frame.

◆ getNextTileToLoadInMainThread()

Tile * Cesium3DTilesSelection::TilesetViewGroup::getNextTileToLoadInMainThread ( )

overridevirtual

Gets the next Tile that this requester would like loaded in the main thread.When hasMoreTilesToLoadInMainThread returns false, this method can and should return nullptr. However, when that method returns true, this method must return a valid Tile pointer.The returned tile must have a reference count greater than zero. Otherwise, the Tile would be immediately eligible for unloading, so it doesn't make sense to load it. In debug builds, this is enforced with an assertion. In release builds, unreferenced tiles are silently ignored.

Returns: The next tile to load in the main thread.

Implements Cesium3DTilesSelection::TileLoadRequester.

◆ getNextTileToLoadInWorkerThread()

Tile * Cesium3DTilesSelection::TilesetViewGroup::getNextTileToLoadInWorkerThread ( )

overridevirtual

Gets the next Tile that this requester would like loaded in a worker thread.When hasMoreTilesToLoadInWorkerThread returns false, this method can and should return nullptr. However, when that method returns true, this method must return a valid Tile pointer.The returned tile must have a reference count greater than zero. Otherwise, the Tile would be immediately eligible for unloading, so it doesn't make sense to load it. In debug builds, this is enforced with an assertion. In release builds, unreferenced tiles are silently ignored.

Returns: The next tile to load in a worker thread.

Implements Cesium3DTilesSelection::TileLoadRequester.

◆ getPreviousLoadProgressPercentage()

float Cesium3DTilesSelection::TilesetViewGroup::getPreviousLoadProgressPercentage ( ) const

Gets the previous load progress percentage for this view group as of the last time it was updated.

This method reports the progress as of the last call to finishFrame.

The reported percentage is computed as:

\(100.0\frac{totalTilesVisited - tilesNeedingLoading}{totalTilesVisited}\)

When loading is complete, this method will return exactly 100.0.

◆ getTraversalState() [1/2]

const TraversalState & Cesium3DTilesSelection::TilesetViewGroup::getTraversalState ( ) const

inlinenoexcept

Gets an object used to track the selection state of tiles as they are traversed for this view group.

Definition at line 87 of file TilesetViewGroup.h.

◆ getTraversalState() [2/2]

TraversalState & Cesium3DTilesSelection::TilesetViewGroup::getTraversalState ( )

inlinenoexcept

Gets an object used to track the selection state of tiles as they are traversed for this view group.

Definition at line 84 of file TilesetViewGroup.h.

◆ getViewUpdateResult()

ViewUpdateResult & Cesium3DTilesSelection::TilesetViewGroup::getViewUpdateResult ( )

Gets the result from the last time this view group was updated by calling Tileset::updateViewGroup.

◆ getWeight()

double Cesium3DTilesSelection::TilesetViewGroup::getWeight ( ) const

overridevirtual

Gets the weight of this requester relative to others.Most requesters should return a weight of 1.0. When all requesters have the same weight, they will all have an equal opportunity to load tiles. If one requester's weight is 2.0 and the rest are 1.0, that requester will have twice as many opportunities to load tiles as the others.A very high weight will prevent all other requesters from loading tiles until this requester has none left to load. A very low weight (but above 0.0!) will allow all other requesters to finish loading tiles before this one starts.

Returns: The weight of this requester, which must be greater than 0.0.

Implements Cesium3DTilesSelection::TileLoadRequester.

◆ hasMoreTilesToLoadInMainThread()

bool Cesium3DTilesSelection::TilesetViewGroup::hasMoreTilesToLoadInMainThread ( ) const

overridevirtual

Determines if this requester has any more tiles that need to be loaded in the main thread. To determine if a particular Tile needs to be loaded in the main thread, call Tile::needsMainThreadLoading.

Returns: true if this requester has further tiles that need loading by the main thread; otherwise, false.

Implements Cesium3DTilesSelection::TileLoadRequester.

◆ hasMoreTilesToLoadInWorkerThread()

bool Cesium3DTilesSelection::TilesetViewGroup::hasMoreTilesToLoadInWorkerThread ( ) const

overridevirtual

Determines if this requester has any more tiles that need to be loaded in a worker thread. To determine if a particular Tile needs to be loaded in a worker thread, call Tile::needsWorkerThreadLoading.

Returns: true if this requester has further tiles that need loading by a worker thread; otherwise, false.

Implements Cesium3DTilesSelection::TileLoadRequester.

◆ restoreTileLoadQueueCheckpoint()

size_t Cesium3DTilesSelection::TilesetViewGroup::restoreTileLoadQueueCheckpoint ( const LoadQueueCheckpoint & checkpoint )

Restores a previously-saved checkpoint of the tile load queue associated with this view group.

Restoring a checkpoint discards all tiles from the queue that were requested, with a call to addToLoadQueue, since the checkpoint was created.

This method should only be called in between calls to startNewFrame and finishFrame.

Parameters

checkpoint The previously-created checkpoint.

Returns: The number of tiles that were discarded from the queue as a result of restoring the checkpoint.

◆ saveTileLoadQueueCheckpoint()

LoadQueueCheckpoint Cesium3DTilesSelection::TilesetViewGroup::saveTileLoadQueueCheckpoint ( )

Saves a checkpoint of the tile load queue associated with this view group.

The saved checkpoint can later be restored by calling restoreTileLoadQueueCheckpoint.

This method should only be called in between calls to startNewFrame and finishFrame.

Returns: The checkpoint.

◆ setWeight()

void Cesium3DTilesSelection::TilesetViewGroup::setWeight ( double weight )

noexcept

Sets the weight of this view group relative to other tile requesters.

See getWeight for an explanation of the meaning of the weight.

Parameters

weight The new weight for this view group.

◆ startNewFrame()

void Cesium3DTilesSelection::TilesetViewGroup::startNewFrame	(	const Tileset &	tileset,
		const TilesetFrameState &	frameState )

Starts a new frame, clearing the set of tiles to be loaded so that a new set can be selected.

Parameters

tileset	The tileset that is starting the new frame.
frameState	The state of the new frame.

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

/home/runner/work/cesium-native/cesium-native/Cesium3DTilesSelection/include/Cesium3DTilesSelection/TilesetViewGroup.h

Classes

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ TraversalState

Constructor & Destructor Documentation

◆ TilesetViewGroup() [1/2]

◆ TilesetViewGroup() [2/2]

Member Function Documentation

◆ addToLoadQueue()

◆ finishFrame()

◆ getNextTileToLoadInMainThread()

◆ getNextTileToLoadInWorkerThread()

◆ getPreviousLoadProgressPercentage()

◆ getTraversalState() [1/2]

◆ getTraversalState() [2/2]

◆ getViewUpdateResult()

◆ getWeight()

◆ hasMoreTilesToLoadInMainThread()

◆ hasMoreTilesToLoadInWorkerThread()

◆ restoreTileLoadQueueCheckpoint()

◆ saveTileLoadQueueCheckpoint()

◆ setWeight()

◆ startNewFrame()