Terrain Y-Testing

The Y-testing API allows you to locate the physical scenery mesh. This would be used to place dynamic graphics on top of the ground in a plausible way or do physics interactions.

The Y-test API works via probe objects, which are allocated by your plugin and used to query terrain. Probe objects exist both to capture which algorithm you have requested (see probe types) and also to cache query information.

Performance Guidelines

It is generally faster to use the same probe for nearby points and different probes for different points. Try not to allocate more than "hundreds" of probes at most. Share probes if you need more. Generally, probing operations are expensive, and should be avoided via caching when possible.

Y testing returns a location on the terrain, a normal vector, and a velocity vector. The normal vector tells you the slope of the terrain at that point. The velocity vector tells you if that terrain is moving (and is in meters/second). For example, if your Y test hits the aircraft carrier deck, this tells you the velocity of that point on the deck.

Note: the Y-testing API is limited to probing the loaded scenery area, which is approximately 300x300 km in X-Plane 9. Probes outside this area will return the height of a 0 MSL sphere.

XPLMProbeType

enum

XPLMProbeType defines the type of terrain probe - each probe has a different algorithm. (Only one type of probe is provided right now, but future APIs will expose more flexible or powerful or useful probes.

Name	Value	Description
xplm_ProbeY	0	The Y probe gives you the location of the tallest physical scenery along the Y axis going through the queried point.

XPLMProbeResult

enum

Probe results - possible results from a probe query.

Name	Value	Description
xplm_ProbeHitTerrain	0	The probe hit terrain and returned valid values.
xplm_ProbeError	1	An error in the API call. Either the probe struct size is bad, the probe is invalid, or the type is mismatched for the specific query call.
xplm_ProbeMissed	2	The probe call succeeded but there is no terrain under this point (perhaps it is off the side of the planet?)

XPLMProbeRef

typedef

An XPLMProbeRef is an opaque handle to a probe, used for querying the terrain.

typedef void * XPLMProbeRef;

XPLMProbeInfo_t

struct

XPLMProbeInfo_t contains the results of a probe call. Make sure to set structSize to the size of the struct before using it.

typedef struct {
     int                       structSize;
     float                     locationX;
     float                     locationY;
     float                     locationZ;
     float                     normalX;
     float                     normalY;
     float                     normalZ;
     float                     velocityX;
     float                     velocityY;
     float                     velocityZ;
     bool                      is_wet;
} XPLMProbeInfo_t;

XPLMCreateProbe

function

Creates a new probe object of a given type and returns.

XPLM_API XPLMProbeRefXPLMCreateProbe(
                         XPLMProbeType        inProbeType
                    );

XPLMDestroyProbe

function

Deallocates an existing probe object.

XPLM_API void       XPLMDestroyProbe(
                         XPLMProbeRef         inProbe
                    );

XPLMProbeTerrainXYZ

function

Probes the terrain. Pass in the XYZ coordinate of the probe point, a probe object, and an XPLMProbeInfo_t struct that has its structSize member set properly. Other fields are filled in if we hit terrain, and a probe result is returned.

XPLM_API XPLMProbeResultXPLMProbeTerrainXYZ(
                         XPLMProbeRef         inProbe,
                         float                inX,
                         float                inY,
                         float                inZ,
                         XPLMProbeInfo_t *    outInfo
                    );