Vortex Studio SDK - Paged Terrain Producer

A paged terrain producer incrementally creates a terrain from smaller elements. The elements are created on an as-needed basis to form a paged terrain. The paged terrain consists of parts and collision geometries.

The paged terrain producer is built on the producer-source pattern. It consists of the following:

Terrain Producer

Terrain object that feeds the Vortex® dynamics with parts and collision geometries.

Paged Terrain Producer

The paged terrain producer serves as an interface between the Vortex dynamics engine and any client-owned terrain database, referred to as terrain source in the remainder of this page. The terrain producer feeds the Vortex dynamics engine with parts and collision geometries that represent regions of the terrain source via regional requests. These requests are limited to regions where simulated entities (such as vehicles) can collide with the terrain.

The paged terrain producer can thereby hold the logical representation of a very large terrain. However, it will allocate only the parts that are needed in a given simulation at a given time.

Paged Terrain Source or Paged Terrain Interface

Description of the functionality a developer must provide to connect a terrain source with Vortex Dynamics through implementation of VxPagedTerrainInterface. For an example implementation, refer to the Paged Terrain Tutorial (found in the Tutorials folder of your Vortex Studio installation).

The producer requests terrains from the source for the areas around active objects in the simulation. The paged terrain producer does not request the same area again until the source provides terrain data for the requested area.

The implementation of the paged terrain source should inquire with the paged terrain producer whether a given terrain feature has already been received by the producer (see VxPagedTerrainProducer::containsTerrain). For an example, please refer to the use of VxPagedTerrainProducer::containsTerrain in the ExPagedTerrain tutorial (found in the Tutorials folder of your Vortex Studio installation).

When the paged terrain source provides data for the terrain region requested by the paged terrain producer (see call to VxPagedTerrainInterface::produce), it should create all the parts and collision geometries associated with the requested region.

For an example, see PagedTerrain.cpp, in the ExPagedTerrain tutorial found in the Tutorials folder of your Vortex Studio installation.

Note The producer does not request the same area a second time until after a sufficient amount of time has passed without any collisions happening and more objects are approaching the area.

When there are no more objects colliding with a given terrain element that was previously provided by a terrain source, these terrain elements are cached out after a configurable period of inactivity (see VxPagedTerrainProducer::setCacheOutFrames).

It is important to note that all communication between the producer and the source is handled in the source's coordinate system. The requested Axis Aligned Bounding Box areas (AABB) specify regions in the source database. This means that the source does not need to care about where its produced terrain is placed in the simulation.

Data Flow Example

Consider a simple terrain source with two dynamic boxes. This sample terrain source consists of two trees, a vehicle, and a building.

Sample Paged Terrain

The terrain source has the height for the terrain at every location. It also has the data for two trees and one building. For an example, see PagedTerrain.cpp, in the ExPagedTerrain tutorial found in the Tutorials folder of your Vortex Studio installation.

When Vortex starts simulating the vehicle, it requests the source for the area under the vehicle. The source then queries the terrain producer to know if it has terrain data for a specific area. If it does not, the terrain source allocates a VxHeightField, puts the height field into a VxCollisionGeometry, and inserts it into the terrain.

Note The source is responsible for placing the height field at the proper coordinates in its coordinate system.

As the vehicle starts moving, the paged terrain producer requests another area from the terrain source. It performs the same query as before to determine whether to insert height fields into the terrain. However, on this second request, this area contains two terrain elements: a tree and a building. The source queries for these objects and inserts these into the terrain.

Note The tree parts and the building may have multiple collision geometries and constraints to simulate correctly. Therefore, the source must convert its terrain data into Vortex objects.

The process is repeated as the vehicle moves into a third area. In this area, the building actually intersects two areas. The source cannot assume the building is still there; it may have been cached out or deleted. It queries for the building as well as the area. The tutorial assumes the building is still in Vortex. The building does not need to be recreated. However, the source does need to inform Dynamics that the building intersects two areas. The source sends the source identifier to the producer to insert the building into the terrain.

After a certain amount of time, Vortex Dynamics uses the source identifier to cache out the building from the simulation once all active objects have cleared both of these areas.

Sample Paged Terrain Data Flow

As can be seen from the data flow, both the producer and source need to provide functions to query and provide data to each other. This is clear in the class diagram.

Paged Terrain Producer Class Diagram