Provides individual tiles for a RasterOverlay on demand. More...

#include <CesiumRasterOverlays/RasterOverlayTileProvider.h>

Inheritance diagram for CesiumRasterOverlays::RasterOverlayTileProvider:

Public Member Functions
	RasterOverlayTileProvider (const CesiumUtility::IntrusivePointer< const RasterOverlay > &pOwner, const CesiumAsync::AsyncSystem &asyncSystem, const std::shared_ptr< CesiumAsync::IAssetAccessor > &pAssetAccessor, const CesiumGeospatial::Ellipsoid &ellipsoid=CesiumGeospatial::Ellipsoid::WGS84) noexcept

	RasterOverlayTileProvider (const CesiumUtility::IntrusivePointer< const RasterOverlay > &pOwner, const CesiumAsync::AsyncSystem &asyncSystem, const std::shared_ptr< CesiumAsync::IAssetAccessor > &pAssetAccessor, std::optional< CesiumUtility::Credit > credit, const std::shared_ptr< IPrepareRasterOverlayRendererResources > &pPrepareRendererResources, const std::shared_ptr< spdlog::logger > &pLogger, const CesiumGeospatial::Projection &projection, const CesiumGeometry::Rectangle &coverageRectangle) noexcept
	Creates a new instance.

virtual	~RasterOverlayTileProvider () noexcept
	Default destructor.

bool	isPlaceholder () const noexcept
	Returns whether this is a placeholder.

RasterOverlay &	getOwner () noexcept
	Returns the `RasterOverlay` that created this instance.

const RasterOverlay &	getOwner () const noexcept
	Returns the `RasterOverlay` that created this instance.

const std::shared_ptr< CesiumAsync::IAssetAccessor > &	getAssetAccessor () const noexcept
	Get the system to use for asychronous requests and threaded work.

const CesiumAsync::AsyncSystem &	getAsyncSystem () const noexcept
	Gets the async system used to do work in threads.

const std::shared_ptr< IPrepareRasterOverlayRendererResources > &	getPrepareRendererResources () const noexcept
	Gets the interface used to prepare raster overlay images for rendering.

const std::shared_ptr< spdlog::logger > &	getLogger () const noexcept
	Gets the logger to which to send messages about the tile provider and tiles.

const CesiumGeospatial::Projection &	getProjection () const noexcept
	Returns the `CesiumGeospatial::Projection` of this instance.

const CesiumGeometry::Rectangle &	getCoverageRectangle () const noexcept
	Returns the coverage `CesiumGeometry::Rectangle` of this instance.

CesiumUtility::IntrusivePointer< RasterOverlayTile >	getTile (const CesiumGeometry::Rectangle &rectangle, const glm::dvec2 &targetScreenPixels)
	Returns a new `RasterOverlayTile` with the given specifications.

int64_t	getTileDataBytes () const noexcept
	Gets the number of bytes of tile data that are currently loaded.

uint32_t	getNumberOfTilesLoading () const noexcept
	Returns the number of tiles that are currently loading.

void	removeTile (RasterOverlayTile *pTile) noexcept
	Removes a no-longer-referenced tile from this provider's cache and deletes it.

const std::optional< CesiumUtility::Credit > &	getCredit () const noexcept
	Get the per-TileProvider `CesiumUtility::Credit` if one exists.

CesiumAsync::Future< TileProviderAndTile >	loadTile (RasterOverlayTile &tile)
	Loads a tile immediately, without throttling requests.

bool	loadTileThrottled (RasterOverlayTile &tile)
	Loads a tile, unless there are too many tile loads already in progress.

Public Member Functions inherited from CesiumUtility::ReferenceCounted< T, isThreadSafe >
void	addReference () const
	Adds a counted reference to this object. Use `CesiumUtility::IntrusivePointer` instead of calling this method directly.

void	releaseReference () const
	Removes a counted reference from this object. When the last reference is removed, this method will delete this instance. Use `CesiumUtility::IntrusivePointer` instead of calling this method directly.

std::int32_t	getReferenceCount () const noexcept
	Returns the current reference count of this instance.

Protected Member Functions
virtual CesiumAsync::Future< LoadedRasterOverlayImage >	loadTileImage (RasterOverlayTile &overlayTile)=0
	Loads the image for a tile.

CesiumAsync::Future< LoadedRasterOverlayImage >	loadTileImageFromUrl (const std::string &url, const std::vector< CesiumAsync::IAssetAccessor::THeader > &headers={}, LoadTileImageFromUrlOptions &&options={}) const
	Loads an image from a URL and optionally some request headers.

Detailed Description

Provides individual tiles for a RasterOverlay on demand.

Instances of this class must be allocated on the heap, and their lifetimes must be managed with CesiumUtility::IntrusivePointer.

Definition at line 146 of file RasterOverlayTileProvider.h.

Constructor & Destructor Documentation

◆ RasterOverlayTileProvider() [1/2]

CesiumRasterOverlays::RasterOverlayTileProvider::RasterOverlayTileProvider	(	const CesiumUtility::IntrusivePointer< const RasterOverlay > &	pOwner,
		const CesiumAsync::AsyncSystem &	asyncSystem,
		const std::shared_ptr< CesiumAsync::IAssetAccessor > &	pAssetAccessor,
		const CesiumGeospatial::Ellipsoid &	ellipsoid = CesiumGeospatial::Ellipsoid::WGS84 )

noexcept

Constructs a placeholder tile provider.

See also: RasterOverlayTileProvider::isPlaceholder

Parameters

pOwner	The raster overlay that created this tile provider.
asyncSystem	The async system used to do work in threads.
pAssetAccessor	The interface used to obtain assets (tiles, etc.) for this raster overlay.
ellipsoid	The `CesiumGeospatial::Ellipsoid`.

◆ RasterOverlayTileProvider() [2/2]

CesiumRasterOverlays::RasterOverlayTileProvider::RasterOverlayTileProvider	(	const CesiumUtility::IntrusivePointer< const RasterOverlay > &	pOwner,
		const CesiumAsync::AsyncSystem &	asyncSystem,
		const std::shared_ptr< CesiumAsync::IAssetAccessor > &	pAssetAccessor,
		std::optional< CesiumUtility::Credit >	credit,
		const std::shared_ptr< IPrepareRasterOverlayRendererResources > &	pPrepareRendererResources,
		const std::shared_ptr< spdlog::logger > &	pLogger,
		const CesiumGeospatial::Projection &	projection,
		const CesiumGeometry::Rectangle &	coverageRectangle )

noexcept

Creates a new instance.

Parameters

pOwner	The raster overlay that created this tile provider.
asyncSystem	The async system used to do work in threads.
pAssetAccessor	The interface used to obtain assets (tiles, etc.) for this raster overlay.
credit	The `CesiumUtility::Credit` for this tile provider, if it exists.
pPrepareRendererResources	The interface used to prepare raster images for rendering.
pLogger	The logger to which to send messages about the tile provider and tiles.
projection	The `CesiumGeospatial::Projection`.
coverageRectangle	The rectangle that bounds all the area covered by this overlay, expressed in projected coordinates.

Member Function Documentation

◆ getAssetAccessor()

const std::shared_ptr< CesiumAsync::IAssetAccessor > & CesiumRasterOverlays::RasterOverlayTileProvider::getAssetAccessor ( ) const

inlinenoexcept

Get the system to use for asychronous requests and threaded work.

Definition at line 231 of file RasterOverlayTileProvider.h.

◆ getAsyncSystem()

const CesiumAsync::AsyncSystem & CesiumRasterOverlays::RasterOverlayTileProvider::getAsyncSystem ( ) const

inlinenoexcept

Gets the async system used to do work in threads.

Definition at line 238 of file RasterOverlayTileProvider.h.

◆ getCoverageRectangle()

const CesiumGeometry::Rectangle & CesiumRasterOverlays::RasterOverlayTileProvider::getCoverageRectangle ( ) const

inlinenoexcept

Returns the coverage CesiumGeometry::Rectangle of this instance.

Definition at line 270 of file RasterOverlayTileProvider.h.

◆ getCredit()

const std::optional< CesiumUtility::Credit > & CesiumRasterOverlays::RasterOverlayTileProvider::getCredit ( ) const

inlinenoexcept

Get the per-TileProvider CesiumUtility::Credit if one exists.

Definition at line 325 of file RasterOverlayTileProvider.h.

◆ getLogger()

const std::shared_ptr< spdlog::logger > & CesiumRasterOverlays::RasterOverlayTileProvider::getLogger ( ) const

inlinenoexcept

Gets the logger to which to send messages about the tile provider and tiles.

Definition at line 255 of file RasterOverlayTileProvider.h.

◆ getNumberOfTilesLoading()

uint32_t CesiumRasterOverlays::RasterOverlayTileProvider::getNumberOfTilesLoading ( ) const

inlinenoexcept

Returns the number of tiles that are currently loading.

Definition at line 305 of file RasterOverlayTileProvider.h.

◆ getOwner() [1/2]

const RasterOverlay & CesiumRasterOverlays::RasterOverlayTileProvider::getOwner ( ) const

inlinenoexcept

Returns the RasterOverlay that created this instance.

Definition at line 225 of file RasterOverlayTileProvider.h.

◆ getOwner() [2/2]

RasterOverlay & CesiumRasterOverlays::RasterOverlayTileProvider::getOwner ( )

inlinenoexcept

Returns the RasterOverlay that created this instance.

Definition at line 222 of file RasterOverlayTileProvider.h.

◆ getPrepareRendererResources()

const std::shared_ptr< IPrepareRasterOverlayRendererResources > & CesiumRasterOverlays::RasterOverlayTileProvider::getPrepareRendererResources ( ) const

inlinenoexcept

Gets the interface used to prepare raster overlay images for rendering.

Definition at line 247 of file RasterOverlayTileProvider.h.

◆ getProjection()

const CesiumGeospatial::Projection & CesiumRasterOverlays::RasterOverlayTileProvider::getProjection ( ) const

inlinenoexcept

Returns the CesiumGeospatial::Projection of this instance.

Definition at line 262 of file RasterOverlayTileProvider.h.

◆ getTile()

CesiumUtility::IntrusivePointer< RasterOverlayTile > CesiumRasterOverlays::RasterOverlayTileProvider::getTile	(	const CesiumGeometry::Rectangle &	rectangle,
		const glm::dvec2 &	targetScreenPixels )

Returns a new RasterOverlayTile with the given specifications.

The returned tile will not start loading immediately. To start loading, call RasterOverlayTileProvider::loadTile or RasterOverlayTileProvider::loadTileThrottled.

Parameters

rectangle	The rectangle that the returned image must cover. It is allowed to cover a slightly larger rectangle in order to maintain pixel alignment. It may also cover a smaller rectangle when the overlay itself does not cover the entire rectangle.
targetScreenPixels	The maximum number of pixels on the screen that this tile is meant to cover. The overlay image should be approximately this many pixels divided by the `RasterOverlayOptions::maximumScreenSpaceError` in order to achieve the desired level-of-detail, but it does not need to be exactly this size.

Returns: The tile.

◆ getTileDataBytes()

int64_t CesiumRasterOverlays::RasterOverlayTileProvider::getTileDataBytes ( ) const

inlinenoexcept

Gets the number of bytes of tile data that are currently loaded.

Definition at line 300 of file RasterOverlayTileProvider.h.

◆ isPlaceholder()

bool CesiumRasterOverlays::RasterOverlayTileProvider::isPlaceholder ( ) const

inlinenoexcept

Returns whether this is a placeholder.

For many types of RasterOverlay, we can't create a functioning RasterOverlayTileProvider right away. For example, we may not know the bounds of the overlay, or what projection it uses, until after we've (asynchronously) loaded a metadata service that gives us this information.

So until that real RasterOverlayTileProvider becomes available, we use a placeholder. When RasterOverlayTileProvider::getTile is invoked on a placeholder, it returns a RasterOverlayTile that is also a placeholder. And whenever we see a placeholder RasterOverlayTile in Cesium3DTilesSelection::RasterMappedTo3DTile::update, we check if the corresponding RasterOverlay is ready yet. Once it's ready, we remove the placeholder tile and replace it with the real tiles.

So the placeholder system gives us a way to defer the mapping of raster overlay tiles to geometry tiles until that mapping can be determined.

Definition at line 217 of file RasterOverlayTileProvider.h.

◆ loadTile()

CesiumAsync::Future< TileProviderAndTile > CesiumRasterOverlays::RasterOverlayTileProvider::loadTile ( RasterOverlayTile & tile )

Loads a tile immediately, without throttling requests.

If the tile is not in the Tile::LoadState::Unloaded state, this method returns without doing anything. Otherwise, it puts the tile into the Tile::LoadState::Loading state and begins the asynchronous process to load the tile. When the process completes, the tile will be in the Tile::LoadState::Loaded or Tile::LoadState::Failed state.

Calling this method on many tiles at once can result in very slow performance. Consider using loadTileThrottled instead.

Parameters

tile	The tile to load.

Returns: A future that, when the tile is loaded, resolves to the loaded tile and the tile provider that loaded it.

◆ loadTileImage()

virtual CesiumAsync::Future< LoadedRasterOverlayImage > CesiumRasterOverlays::RasterOverlayTileProvider::loadTileImage ( RasterOverlayTile & overlayTile )

protectedpure virtual

Loads the image for a tile.

Parameters

overlayTile The overlay tile for which to load the image.

Returns: A future that resolves to the image or error information.

◆ loadTileImageFromUrl()

CesiumAsync::Future< LoadedRasterOverlayImage > CesiumRasterOverlays::RasterOverlayTileProvider::loadTileImageFromUrl	(	const std::string &	url,
		const std::vector< CesiumAsync::IAssetAccessor::THeader > &	headers = {},
		LoadTileImageFromUrlOptions &&	options = {} ) const

protected

Loads an image from a URL and optionally some request headers.

This is a useful helper function for implementing loadTileImage.

Parameters

url	The URL.
headers	The request headers.
options	Additional options for the load process.

Returns: A future that resolves to the image or error information.

◆ loadTileThrottled()

bool CesiumRasterOverlays::RasterOverlayTileProvider::loadTileThrottled ( RasterOverlayTile & tile )

Loads a tile, unless there are too many tile loads already in progress.

If the tile is not in the Tile::LoadState::Unloading state, this method returns true without doing anything. If too many tile loads are already in flight, it returns false without doing anything. Otherwise, it puts the tile into the Tile::LoadState::Loading state, begins the asynchronous process to load the tile, and returns true. When the process completes, the tile will be in the Tile::LoadState::Loaded or Tile::LoadState::Failed state.

The number of allowable simultaneous tile requests is provided in the RasterOverlayOptions::maximumSimultaneousTileLoads property of RasterOverlay::getOptions.

Parameters

tile	The tile to load.

Returns: True if the tile load process is started or is already complete, false if the load could not be started because too many loads are already in progress.

◆ removeTile()

void CesiumRasterOverlays::RasterOverlayTileProvider::removeTile ( RasterOverlayTile * pTile )

noexcept

Removes a no-longer-referenced tile from this provider's cache and deletes it.

This function is not supposed to be called by client. Calling this method in a tile with a reference count greater than 0 will result in undefined behavior.

Parameters

pTile The tile, which must have no oustanding references.

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

/home/runner/work/cesium-native/cesium-native/CesiumRasterOverlays/include/CesiumRasterOverlays/RasterOverlayTileProvider.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ RasterOverlayTileProvider() [1/2]

◆ RasterOverlayTileProvider() [2/2]

Member Function Documentation

◆ getAssetAccessor()

◆ getAsyncSystem()

◆ getCoverageRectangle()

◆ getCredit()

◆ getLogger()

◆ getNumberOfTilesLoading()

◆ getOwner() [1/2]

◆ getOwner() [2/2]

◆ getPrepareRendererResources()

◆ getProjection()

◆ getTile()

◆ getTileDataBytes()

◆ isPlaceholder()

◆ loadTile()

◆ loadTileImage()

◆ loadTileImageFromUrl()

◆ loadTileThrottled()

◆ removeTile()