#ifndef _XPLMScenery_h_
#define _XPLMScenery_h_

/*
 * Copyright 2005-2012 Sandy Barbour and Ben Supnik
 *
 * All rights reserved.  See license.txt for usage.
 *
 * X-Plane SDK Version: 2.1.1
 *
 */

/*
 * 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 vectory, 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 poewrful or useful probes.
 *
 */
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


};
typedef int XPLMProbeType;

/*
 * XPLMProbeResult
 *
 * Probe results - possible results from a probe query.
 *
 */
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, or 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


};
typedef int 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 */
/***************************************************************************
 * 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
 * loaded 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(XPLM200)
/*
 * XPLMDrawObjects
 *
 * 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 /* XPLM200 */

#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