3.6 - Object Operations and Blocking Terrain Calls

Table of Contents

• 3.6.1 Queueing Object Creation
• 3.6.2 Queueing Set Location Requests

There are several circumstances under which terrain data must be available to complete an operation, such as creating objects, completing move to location tasks, and set location data requests.

If you are simulating on paged terrain and required terrain has not paged in yet, the simulation may be blocked pending the availability of the required terrain.

Simulation models cannot make blocking terrain calls that page in terrain patches (or any other operation which takes a long time) without having serious consequences on the simulation. Even a single long tick can have very negative effects on a movement model that is integrating over time. In most cases the DtMovementBasedTerrainPreloadController should take care of paging in the required terrain before an entity reaches it, but in case that does not happen it is important to design simulation models to deal with the consequences.

To prevent terrain intersection calls from blocking while paging in terrain, all simulation models must make their terrain calls using the dataAvailable flag. When specified, this optional parameter prevents the terrain call from blocking while the data is paged in. In addition to specifying this flag on calls into DtPhysicalWorld and DtTerrainInterface, it must also be specified on any call to any of the place(), placePoints(), and clampToGround() functions on the various state repository classes. In the case of a terrain intersection function, the dataAvailable flag will be set to false and no terrain intersections will be returned. In the case of a place() or clampToGround() function, the dataAvailable flag will be set to false and the points will be placed as specified without regard to the terrain. Since the clampToGround() and place() functions are actually doing multiple terrain intersections (one for each support point), they also have a requireAllData flag. This flag causes the call to abort and to reset the state of the entity to the way it was before the call if any of the support points do not have data. This makes it easier to poll on a place() or clampToGround() call until all the data is ready.

To find blocking calls at runtime, the assertOnBlockingTerrainCalls parameter in ./appData/settings/vrfSim/vrfSim.mtl should be set to 1. This causes any terrain calls that do not specify the dataAvailable flag to assert. This only affects back-ends running in debug mode.

Note

Calling the blocking form of any terrain intersection function causes an assertion. It is not necessary for the call to actually block and even non-paging implementations will assert. This is done to make it easier to find potential problems regardless of the particular terrain or location being used. In certain cases, it is safe to turn off the assert by setting the overrideBlockingAssert parameter on the terrain intersection call to true. This could include cases where the call is being made outside the main simulation thread, for instance from the path planning thread.

3.6.1 Queueing Object Creation

When VR-Forces creates an object, the terrain at the requested creation location must be available. If the terrain has not yet been paged in, in most cases the creation of the object must be queued so that the rest of the simulation can continue to run while the terrain is being paged in.

The DtVrfObjectManager queues DtIfCreateVrfObject messages until the terrain data for the requested creation location is available. Each time a creation request is processed, a terrain intersection is done and the dataAvailable flag is checked. If the terrain is available, the request is processed immediately. If not, the object manager adds the request to a queue which is checked each tick.

When creating entities using DtCgf, you can specify whether or not the creation should allow the call to block on terrain paging using the allowBlocking parameter. In most cases if the simulation has not yet started it is preferable to allow this parameter to default to true as you will get a DtVrfObject in return which you can immediately begin to work with. If the simulation is running, allowBlocking should always be set to false to prevent terrain paging from negatively affecting the simulation. In this case a NULL pointer is returned because the creation will be queued.

3.6.2 Queueing Set Location Requests

DtLocalEntitySetController and its subclasses queue Set Location requests until the terrain data is available for the requested location. Only one Set Location request is ever queued at a time. If another request comes in while terrain is still paging in from the first, the original request is cancelled.

[<< Creating and Managing Objects] [Home] [Top of Page] [Control Objects >>]