XPLMScenery API

This package contains APIs to interact with X-Plane’s scenery system.

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

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

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 void * XPLMProbeRef;

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

XPLMProbeInfo_t

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 {
     // Size of structure in bytes - always set this before calling the XPLM.
     int                       structSize;
     // Resulting X location of the terrain point we hit, in local OpenGL coordinates.
     float                     locationX;
     // Resulting Y location of the terrain point we hit, in local OpenGL coordinates.
     float                     locationY;
     // Resulting Z location of the terrain point we hit, in local OpenGL coordinates.
     float                     locationZ;
     // X component of the normal vector to the terrain we found.
     float                     normalX;
     // Y component of the normal vector to the terrain we found.
     float                     normalY;
     // Z component of the normal vector to the terrain we found.
     float                     normalZ;
     // X component of the velocity vector of the terrain we found.
     float                     velocityX;
     // Y component of the velocity vector of the terrain we found.
     float                     velocityY;
     // Z component of the velocity vector of the terrain we found.
     float                     velocityZ;
     // Tells if the surface we hit is water (otherwise it is land).
     int                       is_wet;
} XPLMProbeInfo_t;

XPLMCreateProbe

XPLM_API XPLMProbeRef XPLMCreateProbe(
                         XPLMProbeType        inProbeType);

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

XPLMDestroyProbe

XPLM_API void       XPLMDestroyProbe(
                         XPLMProbeRef         inProbe);

Deallocates an existing probe object.

XPLMProbeTerrainXYZ

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

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.

Magnetic Variation

Use the magnetic variation (more properly, the “magnetic declination”) API to find the offset of magnetic north from true north at a given latitude and longitude within the simulator.

In the real world, the Earth’s magnetic field is irregular, such that true north (the direction along a meridian toward the north pole) does not necessarily match what a magnetic compass shows as north.

Using this API ensures that you present the same offsets to users as X-Plane’s built-in instruments.

XPLMGetMagneticVariation

XPLM_API float      XPLMGetMagneticVariation(
                         double               latitude,
                         double               longitude);

Returns X-Plane’s simulated magnetic variation (declination) at the indication latitude and longitude.

XPLMDegTrueToDegMagnetic

XPLM_API float      XPLMDegTrueToDegMagnetic(
                         float                headingDegreesTrue);

Converts a heading in degrees relative to true north into a value relative to magnetic north at the user’s current location.

XPLMDegMagneticToDegTrue

XPLM_API float      XPLMDegMagneticToDegTrue(
                         float                headingDegreesMagnetic);

Converts a heading in degrees relative to magnetic north at the user’s current location into a value relative to true north.

Object Drawing

The object drawing routines let you load and draw X-Plane OBJ files. Objects are loaded by file path and managed via an opaque handle. X-Plane naturally reference counts objects, so it is important that you balance every successful call to XPLMLoadObject with a call to XPLMUnloadObject!

XPLMObjectRef

typedef void * XPLMObjectRef;

An XPLMObjectRef is a opaque handle to an .obj file that has been loaded into memory.

XPLMDrawInfo_t

The XPLMDrawInfo_t structure contains positioning info for one object that is to be drawn. Be sure to set structSize to the size of the structure for future expansion.

typedef struct {
     // Set this to the size of this structure!
     int                       structSize;
     // X location of the object in local coordinates.
     float                     x;
     // Y location of the object in local coordinates.
     float                     y;
     // Z location of the object in local coordinates.
     float                     z;
     // Pitch in degres to rotate the object, positive is up.
     float                     pitch;
     // Heading in local coordinates to rotate the object, clockwise.
     float                     heading;
     // Roll to rotate the object.
     float                     roll;
} XPLMDrawInfo_t;

XPLMObjectLoaded_f

typedef void (* XPLMObjectLoaded_f)(
                         XPLMObjectRef        inObject,
                         void *               inRefcon);

You provide this callback when loading an object asynchronously; it will be called once the object is loaded. Your refcon is passed back. The object ref passed in is the newly loaded object (ready for use) or NULL if an error occured.

If your plugin is disabled, this callback will be delivered as soon as the plugin is re-enabled. If your plugin is unloaded before this callback is ever called, the SDK will release the object handle for you.

XPLMLoadObject

XPLM_API XPLMObjectRef XPLMLoadObject(
                         const char *         inPath);

This routine loads an OBJ file and returns a handle to it. If X-Plane has already loaded the object, the handle to the existing object is returned. Do not assume you will get the same handle back twice, but do make sure to call unload once for every load to avoid “leaking” objects. The object will be purged from memory when no plugins and no scenery are using it.

The path for the object must be relative to the X-System base folder. If the path is in the root of the X-System folder you may need to prepend ./ to it; loading objects in the root of the X-System folder is STRONGLY discouraged - your plugin should not dump art resources in the root folder!

XPLMLoadObject will return NULL if the object cannot be loaded (either because it is not found or the file is misformatted). This routine will load any object that can be used in the X-Plane scenery system.

It is important that the datarefs an object uses for animation already be registered before you load the object. For this reason it may be necessary to defer object loading until the sim has fully started.

XPLMLoadObjectAsync

XPLM_API void       XPLMLoadObjectAsync(
                         const char *         inPath,
                         XPLMObjectLoaded_f   inCallback,
                         void *               inRefcon);

This routine loads an object asynchronously; control is returned to you immediately while X-Plane loads the object. The sim will not stop flying while the object loads. For large objects, it may be several seconds before the load finishes.

You provide a callback function that is called once the load has completed. Note that if the object cannot be loaded, you will not find out until the callback function is called with a NULL object handle.

There is no way to cancel an asynchronous object load; you must wait for the load to complete and then release the object if it is no longer desired.

XPLMDrawObjects

XPLM_API void       XPLMDrawObjects(
                         XPLMObjectRef        inObject,
                         int                  inCount,
                         XPLMDrawInfo_t *     inLocations,
                         int                  lighting,
                         int                  earth_relative);

Deprecation Warning: use XPLMInstancing to draw 3-d objects by creating instances, rather than these APIs from draw callbacks.

XPLMDrawObjects draws an object from an OBJ file one or more times. You pass in the object and an array of XPLMDrawInfo_t structs, one for each place you would like the object to be drawn.

X-Plane will attempt to cull the objects based on LOD and visibility, and will pick the appropriate LOD.

Lighting is a boolean; pass 1 to show the night version of object with night-only lights lit up. Pass 0 to show the daytime version of the object.

earth_relative controls the coordinate system. If this is 1, the rotations you specify are applied to the object after its coordinate system is transformed from local to earth-relative coordinates – that is, an object with no rotations will point toward true north and the Y axis will be up against gravity. If this is 0, the object is drawn with your rotations from local coordanates – that is, an object with no rotations is drawn pointing down the -Z axis and the Y axis of the object matches the local coordinate Y axis.

XPLMUnloadObject

XPLM_API void       XPLMUnloadObject(
                         XPLMObjectRef        inObject);

This routine marks an object as no longer being used by your plugin. Objects are reference counted: once no plugins are using an object, it is purged from memory. Make sure to call XPLMUnloadObject once for each successful call to XPLMLoadObject.

Library Access

The library access routines allow you to locate scenery objects via the X-Plane library system. Right now library access is only provided for objects, allowing plugin-drawn objects to be extended using the library system.

XPLMLibraryEnumerator_f

typedef void (* XPLMLibraryEnumerator_f)(
                         const char *         inFilePath,
                         void *               inRef);

An XPLMLibraryEnumerator_f is a callback you provide that is called once for each library element that is located. The returned paths will be relative to the X-System folder.

XPLMLookupObjects

XPLM_API int        XPLMLookupObjects(
                         const char *         inPath,
                         float                inLatitude,
                         float                inLongitude,
                         XPLMLibraryEnumerator_f enumerator,
                         void *               ref);

This routine looks up a virtual path in the library system and returns all matching elements. You provide a callback - one virtual path may match many objects in the library. XPLMLookupObjects returns the number of objects found.

The latitude and longitude parameters specify the location the object will be used. The library system allows for scenery packages to only provide objects to certain local locations. Only objects that are allowed at the latitude/longitude you provide will be returned.