Tutorial: Use SimIn SDK to Query Vectors

[theisomizer]

Hi,

Here is a tutorial on querying for vector Data in the simulator using the SimIn API. Vector data includes roads, bodies of water, powerlines, and other linear features that are blended on top of the terrain data. The raw data returned from SimIn could be used for many purposes, such as a moving map or display. This is a continuation of the SimIn tutorial started here: https://www.fsdeveloper.com/forum/threads/use-simin-sdk-to-query-facilities.444018/

Step 1.

Setup your project according to the steps in the above facilities tutorial, up to Step 4. Once you have your .cpp file setup with headers the module initialization, you are ready to add the code to query for vector data.

In addition, you will want to setup a variable for the terrain service like the facilities:

ITerrainServiceV1 *terrain;
// and in module_init
sdk->GetService(SERVICE_ITerrainServiceV1, reinterpret_cast<void**>(&terrain));

Step 2.

You will add code to the DebugCallback (called every frame) to query for vector data using the terrain service. Note that this is an asynchronous service, so although you will request data every frame, you will only receive data in the callbacks once the sim has loaded everything.

First you will create a VectorDBRequest struct. Note that as per the documentation, this struct is shared across several different requests types, each having unique parameter requirements. Here we will use a UserLocation request type, which in this case will query a grid of QMID11 cells around the User simobject within a 4.0km radius.

auto request =  VectorDBRequest
{
    REQUESTTYPE_USERLOCATION,
    ZOOMLEVEL11,
    4.0
}

Note that almost all vector features are clipped to QMID level 11, however, freeway traffic paths are clipped to level 15. If you need these features, you will need to make two separate requests. For more information, see the Prepar3d SDK.

Next, you will issue a terrain service request with a pointer to your VectorDBRequest struct and a callback function that will asynchronously receive the results when the query is complete:

terrain ->QueryVectorAsync(&request, &vectorLoadedCallback);

Step 3.

Define a callback function called vectorLoadedCallback, which has the following prototype:

HRESULT SIMINAPI vectorLoadedCallback (VectorDBData* dataraw)

This function will be called asynchronously when the data is loaded, dataraw->Data will be NULL if failed, else it will contain the data to be read.

The results of the request, stored in dataraw->Data, are a 2D grid of cells, one per QMID in the request. QMIDs increase linearly from top to bottom and left to right. Each QMID contains a 1D array of *VectorShape, these shapes each contain a single vector feature. Therefore, to iterate over all of the results returned, you will need a nested for loop, iterating over each VectorShape inside each cell in the 2D grid. Note that in QMIDs, the Y dimension refers to the rows, while the X dimension refers to the columns.

Step 4.

Now it is time to fire up your debugger! Set breakpoints first inside your DebugCallback and in your vectorLoadedCallback. Notice how immediately after load DebugCallback is called and the request is made, but that the DebugCallback finishes executing, and may even execute again, before the data is loaded and vectorLoadedCallback is called.

Step 5.

When the vectorLoadedCallback is called, inspect the values of what is returned to see how the data is structured. You will note that each VectorDBShape contains all of the fields you would expect on a vector shape that is needed to draw it, including an array of the lat/lon points (with altitudes if present). You also have access to attribute information like types, textures, etc.

For more information on everything related to vector shapes in the simulator, including all of the fields that SimIn has access to read, see the documentation in the P3D SDK on shp2vec here: http://www.prepar3d.com/SDKv4/sdk/world/terrain/terrain_overview.html#The Shp2Vec Tool

If anybody needs static libs for compilation, or custom development for a commercial license, feel free to contact us.

Happy developing!