A tile in a Tileset. More...

#include <Cesium3DTilesSelection/Tile.h>

Public Types
using	Pointer = CesiumUtility::IntrusivePointer<Tile>
	A reference counting pointer to a `Tile`.

typedef CesiumUtility::DoublyLinkedList< Tile, &Tile::_unusedTilesLinks >	UnusedLinkedList
	A `CesiumUtility::DoublyLinkedList` for tile objects.

Public Member Functions
	Tile (TilesetContentLoader *pLoader, const TileID &tileID={}) noexcept
	Construct a tile with unknown content and a loader that is used to load the content of this tile. Tile has Unloaded status when initializing with this constructor.

	Tile (TilesetContentLoader *pLoader, const TileID &tileID, std::unique_ptr< TileExternalContent > &&externalContent) noexcept
	Construct a tile with an external content and a loader that is associated with this tile. Tile has ContentLoaded status when initializing with this constructor.

	Tile (TilesetContentLoader *pLoader, const TileID &tileID, TileEmptyContent emptyContent) noexcept
	Construct a tile with an empty content and a loader that is associated with this tile. Tile has ContentLoaded status when initializing with this constructor.

	~Tile () noexcept
	Default destructor, which clears all resources associated with this tile.

	Tile (const Tile &rhs)=delete
	Copy constructor.

	Tile (Tile &&rhs) noexcept
	Move constructor.

Tile &	operator= (const Tile &rhs)=delete
	Copy constructor.

Tile &	operator= (Tile &&rhs) noexcept=delete
	Move assignment operator.

Tile *	getParent () noexcept
	Returns the parent of this tile in the tile hierarchy.

const Tile *	getParent () const noexcept
	Returns the parent of this tile in the tile hierarchy.

std::span< Tile >	getChildren () noexcept
	Returns a view on the children of this tile.

std::span< const Tile >	getChildren () const noexcept
	Returns a view on the children of this tile.

void	clearChildren () noexcept
	Clears the children of this tile.

void	createChildTiles (std::vector< Tile > &&children)
	Assigns the given child tiles to this tile.

const BoundingVolume &	getBoundingVolume () const noexcept
	Returns the `BoundingVolume` of this tile.

void	setBoundingVolume (const BoundingVolume &value) noexcept
	Set the `BoundingVolume` of this tile.

const std::optional< BoundingVolume > &	getViewerRequestVolume () const noexcept
	Returns the viewer request volume of this tile.

void	setViewerRequestVolume (const std::optional< BoundingVolume > &value) noexcept
	Set the viewer request volume of this tile.

double	getGeometricError () const noexcept
	Returns the geometric error of this tile.

void	setGeometricError (double value) noexcept
	Set the geometric error of the contents of this tile.

double	getNonZeroGeometricError () const noexcept
	Gets the tile's geometric error as if by calling `getGeometricError`, except that if the error is smaller than `CesiumUtility::Math::Epsilon5` the returned geometric error is instead computed as half of the parent tile's (non-zero) geometric error.

bool	getUnconditionallyRefine () const noexcept
	Returns whether to unconditionally refine this tile.

void	setUnconditionallyRefine () noexcept
	Marks that this tile should be unconditionally refined.

TileRefine	getRefine () const noexcept
	The refinement strategy of this tile.

void	setRefine (TileRefine value) noexcept
	Set the refinement strategy of this tile.

const glm::dmat4x4 &	getTransform () const noexcept
	Gets the transformation matrix for this tile.

void	setTransform (const glm::dmat4x4 &value) noexcept
	Set the transformation matrix for this tile.

const TileID &	getTileID () const noexcept
	Returns the `TileID` of this tile.

void	setTileID (const TileID &id) noexcept
	Set the `TileID` of this tile.

const std::optional< BoundingVolume > &	getContentBoundingVolume () const noexcept
	Returns the `BoundingVolume` of the renderable content of this tile.

void	setContentBoundingVolume (const std::optional< BoundingVolume > &value) noexcept
	Set the `BoundingVolume` of the renderable content of this tile.

int64_t	computeByteSize () const noexcept
	Determines the number of bytes in this tile's geometry and texture data.

std::vector< RasterMappedTo3DTile > &	getMappedRasterTiles () noexcept
	Returns the raster overlay tiles that have been mapped to this tile.

const std::vector< RasterMappedTo3DTile > &	getMappedRasterTiles () const noexcept
	Returns the raster overlay tiles that have been mapped to this tile.

const TileContent &	getContent () const noexcept
	Get the content of the tile.

TileContent &	getContent () noexcept
	Get the content of the tile.

bool	isRenderable () const noexcept
	Determines if this tile is currently renderable.

bool	isRenderContent () const noexcept
	Determines if this tile has mesh content.

bool	isExternalContent () const noexcept
	Determines if this tile has external tileset content.

bool	isEmptyContent () const noexcept
	Determines if this tile has empty content.

TilesetContentLoader *	getLoader () const noexcept
	get the loader that is used to load the tile content.

TileLoadState	getState () const noexcept
	Returns the `TileLoadState` of this tile.

bool	needsWorkerThreadLoading () const noexcept
	Determines if this tile requires worker-thread loading.

bool	needsMainThreadLoading () const noexcept
	Determines if this tile requires main-thread loading.

void	addReference (const char *reason=nullptr) noexcept
	Adds a reference to this tile. A live reference will keep this tile from being destroyed, and it may also keep the tile's content from unloading.

void	releaseReference (const char *reason=nullptr) noexcept
	Removes a reference from this tile. A live reference will keep this tile from being destroyed, and it may also keep the tile's content from unloading.

int32_t	getReferenceCount () const noexcept
	Gets the current number of references to this tile.

bool	hasReferencingContent () const noexcept
	Determines if this tile's `getContent` counts as a reference to this tile.

Friends
class	TilesetContentManager

class	MockTilesetContentManagerTestFixture

Detailed Description

A tile in a Tileset.

The tiles of a tileset form a hierarchy, where each tile may contain renderable content, and each tile has an associated bounding volume.

The actual hierarchy is represented with the Tile::getParent and Tile::getChildren functions.

The renderable content is provided as a TileContent from the Tile::getContent function. The Tile::getGeometricError function returns the geometric error of the representation of the renderable content of a tile.

The BoundingVolume is given by the Tile::getBoundingVolume function. This bounding volume encloses the renderable content of the tile itself, as well as the renderable content of all children, yielding a spatially coherent hierarchy of bounding volumes.

The bounding volume of the content of an individual tile is given by the Tile::getContentBoundingVolume function.

Definition at line 122 of file Tile.h.

Member Typedef Documentation

◆ Pointer

using Cesium3DTilesSelection::Tile::Pointer = CesiumUtility::IntrusivePointer<Tile>

A reference counting pointer to a Tile.

An instance of this pointer type will keep the Tile from being destroyed, and it may also keep its content from unloading. See addReference for details.

Definition at line 131 of file Tile.h.

◆ UnusedLinkedList

typedef CesiumUtility::DoublyLinkedList<Tile, &Tile::_unusedTilesLinks> Cesium3DTilesSelection::Tile::UnusedLinkedList

A CesiumUtility::DoublyLinkedList for tile objects.

Definition at line 704 of file Tile.h.

Constructor & Destructor Documentation

◆ Tile() [1/5]

Cesium3DTilesSelection::Tile::Tile	(	TilesetContentLoader *	pLoader,
		const TileID &	tileID = {} )

explicitnoexcept

Construct a tile with unknown content and a loader that is used to load the content of this tile. Tile has Unloaded status when initializing with this constructor.

Parameters

pLoader	The `TilesetContentLoader` that is used to load the tile.
tileID	The ID of this tile. If not specified, the ID will initially be an empty string.

◆ Tile() [2/5]

Cesium3DTilesSelection::Tile::Tile	(	TilesetContentLoader *	pLoader,
		const TileID &	tileID,
		std::unique_ptr< TileExternalContent > &&	externalContent )

noexcept

Construct a tile with an external content and a loader that is associated with this tile. Tile has ContentLoaded status when initializing with this constructor.

If the supplied TileID is not an empty string, the tile's reference count will be incremented on account of the loaded, referencable content. Otherwise, if it is an empty string, the reference count will not be incremented. It is essential that this be accounted for later if the tile ID is changed in order to avoid reference count assertion failures at tileset destruction.

Parameters

pLoader	The `TilesetContentLoader` that is assiocated with this tile.
tileID	The ID of this tile. If it is an empty string, then the external content will not be unloadable.
externalContent	External content that is associated with this tile.

◆ Tile() [3/5]

Cesium3DTilesSelection::Tile::Tile	(	TilesetContentLoader *	pLoader,
		const TileID &	tileID,
		TileEmptyContent	emptyContent )

noexcept

Construct a tile with an empty content and a loader that is associated with this tile. Tile has ContentLoaded status when initializing with this constructor.

If the supplied TileID is not an empty string, the tile's reference count will be incremented on account of the loaded, referencable content. Otherwise, if it is an empty string, the reference count will not be incremented. It is essential that this be accounted for later if the tile ID is changed in order to avoid reference count assertion failures at tileset destruction.

Parameters

pLoader	The `TilesetContentLoader` that is assiocated with this tile.
tileID	The ID of this tile. If it is an empty string, then the empty content will not be unloadable.
emptyContent	A content tag indicating that the tile has no content.

◆ Tile() [4/5]

Cesium3DTilesSelection::Tile::Tile ( const Tile & rhs )

delete

Copy constructor.

Parameters

rhs	The other instance.

◆ Tile() [5/5]

Cesium3DTilesSelection::Tile::Tile ( Tile && rhs )

noexcept

Move constructor.

Parameters

rhs	The other instance.

Member Function Documentation

◆ addReference()

void Cesium3DTilesSelection::Tile::addReference ( const char * reason = nullptr )

noexcept

Adds a reference to this tile. A live reference will keep this tile from being destroyed, and it may also keep the tile's content from unloading.

Use CesiumUtility::IntrusivePointer to manage references to tiles whenever possible, rather than calling this method directly.

When the first reference is added to this tile, this method will automatically add a reference to the tile's parent tile as well. This is to prevent the parent tile from being destroyed, which would implicitly destroy all of its children as well. Parent tiles should never hold references to child tiles.

A reference is also added to a tile when its content is loading or loaded. Content must finish loading, and then be unloaded, before a Tile is eligible for destruction.

Any additional added references, beyond one per referenced child and one representing this tile's content if it exists, indicate interest not just in the Tile itself but also in the Tile's content.

For example: if a Tile has loaded content (1) as well as four children, and two (2) of its children have a reference count greater than zero, it will have a total reference count of at least 1+2=3. If its reference count is exactly three, this means that the tile's content is not currently needed and may be unloaded when the unused tile cache is full. However, if the reference count is greater than 3, this means that the content is also referenced. Therefore, neither the content nor the tile will be unloaded.

Parameters

reason An optional explanation for why this reference is being added. This can help debug reference counts when compiled with CESIUM_DEBUG_TILE_UNLOADING.

◆ clearChildren()

void Cesium3DTilesSelection::Tile::clearChildren ( )

noexcept

Clears the children of this tile.

This function is not supposed to be called by clients.

◆ createChildTiles()

void Cesium3DTilesSelection::Tile::createChildTiles ( std::vector< Tile > && children )

Assigns the given child tiles to this tile.

This function is not supposed to be called by clients.

Parameters

children The child tiles.

Exceptions

`std::runtime_error` if this tile already has children.

◆ getBoundingVolume()

const BoundingVolume & Cesium3DTilesSelection::Tile::getBoundingVolume ( ) const

inlinenoexcept

Returns the BoundingVolume of this tile.

This is a bounding volume that encloses the content of this tile, as well as the content of all child tiles.

See also: Tile::getContentBoundingVolume

Returns: The bounding volume.

Definition at line 279 of file Tile.h.

◆ getChildren() [1/2]

std::span< const Tile > Cesium3DTilesSelection::Tile::getChildren ( ) const

inlinenoexcept

Returns a view on the children of this tile.

The returned span will become invalid when this tile is destroyed.

Returns: The children of this tile.

Definition at line 248 of file Tile.h.

◆ getChildren() [2/2]

std::span< Tile > Cesium3DTilesSelection::Tile::getChildren ( )

inlinenoexcept

Returns a view on the children of this tile.

The returned span will become invalid when this tile is destroyed.

Returns: The children of this tile.

Definition at line 243 of file Tile.h.

◆ getContent() [1/2]

const TileContent & Cesium3DTilesSelection::Tile::getContent ( ) const

inlinenoexcept

Get the content of the tile.

Definition at line 494 of file Tile.h.

◆ getContent() [2/2]

TileContent & Cesium3DTilesSelection::Tile::getContent ( )

inlinenoexcept

Get the content of the tile.

Definition at line 497 of file Tile.h.

◆ getContentBoundingVolume()

const std::optional< BoundingVolume > & Cesium3DTilesSelection::Tile::getContentBoundingVolume ( ) const

inlinenoexcept

Returns the BoundingVolume of the renderable content of this tile.

The content bounding volume is a bounding volume that tightly fits only the renderable content of the tile. This enables tighter view frustum culling, making it possible to exclude from rendering any content not in the view frustum.

See also: Tile::getBoundingVolume

Definition at line 455 of file Tile.h.

◆ getGeometricError()

double Cesium3DTilesSelection::Tile::getGeometricError ( ) const

inlinenoexcept

Returns the geometric error of this tile.

This is the error, in meters, introduced if this tile is rendered and its children are not. This is used to compute screen space error, i.e., the error measured in pixels.

Returns: The geometric error of this tile, in meters.

Definition at line 330 of file Tile.h.

◆ getMappedRasterTiles() [1/2]

const std::vector< RasterMappedTo3DTile > & Cesium3DTilesSelection::Tile::getMappedRasterTiles ( ) const

inlinenoexcept

Returns the raster overlay tiles that have been mapped to this tile.

Definition at line 487 of file Tile.h.

◆ getMappedRasterTiles() [2/2]

std::vector< RasterMappedTo3DTile > & Cesium3DTilesSelection::Tile::getMappedRasterTiles ( )

inlinenoexcept

Returns the raster overlay tiles that have been mapped to this tile.

Definition at line 481 of file Tile.h.

◆ getNonZeroGeometricError()

double Cesium3DTilesSelection::Tile::getNonZeroGeometricError ( ) const

noexcept

Gets the tile's geometric error as if by calling getGeometricError, except that if the error is smaller than CesiumUtility::Math::Epsilon5 the returned geometric error is instead computed as half of the parent tile's (non-zero) geometric error.

This is useful for determining when to refine what would ordinarily be a leaf tile, for example to attach more detailed raster overlays to it.

If this tile and all of its ancestors have a geometric error less than CesiumUtility::Math::Epsilon5, returns CesiumUtility::Math::Epsilon5.

Returns: The non-zero geometric error.

◆ getParent() [1/2]

const Tile * Cesium3DTilesSelection::Tile::getParent ( ) const

inlinenoexcept

Returns the parent of this tile in the tile hierarchy.

This will be the nullptr if this is the root tile.

Returns: The parent.

Definition at line 234 of file Tile.h.

◆ getParent() [2/2]

Tile * Cesium3DTilesSelection::Tile::getParent ( )

inlinenoexcept

Returns the parent of this tile in the tile hierarchy.

This will be the nullptr if this is the root tile.

Returns: The parent.

Definition at line 231 of file Tile.h.

◆ getReferenceCount()

int32_t Cesium3DTilesSelection::Tile::getReferenceCount ( ) const

noexcept

Gets the current number of references to this tile.

See addReference for details of when and why references are added, and how they impact a tile's eligibility to have its content unloaded.

◆ getRefine()

TileRefine Cesium3DTilesSelection::Tile::getRefine ( ) const

inlinenoexcept

The refinement strategy of this tile.

Returns the TileRefine value that indicates the refinement strategy for this tile. This is Add when the content of the child tiles is added to the content of this tile during refinement, and Replace when the content of the child tiles replaces the content of this tile during refinement.

Returns: The refinement strategy.

Definition at line 393 of file Tile.h.

◆ getTileID()

const TileID & Cesium3DTilesSelection::Tile::getTileID ( ) const

inlinenoexcept

Returns the TileID of this tile.

This function is not supposed to be called by clients.

Returns: The tile ID.

Definition at line 432 of file Tile.h.

◆ getTransform()

const glm::dmat4x4 & Cesium3DTilesSelection::Tile::getTransform ( ) const

inlinenoexcept

Gets the transformation matrix for this tile.

This matrix does not need to be multiplied with the tile's parent's transform as this has already been done.

Returns: The transform matrix.

Definition at line 412 of file Tile.h.

◆ getUnconditionallyRefine()

bool Cesium3DTilesSelection::Tile::getUnconditionallyRefine ( ) const

inlinenoexcept

Returns whether to unconditionally refine this tile.

This is useful in cases such as with external tilesets, where instead of a tile having any content, it points to an external tileset's root. So the tile always needs to be refined otherwise the external tileset will not be displayed.

Returns: Whether to uncoditionally refine this tile.

Definition at line 369 of file Tile.h.

◆ getViewerRequestVolume()

const std::optional< BoundingVolume > & Cesium3DTilesSelection::Tile::getViewerRequestVolume ( ) const

inlinenoexcept

Returns the viewer request volume of this tile.

The viewer request volume is an optional BoundingVolume that may be associated with a tile. It allows controlling the rendering process of the tile content: If the viewer request volume is present, then the content of the tile will only be rendered when the viewer (i.e. the camera position) is inside the viewer request volume.

Returns: The viewer request volume, or an empty optional.

Definition at line 305 of file Tile.h.

◆ hasReferencingContent()

bool Cesium3DTilesSelection::Tile::hasReferencingContent ( ) const

noexcept

Determines if this tile's getContent counts as a reference to this tile.

Content only counts as a reference to the tile when that content may be unloaded. This ensures that the Tile will not be destroyed before the content is unloaded.

Content that TileContent::isUnknownContent cannot be unloaded, so it is non-referencing. In addition, if the tile's getTileID is a blank string, then content of any type will be non-referencing. This is because the content for a tile without an ID cannot be reloaded, and so it will never been unloaded except when the entire Tileset is destroyed.

Returns: true if this tile's content counts as a reference to this tile; otherwise, false.

◆ needsMainThreadLoading()

bool Cesium3DTilesSelection::Tile::needsMainThreadLoading ( ) const

noexcept

Determines if this tile requires main-thread loading.

Returns: true if this Tile needs further work done in the main thread to load it; otherwise, false.

◆ needsWorkerThreadLoading()

bool Cesium3DTilesSelection::Tile::needsWorkerThreadLoading ( ) const

noexcept

Determines if this tile requires worker-thread loading.

Returns: true if this Tile needs further work done in a worker thread to load it; otherwise, false.

◆ operator=() [1/2]

Tile & Cesium3DTilesSelection::Tile::operator= ( const Tile & rhs )

delete

Copy constructor.

Parameters

rhs	The other instance.

◆ operator=() [2/2]

Tile & Cesium3DTilesSelection::Tile::operator= ( Tile && rhs )

deletenoexcept

Move assignment operator.

Parameters

rhs	The other instance.

◆ releaseReference()

void Cesium3DTilesSelection::Tile::releaseReference ( const char * reason = nullptr )

noexcept

Removes a reference from this tile. A live reference will keep this tile from being destroyed, and it may also keep the tile's content from unloading.

Use CesiumUtility::IntrusivePointer to manage references to tiles whenever possible, rather than calling this method directly.

When the last reference is removed from this tile (its count goes from 1 to 0), this method will automatically remove a reference from the tile's parent tile as well. This is the inverse of the addReference that the child previously invoked on its parent when the child reference count went from 0 to 1. Removing it indicates that it is ok to destroy the child tile, such as by unloading an external tileset.

See addReference for details of how references affect a tile's eligibility to have its content unloaded.

Parameters

reason An optional explanation for why this reference is being removed. This can help debug reference counts when compiled with CESIUM_DEBUG_TILE_UNLOADING.

◆ setBoundingVolume()

void Cesium3DTilesSelection::Tile::setBoundingVolume ( const BoundingVolume & value )

inlinenoexcept

Set the BoundingVolume of this tile.

This function is not supposed to be called by clients.

Parameters

value The bounding volume.

Definition at line 290 of file Tile.h.

◆ setContentBoundingVolume()

void Cesium3DTilesSelection::Tile::setContentBoundingVolume ( const std::optional< BoundingVolume > & value )

inlinenoexcept

Set the BoundingVolume of the renderable content of this tile.

This function is not supposed to be called by clients.

Parameters

value The content bounding volume

Definition at line 467 of file Tile.h.

◆ setGeometricError()

void Cesium3DTilesSelection::Tile::setGeometricError ( double value )

inlinenoexcept

Set the geometric error of the contents of this tile.

This function is not supposed to be called by clients.

Parameters

value The geometric error, in meters.

Definition at line 339 of file Tile.h.

◆ setRefine()

void Cesium3DTilesSelection::Tile::setRefine ( TileRefine value )

inlinenoexcept

Set the refinement strategy of this tile.

This function is not supposed to be called by clients.

Parameters

value The refinement strategy.

Definition at line 402 of file Tile.h.

◆ setTileID()

void Cesium3DTilesSelection::Tile::setTileID ( const TileID & id )

inlinenoexcept

Set the TileID of this tile.

This function is not supposed to be called by clients.

Parameters

id	The tile ID.

Definition at line 441 of file Tile.h.

◆ setTransform()

void Cesium3DTilesSelection::Tile::setTransform ( const glm::dmat4x4 & value )

inlinenoexcept

Set the transformation matrix for this tile.

This function is not supposed to be called by clients.

Parameters

value The transform matrix.

Definition at line 421 of file Tile.h.

◆ setUnconditionallyRefine()

void Cesium3DTilesSelection::Tile::setUnconditionallyRefine ( )

inlinenoexcept

Marks that this tile should be unconditionally refined.

This function is not supposed to be called by clients.

Definition at line 378 of file Tile.h.

◆ setViewerRequestVolume()

void Cesium3DTilesSelection::Tile::setViewerRequestVolume ( const std::optional< BoundingVolume > & value )

inlinenoexcept

Set the viewer request volume of this tile.

This function is not supposed to be called by clients.

Parameters

value The viewer request volume.

Definition at line 317 of file Tile.h.

Friends And Related Symbol Documentation

◆ MockTilesetContentManagerTestFixture

friend class MockTilesetContentManagerTestFixture

friend

Definition at line 697 of file Tile.h.

◆ TilesetContentManager

friend class TilesetContentManager

friend

Definition at line 696 of file Tile.h.

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

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

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ Pointer

◆ UnusedLinkedList

Constructor & Destructor Documentation

◆ Tile() [1/5]

◆ Tile() [2/5]

◆ Tile() [3/5]

◆ Tile() [4/5]

◆ Tile() [5/5]

Member Function Documentation

◆ addReference()

◆ clearChildren()

◆ createChildTiles()

◆ getBoundingVolume()

◆ getChildren() [1/2]

◆ getChildren() [2/2]

◆ getContent() [1/2]

◆ getContent() [2/2]

◆ getContentBoundingVolume()

◆ getGeometricError()

◆ getMappedRasterTiles() [1/2]

◆ getMappedRasterTiles() [2/2]

◆ getNonZeroGeometricError()

◆ getParent() [1/2]

◆ getParent() [2/2]

◆ getReferenceCount()

◆ getRefine()

◆ getTileID()

◆ getTransform()

◆ getUnconditionallyRefine()

◆ getViewerRequestVolume()

◆ hasReferencingContent()

◆ needsMainThreadLoading()

◆ needsWorkerThreadLoading()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ releaseReference()

◆ setBoundingVolume()

◆ setContentBoundingVolume()

◆ setGeometricError()

◆ setRefine()

◆ setTileID()

◆ setTransform()

◆ setUnconditionallyRefine()

◆ setViewerRequestVolume()

Friends And Related Symbol Documentation

◆ MockTilesetContentManagerTestFixture

◆ TilesetContentManager