A 3D Tiles tileset, used for streaming massive heterogeneous 3D geospatial datasets. More...

#include <Cesium3DTilesSelection/Tileset.h>

Public Member Functions
	Tileset (const TilesetExternals &externals, std::unique_ptr< TilesetContentLoader > &&pCustomLoader, std::unique_ptr< Tile > &&pRootTile, const TilesetOptions &options=TilesetOptions())
	Constructs a new instance with a given custom tileset loader.

	Tileset (const TilesetExternals &externals, const std::string &url, const TilesetOptions &options=TilesetOptions())
	Constructs a new instance with a given `tileset.json` URL.

	Tileset (const TilesetExternals &externals, int64_t ionAssetID, const std::string &ionAccessToken, const TilesetOptions &options=TilesetOptions(), const std::string &ionAssetEndpointUrl="https://api.cesium.com/")
	Constructs a new instance with the given asset ID on Cesium ion.

	Tileset (const TilesetExternals &externals, TilesetContentLoaderFactory &&loaderFactory, const TilesetOptions &options=TilesetOptions())
	Constructs a new instance with the given TilesetContentLoaderFactory.

	~Tileset () noexcept
	Destroys this tileset.

CesiumAsync::SharedFuture< void > &	getAsyncDestructionCompleteEvent ()
	A future that resolves when this Tileset has been destroyed (i.e. its destructor has been called) and all async operations that it was executing have completed.

CesiumAsync::SharedFuture< void > &	getRootTileAvailableEvent ()
	A future that resolves when the details of the root tile of this tileset are available. The root tile's content (e.g., 3D model), however, will not necessarily be loaded yet.

std::optional< CesiumUtility::Credit >	getUserCredit () const noexcept
	Gets the `CesiumUtility::Credit` created from `TilesetOptions::credit`, if any.

const std::vector< CesiumUtility::Credit > &	getTilesetCredits () const noexcept
	Get tileset credits.

void	setShowCreditsOnScreen (bool showCreditsOnScreen) noexcept
	Sets whether or not the tileset's credits should be shown on screen.

TilesetExternals &	getExternals () noexcept
	Gets the `TilesetExternals` that summarize the external interfaces used by this tileset.

const TilesetExternals &	getExternals () const noexcept
	Gets the `TilesetExternals` that summarize the external interfaces used by this tileset.

CesiumAsync::AsyncSystem &	getAsyncSystem () noexcept
	Returns the `CesiumAsync::AsyncSystem` that is used for dispatching asynchronous tasks.

const CesiumAsync::AsyncSystem &	getAsyncSystem () const noexcept
	Returns the `CesiumAsync::AsyncSystem` that is used for dispatching asynchronous tasks.

const TilesetOptions &	getOptions () const noexcept
	Gets the `TilesetOptions` of this tileset.

TilesetOptions &	getOptions () noexcept
	Gets the `TilesetOptions` of this tileset.

const CesiumGeospatial::Ellipsoid &	getEllipsoid () const
	Gets the `CesiumGeospatial::Ellipsoid` used by this tileset.

CesiumGeospatial::Ellipsoid &	getEllipsoid () noexcept
	Gets the `CesiumGeospatial::Ellipsoid` used by this tileset.

Tile *	getRootTile () noexcept
	Gets the root tile of this tileset.

const Tile *	getRootTile () const noexcept
	Gets the root tile of this tileset.

RasterOverlayCollection &	getOverlays () noexcept
	Returns the `RasterOverlayCollection` of this tileset.

const RasterOverlayCollection &	getOverlays () const noexcept
	Returns the `RasterOverlayCollection` of this tileset.

TilesetSharedAssetSystem &	getSharedAssetSystem () noexcept
	Returns the `TilesetSharedAssetSystem` of this tileset.

const TilesetSharedAssetSystem &	getSharedAssetSystem () const noexcept
	Returns the `TilesetSharedAssetSystem` of this tileset.

const ViewUpdateResult &	updateViewOffline (const std::vector< ViewState > &frustums)
	Updates this view but waits for all tiles that meet sse to finish loading and ready to be rendered before returning the function. This method is significantly slower than `Tileset::updateView` and should only be used for capturing movie or non-realtime situation.

const ViewUpdateResult &	updateView (const std::vector< ViewState > &frustums, float deltaTime=0.0f)
	Updates this view, returning the set of tiles to render in this view.

int32_t	getNumberOfTilesLoaded () const
	Gets the total number of tiles that are currently loaded.

float	computeLoadProgress () noexcept
	Gets the percentage of tiles that had been loaded for the default view group as of the last time it was updated.

LoadedConstTileEnumerator	loadedTiles () const
	Gets an object that can be used to enumerate the loaded tiles of this tileset.

LoadedTileEnumerator	loadedTiles ()
	Gets an object that can be used to enumerate the loaded tiles of this tileset.

void	forEachLoadedTile (const std::function< void(Tile &tile)> &callback)
	Invokes a function for each tile that is currently loaded.

void	forEachLoadedTile (const std::function< void(const Tile &tile)> &callback) const
	Invokes a function for each tile that is currently loaded.

int64_t	getTotalDataBytes () const noexcept
	Gets the total number of bytes of tile and raster overlay data that are currently loaded.

const TilesetMetadata *	getMetadata (const Tile *pTile=nullptr) const
	Gets the `TilesetMetadata` associated with the main or external tileset.json that contains a given tile. If the metadata is not yet loaded, this method returns nullptr.

CesiumAsync::Future< const TilesetMetadata * >	loadMetadata ()
	Asynchronously loads the metadata associated with the main tileset.json.

CesiumAsync::Future< SampleHeightResult >	sampleHeightMostDetailed (const std::vector< CesiumGeospatial::Cartographic > &positions)
	Initiates an asynchronous query for the height of this tileset at a list of cartographic positions (longitude and latitude). The most detailed available tiles are used to determine each height.

TilesetViewGroup &	getDefaultViewGroup ()
	Gets the default view group that is used when calling `updateView`.

const TilesetViewGroup &	getDefaultViewGroup () const
	Gets the default view group that is used when calling `updateView`.

const ViewUpdateResult &	updateViewGroup (TilesetViewGroup &viewGroup, const std::vector< ViewState > &frustums, float deltaTime=0.0f)
	Updates a view group, returning the set of tiles to render in this view.

const ViewUpdateResult &	updateViewGroupOffline (TilesetViewGroup &viewGroup, const std::vector< ViewState > &frustums)
	Updates a view group, returning the set of tiles to render in this view. Unlike `updateViewGroup`, this method blocks the calling thread until all tiles suitable for the views have been loaded.

void	loadTiles ()
	Loads the tiles that are currently deemed the most important, across all height queries and `TilesetViewGroup` instances.

void	registerLoadRequester (TileLoadRequester &requester)
	Registers a tile load requester with this Tileset. Registered tile load requesters get to influence which tiles are loaded when `loadTiles` is called.

	Tileset (const Tileset &rhs)=delete

Tileset &	operator= (const Tileset &rhs)=delete

Detailed Description

A 3D Tiles tileset, used for streaming massive heterogeneous 3D geospatial datasets.

Definition at line 42 of file Tileset.h.

Constructor & Destructor Documentation

◆ Tileset() [1/4]

Cesium3DTilesSelection::Tileset::Tileset	(	const TilesetExternals &	externals,
		std::unique_ptr< TilesetContentLoader > &&	pCustomLoader,
		std::unique_ptr< Tile > &&	pRootTile,
		const TilesetOptions &	options = TilesetOptions() )

Constructs a new instance with a given custom tileset loader.

Parameters

externals	The external interfaces to use.
pCustomLoader	The custom loader used to load the tileset and tile content.
pRootTile	The root tile that is associated with the custom loader
options	Additional options for the tileset.

◆ Tileset() [2/4]

Cesium3DTilesSelection::Tileset::Tileset	(	const TilesetExternals &	externals,
		const std::string &	url,
		const TilesetOptions &	options = TilesetOptions() )

Constructs a new instance with a given tileset.json URL.

Parameters

externals	The external interfaces to use.
url	The URL of the `tileset.json`.
options	Additional options for the tileset.

◆ Tileset() [3/4]

Cesium3DTilesSelection::Tileset::Tileset	(	const TilesetExternals &	externals,
		int64_t	ionAssetID,
		const std::string &	ionAccessToken,
		const TilesetOptions &	options = TilesetOptions(),
		const std::string &	ionAssetEndpointUrl = "https://api.cesium.com/" )

Constructs a new instance with the given asset ID on Cesium ion.

Parameters

externals	The external interfaces to use.
ionAssetID	The ID of the Cesium ion asset to use.
ionAccessToken	The Cesium ion access token authorizing access to the asset.
options	Additional options for the tileset.
ionAssetEndpointUrl	The URL of the ion asset endpoint. Defaults to Cesium ion but a custom endpoint can be specified.

◆ Tileset() [4/4]

Cesium3DTilesSelection::Tileset::Tileset	(	const TilesetExternals &	externals,
		TilesetContentLoaderFactory &&	loaderFactory,
		const TilesetOptions &	options = TilesetOptions() )

Constructs a new instance with the given TilesetContentLoaderFactory.

Parameters

externals	The external interfaces to use.
loaderFactory	The factory to use to create the TilesetContentLoader.
options	Additional options for the tileset.

◆ ~Tileset()

Cesium3DTilesSelection::Tileset::~Tileset ( )

noexcept

Destroys this tileset.

Destroying the tileset will immediately (before the destructor returns) unload as much tile content as possible. However, tiles that are currently in the process of being loaded cannot be unloaded immediately. These tiles will be unloaded asynchronously some time after this destructor returns. To be notified of completion of the async portion of the tileset destruction, subscribe to getAsyncDestructionCompleteEvent.

Member Function Documentation

◆ computeLoadProgress()

float Cesium3DTilesSelection::Tileset::computeLoadProgress ( )

noexcept

Gets the percentage of tiles that had been loaded for the default view group as of the last time it was updated.

To get the load progress of a view group other than the default, call TilesetViewGroup::getPreviousLoadProgressPercentage.

◆ forEachLoadedTile() [1/2]

void Cesium3DTilesSelection::Tileset::forEachLoadedTile ( const std::function< void(const Tile &tile)> & callback ) const

Invokes a function for each tile that is currently loaded.

Parameters

callback The function to invoke.

◆ forEachLoadedTile() [2/2]

void Cesium3DTilesSelection::Tileset::forEachLoadedTile ( const std::function< void(Tile &tile)> & callback )

Invokes a function for each tile that is currently loaded.

Parameters

callback The function to invoke.

◆ getAsyncSystem() [1/2]

const CesiumAsync::AsyncSystem & Cesium3DTilesSelection::Tileset::getAsyncSystem ( ) const

inlinenoexcept

Returns the CesiumAsync::AsyncSystem that is used for dispatching asynchronous tasks.

Definition at line 167 of file Tileset.h.

◆ getAsyncSystem() [2/2]

CesiumAsync::AsyncSystem & Cesium3DTilesSelection::Tileset::getAsyncSystem ( )

inlinenoexcept

Returns the CesiumAsync::AsyncSystem that is used for dispatching asynchronous tasks.

Definition at line 162 of file Tileset.h.

◆ getDefaultViewGroup() [1/2]

TilesetViewGroup & Cesium3DTilesSelection::Tileset::getDefaultViewGroup ( )

Gets the default view group that is used when calling updateView.

Returns: The view group.

◆ getDefaultViewGroup() [2/2]

const TilesetViewGroup & Cesium3DTilesSelection::Tileset::getDefaultViewGroup ( ) const

Gets the default view group that is used when calling updateView.

Returns: The view group.

◆ getEllipsoid() [1/2]

const CesiumGeospatial::Ellipsoid & Cesium3DTilesSelection::Tileset::getEllipsoid ( ) const

inline

Gets the CesiumGeospatial::Ellipsoid used by this tileset.

Definition at line 182 of file Tileset.h.

◆ getEllipsoid() [2/2]

CesiumGeospatial::Ellipsoid & Cesium3DTilesSelection::Tileset::getEllipsoid ( )

inlinenoexcept

Gets the CesiumGeospatial::Ellipsoid used by this tileset.

Definition at line 187 of file Tileset.h.

◆ getExternals() [1/2]

const TilesetExternals & Cesium3DTilesSelection::Tileset::getExternals ( ) const

inlinenoexcept

Gets the TilesetExternals that summarize the external interfaces used by this tileset.

Definition at line 154 of file Tileset.h.

◆ getExternals() [2/2]

TilesetExternals & Cesium3DTilesSelection::Tileset::getExternals ( )

inlinenoexcept

Gets the TilesetExternals that summarize the external interfaces used by this tileset.

Definition at line 148 of file Tileset.h.

◆ getMetadata()

const TilesetMetadata * Cesium3DTilesSelection::Tileset::getMetadata ( const Tile * pTile = nullptr ) const

Gets the TilesetMetadata associated with the main or external tileset.json that contains a given tile. If the metadata is not yet loaded, this method returns nullptr.

If this tileset's root tile is not yet available, this method returns nullptr.

If the tileset has a TilesetMetadata::schemaUri, it will not necessarily have been loaded yet.

If the provided tile is not the root tile of a tileset.json, this method walks up the Tile::getParent chain until it finds the closest root and then returns the metadata associated with the corresponding tileset.json.

Consider calling loadMetadata instead, which will return a future that only resolves after the root tile is loaded and the schemaUri, if any, has been resolved.

Parameters

pTile The tile. If this parameter is nullptr, the metadata for the main tileset.json is returned.

Returns: The found metadata, or nullptr if the root tile is not yet loaded.

◆ getOptions() [1/2]

const TilesetOptions & Cesium3DTilesSelection::Tileset::getOptions ( ) const

inlinenoexcept

Gets the TilesetOptions of this tileset.

Definition at line 172 of file Tileset.h.

◆ getOptions() [2/2]

TilesetOptions & Cesium3DTilesSelection::Tileset::getOptions ( )

inlinenoexcept

Gets the TilesetOptions of this tileset.

Definition at line 177 of file Tileset.h.

◆ getOverlays()

const RasterOverlayCollection & Cesium3DTilesSelection::Tileset::getOverlays ( ) const

noexcept

Returns the RasterOverlayCollection of this tileset.

◆ getRootTile() [1/2]

const Tile * Cesium3DTilesSelection::Tileset::getRootTile ( ) const

noexcept

Gets the root tile of this tileset.

This may be nullptr if there is currently no root tile.

◆ getRootTile() [2/2]

Tile * Cesium3DTilesSelection::Tileset::getRootTile ( )

noexcept

Gets the root tile of this tileset.

This may be nullptr if there is currently no root tile.

◆ getSharedAssetSystem()

const TilesetSharedAssetSystem & Cesium3DTilesSelection::Tileset::getSharedAssetSystem ( ) const

noexcept

Returns the TilesetSharedAssetSystem of this tileset.

◆ loadedTiles() [1/2]

LoadedTileEnumerator Cesium3DTilesSelection::Tileset::loadedTiles ( )

Gets an object that can be used to enumerate the loaded tiles of this tileset.

Before the root tile is available, this method will return an enumerator that is empty, and that instance will remain empty even after the root tile is available.

Once the root tile is available (see getRootTile and getRootTileAvailableEvent), the returned instance will remain valid until the tileset is destroyed.

While the returned enumerator itself will remain valid as long as the Tileset does, a given iteration may be invalidated by any operation that modifies the Tile hierarchy.

◆ loadedTiles() [2/2]

LoadedConstTileEnumerator Cesium3DTilesSelection::Tileset::loadedTiles ( ) const

Gets an object that can be used to enumerate the loaded tiles of this tileset.

Before the root tile is available, this method will return an enumerator that is empty, and that instance will remain empty even after the root tile is available.

Once the root tile is available (see getRootTile and getRootTileAvailableEvent), the returned instance will remain valid until the tileset is destroyed.

While the returned enumerator itself will remain valid as long as the Tileset does, a given iteration may be invalidated by any operation that modifies the Tile hierarchy.

◆ loadMetadata()

CesiumAsync::Future< const TilesetMetadata * > Cesium3DTilesSelection::Tileset::loadMetadata ( )

Asynchronously loads the metadata associated with the main tileset.json.

Before the returned future resolves, the root tile of this tileset will be loaded and the TilesetMetadata::schemaUri will be loaded if one has been specified.

If the tileset or schemaUri fail to load, the returned future will reject.

Returns: A shared future that resolves to the loaded metadata. Once this future resolves, getMetadata can be used to synchronously obtain the same metadata instance.

◆ loadTiles()

void Cesium3DTilesSelection::Tileset::loadTiles ( )

Loads the tiles that are currently deemed the most important, across all height queries and TilesetViewGroup instances.

In order to minimize tile load latency, this method should be called frequently, such as once per render frame. It will return quickly when there is no work to do.

This method also calls CesiumAsync::AsyncSystem::dispatchMainThreadTasks on the tileset's getAsyncSystem.

◆ registerLoadRequester()

void Cesium3DTilesSelection::Tileset::registerLoadRequester ( TileLoadRequester & requester )

Registers a tile load requester with this Tileset. Registered tile load requesters get to influence which tiles are loaded when loadTiles is called.

If the given requester is already registered with this Tileset, this method does nothing.

To unregister a load requester, call TileLoadRequester::unregister.

Parameters

requester The requester to register.

◆ sampleHeightMostDetailed()

CesiumAsync::Future< SampleHeightResult > Cesium3DTilesSelection::Tileset::sampleHeightMostDetailed ( const std::vector< CesiumGeospatial::Cartographic > & positions )

Initiates an asynchronous query for the height of this tileset at a list of cartographic positions (longitude and latitude). The most detailed available tiles are used to determine each height.

The height of the input positions is ignored. The output height is expressed in meters above the ellipsoid (usually WGS84), which should not be confused with a height above mean sea level.

Note that Tileset::updateView must be called periodically, or else the returned Future will never resolve. If you are not using this tileset for visualization, you can call updateView with an empty list of frustums.

Parameters

positions The positions for which to sample heights.

Returns: A future that asynchronously resolves to the result of the height query.

◆ setShowCreditsOnScreen()

void Cesium3DTilesSelection::Tileset::setShowCreditsOnScreen ( bool showCreditsOnScreen )

noexcept

Sets whether or not the tileset's credits should be shown on screen.

Parameters

showCreditsOnScreen Whether the credits should be shown on screen.

◆ updateView()

const ViewUpdateResult & Cesium3DTilesSelection::Tileset::updateView	(	const std::vector< ViewState > &	frustums,
		float	deltaTime = 0.0f )

Updates this view, returning the set of tiles to render in this view.

Calling this method is equivalent to calling updateViewGroup with the default view group (getDefaultViewGroup) and then calling loadTiles.

Parameters

frustums	The `ViewState`s that the view should be updated for
deltaTime	The amount of time that has passed since the last call to updateView, in seconds.

Returns: The set of tiles to render in the updated view. This value is only valid until the next call to updateView or until the tileset is destroyed, whichever comes first.

◆ updateViewGroup()

const ViewUpdateResult & Cesium3DTilesSelection::Tileset::updateViewGroup	(	TilesetViewGroup &	viewGroup,
		const std::vector< ViewState > &	frustums,
		float	deltaTime = 0.0f )

Updates a view group, returning the set of tiles to render in this view.

This method should typically be called once per "render frame", but it may be called at different rates for different view groups.

Users must also periodically call loadTiles, which will start or continue the asynchronous process of loading tiles that are needed across all view groups.

Parameters

viewGroup	The view group to update. The first time `updateViewGroup` is called, simply create a new `TilesetViewGroup` to pass as this parameter. For successive calls to `updateViewGroup`, pass this same instance.
frustums	The `ViewState` instances that are observing the tileset in this view group.
deltaTime	The amount of time that has passed since the last call to updateView, in seconds.

Returns: The set of tiles to render in the updated view. This value is only valid until the next call to updateViewGroup or until the view group is destroyed, whichever comes first.

◆ updateViewGroupOffline()

const ViewUpdateResult & Cesium3DTilesSelection::Tileset::updateViewGroupOffline	(	TilesetViewGroup &	viewGroup,
		const std::vector< ViewState > &	frustums )

Updates a view group, returning the set of tiles to render in this view. Unlike updateViewGroup, this method blocks the calling thread until all tiles suitable for the views have been loaded.

This method is significantly slower than updateViewGroup and should only be used for capturing a movie or for other non-realtime situations.

Parameters

viewGroup	The view group to update. The first time `updateViewGroup` is called, simply create a new `TilesetViewGroup` to pass as this parameter. For successive calls to `updateViewGroup`, pass this same instance.
frustums	The `ViewState` instances that are observing the tileset in this view group.

Returns: The set of tiles to render in the updated view. This value is only valid until the next call to updateViewGroup or until the view group is destroyed, whichever comes first.

◆ updateViewOffline()

const ViewUpdateResult & Cesium3DTilesSelection::Tileset::updateViewOffline ( const std::vector< ViewState > & frustums )

Updates this view but waits for all tiles that meet sse to finish loading and ready to be rendered before returning the function. This method is significantly slower than Tileset::updateView and should only be used for capturing movie or non-realtime situation.

Parameters

frustums The ViewStates that the view should be updated for

Returns: The set of tiles to render in the updated view. This value is only valid until the next call to updateView or until the tileset is destroyed, whichever comes first.

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

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Tileset() [1/4]

◆ Tileset() [2/4]

◆ Tileset() [3/4]

◆ Tileset() [4/4]

◆ ~Tileset()

Member Function Documentation

◆ computeLoadProgress()

◆ forEachLoadedTile() [1/2]

◆ forEachLoadedTile() [2/2]

◆ getAsyncSystem() [1/2]

◆ getAsyncSystem() [2/2]

◆ getDefaultViewGroup() [1/2]

◆ getDefaultViewGroup() [2/2]

◆ getEllipsoid() [1/2]

◆ getEllipsoid() [2/2]

◆ getExternals() [1/2]

◆ getExternals() [2/2]

◆ getMetadata()

◆ getOptions() [1/2]

◆ getOptions() [2/2]

◆ getOverlays()

◆ getRootTile() [1/2]

◆ getRootTile() [2/2]

◆ getSharedAssetSystem()

◆ loadedTiles() [1/2]

◆ loadedTiles() [2/2]

◆ loadMetadata()

◆ loadTiles()

◆ registerLoadRequester()

◆ sampleHeightMostDetailed()

◆ setShowCreditsOnScreen()

◆ updateView()

◆ updateViewGroup()

◆ updateViewGroupOffline()

◆ updateViewOffline()