#ifndef _XPLMScenery_h_
#define _XPLMScenery_h_

/***************************************************************************
 * XPLMScenery
 ***************************************************************************/
/*
 * This package contains APIs to interact with X-Plane's scenery system.
 *
 */

#include "XPLMDefs.h"

#ifdef __cplusplus
extern "C" {
#endif

#if defined(XPLM200)
/***************************************************************************
 * 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.
 *
 */
XPLM_MAYBE_TYPEDEF enum XPLM_ENUM {
    /* The Y probe gives you the location of the tallest physical scenery along
     * * the Y axis going through the queried point. */
    xplm_ProbeY = 0,

} XPLM_ENUM_NAME(XPLMProbeType);
XPLM_ENUM_C(XPLMProbeType)

/*
 * XPLMProbeResult
 *
 * Probe results - possible results from a probe query.
 *
 */

XPLM_MAYBE_TYPEDEF enum XPLM_ENUM {
    /* The probe hit terrain and returned valid values. */
    xplm_ProbeHitTerrain = 0,

    /* 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_ProbeError = 1,

    /* The probe call succeeded but there is no terrain under this point
     * (perhaps * it is off the side of the planet?) */
    xplm_ProbeMissed = 2,

} XPLM_ENUM_NAME(XPLMProbeResult);
XPLM_ENUM_C(XPLMProbeResult)

/*
 * XPLMProbeRef
 *
 * An XPLMProbeRef is an opaque handle to a probe, used for querying the
 * terrain.
 *
 */
typedef void* XPLMProbeRef;

/*
 * 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
 *
 * Creates a new probe object of a given type and returns.
 *
 */
XPLM_API XPLMProbeRef XPLMCreateProbe(XPLMProbeType inProbeType);

/*
 * XPLMDestroyProbe
 *
 * Deallocates an existing probe object.
 *
 */
XPLM_API void XPLMDestroyProbe(XPLMProbeRef inProbe);

/*
 * XPLMProbeTerrainXYZ
 *
 * 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 XPLMProbeResult XPLMProbeTerrainXYZ(XPLMProbeRef inProbe, float inX,
                                             float inY, float inZ,
                                             XPLMProbeInfo_t* outInfo);

#endif /* XPLM200 */
#if defined(XPLM300)
/***************************************************************************
 * 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
 *
 * Returns X-Plane's simulated magnetic variation (declination) at the
 * indication latitude and longitude.
 *
 */
XPLM_API float XPLMGetMagneticVariation(double latitude, double longitude);

/*
 * XPLMDegTrueToDegMagnetic
 *
 * Converts a heading in degrees relative to true north into a value relative
 * to magnetic north at the user's current location.
 *
 */
XPLM_API float XPLMDegTrueToDegMagnetic(float headingDegreesTrue);

/*
 * XPLMDegMagneticToDegTrue
 *
 * Converts a heading in degrees relative to magnetic north at the user's
 * current location into a value relative to true north.
 *
 */
XPLM_API float XPLMDegMagneticToDegTrue(float headingDegreesMagnetic);

#endif /* XPLM300 */
/***************************************************************************
 * 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!
 *
 */

#if defined(XPLM200)
/*
 * XPLMObjectRef
 *
 * An XPLMObjectRef is a opaque handle to an .obj file that has been loaded
 * into memory.
 *
 */
typedef void* XPLMObjectRef;
#endif /* XPLM200 */

#if defined(XPLM200)
/*
 * 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;
#endif /* XPLM200 */

#if defined(XPLM210)
/*
 * XPLMObjectLoaded_f
 *
 * 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.
 *
 */
typedef void (*XPLMObjectLoaded_f)(XPLMObjectRef inObject, void* inRefcon);
#endif /* XPLM210 */

#if defined(XPLM200)
/*
 * XPLMLoadObject
 *
 * 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.
 *
 */
XPLM_API XPLMObjectRef XPLMLoadObject(const char* inPath);
#endif /* XPLM200 */

#if defined(XPLM210)
/*
 * XPLMLoadObjectAsync
 *
 * 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.
 *
 */
XPLM_API void XPLMLoadObjectAsync(const char* inPath,
                                  XPLMObjectLoaded_f inCallback,
                                  void* inRefcon);
#endif /* XPLM210 */

#if defined(XPLM_DEPRECATED)
/*
 * XPLMDrawObjects
 *
 * __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.
 *
 */
XPLM_API void XPLMDrawObjects(XPLMObjectRef inObject, int inCount,
                              XPLMDrawInfo_t* inLocations, int lighting,
                              int earth_relative);
#endif /* XPLM_DEPRECATED */

#if defined(XPLM200)
/*
 * XPLMUnloadObject
 *
 * 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.
 *
 */
XPLM_API void XPLMUnloadObject(XPLMObjectRef inObject);
#endif /* XPLM200 */

#if defined(XPLM200)
/***************************************************************************
 * 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
 *
 * 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.
 *
 */
typedef void (*XPLMLibraryEnumerator_f)(const char* inFilePath, void* inRef);

/*
 * XPLMLookupObjects
 *
 * 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.
 *
 */
XPLM_API int XPLMLookupObjects(const char* inPath, float inLatitude,
                               float inLongitude,
                               XPLMLibraryEnumerator_f enumerator, void* ref);

#endif /* XPLM200 */
#ifdef __cplusplus
}
#endif

#endif