A pager that will dynamically handle terrain tiles in a agxSDK::Simulation. More...

#include <TerrainPager.h>

Inheritance diagram for agxTerrain::TerrainPager:

Classes
struct	TileAttachments

Public Types
enum	TerrainRaycastResult { RAYCAST_NO_RESULT , RAYCAST_HIT_ACTIVE_TERRAIN_TILE , RAYCAST_RESULT_FROM_DATASOURCE }
	Enum with different types of result from the raycast method. More...

typedef agx::Vector< const TerrainPager::TileAttachments * >	TileAttachmentConstPtrVector

typedef agx::Vector< TerrainPager::TileAttachments * >	TileAttachmentPtrVector

typedef agx::Callback2< agxTerrain::TileId, agxTerrain::Terrain * >	TileCallback
	Callback type.

typedef agx::Event2< agxTerrain::TileId, agxTerrain::Terrain * >	TileLoadEvent
	Event types.

typedef agx::Event2< agxTerrain::TileId, agxTerrain::Terrain * >	TileUnloadEvent

Public Types inherited from agxSDK::StepEventListener
enum	ActivationMask { STEP_NONE = 0x0 , PRE_COLLIDE = 0x1 , PRE_STEP = 0x2 , POST_STEP = 0x4 , LAST_STEP = 0x8 , DEFAULT = PRE_STEP \| POST_STEP , ALL = PRE_COLLIDE \| PRE_STEP \| POST_STEP \| LAST_STEP }
	Defines the event states for which a listener will be activated, a mask can be bitwise OR:ed from these members. More...

Public Types inherited from agxSDK::EventListener
enum	Type { UNDEFINED_TYPE , STEP_EVENT_LISTENER , CONTACT_EVENT_LISTENER , GUI_EVENT_LISTENER }
	Type of EventListener. More...

Public Types inherited from agx::Component
typedef Event2< Component , Object >	ObjectEvent
	Event when adding removing child objects.

typedef Callback1< Object * >	TraverseCallback

Public Types inherited from agx::Object
typedef agx::observer_ptr< const Event >	EventConstObserver

typedef agx::ref_ptr< const Event >	EventConstRef

typedef agx::observer_ptr< Event >	EventObserver

typedef agx::Vector< EventObserver >	EventObserverVector

typedef agx::VectorPOD< Event * >	EventPtrVector

typedef agx::ref_ptr< Event >	EventRef

typedef agx::Vector< EventRef >	EventRefVector

Public Member Functions
	TerrainPager (size_t tileResolution, size_t tileOverlap, agx::Real tileElementSize, agx::Real maximumDepth, agx::Vec3 refPoint, agx::Quat refRotation, agxTerrain::Terrain *templateTerrain)
	Constructor.

bool	add (agx::RigidBody *body, agx::Real requiredTileRadius, agx::Real preloadTileRadius)
	Adds a RigidBody to the terrain pager.

bool	add (agxTerrain::Shovel *shovel, agx::Real requiredTileRadius, agx::Real preloadTileRadius)
	Adds a Shovel and its RigidBody to the terrain pager.

bool	add (agxTerrain::TerrainWheel *TerrainWheel, agx::Real requiredTileRadius, agx::Real preloadTileRadius)
	Adds a TerrainWheel and its RigidBody to the terrain pager.

virtual void	addNotification () override
	Notification to the TerrainPager when being added to a Simulation.

void	applyChangesToTemplateTerrain ()
	Signals to the TerrainPager that the template terrain has been updated and that any changes to the template terrain should be applied to the active terrain tiles in the pager.

TileAttachmentPtrVector	getActiveTileAttachments ()
	Returns a vector of the terrains currently tracked by this pager.

TileAttachmentConstPtrVector	getActiveTileAttachments () const
	Returns a vector of the terrains currently tracked by this pager.

bool	getDeformable () const
	Gets whether or not deformations are enabled for the tiles managed by this pager.

bool	getEmbedCacheFilesInArhive () const
	Returns if cached files should be embedded in AGX Archives used for serialization.

agx::String	getFileCacheDirectory () const
	Return the location for where files should be temporary cached when not needed in memory.

agx::Physics::GranularBodySystem *	getGranularBodySystem () const
	Returns the internal GranularBodySystem used to simulate the soil particles.

bool	getShouldStoreCompaction () const
	Returns whether the terrain pager should store compaction data for tiles that are paged out.

bool	getShouldStoreDeltas () const
	Return whether the terrain pager should store changes to the terrain every time step.

bool	getShouldSynchronizeOverlapCompaction ()
	Return whether the terrain pager should synchronize compaction between tiles if shouldStoreCompaction is false.

SoilSimulationInterface *	getSoilSimulationInterface ()
	Returns the soil simulation interface used by the terrains tracked by this pager or nullptr if there are no active terrains.

agxTerrain::Terrain *	getTemplateTerrain ()
	Fetches the template terrain.

TerrainDataSource *	getTerrainDataSource ()
	Returns the data source the pager uses for fetching height data for tiles.

agx::RealPair	getTileLoadRadius (agx::RigidBody *body)
	Get the tile readiuses for a body.

const TileSpecification &	getTileSpecification () const
	Specifies a new reference point for the terrain grid tiles.

agx::Real	getTotalTerrainMass ()
	Calculates the total mass of all currently paged in terrain tiles.

virtual void	last (const agx::TimeStamp &time) override
	Callback from Simulation.

virtual void	preCollide (const agx::TimeStamp &time) override
	Callback from Simulation.

TerrainRaycastResult	raycast (agx::Vec3 start, agx::Vec3 end, agx::Vec3 &result)
	Perform raycasting against the paged terrain.

bool	remove (agx::RigidBody *body)
	Remove body so that the terrain pager no longer uses the body when determining which terrain tiles that are needed.

bool	remove (agxTerrain::Shovel *shovel)
	Removes a shovel object from the terrain pager, if it exists.

virtual void	removeNotification () override
	Performs cleanup when removed from the simulation.

void	reset ()
	Resets paged terrain.

void	restore (const agxTerrain::TileModificationVector &restoreData)
	Restores internal data from stream.

void	setBlockingCallbacks (TerrainCache::PreBlockFunc preBlock, TerrainCache::PostBlockFunc postBlock)
	Set callbacks invoked before and after the main thread blocks waiting for the background tile-loading thread.

void	setDeformable (bool deformable)
	Sets if deformation should be enabled for terrains managed by this pager.

void	setEmbedCacheFilesInArchive (bool embed)
	Sets if cached files written out to disk should be embeded in AGX Archives when store is called.

bool	setFileCacheDirectory (agx::String dir)
	Specify the location for there terrain tiles should be stored when cached to disk.

void	setShouldStoreCompaction (bool shouldStoreCompaction, size_t maximumCompactionDepth)
	Sets if the terrain pager should store compaction data for tiles that are paged out.

void	setShouldStoreDeltas (bool shouldStoreDeltas)
	Specify whether the terrain pager should store changes to the terrain every time step.

void	setShouldSynchronizeOverlapCompaction (bool shouldSynchronizeCompaction)
	Specify whether the terrain pager should synchronize compaction changes in tile overlaps even if shouldStoreCompaction is false.

void	setTerrainDataSource (TerrainDataSource *tds)
	Sets the data source that the pager needs to fetch terrain tile data.

bool	setTileLoadRadiuses (agx::RigidBody *body, agx::Real requiredTileRadius, agx::Real preloadTileRadius)
	Set tile radiuses for a already added RigidBody.

void	store (agxTerrain::TileModificationVector &storeData)
	Stores internal data into stream.

void	syncOverlap (const agxTerrain::TileId &tileIndex, const agx::Vec2i &sourceIndex, bool shouldSynchronizeCompaction)
	Sync all terrain data from the modifiedVertices in the tile given by the tileIndex to any surrounding tiles which overlap.

void	syncOverlapCallback (agxTerrain::Terrain *terrain)
	Callback from Terrain::preCollide, after shovels, avalanching, etc have modified the terrain for this timestep.

Public Member Functions inherited from agxSDK::StepEventListener
	StepEventListener (int mask=DEFAULT)
	Default constructor, sets the default activation mask to all (POST_STEP and PRE_STEP) events.

	AGXSTREAM_DECLARE_SERIALIZABLE_BASE (agxSDK::StepEventListener)

virtual void	last (const agx::TimeStamp &time)
	Called after a step is taken in the simulation Implement this method in the derived class to get callbacks.

virtual void	post (const agx::TimeStamp &time)
	Called after a step is taken in the simulation Implement this method in the derived class to get callbacks.

virtual void	pre (const agx::TimeStamp &time)
	Called before a step is taken in the simulation Implement this method in the derived class to get callbacks.

virtual void	preCollide (const agx::TimeStamp &time)
	Called before collision detection is performed in the simulation Implement this method in the derived class to get callbacks.

virtual void	setMask (int mask) override
	Specifies a bitmask which determines which event types will activate this listener.

Public Member Functions inherited from agxSDK::EventListener
virtual void	addNotification ()
	Called when this listener is added to the simulation.

	AGXSTREAM_DECLARE_SERIALIZABLE_BASE (agxSDK::EventListener)

int	getMask () const

agx::UInt32	getPriority () const

Simulation *	getSimulation ()

const Simulation *	getSimulation () const

Type	getType () const

bool	isEnabled () const

virtual void	removeNotification ()
	Called when this listener is removed from the simulation.

void	setEnable (bool enable)
	Specify whether the listener should react at all at events.

virtual void	setMask (int f)
	Specifies a bit mask which determines which event types that will activate this listener.

Public Member Functions inherited from agx::Component
	Component (const agx::Name &name=agx::Name(), agx::Model model=agx::Component::ClassModel(), agx::Device device=nullptr)

virtual void	addObject (agx::Object *object, bool assignContext=true)
	Add an object to the component.

virtual String	autoComplete (const String &partialName, StringVector &matchingNames) const

virtual void	buildNavigationTree (agxJson::Value &eNode) const override

void	configure (Model *model)

virtual void	configure (TiXmlElement *eComponent) override

agx::Device *	getDevice ()

template<typename T >
T *	getDevice ()

const agx::Device *	getDevice () const

template<typename T >
const T *	getDevice () const

size_t	getNumObjects (const agx::Name &name) const

agx::Object *	getObject (const agx::Name &name, agx::Model *model, size_t index=0)

const agx::Object *	getObject (const agx::Name &name, agx::Model *model, size_t index=0) const

agx::Object *	getObject (const agx::Name &name, size_t index=0)

template<typename T >
T *	getObject (const agx::Name &name, size_t index=0)

const agx::Object *	getObject (const agx::Name &name, size_t index=0) const

template<typename T >
const T *	getObject (const agx::Name &name, size_t index=0) const

const agx::ObjectRefVector &	getObjects () const

template<typename T >
void	getObjects (agx::ObjectPtrVector &result, bool recursive=false) const
	Returns All child objects of a specified type in the result container.

void	getObjects (agx::ObjectPtrVector &result, const agx::Model *model, bool recursive=false) const

virtual Object *	getResourceImpl (const Path &path, agx::Model *model) override

virtual void	printSubtree () const override

void	printSubtree (std::ostream &stream, int depth=0) const

virtual void	rebind () override

void	removeAllObjects ()
	Remove all components.

virtual void	removeObject (agx::Object *object)
	Remove an object from the component.

void	removeObject (const agx::Name &name, size_t index=0)
	Remove an object with a specified name (and optional index) from the component.

virtual void	snapshot (TiXmlNode *eParent, const String &directory) const override

void	traverse (ComponentVisitor *)

void	traverse (const TraverseCallback &callback)

Public Member Functions inherited from agx::Object
	Object (const Name &name=Name(), Model *model=Object::ClassModel())

void	addListener (EventListener *listener)

virtual void	buildNavigationTree (agxJson::Value &eNode) const

virtual void	configure (TiXmlElement *)

agx::String	fullName () const

agx::String	fullPath () const

agx::String	fullPath (const agx::Object *root) const

template<typename T >
T *	getAutoScopedResource (const agx::Path &path)

template<typename T >
const T *	getAutoScopedResource (const agx::Path &path) const

agx::Object *	getAutoScopedResource (const agx::Path &path, agx::Model *model=nullptr)

const agx::Object *	getAutoScopedResource (const agx::Path &path, agx::Model *model=nullptr) const

agx::Object *	getContext ()

template<typename T >
T *	getContext ()

const agx::Object *	getContext () const

template<typename T >
const T *	getContext () const

agx::UInt32	getId () const

const agx::Name &	getImplementationName () const

agx::Model *	getModel ()

const agx::Model *	getModel () const

const agx::Name &	getName () const

agx::Object *	getNextSibling ()

const agx::Object *	getNextSibling () const

agx::Path	getPath () const

agx::Path	getPath (const agx::Object *root) const

template<typename T >
T *	getResource (const agx::Path &path)

template<typename T >
const T *	getResource (const agx::Path &path) const

agx::Object *	getResource (const agx::Path &path, agx::Model *model=nullptr)

const agx::Object *	getResource (const agx::Path &path, agx::Model *model=nullptr) const

virtual agx::Object *	getResourceImpl (const agx::Path &path, agx::Model *model)

agx::Object *	getRootContext ()

const agx::Object *	getRootContext () const

bool	hasListener (EventListener *listener)

bool	hasParent (const agx::Object *node) const

bool	isUnique () const

virtual void	printSubtree () const

virtual void	rebind ()

void	removeListener (EventListener *listener)

virtual void	save (TiXmlElement *) const

virtual void	setContext (agx::Object *context)

void	setId (UInt32 id)

void	setModel (agx::Model *model)
	Set the object model (handled automatically).

void	setName (const agx::Name &name)
	Set the name of the object.

virtual void	snapshot (TiXmlNode *, const String &) const

Public Member Functions inherited from agx::Referenced
	Referenced ()
	Default constructor.

	Referenced (const Referenced &)

template<typename T >
T *	as ()
	Subclass casting.

template<typename T >
const T *	as () const

template<typename T >
T *	asSafe ()
	Safe subclass casting, return nullptr if template type does not match.

template<typename T >
const T *	asSafe () const

int	getReferenceCount () const

template<typename T >
bool	is () const
	Subclass test.

Referenced &	operator= (const Referenced &)
	Assignment operator. Will increment the number of references to the referenced object.

void	reference (void *ptr=nullptr) const
	Explicitly increment the reference count by one, indicating that this object has another pointer which is referencing it.

void	unreference (void *ptr=nullptr) const
	Decrement the reference count by one, indicating that a pointer to this object is referencing it.

void	unreference_nodelete () const
	Decrement the reference count by one, indicating that a pointer to this object is referencing it.

Public Member Functions inherited from agxStream::Serializable
virtual	~Serializable ()
	Destructor for normal C++ use but hidden from SWIG bindings.

virtual const char *	getClassName () const

bool	getEnableSerialization () const

bool	getEnableUuidGeneration ()

agx::UInt32	getIndex () const
	This index is given at creation of this object.

virtual StorageAgent *	getStorageAgent () const =0

agx::Uuid	getUuid () const

bool	isFinished () const

void	setEnableSerialization (bool flag)
	Set to false to disable serialization of this object.

void	setFinished ()
	Tells this class that it is restored correctly and should not be deleted during destruction of an Archive.

void	setUuid (const agx::Uuid &uuid)
	Explicitly set a Uuid on a serializable object.

Public Attributes
TileLoadEvent	tileLoadEvent
	An event that the TerrainPager will trigger after a new tile as been loaded and added to the simulation.

TileUnloadEvent	tileUnloadEvent
	An event that the TerrainPager will trigger just before it removes a tile from the simulation.

Public Attributes inherited from agx::Component
ObjectEvent	addObjectEvent

ObjectEvent	removeObjectEvent

Protected Member Functions
	TerrainPager ()
	Serializable.

virtual	~TerrainPager ()

agx::Real	getOverlappingAreaSolidMass (agxTerrain::TileId, agxTerrain::TileId)

agx::Real	getSolidMassBeneathSurfaceCoord (const size_t &x, const size_t &y, agxTerrain::TerrainRef &terrainTile)

void	handleNewTerrainTile (agxTerrain::TerrainTile)

bool	isIndexWithinTileMargin (const agx::Vec2i &terrainIndex) const

void	prepareSimulation (bool fromRestore)

void	synchronizeCompactionInColumn (agxTerrain::Terrain sourceTile, agx::Vec2i sourceIndex, agxTerrain::Terrain targetTile, agx::Vec2i targetIndex)

void	synchronizeDataInColumn (agxTerrain::TileId sourceTileId, agxTerrain::TileId tileIdOffset, agx::Vec2i sourceIndex, bool shouldSynchronizeCompaction)

void	synchronizeTerrainMaterialInColumn (agxTerrain::Terrain sourceTile, agx::Vec2i sourceIndex, agxTerrain::Terrain targetTile, agx::Vec2i targetIndex)

void	unloadAllTiles ()

void	unloadUnusedTiles (bool partOfRemoveNotification)

void	updateActiveTiles ()

Protected Member Functions inherited from agxSDK::StepEventListener
virtual	~StepEventListener ()
	Destructor.

Protected Member Functions inherited from agxSDK::EventListener
	EventListener (Type type=UNDEFINED_TYPE)
	Default constructor.

virtual	~EventListener ()
	Destructor.

void	setSimulation (Simulation *simulation)
	Set the associated simulation for this EventListener.

Protected Member Functions inherited from agx::Component
virtual	~Component ()

String	expandAutoCompletionMatch (const String &query, const StringVector &matchingNames) const

void	setDevice (Device *device)

Protected Member Functions inherited from agx::Object
virtual	~Object ()

Protected Member Functions inherited from agx::Referenced
virtual	~Referenced ()
	Destructor.

void	allocateObserverVector () const

void	deleteUsingDeleteHandler () const

Protected Member Functions inherited from agxStream::Serializable
	Serializable ()
	Default constructor.

	Serializable (const Serializable &other)
	Copy constructor.

void	generateUuid ()

Additional Inherited Members
Static Public Member Functions inherited from agxSDK::StepEventListener
static agxStream::Serializable *	create (agxStream::InputArchive &)

Static Public Member Functions inherited from agxSDK::EventListener
static agxStream::Serializable *	create (agxStream::InputArchive &)

Static Public Member Functions inherited from agx::Component
static Component *	_load (TiXmlElement eComponent, Device device)

static agx::Model *	ClassModel ()

static Component *	load (const Path &path, const Name &implementation, Device *device, const Path &_namespace=Path())

static Component *	load (const String &path, const Path &_namespace=Path())

static Component *	load (const String &path, Device *device, const Path &_namespace=Path())

static Component *	load (TiXmlElement eComponent, Device device)

Static Public Member Functions inherited from agx::Object
static agx::Model *	ClassModel ()

static agx::String	generateName (const agx::String &bindPath)

static const HashSet< Object * > &	getActiveObjects ()

static bool	getEnableRebind ()
	Should rebinding be allowed? Right now a global setting.

static Object *	load (const String &path, Device *device, const String &type, const String &attribute, const String &value)

template<typename T >
static T *	load (const String &path, Device *device, const String &type, const String &attribute, const String &value)

static Object *	load (const String &path, Device *device, const String &type="", size_t instance=0)

template<typename T >
static T *	load (const String &path, Device *device, const String &type="", size_t instance=0)

static void	load (const String &path, Device *device, ObjectPtrVector &loadedObjects)

static Object *	load (TiXmlElement eObject, Device device)

template<typename T >
static T *	load (TiXmlElement eObject, Device device)

static TiXmlDocument	openDocument (const String &path)

static void	setEnableRebind (bool flag)
	Sets if rebinding of objects should be allowed (Right now a global setting).

Static Public Member Functions inherited from agx::Referenced
template<typename T >
static bool	ValidateCast (const Referenced *object)

Static Public Member Functions inherited from agxStream::Serializable
static void	setEnableUuidGeneration (bool flag)
	Specify if there should be UUID:s generated for each new Serializable object. By default it is enabled.

Static Protected Member Functions inherited from agx::Referenced
static DeleteHandler *	getDeleteHandler ()

static void	setDeleteHandler (DeleteHandler *handler)
	Internal: Set a DeleteHandler to which deletion of all referenced counted objects will be delegated to.

Protected Attributes inherited from agxSDK::EventListener
bool	m_enabled

int	m_mask

agx::UInt32	m_priority

Type	m_type

Protected Attributes inherited from agx::Referenced
Mutex	m_mutex

ObserverContainer	m_observers

AtomicValue	m_refCount

Detailed Description

A pager that will dynamically handle terrain tiles in a agxSDK::Simulation.

The pager uses a 2D-grid and populates the grid tiles with terrain instances as needed. There is a reference point which specifies the (0,0) position for the 2D-grid. There is also a reference rotation which should be used to map the grids local Z-axis to the up direction at the reference point.

The reference point should be specified to be near the location in the world where the simulation is being performed.

In a default created Simulation with uniform gravity, the reference rotation can be set to the identity matrix since AGX uses Z as default up axis. If the gravity direction is changed and e.g. the x-z plane is used for ground and y for up, then the rotation must be set accordingly.

On the other hand, if the Simulation is being performed on a sphere (e.g Earth) with a point gravity source, then it is important that the working area is relatively close to the reference point. With Earths radius and a distance 10km away from the reference point, a height difference of a few meters can be observed due to Earths curvature. The approximation within the pager to work with a 2D-grid can handle these heigh differences within the different tiles without problem. But if the reference point is set at the north pole and the working area is near the equator problems will occur.

To track which grid tiles that needs to have active terrain instances, one or more bodies are added to the TerrainPager. The world position for those bodies will be used to determine which tiles should be available. Along with the body position, two radiuses are used:

One radius for required tiles. These must be available for the simulation to step. This will add a small delay in the initial setup.
A second radius for preloading. The preloading radius should be larger than the required radius and is used so that tiles are made available before they are reached by the required radius. Preloaded tiles are inserted into the simulation when ready and the simulation can be stepped while the preloading occurs.

Excavation in the Terrain works best when the excavation is being performed within a tile. Therefor tiles can have a margin so that they have a overlap to make the transition from one tile to the next work so the excavation is always kept within a single tile and never reaches a tile edge. This margin is specified via how many height values that should overlap.

If margins larger than 0 are used, then this affects which data points from each tiles heightfield that should be used for rendering to avoid drawing the same part twice.

NOTE:

The agxSDK::Simulation does not support that the update task is rebuilt during stepForward.
The TerrainPager must be able to add terrains to the simulation during stepForward.
Adding a terrain to the simulation will set some solver parameters and possibly cause the update task to be rebuilt.
Hence, simulation->add( terrainpager ) prepares the Simulation so that the update task will not be rebuilt when adding terrains.
It is NOT supported to change the following Solver parameters after a TerrainPager has been added to a Simulation: setUseParallelPgs, setUse32bitGranularBodySolver, setUseGranularWarmStarting
The Broadphase algorithm will be set to Hierarchical_Grid and it is NOT supported to change it back to Sweep-And-Prune.

Definition at line 99 of file TerrainPager.h.

Member Typedef Documentation

◆ TileAttachmentConstPtrVector

typedef agx::Vector<const TerrainPager::TileAttachments*> agxTerrain::TerrainPager::TileAttachmentConstPtrVector

Definition at line 120 of file TerrainPager.h.

◆ TileAttachmentPtrVector

typedef agx::Vector<TerrainPager::TileAttachments*> agxTerrain::TerrainPager::TileAttachmentPtrVector

Definition at line 119 of file TerrainPager.h.

◆ TileCallback

typedef agx::Callback2< agxTerrain::TileId, agxTerrain::Terrain* > agxTerrain::TerrainPager::TileCallback

Callback type.

Definition at line 104 of file TerrainPager.h.

◆ TileLoadEvent

typedef agx::Event2< agxTerrain::TileId, agxTerrain::Terrain* > agxTerrain::TerrainPager::TileLoadEvent

Event types.

Definition at line 107 of file TerrainPager.h.

◆ TileUnloadEvent

typedef agx::Event2< agxTerrain::TileId, agxTerrain::Terrain* > agxTerrain::TerrainPager::TileUnloadEvent

Definition at line 108 of file TerrainPager.h.

Member Enumeration Documentation

◆ TerrainRaycastResult

enum agxTerrain::TerrainPager::TerrainRaycastResult

Enum with different types of result from the raycast method.

Enumerator
RAYCAST_NO_RESULT
RAYCAST_HIT_ACTIVE_TERRAIN_TILE
RAYCAST_RESULT_FROM_DATASOURCE

Definition at line 392 of file TerrainPager.h.

Constructor & Destructor Documentation

◆ TerrainPager() [1/2]

agxTerrain::TerrainPager::TerrainPager	(	size_t	tileResolution,
		size_t	tileOverlap,
		agx::Real	tileElementSize,
		agx::Real	maximumDepth,
		agx::Vec3	refPoint,
		agx::Quat	refRotation,
		agxTerrain::Terrain *	templateTerrain
	)

Constructor.

Specifies tile information and the 2D-plane used for dynamic terrain tiles.

The TerrainPager do not mirror all the different parameters a terrain exposes, instead a template terrain is used for settings and default material parameters.

To use multiple terrain materials, the materials and their assigned regions need to be set on the TerrainDataSource.

To support excavation, the terrain tiles have an optional margin. This margin can be set so that the excavation is performed within one tile and correct soil wedges are formed.

Example: tileResolution = 301, tileOverlap 10, tileElementSize = 0.25, ....

Each tile then becomes (301-1)*0.25 = 75m x 75m The overlap on each side will be 10*0.25 = 2.5m

Parameters

tileResolution	Specifies the number of height values for each dimension for (tile+margin).
tileOverlap	Specifies the number of height values that should overlap between two tiles.
tileElementSize	Size in meters for one element. Same as distance between two height values.
maximumDepth	How deep in meters the terrain can be excavated
refPoint	A world reference point for where the terrain is located
refRotation	A rotation that will transform the Z-axis to the up direction at the referencePoint
templateTerrain	A template terrain whose settings will be used for the terrain tiles.

◆ TerrainPager() [2/2]

agxTerrain::TerrainPager::TerrainPager ( )

protected

Serializable.

Default constructor.

◆ ~TerrainPager()

virtual agxTerrain::TerrainPager::~TerrainPager ( )

protectedvirtual

Member Function Documentation

◆ add() [1/3]

bool agxTerrain::TerrainPager::add	(	agx::RigidBody *	body,
		agx::Real	requiredTileRadius,
		agx::Real	preloadTileRadius
	)

Adds a RigidBody to the terrain pager.

The pager will make sure that terrain tiles within the required radius are present in the Simulation before stepping and tiles within the preload radius will be loaded and inserted when available.

◆ add() [2/3]

bool agxTerrain::TerrainPager::add	(	agxTerrain::Shovel *	shovel,
		agx::Real	requiredTileRadius,
		agx::Real	preloadTileRadius
	)

Adds a Shovel and its RigidBody to the terrain pager.

The pager will make sure that terrain tiles within the required radius are present in the Simulation before stepping and tiles within the preload radius will be loaded and inserted when available.

◆ add() [3/3]

bool agxTerrain::TerrainPager::add	(	agxTerrain::TerrainWheel *	TerrainWheel,
		agx::Real	requiredTileRadius,
		agx::Real	preloadTileRadius
	)

Adds a TerrainWheel and its RigidBody to the terrain pager.

The pager will make sure that terrain tiles within the required radius are present in the Simulation before stepping and tiles within the preload radius will be loaded and inserted when available.

◆ addNotification()

virtual void agxTerrain::TerrainPager::addNotification ( )

overridevirtual

Notification to the TerrainPager when being added to a Simulation.

Reimplemented from agxSDK::EventListener.

◆ applyChangesToTemplateTerrain()

void agxTerrain::TerrainPager::applyChangesToTemplateTerrain ( )

Signals to the TerrainPager that the template terrain has been updated and that any changes to the template terrain should be applied to the active terrain tiles in the pager.

◆ getActiveTileAttachments() [1/2]

TileAttachmentPtrVector agxTerrain::TerrainPager::getActiveTileAttachments ( )

Returns a vector of the terrains currently tracked by this pager.

◆ getActiveTileAttachments() [2/2]

TileAttachmentConstPtrVector agxTerrain::TerrainPager::getActiveTileAttachments ( ) const

Returns a vector of the terrains currently tracked by this pager.

◆ getDeformable()

bool agxTerrain::TerrainPager::getDeformable ( ) const

inline

Gets whether or not deformations are enabled for the tiles managed by this pager.

If false, then no dynamic mass particles or fluid mass is created. Additionally, no avalanching or compaction occurs on the terrain.

Returns: true if deformations are enabled for this pager, false otherwise

Definition at line 592 of file TerrainPager.h.

References agxTerrain::TerrainCache::getTemplateTerrain().

◆ getEmbedCacheFilesInArhive()

bool agxTerrain::TerrainPager::getEmbedCacheFilesInArhive ( ) const

inline

Returns if cached files should be embedded in AGX Archives used for serialization.

Definition at line 587 of file TerrainPager.h.

References agxTerrain::TerrainCache::getEmbedCacheFilesInArhive().

◆ getFileCacheDirectory()

agx::String agxTerrain::TerrainPager::getFileCacheDirectory ( ) const

Return the location for where files should be temporary cached when not needed in memory.

◆ getGranularBodySystem()

agx::Physics::GranularBodySystem * agxTerrain::TerrainPager::getGranularBodySystem ( ) const

Returns the internal GranularBodySystem used to simulate the soil particles.

Note: Editing or otherwise change the internal particle data is undefined behavior.

◆ getOverlappingAreaSolidMass()

agx::Real agxTerrain::TerrainPager::getOverlappingAreaSolidMass	(	agxTerrain::TileId	,
		agxTerrain::TileId
	)

protected

◆ getShouldStoreCompaction()

bool agxTerrain::TerrainPager::getShouldStoreCompaction ( ) const

Returns whether the terrain pager should store compaction data for tiles that are paged out.

◆ getShouldStoreDeltas()

bool agxTerrain::TerrainPager::getShouldStoreDeltas ( ) const

Return whether the terrain pager should store changes to the terrain every time step.

◆ getShouldSynchronizeOverlapCompaction()

bool agxTerrain::TerrainPager::getShouldSynchronizeOverlapCompaction ( )

Return whether the terrain pager should synchronize compaction between tiles if shouldStoreCompaction is false.

◆ getSoilSimulationInterface()

SoilSimulationInterface * agxTerrain::TerrainPager::getSoilSimulationInterface ( )

Returns the soil simulation interface used by the terrains tracked by this pager or nullptr if there are no active terrains.

◆ getSolidMassBeneathSurfaceCoord()

agx::Real agxTerrain::TerrainPager::getSolidMassBeneathSurfaceCoord	(	const size_t &	x,
		const size_t &	y,
		agxTerrain::TerrainRef &	terrainTile
	)

protected

◆ getTemplateTerrain()

agxTerrain::Terrain * agxTerrain::TerrainPager::getTemplateTerrain ( )

Fetches the template terrain.

The settings for the template terrain are used on new terrain tiles when they are inserted into the simulation.

See also: applyChangesToTemplateTerrain

◆ getTerrainDataSource()

TerrainDataSource * agxTerrain::TerrainPager::getTerrainDataSource ( )

Returns the data source the pager uses for fetching height data for tiles.

◆ getTileLoadRadius()

agx::RealPair agxTerrain::TerrainPager::getTileLoadRadius ( agx::RigidBody * body )

Get the tile readiuses for a body.

If body is not found, (-1,-1) is returned. The first number in the pair is the required radius, the second the preload radius

◆ getTileSpecification()

const TileSpecification & agxTerrain::TerrainPager::getTileSpecification ( ) const

Specifies a new reference point for the terrain grid tiles.

This is an expensive operation and should be avoided if possible.

All old data and the cache will be cleared since the transform from 2D-grid to world will be affected
All required tiles will have to be reloaded. Can cause some delay on the next simulation stepForward. The tile specification is set via the constructor and optionally modified via setTerrainPlanLocation. This method gives read access to terrain tile paging setup.

◆ getTotalTerrainMass()

agx::Real agxTerrain::TerrainPager::getTotalTerrainMass ( )

Calculates the total mass of all currently paged in terrain tiles.

The mass of the areas where tiles are overlapping is not counted twice. NOTE: The mass of the areas where tiles are overlapping might be out of sync if this method is called in a time-step where one or more vertices within the overlapping area has been modified. Which might make this calculation invalid.

◆ handleNewTerrainTile()

void agxTerrain::TerrainPager::handleNewTerrainTile ( agxTerrain::TerrainTile )

protected

◆ isIndexWithinTileMargin()

bool agxTerrain::TerrainPager::isIndexWithinTileMargin ( const agx::Vec2i & terrainIndex ) const

protected

◆ last()

virtual void agxTerrain::TerrainPager::last ( const agx::TimeStamp & time )

overridevirtual

Callback from Simulation.

Height synchronization for overlapping parts. No longer needed tiles are removed at this stage.

Reimplemented from agxSDK::StepEventListener.

◆ preCollide()

virtual void agxTerrain::TerrainPager::preCollide ( const agx::TimeStamp & time )

overridevirtual

Callback from Simulation.

Ready preloaded terraintiles are inserted at this stage.

Reimplemented from agxSDK::StepEventListener.

◆ prepareSimulation()

void agxTerrain::TerrainPager::prepareSimulation ( bool fromRestore )

protected

◆ raycast()

TerrainRaycastResult agxTerrain::TerrainPager::raycast	(	agx::Vec3	start,
		agx::Vec3	end,
		agx::Vec3 &	result
	)

Perform raycasting against the paged terrain.

Test via active tiles:

hit: return RAYCAST_HIT_ACTIVE_TILE
miss: Perform test via TerrainDataSource if supported
hit: return RAYCAST_RESULT_FROM_DATASOURCE
miss/not supported: return RAYCAST_NO_RESULT

If a terrain tile is modified and then paged out, a result from the datasource will not show those modifications. For best results, raycasting should be performed against paged in tiles.

◆ remove() [1/2]

bool agxTerrain::TerrainPager::remove ( agx::RigidBody * body )

Remove body so that the terrain pager no longer uses the body when determining which terrain tiles that are needed.

◆ remove() [2/2]

bool agxTerrain::TerrainPager::remove ( agxTerrain::Shovel * shovel )

Removes a shovel object from the terrain pager, if it exists.

Returns: true if successful, false otherwise

◆ removeNotification()

virtual void agxTerrain::TerrainPager::removeNotification ( )

overridevirtual

Performs cleanup when removed from the simulation.

Reimplemented from agxSDK::EventListener.

◆ reset()

void agxTerrain::TerrainPager::reset ( )

Resets paged terrain.

◆ restore()

void agxTerrain::TerrainPager::restore ( const agxTerrain::TileModificationVector & restoreData )

Restores internal data from stream.

◆ setBlockingCallbacks()

void agxTerrain::TerrainPager::setBlockingCallbacks	(	TerrainCache::PreBlockFunc	preBlock,
		TerrainCache::PostBlockFunc	postBlock
	)

inline

Set callbacks invoked before and after the main thread blocks waiting for the background tile-loading thread.

Use this to release any lock the calling thread holds so the background thread can proceed. Must be called before tiles are requested (before adding to simulation).

Definition at line 579 of file TerrainPager.h.

References agxTerrain::TerrainCache::setBlockingCallbacks().

◆ setDeformable()

void agxTerrain::TerrainPager::setDeformable ( bool deformable )

Sets if deformation should be enabled for terrains managed by this pager.

If this is set to false no dynamic mass particles or fluid mass is created. Additionally, no avalanching or compaction occurs on the terrain. This changes and applies the undelying template terrain.

Parameters

deformable - Whether or not to deformations should occur on this terrain

◆ setEmbedCacheFilesInArchive()

void agxTerrain::TerrainPager::setEmbedCacheFilesInArchive ( bool embed )

inline

Sets if cached files written out to disk should be embeded in AGX Archives when store is called.

Default false.

Definition at line 574 of file TerrainPager.h.

References agxTerrain::TerrainCache::setEmbedCacheFilesInArchive().

◆ setFileCacheDirectory()

bool agxTerrain::TerrainPager::setFileCacheDirectory ( agx::String dir )

Specify the location for there terrain tiles should be stored when cached to disk.

◆ setShouldStoreCompaction()

void agxTerrain::TerrainPager::setShouldStoreCompaction	(	bool	shouldStoreCompaction,
		size_t	maximumCompactionDepth
	)

Sets if the terrain pager should store compaction data for tiles that are paged out.

Parameters

shouldStoreCompaction	Bool flag to set if compction should be stored.
maximumCompactionDepth	Sets how deep compaction data should be stored. Specifically how many voxels below the surface.

◆ setShouldStoreDeltas()

void agxTerrain::TerrainPager::setShouldStoreDeltas ( bool shouldStoreDeltas )

Specify whether the terrain pager should store changes to the terrain every time step.

Should only be true if restore function is planned to be used.

◆ setShouldSynchronizeOverlapCompaction()

void agxTerrain::TerrainPager::setShouldSynchronizeOverlapCompaction ( bool shouldSynchronizeCompaction )

Specify whether the terrain pager should synchronize compaction changes in tile overlaps even if shouldStoreCompaction is false.

Parameters

shouldSynchronizeCompaction - true if compaction should be synchronized in tile overlaps if shouldStoreCompaction is false. (Default: true)

Note: If shouldStoreCompaction is true compaction will be synchronized and this setting will be overidden.

◆ setTerrainDataSource()

void agxTerrain::TerrainPager::setTerrainDataSource ( TerrainDataSource * tds )

Sets the data source that the pager needs to fetch terrain tile data.

See also: TerrainRasterizer

◆ setTileLoadRadiuses()

bool agxTerrain::TerrainPager::setTileLoadRadiuses	(	agx::RigidBody *	body,
		agx::Real	requiredTileRadius,
		agx::Real	preloadTileRadius
	)

Set tile radiuses for a already added RigidBody.

If a radius is negative, then it is ignored making it possible to have a body that does not require any tiles but can be used to preload tiles.

◆ store()

void agxTerrain::TerrainPager::store ( agxTerrain::TileModificationVector & storeData )

Stores internal data into stream.

◆ synchronizeCompactionInColumn()

void agxTerrain::TerrainPager::synchronizeCompactionInColumn	(	agxTerrain::Terrain *	sourceTile,
		agx::Vec2i	sourceIndex,
		agxTerrain::Terrain *	targetTile,
		agx::Vec2i	targetIndex
	)

protected

◆ synchronizeDataInColumn()

void agxTerrain::TerrainPager::synchronizeDataInColumn	(	agxTerrain::TileId	sourceTileId,
		agxTerrain::TileId	tileIdOffset,
		agx::Vec2i	sourceIndex,
		bool	shouldSynchronizeCompaction
	)

protected

◆ synchronizeTerrainMaterialInColumn()

void agxTerrain::TerrainPager::synchronizeTerrainMaterialInColumn	(	agxTerrain::Terrain *	sourceTile,
		agx::Vec2i	sourceIndex,
		agxTerrain::Terrain *	targetTile,
		agx::Vec2i	targetIndex
	)

protected

◆ syncOverlap()

void agxTerrain::TerrainPager::syncOverlap	(	const agxTerrain::TileId &	tileIndex,
		const agx::Vec2i &	sourceIndex,
		bool	shouldSynchronizeCompaction
	)

Sync all terrain data from the modifiedVertices in the tile given by the tileIndex to any surrounding tiles which overlap.

Called by last and syncOverlapCallback.

Needs to be called by last to set up correct state prior to TerrainManager::preCollide is run.
Needs to be called after TerrainManager::preCollide so that anyone (user, sensor environment) that looks at a tile overlap wont find invalid heights between TerrainManager::preCollide and TerrainPager::last

◆ syncOverlapCallback()

void agxTerrain::TerrainPager::syncOverlapCallback ( agxTerrain::Terrain * terrain )

Callback from Terrain::preCollide, after shovels, avalanching, etc have modified the terrain for this timestep.

Calls syncOverlap.

◆ unloadAllTiles()

void agxTerrain::TerrainPager::unloadAllTiles ( )

protected

◆ unloadUnusedTiles()

void agxTerrain::TerrainPager::unloadUnusedTiles ( bool partOfRemoveNotification )

protected

◆ updateActiveTiles()

void agxTerrain::TerrainPager::updateActiveTiles ( )

protected

Member Data Documentation

◆ tileLoadEvent

TileLoadEvent agxTerrain::TerrainPager::tileLoadEvent

An event that the TerrainPager will trigger after a new tile as been loaded and added to the simulation.

Definition at line 439 of file TerrainPager.h.

◆ tileUnloadEvent

TileUnloadEvent agxTerrain::TerrainPager::tileUnloadEvent

An event that the TerrainPager will trigger just before it removes a tile from the simulation.

Definition at line 445 of file TerrainPager.h.

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

TerrainPager.h

Classes

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ TileAttachmentConstPtrVector

◆ TileAttachmentPtrVector

◆ TileCallback

◆ TileLoadEvent

◆ TileUnloadEvent

Member Enumeration Documentation

◆ TerrainRaycastResult

Constructor & Destructor Documentation

◆ TerrainPager() [1/2]

◆ TerrainPager() [2/2]

◆ ~TerrainPager()

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ addNotification()

◆ applyChangesToTemplateTerrain()

◆ getActiveTileAttachments() [1/2]

◆ getActiveTileAttachments() [2/2]

◆ getDeformable()

◆ getEmbedCacheFilesInArhive()

◆ getFileCacheDirectory()

◆ getGranularBodySystem()

◆ getOverlappingAreaSolidMass()

◆ getShouldStoreCompaction()

◆ getShouldStoreDeltas()

◆ getShouldSynchronizeOverlapCompaction()

◆ getSoilSimulationInterface()

◆ getSolidMassBeneathSurfaceCoord()

◆ getTemplateTerrain()

◆ getTerrainDataSource()

◆ getTileLoadRadius()

◆ getTileSpecification()

◆ getTotalTerrainMass()

◆ handleNewTerrainTile()

◆ isIndexWithinTileMargin()

◆ last()

◆ preCollide()

◆ prepareSimulation()

◆ raycast()

◆ remove() [1/2]

◆ remove() [2/2]

◆ removeNotification()

◆ reset()

◆ restore()

◆ setBlockingCallbacks()

◆ setDeformable()

◆ setEmbedCacheFilesInArchive()

◆ setFileCacheDirectory()

◆ setShouldStoreCompaction()

◆ setShouldStoreDeltas()

◆ setShouldSynchronizeOverlapCompaction()

◆ setTerrainDataSource()

◆ setTileLoadRadiuses()

◆ store()

◆ synchronizeCompactionInColumn()

◆ synchronizeDataInColumn()

◆ synchronizeTerrainMaterialInColumn()

◆ syncOverlap()

◆ syncOverlapCallback()

◆ unloadAllTiles()

◆ unloadUnusedTiles()

◆ updateActiveTiles()

Member Data Documentation

◆ tileLoadEvent

◆ tileUnloadEvent