Blue Marble Geographics logo
Welcome
Log in Cart icon
Image of mountains with geospatial contour overlay
Global Mapper SDK Reference

Global Mapper Software Development Kit (SDK) Reference

Contents


General Overview

The Global Mapper SDK allows the use of Global Mapper loading, rendering, and export technology within your own applications. Using the SDK you can perform a vast array of functions, a few of which include:

  • Load any number of layers from almost all of the formats supported by Global Mapper. This includes nearly all imagery, elevation, and vector data formats.
  • Draw loaded layers to your own device context, allowing Global Mapper-style rendering in your own application. You can draw any specified portion of the loaded data.
  • Retrieve the color at any location from loaded raster and elevation layers.
  • Retrieve the elevation at any location from loaded elevation layers.
  • Get information about loaded layers, including projection/datum, bounding rectangle, description, ground control points, pixel size, etc.
  • Retrieve detailed information about every feature in a vector layer, including coordinate and attribute data.
  • Reproject loaded data to a user-specified projection/datum.
  • Load imagery that has not been georeferenced by providing ground control points and projection, the DLL will perform the rectification.
  • Auto-clip the collar off of USGS DRGs.
  • Export loaded layers to many of the export formats supported by Global Mapper, such as GeoTIFF and JPG.
  • Export a user-supplied bitmap to a GeoTIFF or JPG file.
  • Re-project coordinates from one projection/datum to another projection/datum.
  • Generate contour lines from gridded elevation data.
  • Perform a view shed analysis from gridded elevation data.

Lidar Module Functionality (Lidar SDK)

Some functionality from the Lidar Module in the Global Mapper application is also available in the SDK, including automatic classification of ground, building, and vegetation points and automatic extraction of building outlines and tree points/polygons. See http://www.bluemarblegeo.com/products/global-mapper-lidar.php for more information on everything in the Lidar module, noting that the visual components of the Lidar module (i.e. path profile and Lidar toolbar) are not available in the SDK. Use of any supported Lidar module functionality requires an updated license for the SDK to be enabled. Please contact sales@bluemarblegeo.com if you would like to use these functions from the SDK.


Global Mapper Extensions

The Global Mapper SDK allows you to add your own functionality directly to Global Mapper by creating an extension DLL. Global Mapper takes care of loading and displaying the data. The extension only needs to implement the custom functionality. Global Mapper extensions can perform all of the functions listed above for applications, in addition to the following:

  • Add a toolbar used to invoke the custom functionality to the Global Mapper user interface.
  • Add menu items to the Digitizer context menu.
  • Access the layers and features that are currently open in Global Mapper.
  • Access a list of the features that are currently selected in the Global Mapper view.
  • Request that Global Mapper refresh the view.

Global Mapper Extension Developers Guide

Creating a Global Mapper extension requires the following tasks:

Extension DLL Requirements

Global Mapper Extension DLLs have the following requirements:

  • The DLL must have a file extension of ".gmx" instead of ".dll".
  • The DLL must implement a proxy class. The proxy class provides the "plug-in" interface for an extension DLL, and is derived from GM_ExtensionProxy.
  • The DLL must implement an extension class. The extension class performs the custom functionality, and must be derived from GM_Extension.
  • The extension DLL must have a single exported function:
    GM_ExtensionProxy* GetExtensionProxy(void)

Once you have installed the SDK, you will find two extension samples. The folder sample_tb_extension contains an extension that is primarily intended to illustrate the basics of how to implement an extension that uses both a toolbar and menus. Folder sample_tb_extension_mfc has a sample that illustrates more of the functionality such as:

  1. loading layers
  2. accessing layers that are already loaded
  3. adding menu items to the Digitizer menu
  4. working with selected features
  5. handling stock Global Mapper events
  6. etc.

The Proxy Class

The proxy class, GM_ExtensionProxy, provides the "plug-in" interface for an extension DLL. The proxy class is an abstract class, so a developer will have to create a proxy class that is derived from GM_ExtensionProxy. The extension DLL will have an entry point, called GetExtensionProxy, that returns a pointer to the proxy object.

struct GM_ExtensionProxy
{
	virtual const char* GetName(void) = 0;
	virtual const char* GetLicenseString(void) = 0;
	virtual GM_Extension* CreateExtension(void) = 0;
	virtual void Release() = 0;
};

The GM_ExtensionProxy class contains the following pure virtual methods that must be overridden when implementing a Global Mapper Extension:

  • The GetName method returns a name that identifies the extension. This name will identify the extension in cases where the extension cannot be loaded or licensed for some reason.
  • The GetLicenseString function returns the SDK license string required for the extension. This license string verifies that the DLL is a valid extension. Global Mapper will validate the returned license string when it attempts to load the extension. If the license string is not valid, the extension will not be loaded. If an extension requires a user license of some sort, then it is up to the developer to implement functionality to validate the existance of that license.
  • The CreateExtension method allocates an instance of the extension class and returns a pointer to it. When the user clicks a button on the extension's toolbar, Global Mapper will call methods on this class to perform the requested function. Global Mapper will take ownership of this pointer, and delete it when it is no longer needed.
  • The Release method frees the proxy object.

The Extension Class

The extension class, GM_Extension, performs the work of the extension. GM_Extension is an abstract class, so developers will have to use a class derived from GM_Extension to implement their extension functionality. The GM_ExtensionProxy::CreateExtension() function returns an instance of this class.

struct GM_Extension
{
	virtual const char* GetDisplayName(void) const = 0;
	virtual const char* GetDescription(void) const = 0;
	virtual const char* GetButtonTooltipText(UINT aButtonIndex) const = 0;
	virtual void HandleCustomEvent(UINT aEventID, HWND aParentWindow) = 0;
	virtual void HandleGMEvent(GM_Event_t aEvent, void* aEventData,	HWND aParentWindow) = 0;
	virtual GM_ExtensionToolbarDef_t* GetToolbarDefinition() const = 0;
	virtual GM_ExtensionMenuDef_t* GetMenuDefinition(const GM_ExtensionMenuCriteria_t& aCriteria) const = 0;
	virtual void Release() = 0;
}

The GM_Extension class contains the following pure virtual methods that must be overridden when implementing a Global Mapper Extension:

  • The GetDisplayName method returns the name that will be included in the Extension Manager's list of registered extensions.
  • The GetDescription method returns text that will be displayed on the Extension Properties dialog. This is a good place to include version and copyright information.
  • The GetToolbarDefinition returns an object derived from GM_ExtensionToolbarDef_t that defines the extension toolbar.
  • The GetMenuDefinition method returns an object derived from GM_ExtensionMenuDef_t that defines menu items to be added to the Digitizer context menu. The aCriteria parameter provides information about what types of objects are currently selected in the Global Mapper user interface. This allows the extension to implement menu items that designed to operate in a specific context with respect to selected feature geometry (areas, lines, etc.) If the extension does not add menu items to the Digitizer menu, this method should return NULL.
  • The GetButtonTooltipText method returns the text that will be used as a tooltip for the specified button. The aButtonIndex parameter contains the index of the button for which the tooltip will be displayed. If you are not using tooltips, this method should return a NULL pointer.
  • The HandleCustomEvent method will be called when the user clicks one of the buttons on the extension's toolbar. The aEventID parameter contains the index of the button clicked by the user. The aParentWindow argument contains the handle of the main Global Mapper window, which can be used as the parent window for dialogs, etc.
  • The HandleGMEvent method handles stock events generated by Global Mapper, such as notification that a new layer has been loaded or that the global projection has been changed. The aEvent parameter identifies the event being raised. The GM_Event_t enumeration is defined in GlobalMapperTypes.h. The aEventData parameter contains related data associated with the event. The comments for the enumeration members indicate the what event data is included with each event type. There are a couple of special cases that developers should be aware of:
    • When the event data is described as a Feature*, it will be passed to an extension as a GM_FoundFeature_t*.
    • When the event data is described as a GeographicOverlay*, it will be passed to an extension as a GM_LayerHandle_t32.
    In cases where no data is provided, this value will be NULL. The aParentWindow argument contains the handle of the main Global Mapper window, which can be used as the parent window for dialogs, etc.
  • The Release method frees the extension object.

The Extension Toolbar Definition

The GM_ExtensionToolbarDef_t structure defines the toolbar associated with a Global Mapper extension DLL. GM_ExtensionToolbarDef_t is an abstract definition, so developers will need to derive a class from GM_ExtensionToolbarDef_t in order to provide their toolbar definition.

struct GM_ExtensionToolbarDef_t
{
	// Data Accessors
	virtual UINT GetBitmapID(void) const = 0;
	virtual int  GetNumButtons(void) const = 0;
	virtual UINT GetButtonCommandID(int aIndex) = 0;
	virtual BOOL UsesTooltips(void) const = 0;
	virtual const char* GetTitle(void) const = 0;
	virtual void Release() = 0;
};

The GM_ExtensionToolbarDef_t structure includes the following pure virtual methods that must be implemented in your derived class:

  • GetBitmapID returns the resource ID for the toolbar button bitmap. Global Mapper will attempt to read the toolbar bitmap from the extension DLL resources using this ID. If the toolbar bitmap is not found in the extension DLL, toolbar initialization will fail and an error message will be displayed. In a Global Mapper extension, toolbar buttons are assumed be 19 pixels wide by 19 pixels high. If the actual bitmap resource defines buttons of a different size, the toolbar will still be displayed, but it will probably not look right.
  • GetNumButtons returns the number of buttons in the toolbar.
  • GetButtonCommandID returns the extension command ID for the specified button. The aIndex argument indicates which button ID to return. This is the value that will be passed back to the extension via the HandleCustomEvent method when the user clicks a toolbar button.
  • UsesTooltips indicates whether or not tooltips should be displayed when the user holds the mouse over a toolbar button.
  • GetTitle returns the title text to be displayed on the toolbar when it is not docked.
  • The Release method frees the toolbar definition object.

The Extension Menu Definition

The GM_ExtensionMenuDef_t structure defines the menu items to be displayed in the Digitizer menu. GM_ExtensionMenuDef_t is an abstract definition, so developers will need to derive a class from GM_ExtensionMenuDef_t in order to provide the menu definition.

struct GM_ExtensionMenuDef_t
{
	// Data Accessors
	virtual GM_MenuType_t GetMenuType(void) const = 0;
	virtual UINT GetNumMenuItems(void) const = 0;
	virtual const char* GetMenuItemText(UINT aIndex) const = 0;
	virtual UINT GetCommandID(UINT aIndex) const = 0;
	virtual void Release() = 0;
};

The GM_ExtensionMenuDef_t structure includes the following pure virtual methods that must be implemented in your derived class:

  • GetMenuType returns an enumeration that specifies which Global Mapper menu the menu items will be added to. Currently, menu items can only be added to the Digitizer context menu.
  • GetNumMenuItems returns the number of menu items contained in the definition.
  • GetMenuItemText returns the text for the specified menu item. The aIndex parameter indicates which menu item to retrieve.
  • GetCommandID returns the extension command ID for the specified menu item. The aIndex argument indicates which menu item ID to return. This is the value that will be passed back to the extension via the HandleCustomEvent method when the user clicks the menu item.
  • The Release method frees the menu definition object.

Extension Toolbar Button/Menu Options State (Disabling and Checking)

By default all toolbar buttons and menu items and enabled and unchecked. If you would like to have your command items (buttons and menu options) be disabled/checked at some times, you can do this by handling the GM_Event_GetExtensionCommandState event which passes a GM_ExtCommandState_t* to the extension. You can then set the enabled/disabled and checked/unchecked state flags for the requested command ID based on the current options that are set. Note that marking a toolbar button as checked means it is depressed. This event will only be sent by Global Mapper v16.2.4 and later. Previous versions do not support disabling or checking toolbar buttons or menu options.

The Extension DLL Entry Point

A Global Mapper Extension DLL must have one entry point:

GM_ExtensionProxy* GetExtensionProxy(void);

When attempting to load an extension, Global Mapper will verify that the extension DLL contains this entry point. If it is not there, then the load operation will fail. The following code snippet illustrates one way to implement the GetExtensionProxy function:

// TestProxy.h contains the extension proxy definition.
#include "TestProxy.h"

TestProxy theProxy;
extern "C" TestProxy* g_pProxy = &theProxy;

// This the exported function that returns the proxy instance
extern "C" __declspec(dllexport) GM_ExtensionProxy* GetExtensionProxy(void)
{
	return g_pProxy;
}

TestProxy is a class derived from GM_ExtensionProxy. Note that in this example, the instance of TestProxy (theProxy) is a static variable. Because of this, the implementation of TestProxy::Release() is empty, since the static object cannot be deleted.

Registering the Extension DLL

Before the extension can be used, it must be registered with Global Mapper. This can be accomplished in two ways:

  1. Using the Extension Manager in the Global Mapper UI
  2. In a script (e.g., an installer script) by starting Global Mapper and passing it the name of the extension DLL along with -regex parameter.

Similarly, before an extension gets removed from the computer, it must be unregistered. This can be accomplished in two ways:

  1. Using the Extension Manager in the Global Mapper UI
  2. In an uninstall script by starting Global Mapper and passing it the name of the extension DLL along with -unregex parameter.

PDF Support

The Global Mapper SDK provides support for importing and exporting geo-spatial PDF through the QuickPDF library from http://www.quickpdflibrary.com/. We cannot sub-license this library directly, so if you need PDF support you need to purchase a license for Quick PDF v11 and then provide your unlock key to the Global Mapper SDK via the GM_SetQuickPDFUnlockCode function before you try to import or export any PDF files. You will also need to provide the QuickPDFDLL.dll and QuickPDFRenderer.dll files from the 'bin' or 'bin64' folder with your application.


ECW/JPEG2000 Unlimited Compression Support

The SDK includes free unlimited import support for ECW and JPEG2000 files, but the 3rd-party library (from Intergraph) is limited to 500MB (uncompressed) per export. If you have obtained the appropriate license to export unlimited size, please contact us at geohelp@bluemarblegeo.com and we will provide instructions on how to enable this support in your SDK-based application.


GM_3DCloseViewWindow
GM_Error_t32 __stdcall GM_3DCloseViewWindow
    (
    void
    );

Closes the 3D view window if it is open.


GM_3DGetCameraPosition
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_3DGetCameraPosition
	(
	double* aX,         // OUT: X coordinate for camera in current view projection
	double* aY,	        // OUT: Y coordinate for camera in current view projection
	float*  aElev,		// OUT: Elevation in meters for camera
	double* aHeading,	// OUT: Heading in degrees from North (0)
	double* aPitch,		// OUT: Pitch in degrees (+ is up, - is down)
	double* aBank		// OUT: not currently used
	);

Retrieves the position of the camera in the current 3D view. You can set the camera position using the GM_3DPositionCamera function.


GM_3DIsWindowOpen
BOOL __stdcall GM_3DIsWindowOpen
    (
    void
    );

Returns TRUE if the 3D view window is open.


GM_3DPositionCamera
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_3DPositionCamera
	(
	double	aX,         // IN: X coordinate for camera in current view projection
	double	aY,         // IN: Y coordinate for camera in current view projection
	float	aElev,		// IN: Elevation in meters for camera
	double	aHeading,	// IN: Heading in degrees from North (0)
	double	aPitch,		// IN: Pitch in degrees (+ is up, - is down)
	double	aBank		// IN: not currently used
	);

Sets the position of the camera in the current 3D view. You can get the current camera position using the GM_3DGetCameraPosition function.


GM_3DSaveViewToFile
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_3DSaveViewToFile
	(
    const char*                 aFilename,  // IN: filename to save to
    GM_RasterExportFormat_t32   aFormat,    // IN: format to use (only BMP, JPG, and PNG supported)
    sint32                      aPixWidth,  // IN: pixel width to save (use 0 for current view size)
    sint32                      aPixHeight  // IN: pixel height to save (use 0 for current view size)
	);

Saves the current 3D view to an image file (BMP, JPG, or PNG). If you provide 0 for the pixel width or height parameters, the size of the current 3D view will be used.


GM_3DSetChangeViewCallback
void __stdcall GM_3DSetChangeViewCallback
    (
    GM_3DChangeViewCallbackFunc aCallbackFunc,
    void*                       aUserData
    );

Sets the callback function to be called when a button is pressed (either a pan or zoom button) in the 3D view that would typically result in a new set of data to be displayed in the 3D window.

Provide this callback if you want to keep your main view in sync with the 3D view, like in the Global Mapper application. If you do not provide a callback, the default behavior is to just update the data displayed in the 3D view independent of any other view.


GM_3DSetView
GM_Error_t32 __stdcall GM_3DSetView
    (
    GM_LayerHandle_t32*     aLayerList,     // IN: List of layers to drape on top of terrain or NULL for all
    uint32                  aLayerCount,    // IN: Number of layers in list (0 for all)
    GM_DrawFlags_t32        aDrawFlags,     // IN: Flags controlling how the draw is performed
    const GM_Rectangle_t*   aWorldBounds,   // IN: World bounds to convert from or NULL for last drawn
    const GM_PixelRect_t*   aPixelRect,     // IN: Pixel bounds to convert from or NULL for last drawn 
    uint32                  aReserved       // IN: Reserved (set to 0)
    );

Sets what to display in the currently open 3D view window. The 3D view window will be opened if necessary.


GM_AddAreaToVectorLayer
GM_DLL_EXPORTED GM_Error_t32 GM_AddAreaToVectorLayer
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer to add area to
    const GM_AreaFeature_t* aArea,              // IN: Area feature to add
    GM_AddFeatureFlags_t8   aFlags              // IN: Flags controlling the add
    );

Adds an area feature to a loaded vector layer or custom vector layer create with the GM_CreateCustomVectorLayer function.


GM_AddCustomAreaClass
GM_Error_t32 __stdcall GM_AddCustomAreaClass
    (
    const char*             aName,              // IN: Custom type name
    const GM_AreaStyle_t*   aStyle,             // IN: Default draw style for features of this type
    AreaFeatureClass_t16*   aFeatureCode        // OUT: Classification code for new type
    );

Adds a new custom area classification. If this function succeeds, the new feature classification code will be returned in the aFeatureCode value. This code can then be used as the feature classification for area features.


GM_AddCustomBrushStyle
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_AddCustomBrushStyle
    (
    const char*             aImageFilename,     // IN: Full path to image filename to use for custom fill pattern
    const char*             aStyleName,         // IN: Text name to use when referring to the fill style
    GM_BrushStyle_t16*      aStyleVal           // OUT: Value of created custom fill style
    );

Adds a custom brush style to use when drawing area features. The returned brush style value can be used as part of a GM_AreaStyle_t definition to specify to fill an area with a pattern based on the provided image file.

If a custom brush style exists with the provided aStyleName the aStyleVal will be set to the enumeration for that style and GM_Error_BrushAlreadyCreated will be returned.


GM_AddCustomDatum
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_AddCustomDatum
    (
    const GM_DatumInfo_t*   aDatumInfo,     // IN: Information about datum transformation to add
    DATUM*                  aDatumCode      // OUT: Datum code assigned to new custom datum
    )

Adds a new custom datum definition based on the provided GM_DatumInfo_t structure. The datum code assigned for the new datum is returned in aDatumCode. If a custom datum with the same name already exists, the parameters for that datum will be updated.

EXAMPLE 1: - Add custom Bursa-Wolfe datum (this is identical to Lisboa 1937 datum)
// Setup the custom datum information
GM_DatumInfo_t theDatumInfo;
::memset( &theDatumInfo, 0, sizeof theDatumInfo );
theDatumInfo.mMethod = GM_Datum_BursaWolfe;
theDatumInfo.mDatumName = "DLx"; 
theDatumInfo.mEllipsoidName = "International 1909 (Hayford/Intl 1924)"; // Name of ellipsoid this datum is based on
theDatumInfo.mDeltaX = -288.88;      
theDatumInfo.mDeltaY = -91.74;       
theDatumInfo.mDeltaZ = 126.24;       
theDatumInfo.mScale = -4.598E-6;     
theDatumInfo.mRotX = -1.6910;       // X rotation in arc seconds      
theDatumInfo.mRotY = 0.41;          // Y rotation in arc seconds
theDatumInfo.mRotZ = -0.211;        // Z rotation in arc seconds

// Add the datum
DATUM theDatumCode = GM_DATUM_UNKNOWN;
GM_Error_t32 theRetCode = GM_AddCustomDatum( &theDatumInfo, &theDatumCode );

GM_AddCustomEllipsoid
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_AddCustomEllipsoid
    (
    const char*             aEllipsoidName, // IN: Name of ellipsoid
    double                  aSemiMajor,     // IN: Semi-major axis in meters
    double                  aSemiMinor      // IN: Semi-minor axis in meters
    )

Adds a new custom ellispoid based on the provided parameters. If this succeeds, you can use the provided ellipsoid name in later calls to GM_AddCustomDatum to create a new custom datum.


GM_AddCustomLineClass
GM_Error_t32 __stdcall GM_AddCustomLineClass
    (
    const char*             aName,              // IN: Custom type name
    const GM_LineStyle_t*   aStyle,             // IN: Default draw style for features of this type
    LineFeatureClass_t16*   aFeatureCode        // OUT: Classification code for new type
    );

Adds a new custom line classification. If this function succeeds, the new feature classification code will be returned in the aFeatureCode value. This code can then be used as the feature classification for line features.


GM_AddCustomPointClass
GM_Error_t32 __stdcall GM_AddCustomPointClass
    (
    const char*             aName,              // IN: Custom type name
    const GM_PointStyle_t*  aStyle,             // IN: Default draw style for features of this type
    PointFeatureClass_t16*  aFeatureCode        // OUT: Classification code for new type
    );

Adds a new custom point classification. If this function succeeds, the new feature classification code will be returned in the aFeatureCode value. This code can then be used as the feature classification for point features.


GM_AddCustomShader
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_AddCustomShader
    (
    const GM_CustomShader_t*    aShader,    // in: shader to add
    uint32                      aReserved   // reserved, must be 0
    );

Adds a new custom shader for possible use for elevation layer display. Once the shader is added, you can use the GM_SetVerticalDisplayOptions function to make it the active shader for rendering elevation layers or the GM_SetElevationOverrides function to set it as the shader to use for rendering a particular layer.

If a custom shader with the name specified already exists, that shader will be updated. Otherwise a new custom shader with the specified name will be created.

If you would like to create a custom shader that shades the slopes of a terrain layer rather than the elevation value, provide the flag GM_CustomShader_ShadeSlopes as part of the GM_CustomShader_t structure.


GM_AddCustomSymbol
GM_Error_t32 GM_AddCustomSymbol
    (
    const char* aSymbolFilename,                // Full path to symbol file (BMP or ICO)
    const char* aSymbolName                     // Text name to use when referring to the symbol
    );

Adds a new custom symbol that can be used when drawing point features (see the GM_SetPointFeatureDrawStyle function).


GM_AddLineToVectorLayer
GM_DLL_EXPORTED GM_Error_t32 GM_AddLineToVectorLayer
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer to add line to
    const GM_LineFeature_t* aLine,              // IN: Line feature to add
    GM_AddFeatureFlags_t8   aFlags              // IN: Flags controlling the add
    );

Adds a line feature to a loaded vector layer or custom vector layer create with the GM_CreateCustomVectorLayer function.


GM_AddPointToVectorLayer
GM_DLL_EXPORTED GM_Error_t32 GM_AddPointToVectorLayer
    (
    GM_LayerHandle_t32			aLayer,         // IN: Layer to add point to
    const GM_PointFeature_t*	aPoint,         // IN: Point feature to add
    GM_AddFeatureFlags_t8       aFlags          // IN: Flags controlling the add
    );

Adds a point feature to a loaded vector layer or custom vector layer create with the GM_CreateCustomVectorLayer function.


GM_AreProjectionsEquivalent
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_AreProjectionsEquivalent
    (
    const GM_Projection_t*  aProj1,     // IN: First projection to check
    const GM_Projection_t*  aProj2,     // IN: Second projection to check
    boolean*                aEquivalent // OUT: Are they the same?
    )

Determines if 2 projections represent the same coordinate system. This is smart enough to treat projections like a particular UTM zone as equivalent to its base Transverse Mercator projection with the right parameters.


GM_CalcAreaElevStats
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_CalcAreaElevStats
    (
    GM_LayerHandle_t32*         aLayerList,     // IN: List of layers to use or NULL for all
    uint32                      aLayerCount,    // IN: Number of layers in list (0 for all)
    GM_AreaElevStats_t*         aElevStats,     // OUT: Calculated area statistics
    const GM_Point_t*           aAreaPoints,    // IN: List of points in area in global coordinate system
    uint32                      aNumPoints,     // IN: Number of points in aAreaPoints
    double                      aXSpacing,      // IN: Sample spacing in the x direction in global units (use 0.0 to get a good default)
    double                      aYSpacing,      // IN: Sample spacing in the y direction in global units (use 0.0 to get a good default)
    void*                       aReserved       // IN: Reserved for future use, must be NULL
    );

Calculates elevation statistics from loaded elevation data within a provided bounding polygon at a provided spacing.


GM_CalcBearing
GM_Error_t32 GM_CalcBearing
    (
    double  aFromX,     // IN: start X/longitude coordinate
    double  aFromY,     // IN: start Y/latitude coordinate
    double  aToX,       // IN: stop X/longitude coordinate
    double  aToY,       // IN: stop Y/latitude coordinate
    boolean aLatLon,    // IN: TRUE - coordinates are lat/lon, FALSE - coordinates are in the current projection?
    double* aBearing    // OUT: bearing in radians between the points
    );

Calculates the bearing in radians between two points. The points can either be specified as lat/lon values or in the current projection. The bearing retrieved is a cartographic bearing, with 0 being north, PI / 2 being east, PI being south, and 3 * PI / 2 being west.


GM_CalcDistance
GM_Error_t32 GM_CalcDistance
    (
    double  aFromX,     // IN: start X/longitude coordinate
    double  aFromY,     // IN: start Y/latitude coordinate
    double  aToX,       // IN: stop X/longitude coordinate
    double  aToY,       // IN: stop Y/latitude coordinate
    boolean aLatLon,    // IN: TRUE - coordinates are lat/lon, FALSE - coordaintes are in the current projection?
    double* aDist       // OUT: distance in meters between the points
    );

Calculates the great-circle distance in meters between two points. The points can either be specified as lat/lon values or in the current projection.


GM_CalcEnclosedArea
GM_Error_t32 __stdcall GM_CalcEnclosedArea
    (
    const GM_Point_t*       aPtList,    // IN: list of points defining area
    uint32                  aNumPoints, // IN: number of points in list
    const GM_Projection_t*  aProj,      // IN: projection of points in list (use NULL for current projection returned by GM_GetProjection)
    double*                 aArea       // OUT: enclosed area in square meters
    );

Calculates the enclosed area of a list of points. The coordinates in aPtList are in the projection defined by aProj. If NULL is passed for aProj then the current global projection as returned by GM_GetProjection is assumed.


GM_CalcProjectedLocation
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_CalcProjectedLocation
    (
    double  aFromX,     // IN: start X/longitude coordinate
    double  aFromY,     // IN: start Y/latitude coordinate
    double  aBearing,   // IN: bearing in degrees to project along (0 is north, 90 is east, 180 is south, 270 is west)
    double  aDist,      // IN: distance to project along bearing in meters
    double* aToX,       // OUT: stop X/longitude coordinate
    double* aToY,       // OUT: stop Y/latitude coordinate
    boolean aLatLon     // IN: TRUE - coordinates are lat/lon, FALSE - coordinates are in the current projection
    );

Calculates the location of a new point projected from a start point along a given bearing. The input and output points can either be specified as lat/lon values or in the current projection.


GM_CalcScaleRectangle
GM_Error_t32 GM_CalcScaleRectangle
    (
    const GM_Point_t*       aCenterPoint,   // IN: Center point in global coordinates
    double                  aScale,         // IN: Scale to calculate at (i.e. for 1:24K, pass 24000.0)
    HDC                     aDC,            // IN: Device context that will be drawn to
    sint32                  aPixWidth,      // IN: pixel width
    sint32                  aPixHeight,     // IN: pixel height
    GM_Rectangle_t*         aScaleRect      // OUT: rectangle at given scale
    );

Calculates the rectangle in global coordinates required to draw at the provided scale to the given device of the given size.


GM_CalcViewShed
GM_Error_t32 GM_CalcViewShed
    (
    GM_LayerHandle_t32          aLayer,         // IN: Layer to get elevations from or NULL for topmost layer at each point
    const GM_ViewShedParams_t*  aViewShedParms, // IN: Parameters for creating view shed
    GM_LayerHandle_t32*         aViewShedLayer  // OUT: Created view shed layer
    );

Performs a view-shed analysis on loaded elevation data and creates a new view shed layer with the results. The layer handle returned in aViewShedLayer must be closed with GM_CloseLayer when you are done with it.


GM_CalcVolumeAlongLine
GM_Error_t32 GM_CalcVolumeAlongLine
    (
    GM_LayerHandle_t32              aLayer,         // IN: Layer to get elevations from or NULL for topmost layer at each point
    const GM_LineVolumeParams_t*    aVolumeParms,   // IN: Parameters for line volume calculation
    double*                         aCutVolume,     // OUT: Cut volume in cubic meters
    double*                         aFillVolume     // OUT: Fill volume in cubic meters
    );

Calculates the cut-and-fill volumes along the given line relative to the cut heights for each vertex. The heights used between points will be interpolated between the heights at the start and end of each segment.


GM_CalcVolumeOfArea
GM_Error_t32 GM_CalcVolumeOfArea
    (
    GM_LayerHandle_t32              aLayer,         // IN: Layer to get elevations from or NULL for topmost layer at each point
    const GM_AreaVolumeParams_t*    aVolumeParms,   // IN: Parameters for area volume calculation
    double*                         aCutVolume,     // OUT: Cut volume in cubic meters
    double*                         aFillVolume     // OUT: Fill volume in cubic meters
    );

Calculates the cut-and-fill volumes with the given area relative to the cut height.


GM_CalcWorldRectSize
GM_Error_t32 GM_CalcWorldRectSize
    (
    const GM_Rectangle_t*   aWorldBounds,   // IN: World bounds to calc size of or NULL for last drawn
    double*                 aWidthMeters,   // OUT: Width of rectangle in meters
    double*                 aHeightMeters   // OUT: Height of rectangle in meters
    );

Calculates the width and height of a rectangle in the current projection. The rectangle can either be specified or the last drawn rectangle can be used.


GM_CloseLayer
GM_Error_t32 GM_CloseLayer
    ( 
    GM_LayerHandle_t32  aLayer
    );

The GM_CloseLayer function closes a previously opened layer.


GM_ClosePackage
GM_Error_t32 GM_ClosePackage
    ( 
    GM_PackageHandle_t32    aPackage
    );

Closes a previously opened package that was opened with the GM_LoadPackage function.


GM_CombineAreas
GM_Error_t32 __stdcall GM_CombineAreas
    (
    const GM_AreaFeature_t**    aAreaList,      // IN: List of areas to combine
    uint32                      aNumAreas,      // IN: Number of areas in aAreaList
    const GM_Projection_t*      aAreaProj,      // IN: Projection system the area coordinates are in (use NULL for current projection)
    GM_LayerHandle_t32          aNewAreaLayer   // IN: Layer to add new combined areas to
    )

Combines the given list of areas into one or more new area features and adds the new area to the given layer. Any areas that touch or overlap should be combined.

Here is an example showing how to combine all of the areas in a layer into a new layer:

// Build the list of areas to combine
GM_AreaFeature_t** theAreaList = new GM_AreaFeature_t*[ theLayerInfo->mNumAreas ];
uint32 i;
for ( i = 0; i < theLayerInfo->mNumAreas; i++ )
{
    // Get the area feature
    theAreaList[i] = GM_GetAreaFeature( aLayerHandle, i );
}

// Create a new layer and combine the areas into it
GM_LayerHandle_t32 theNewAreaLayer = GM_CreateCustomVectorLayer( "CombinedAreas", &theLayerInfo->mNativeProj );
theErr = GM_CombineAreas( (const GM_AreaFeature_t**)theAreaList, theLayerInfo->mNumAreas, &theLayerInfo->mNativeProj, theNewAreaLayer );

// Free the area features that we combined
for ( i = 0; i < theLayerInfo->mNumAreas; i++ )
{
    GM_FreeAreaFeature( theAreaList[i] );
}

// Free the area list
delete[] theAreaList;
theAreaList = NULL;

GM_CombineTerrainLayers
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_CombineTerrainLayers
    (
    const GM_GridCombineSetup_t*    aSetup,         // IN: Setup for operation
    GM_LayerHandle_t32*             aCombinedLayer, // OUT: Layer handle for newly created combined layer
    void*                           aReserved       // IN: Reserved for future use, must be NULL
    )

Combines two loaded terrain layers using some operation (i.e. addition, subtraction, etc.) and creates a new terrain layer from the combined return. The returned new layer must be closed with GM_CloseLayer when you are done working with it.


GM_ConvertCoordGroundToPixel
GM_Error_t32 GM_ConvertCoordGroundToPixel
    ( 
    double                  aGroundX,       // IN: X Coord in current projection
    double                  aGroundY,       // IN: Y Coord in current projection
    sint32*                 aPixelX,        // OUT: X Coord in pixel space
    sint32*                 aPixelY,        // OUT: Y Coord in pixel space
    const GM_Rectangle_t*   aWorldBounds,   // IN: World bounds to convert from or NULL for last drawn
    const GM_PixelRect_t*   aPixelRect      // IN: Pixel bounds to convert from or NULL for last drawn 
    );

The GM_ConvertCoordGroundToPixel function converts a coordinate between the current projection and pixel space. The conversion space can be either the last drawn coordinate space or the caller can provide the coordinate space to work in.


GM_ConvertCoordGroundToPixelWithOrientation
GM_Error_t32 __stdcall GM_ConvertCoordGroundToPixelWithOrientation
    ( 
    double                  aGroundX,       // IN: X Coord in current projection
    double                  aGroundY,       // IN: Y Coord in current projection
    sint32*                 aPixelX,        // OUT: X Coord in pixel space
    sint32*                 aPixelY,        // OUT: Y Coord in pixel space
    const GM_Rectangle_t*   aWorldBounds,   // IN: World bounds to convert from or NULL for last drawn
    const GM_PixelRect_t*   aPixelRect,     // IN: Pixel bounds to convert from or NULL for last drawn 
    double                  aOrientation    // IN Orientation of coordinate space to use (0 is north up, 90 is east up, 180 is south up, 270 is west up)
    )

Convert a coordinate between the current projection and a pixel coordinate. The conversion space can be either the last drawn coordinate space or the caller can provide the coordinate space to work in. You also supply an orientation angle to perform the conversion with.

The only time that you should need to call this function is if you want to do a coordinate conversion in a different orientation than what has been set globally with GM_SetOrientation.


GM_ConvertCoordLayerGroundToPixel
GM_Error_t32 __stdcall GM_ConvertCoordLayerGroundToPixel
    ( 
    GM_LayerHandle_t32      aLayer,         // IN: raster layer to do conversion in
    double                  aGroundX,       // IN: X Coord in current projection
    double                  aGroundY,       // IN: Y Coord in current projection
    double*                 aPixelX,        // OUT: X Coord in layer pixel space
    double*                 aPixelY         // OUT: Y Coord in layer pixel space
    )

Convert a coordinate between the current projection and layer pixel space and the current. The input layer must be a raster or gridded elevation layer (i.e. a layer where a pixel coordinate makes sense).


GM_ConvertCoordLayerPixelToGround
GM_Error_t32 __stdcall GM_ConvertCoordLayerPixelToGround
    ( 
    GM_LayerHandle_t32      aLayer,         // IN: raster layer to do conversion in
    double                  aPixelX,        // IN: X Coord in layer pixel space
    double                  aPixelY,        // IN: Y Coord in layer pixel space
    double*                 aGroundX,       // OUT: X Coord in current projection
    double*                 aGroundY        // OUT: Y Coord in current projection
    )

Convert a coordinate between layer pixel space and the current projection. The input layer must be a raster or gridded elevation layer (i.e. a layer where a pixel coordinate makes sense).


GM_ConvertCoordPixelToGround
GM_Error_t32 GM_ConvertCoordPixelToGround
    ( 
    sint32                  aPixelX,        // IN: X Coord in pixel space
    sint32                  aPixelY,        // IN: Y Coord in pixel space
    double*                 aGroundX,       // OUT: X Coord in current projection
    double*                 aGroundY,       // OUT: Y Coord in current projection
    const GM_Rectangle_t*   aWorldBounds,   // IN: World bounds to convert from or NULL for last drawn
    const GM_PixelRect_t*   aPixelRect      // IN: Pixel bounds to convert from or NULL for last drawn 
    );

The GM_ConvertCoordPixelToGround function converts a coordinate between pixel space and the current projection. The conversion space can be either the last drawn coordinate space or the caller can provide the coordinate space to work in.


GM_ConvertCoordPixelToGroundWithOrientation
GM_Error_t32 __stdcall GM_ConvertCoordPixelToGroundWithOrientation
    ( 
    sint32                  aPixelX,        // IN: X Coord in pixel space
    sint32                  aPixelY,        // IN: Y Coord in pixel space
    double*                 aGroundX,       // OUT: X Coord in current projection
    double*                 aGroundY,       // OUT: Y Coord in current projection
    const GM_Rectangle_t*   aWorldBounds,   // IN: World bounds to convert from or NULL for last drawn
    const GM_PixelRect_t*   aPixelRect,     // IN: Pixel bounds to convert from or NULL for last drawn 
    double                  aOrientation    // IN Orientation of coordinate space to use (0 is north up, 90 is east up, 180 is south up, 270 is west up)
    )

Convert a coordinate between pixel space and the current projection. The conversion space can be either the last drawn coordinate space or the caller can provide the coordinate space to work in. You also need to supply an orientation (rotation angle) at which to do the conversion.

The only time that you should need to call this function is if you want to do a coordinate conversion in a different orientation than what has been set globally with GM_SetOrientation.


GM_CreateBufferArea
GM_Error_t32 __stdcall GM_CreateBufferArea
    (
    GM_LayerHandle_t32      aFeatureLayer,      // IN: Layer the feature is in
    GM_FeatureClassType_t8  aFeatureClassType,  // IN: Type of feature class (area, point, line)
    uint32                  aFeatureIndex,      // IN: Index of feature in layer
    double                  aBufferDistance,    // IN: Distance in meters of buffer to create (use negative values to create a buffer inside an area feature)
    GM_LayerHandle_t32      aBufferLayer        // IN: Layer to add new buffer area(s) to
    );

Create a buffer area some distance around the specified feature. The parameters specify the existing feature (this can be a point, line, or area feature) that you want to create a buffer around as well as the buffer distance to use. If you want to create a buffer inside an area boundary, use a negative buffer distance.

The newly created buffer area(s) will be added to the layer <aBufferLayer>. You can use GM_CreateCustomVectorLayer if you want to add these to a new layer. The new buffer areas will be added to the end of the area list for <aBufferLayer>, so you can use the mNumAreas value in the GM_LayerInfo_t structure for that layer before and after the call to determine how many buffer areas were added and the indices used.


GM_CreateCustomElevGridLayer - (DEPRECATED)
GM_LayerHandle_t32 GM_CreateCustomElevGridLayer
    (
    const char*             aDescription,       // IN: Description to use for layer (can be NULL to use default)
    const GM_Projection_t*  aProj,              // IN: Native projection of new layer
    const GM_Point_t*       aTopLeft,           // IN: Ground coordinates of top left sample
    double                  aXSampleSize,       // IN: Size of each grid cell in the x direction
    double                  aYSampleSize,       // IN: Size of each grid cell in the y direction
    sint32                  aNumSamplesX,       // IN: Number of samples in the x direction
    sint32                  aNumSamplesY,       // IN: Number of samples in the y direction
    const void*             aElevGrid,          // IN: Grid of elevation values in row-major order
    GM_GridLayout_t8        aGridLayout,        // IN: Layout of elevation grid
    float                   aNoDataValue        // IN: Value of samples for which the value isn't known (i.e. -9999.9)
    );

Creates a new custom layer that represents an in-memory elevation grid. The handle to the newly created layer is returned. You must call GM_CloseLayer on the returned handle when you are done with it. If a problem occurs, NULL is returned for the layer handle.

The layer handle returned can be used just like any other layer handle. This means that you can do things like generate contours and calculate view sheds using the data.

This function is DEPRECATED. You should use the GM_CreateCustomElevGridLayerEx function instead.


GM_CreateCustomElevGridLayerEx
GM_DLL_EXPORTED GM_LayerHandle_t32 __stdcall GM_CreateCustomElevGridLayerEx
    (
    const char*             aDescription,       // IN: Description to use for layer (can be NULL to use default)
    const GM_Projection_t*  aProj,              // IN: Native projection of new layer
    const GM_GridLayout_t*  aGridLayout,        // IN: Grid layer layout and type
    const void*             aElevGrid,          // IN: Grid of elevation values in row-major order
    void*                   aReserved           // IN: Reserved for future use (must be NULL)
    )

Creates a new custom layer that represents an in-memory elevation grid. The handle to the newly created layer is returned. You must call GM_CloseLayer on the returned handle when you are done with it. If a problem occurs, NULL is returned for the layer handle.

The layer handle returned can be used just like any other layer handle. This means that you can do things like generate contours and calculate view sheds using the data.


GM_CreateCustomRasterLayer
GM_LayerHandle_t32 __stdcall GM_CreateCustomRasterLayer
    (
    const char*                 aDescription,       // IN: Description to use for layer (can be NULL to use default)
    const GM_Projection_t*      aProj,              // IN: Native projection of new layer
    const GM_RasterLayout_t*    aRasterLayout,      // IN: Raster layer layout
    const void*                 aDataBuf            // IN: Grid of raster data values in row-major order
    )

Creates a new custom layer that represents an in-memory raster. The handle to the newly created layer is returned. You must call GM_CloseLayer on the returned handle when you are done with it. If a problem occurs, NULL is returned for the layer handle.

The layer handle returned can be used just like any other layer handle.

EXAMPLE: - Create a Square 24-bit RGB Raster Layer
    // Setup raster layout
    const sint32 thePixWidth = 128;
    const sint32 thePixHeight = 128;
    GM_RasterLayout_t theLayout;
    memset( &theLayout, 0, sizeof theLayout );
    theLayout.mFlags = GM_RasterLayout_CopyData; // copy data buffer so we can free ours
    theLayout.mTopLeft.mX = -90.0;   // place it in the US somewhere
    theLayout.mTopLeft.mY = 35.0;
    theLayout.mXPixelSize = 1.0 / 3600.0;   // one arc second in size
    theLayout.mYPixelSize = 1.0 / 3600.0;   // one arc second in size
    theLayout.mPixelWidth = thePixWidth;
    theLayout.mPixelHeight = thePixHeight;
    theLayout.mNumBands = 3;
    theLayout.mBitsPerBand = 8;

    // Setup projection as lat/lon
    GM_Projection_t theGeoProj;
    memset( &theGeoProj, 0, sizeof theGeoProj );
    theGeoProj.mProjSys = GM_PRJ_GEO;
    theGeoProj.mDatum = GM_DATUM_WGS_84;
    theGeoProj.mUnit = GM_PRJ_UNIT_ARC_DEGREES;

    // Allocate color buffer
    uint8* theColorBuf = (uint8*)malloc( ( theLayout.mPixelWidth * theLayout.mPixelHeight * theLayout.mNumBands * theLayout.mBitsPerBand + 7 ) / 8 );
    if ( NULL == theColorBuf )
    {
        // Out of memory
        return;
    }

    // Fill in the color buffer. We'll just generate some basic colors
    uint8* theCurColorPos = theColorBuf;
    for ( sint32 i = 0; i < theLayout.mPixelHeight; i++ )
    {
        for ( sint32 j = 0; j < theLayout.mPixelWidth; j++ )
        {
            *theCurColorPos++ = i % 256; // set red
            *theCurColorPos++ = ( i + j ) % 256; // set green
            *theCurColorPos++ = j % 256; // set blue
        }
    }

    // Create custom raster layer
    GM_LayerHandle_t32 theRasterLayer = GM_CreateCustomRasterLayer
        (
        "My Custom Raster Layer", &theGeoProj, &theLayout, theColorBuf
        );

    // Free the color buffer
    free( theColorBuf );

GM_CreateCustomVectorLayer
GM_DLL_EXPORTED GM_LayerHandle_t32 GM_CreateCustomVectorLayer
    (
    const char*             aDescription,       // IN: Description to use for layer (can be NULL to use default)
    const GM_Projection_t*  aProj               // IN: Native projection of new layer
    );

Creates a new custom layer for adding vector features to. The handle to the newly created layer is returned. You must call GM_CloseLayer on the returned handle when you are done with it. If a problem occurs, NULL is returned for the layer handle. After creating the layer, use the GM_AddAreaToVectorLayer, GM_AddLineToVectorLayer, and GM_AddPointToVectorLayer functions to add features to the layer.


GM_CreateS63UserPermitFile
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_CreateS63UserPermitFile
    (
    const char* aFilename   // IN: Name of user permit file to create
    );

Creates a S-63 user permit file for use by clients to request encrypted S-63 chart files from data providers for loading with Global Mapper or your Global Mapper SDK-based application.


GM_CreateVectorLayerFromFindResults
GM_DLL_EXPORTED GM_LayerHandle_t32 __stdcall GM_CreateVectorLayerFromFindResults
    (
    const char*                     aDescription,   // IN: Description to use for layer (can be NULL to use default)
    const GM_Projection_t*          aProj,          // IN: Native projection of new layer
    const GM_FoundFeatureResults_t* aResultList     // OUT: Results of find operation (use GM_FreeFeatureResultList to free when done)
    )

Creates a new custom layer from a list of vector features returned from a find call, like GM_FindFeaturesInAreas. The handle to the newly created layer is returned. You must call GM_CloseLayer on the returned handle when you are done with it. If a problem occurs, NULL is returned for the layer handle.


GM_CropLayerCollar
GM_Error_t32 GM_CropLayerCollar
    (
    GM_LayerHandle_t32      aLayer,         // Layer to crop collar from
    boolean                 aCropCollar     // Crop the collar? (TRUE or FALSE)
    );

The GM_CropLayerCollar function allows users to enable and disable the automatic cropping of the collar off of previously loaded USGS DRG and DOQQ quads.

This function is deprecated. You should use the GM_GetRasterDisplayOptions and GM_SetRasterDisplayOptions functions as they offer the collar cropping option as well as several additional display options.


GM_DecodeMGRSCoordinates
GM_Error_t32 __stdcall GM_DecodeMGRSCoordinates
    (
    const char* aMgrsStr,   // IN: buffer with MGRS coordinate text
    double*     aX,         // OUT: point X/longitude coordinate
    double*     aY,         // OUT: point Y/latitude coordinate
    boolean     aLatLon     // IN: TRUE - return coordinates are lat/lon, FALSE - return coordinates are in the current projection
    )

Decodes a MGRS (military grid reference system) coordinate string into a X/Y or lat/lon location.


GM_DeleteFeature
GM_Error_t32 GM_DeleteFeature
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer the point is in
    GM_FeatureClassType_t8  aFeatureClassType,  // IN: Type of feature class (area, point, line)
    uint32                  aFeatureIndex,      // IN: Index of feature in layer
    boolean                 aDelete             // IN: Use TRUE to mark as deleted, FALSE to clear delete flag
    );

Changes the delete status of the area, line, or point feature at the given index in the layer. Note that "deleting" a feature doesn't actually free it or remove it from the list of features for a layer, it just marks it as deleted and makes it inactive for the purposes of drawing. To re-activate a feature that has been marked as deleted, simply call this with the aDelete value set to FALSE.


GM_DrawGridLines
GM_Error_t32 GM_DrawGridLines
    (
    HDC                     aDC,            // Device context to draw to
    boolean                 aLatLonGrid,    // Draw a lat/lon grid or a view projection grid
    double                  aGridSpacing,   // Grid spacing (use 0.0 for default)
    const GM_Rectangle_t*   aWorldBounds,   // World bounds to draw or NULL for all
    sint32                  aLeftPixel,     // Left pixel coordinate to draw to
    sint32                  aTopPixel,      // Top pixel coordinate to draw to
    sint32                  aPixelWidth,    // Width in pixels to draw
    sint32                  aPixelHeight    // Height in pixels to draw
    );

Draws grid lines (either lat/lon or in the view projection) for the specified location to the provided device context at the given location. If aWorldBounds is not NULL, at least the specified area will be drawn. The aspect ratio of the screen pixels will be maintained, so slightly more of the world bounds than specified may be drawn. If aWorldBounds is NULL, the grid bounds rendered will be that of all loaded layers.


GM_DrawGridLinesEx
GM_Error_t32 GM_DrawGridLinesEx
    (
    HDC                     aDC,            // Device context to draw to
    boolean                 aLatLonGrid,    // Draw a lat/lon grid or a view projection grid
    double                  aGridSpacing,   // Grid spacing (use 0.0 for default)
    const GM_Rectangle_t*   aWorldBounds,   // World bounds to draw or NULL for all
    sint32                  aLeftPixel,     // Left pixel coordinate to draw to
    sint32                  aTopPixel,      // Top pixel coordinate to draw to
    sint32                  aPixelWidth,    // Width in pixels to draw
    sint32                  aPixelHeight,   // Height in pixels to draw
    const GM_Rectangle_t*   aMaxGridBounds  // Maximum grid bounds (NULL for loaded data bounds)
    );

Draws grid lines (either lat/lon or in the view projection) for the specified location to the provided device context at the given location. If aWorldBounds is not NULL, at least the specified area will be drawn. The aspect ratio of the screen pixels will be maintained, so slightly more of the world bounds than specified may be drawn. If aWorldBounds is NULL, the grid bounds rendered will be that of all loaded layers.

If aMaxGridBounds is specified the grid lines will be allowed to draw anywhere within the value specified. Otherwise, the grid lines will be clamped at the bounds of all loaded data.


GM_DrawLayer
GM_Error_t32 GM_DrawLayer
    (
    HDC                     aDC,            // Device context to draw to
    GM_LayerHandle_t32      aLayer,         // Layer to draw or NULL for all
    const GM_Rectangle_t*   aWorldBounds,   // World bounds to draw or NULL for all
    sint32                  aLeftPixel,     // Left pixel coordinate to draw to
    sint32                  aTopPixel,      // Top pixel coordinate to draw to
    sint32                  aPixelWidth,    // Width in pixels to draw
    sint32                  aPixelHeight    // Height in pixels to draw
    );

Draws one or more layers to the provided device context at the given location. If aWorldBounds is not NULL, at least the specified area will be drawn. The aspect ratio of the screen pixels will be maintained, so slightly more of the world bounds than specified may be drawn. If aWorldBounds is NULL, the entire specified layer or all of the loaded layers will be rendered.


GM_DrawLayerList
GM_Error_t32 GM_DrawLayerList
    (
    HDC                     aDC,            // Device context to draw to
    GM_LayerHandle_t32*     aLayerList,     // List of layers to draw or NULL for all
    uint32                  aLayerCount,    // Number of layers in list (0 for all)
    GM_DrawFlags_t32        aDrawFlags,     // Flags controlling how the draw is performed
    const GM_Rectangle_t*   aWorldBounds,   // World bounds to draw or NULL for all
    sint32                  aLeftPixel,     // Left pixel coordinate to draw to
    sint32                  aTopPixel,      // Top pixel coordinate to draw to
    sint32                  aPixelWidth,    // Width in pixels to draw
    sint32                  aPixelHeight    // Height in pixels to draw
    );

Draws one or more layers to the provided device context at the given location. If aWorldBounds is not NULL, at least the specified area will be drawn. The aspect ratio of the screen pixels will be maintained, so slightly more of the world bounds than specified may be drawn. If aWorldBounds is NULL, the entire specified layer or all of the loaded layers will be rendered.


GM_DrawLayerListToMemory
GM_Error_t32 GM_DrawLayerListToMemory
    ( 
    GM_LayerHandle_t32*     aLayerList,     // List of layers to draw or NULL for all
    uint32                  aLayerCount,    // Number of layers in list (0 for all)
    GM_DrawFlags_t32        aDrawFlags,     // Flags controlling how the draw is performed
    const GM_Rectangle_t*   aWorldBounds,   // World bounds to draw or NULL for all
    GM_ColorFormat_t32      aColorFormat,   // Color format used in data buffer
    sint32                  aPixelWidth,    // Width in pixels to draw
    sint32                  aPixelHeight,   // Height in pixels to draw
    void*                   aDataBuf,       // Buffer to hold output color data
    sint32                  aRowWidthBytes  // Width of a single row in the array in bytes
    );

Draws one or more layers to the provided memory buffer at the given location. If aWorldBounds is not NULL, at least the specified area will be drawn. The aspect ratio of the screen pixels will be maintained, so slightly more of the world bounds than specified may be drawn. If aWorldBounds is NULL, the entire specified layer or all of the loaded layers will be rendered.


GM_DrawPackageList
GM_Error_t32 GM_DrawPackageList
    (
    HDC                     aDC,            // Device context to draw to
    GM_PackageHandle_t32*   aPackageList,   // List of packages to draw or NULL for all
    uint32                  aPackageCount,  // Number of packages in list (0 for all)
    GM_DrawFlags_t32        aDrawFlags,     // Flags controlling how the draw is performed
    const GM_Rectangle_t*   aWorldBounds,   // World bounds to draw or NULL for all
    sint32                  aLeftPixel,     // Left pixel coordinate to draw to
    sint32                  aTopPixel,      // Top pixel coordinate to draw to
    sint32                  aPixelWidth,    // Width in pixels to draw
    sint32                  aPixelHeight    // Height in pixels to draw
    );

Draws the specified portion of the specified packages to the device context. If no packages are explicitly specified, all packages loaded with the GM_LoadPackage function will be drawn.


GM_ExportElevation
GM_Error_t32 GM_ExportElevation
    (
    const char*                     aFilename,      // Name of new file to create
    GM_ElevationExportFormat_t32    aFormat,        // Format to export
    GM_LayerHandle_t32              aLayer,         // Layer to export or NULL for all
    const GM_Rectangle_t*           aWorldBounds,   // World bounds to export or NULL for all
    sint32                          aPixelWidth,    // Width in samples of new image
    sint32                          aPixelHeight,   // Height in samples of new image
    GM_RasterExportFlags_t32        aFlags,         // Export flags
    GM_ElevUnits_t8                 aElevUnits      // Elevation units for export, if applicable
    );

Exports one or more layers to a new gridded elevation file. If NULL is passed for the layer handle, all elevation layers will be saved to the new elevation file, otherwise only the specified layer will be exported. If NULL is provided for the world bounds, all available data will be exported, otherwise only data within the specified bounds will be exported.

The new elevation file create will be in the current view projection as returned by the GM_GetProjection function. You can change the view projection, and thus the export projection, by calling the GM_SetProjection function.


GM_ExportElevationEx
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_ExportElevationEx
    (
    const char*                     aFilename,      // Name of new file to create
    GM_ElevationExportFormat_t32    aFormat,        // Format to export
    GM_LayerHandle_t32*             aLayerList,     // List of layers to export or NULL for all
    uint32                          aLayerCount,    // Number of layers in list (0 for all)
    const GM_Rectangle_t*           aWorldBounds,   // World bounds to export or NULL for all
    sint32                          aPixelWidth,    // Width in samples of new image
    sint32                          aPixelHeight,   // Height in samples of new image
    GM_RasterExportFlags_t32        aFlags,         // Export flags
    GM_ElevUnits_t8                 aElevUnits,     // Elevation units for export, if applicable
    const char*                     aExtraFlags     // Additional text-based flags for some formats (use NULL for defaults)
    )

Exports one or more layers to a new gridded elevation file. If NULL is passed for the layer list, all elevation layers will be saved to the new elevation file, otherwise only the specified layer will be exported. If NULL is provided for the world bounds, all available data will be exported, otherwise only data within the specified bounds will be exported.

The new elevation file create will be in the current view projection as returned by the GM_GetProjection function. You can change the view projection, and thus the export projection, by calling the GM_SetProjection function.

The aExtraFlags parameter allows the specification of any extra options not supports in the aFlags parameter. The options should be specified with the option name, followed by an equal sign, followed by the option value. Most users will pass NULL for this value unless they need a non-default value for an extra option. Currently the following extra options are supported:

  • VOID_VALUE (GeoTIFF format only) - specifies the void value to use for the export. By default the commonly used -32767 is used, but you can add this parameter to specify any valid signed 16-bit integer to use, like VOID_VALUE=-9999 to use -9999.
  • ROUGHNESS_LAYER_LIST (WindSim GWS format only) - specifies the layer indices (0-based) for those layers that are roughness rather than elevation in the provided list of elevation layers. For example, if the 2nd and 3rd layers in the list are roughness, use "ROUGHNESS_LAYER_LIST=1,2". Only required if the roughness grids were created outside the SDK and loaded as elevation grids. Otherwise this is automatically determined.
  • ADD_COLORS (VRML format only) - controls whether or not a color value is written out for each VRML vertex from the input layers. By default this is enabled, use "ADD_COLORS=NO" to disable adding colors.
  • DELIM (XYZ ASCII grid format only) - specifies the coordinate delimiter to use. The default is a comma, but special keywords of COMMA, SPACE, and TAB are supported. For example to use a space as the delimiter use "DELIM=SPACE". This is supported in the SDK v13.2.0 and higher.

GM_ExportMapLayoutComponent
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_ExportMapLayoutComponent
    (
    const char*             aFilename,      // in: name of bitmap file to save to
    GM_MapLayoutPiece_t8    aPiece,         // in: which piece of the map layout to save
    const GM_Rectangle_t*   aWorldBounds,   // in: World bounds to use for rendering layout or NULL for last drawn
    sint32                  aPixelWidth,    // in: Width in pixels of FULL RENDER SCREEN (NOT LAYOUT PIECE) to use for generating map layout. Use 0 for last drawn.
    sint32                  aPixelHeight,   // in: Height in pixels of FULL RENDER SCREEN (NOT LAYOUT PIECE) to use for generating map layout. Use 0 for last drawn.
    void*                   aReserved       // reserved for later use, must be NULL
    )

Exports a component of the currently setup map layout (use GM_LoadMapLayoutFile to load a layout definition) to a bitmap (BMP) file. The bounding box and pixel dimensions that you specify are the same as you would provide to the GM_DrawLayerList function and are used to determine the pixel size that the BMP file will use. If you always call this after a draw, just pass in NULL for the world bounds and 0 for both pixel dimensions.


GM_ExportPackage
GM_Error_t32 __stdcall GM_ExportPackage
    (
    const char*                 aFilename,      // Name of new file to create
    GM_LayerHandle_t32*         aLayerList,     // List of layers to export or NULL for all
    uint32                      aLayerCount,    // Number of layers in list (0 for all)
    const GM_Rectangle_t*       aWorldBounds,   // World bounds to export or NULL for all
    double                      aSimpThreshold, // Simplification threshold, use 0.0 for no simplification
    GM_PackageExportFlags_t32   aFlags          // Export flags
    );

Exports one or more layers to a new Global Mapper package file. If NULL is passed for the layer list handle, all loaded layers will be saved to the new package file, otherwise only the specified layer(s) will be exported. If NULL is provided for the world bounds, the entirety of each layer will be exported, otherwise only data within the specified bounds will be exported.


GM_ExportPDF
GM_Error_t32 __stdcall GM_ExportPDF
    (
    const char*                 aFilename,      // Name of new file to create
    GM_LayerHandle_t32*         aLayerList,     // List of layers to export or NULL for all
    uint32                      aLayerCount,    // Number of layers in list (0 for all)
    const GM_Rectangle_t*       aWorldBounds,   // World bounds to export or NULL for all
    const GM_ExportOptsPDF_t*   aExportOpts     // PDF export options (NULL for default)
    );

Exports one or more layers to a new Geo-enabled PDF file. If NULL is passed for the layer list handle, all loaded layers will be saved to the new package file, otherwise only the specified layer(s) will be exported. If NULL is provided for the world bounds, the entirety of each layer will be exported, otherwise only data within the specified bounds will be exported.

IMPORTANT NOTE: You must purchase a license to the QuickPDF library from http://www.quickpdflibrary.com/ and use the GM_SetQuickPDFUnlockCode function to provide your registration key prior to calling this function. For SDK v1.37 and earlier you need a QuickPDF v7 license, for v1.38 and later you need a QuickPDF v8 license.

EXAMPLE: - Export Geo-enabled PDF from all loaded files with some options set
// Setup PDF export options
GM_ExportOptsPDF_t thePdfOpts;
::memset( &thePdfOpts, 0, sizeof thePdfOpts );
thePdfOpts.mFlags = GM_PDF_FillPage | GM_PDF_BorderStyleValid;
thePdfOpts.mPageSizeName = "Letter"; // Use 8 1/2" by 11" letter paper
thePdfOpts.mDPI = 150;
thePdfOpts.mMarginRect.mMinX = 0.5; // 1/2" left margin
thePdfOpts.mMarginRect.mMaxX = 0.5; // 1/2" right margin
thePdfOpts.mMarginRect.mMaxY = 1.0; // 1" top margin
thePdfOpts.mMarginRect.mMinY = 0.5; // 1/2" bottom margin
thePdfOpts.mBorderStyle = GM_PEN_SOLID; // solid pen
thePdfOpts.mBorderWidth = 3; // border pen 3 PDF points (pixels) wide
thePdfOpts.mBorderColor = RGB(255,0,0); // border color is red
thePdfOpts.mHeaderStr = "My Map Name";

// Do export
GM_Error_t32 theErr = GM_ExportPDF
    (
    "c:\\temp\\export test\\test.pdf",
    NULL, 0,    // export all loaded layers
    NULL,       // export entire bounds of loaded data
    &thePdfOpts
    );

GM_ExportRaster
GM_Error_t32 GM_ExportRaster
    (
    const char*                 aFilename,      // Name of new file to create
    GM_RasterExportFormat_t32   aFormat,        // Format to export
    GM_LayerHandle_t32          aLayer,         // Layer to export or NULL for all
    const GM_Rectangle_t*       aWorldBounds,   // World bounds to export or NULL for all
    sint32                      aPixelWidth,    // Width in pixels of new image
    sint32                      aPixelHeight,   // Height in pixels of new image
    GM_RasterExportFlags_t32    aFlags          // Export flags
    );

Exports one or more layers to a new raster file. If NULL is passed for the layer handle, all loaded layers will be saved to the new raster file, otherwise only the specified layer will be exported. If NULL is provided for the world bounds, all available data will be exported, otherwise only data within the specified bounds will be exported.

The new raster file create will be in the current view projection as returned by the GM_GetProjection function. You can change the view projection, and thus the export projection, by calling the GM_SetProjection function.


GM_ExportRasterEx
GM_Error_t32 __stdcall GM_ExportRasterEx
    (
    const char*                 aFilename,      // Name of new file to create
    GM_RasterExportFormat_t32   aFormat,        // Format to export
    GM_LayerHandle_t32*         aLayerList,     // List of layers to export or NULL for all
    uint32                      aLayerCount,    // Number of layers in list (0 for all)
    const GM_Rectangle_t*       aWorldBounds,   // World bounds to export or NULL for all
    sint32                      aPixelWidth,    // Width in pixels of new image
    sint32                      aPixelHeight,   // Height in pixels of new image
    GM_RasterExportFlags_t32    aFlags,         // Export flags
    const char*                 aExtraFlags     // Additional text-based flags for some formats (use NULL for defaults)
    )

Exports one or more layers to a new raster file. If NULL is passed for the layer handle, all loaded layers will be saved to the new raster file, otherwise only the specified layer(s) will be exported. If NULL is provided for the world bounds, all available data will be exported, otherwise only data within the specified bounds will be exported.

The new raster file create will be in the current view projection as returned by the GM_GetProjection function. You can change the view projection, and thus the export projection, by calling the GM_SetProjection function.

The aExtraFlags parameter allows the specification of any extra options not supports in the aFlags parameter. The options should be specified with the option name, followed by an equal sign, followed by the option value. Most users will pass NULL for this value unless they need a non-default value for an extra option. Currently the following extra options are supported:

  • QUALITY (JPG or GeoTIFF formats only) - specifies the export quality value. Values should range from 1 to 100. The default is 75. Higher values result in a higher quality, but larger result. For example, to set the quality to 90, use "QUALITY=90" as your extra flags value. For GeoTIFF exports this is only used for an export using JPG-in-TIFF compression.
  • COMPRESSION (ECW and JPG2000 formats only) - specifies the target compression ratio for the export. Values should range from 1 (lossless) to 100. The default is 10. Higher values result in a smaller files but lower quality. For example, to set the target comprssion ratio to 1:20, use "COMPRESSION=20" as your extra flags value.
  • DPI (BMP, GeoTIFF, and JPG formats only) - specifies the DPI value to store in the file. The default value of 0 means that no DPI value will be stored in the file.
  • PALETTE (GeoTIFF format only) - specifies the name of a palette file to use for the export. If any part of the path has spaces use %20 for the space.
  • TILE_SIZE (GeoTIFF format only) - specifies that the exported GeoTIFF file should use tile rather than strip orientation and specifies the size of the tile. For example, to create 512x512 tiles internal to the GeoTIFF file, use TILE_SIZE=512.
  • HEADER (GeoTIFF format only) - specifies whether or not the generated GeoTIFF file should have a GeoTIFF header written. This is enabled by default, add HEADER=NO to disable saving a header.
  • OPTIMIZE_CODING (JPG format only) - specifies whether or not entropy encoding should be optimized for JPEG compression. This is for advanced users only. Use OPTIMIZE_CODING=1 to enable optimizing entropy encoding.
  • WRITE_JFIF_HEADER (JPG format only) - specifies whether or not a JFIF header should be written to the exported JPEG file. This is for advanced users only. Use WRITE_JFIF_HEADER=1 to enable writing a JFIF header.
  • DCT_METHOD (JPG format only) - specifies the DCT method to use for JPEG compression. This is for advanced users only. Valid values are 0 for JDCT_ISLOW, 1 for JDCT_IFAST, and 2 for JDCT_FLOAT.
  • VALID_ALPHA (PNG format only) - specifies the alpha value (between 1 and 255) to use for valid pixels. By default any valid pixels will be completely opaque (i.e. alpha = 255).
  • RES_MULT - (ADVANCED USERS) specifies a multiplier to apply to the export resolution when choosing which layer of an online source to pull from. For example, adding RES_MULT=2 will cause an export at 5m per pixel to choose an online zoom level more appropriate for a 10m per pixel export. Values smaller than 1 cause a more detailed layer to be pulled from.

The CADRG/CIB export format has a set of required value that describe the export. In addition the filename provided should be for the a.toc (table of contents) file for the data set. The frame files will be saved in folders underneath that. The following flag values are used:

  • MAP_NAME - The map name, usually a 6-character name
  • SERIES - The chart series 2-letter code from [Section 5.1.4, MIL-STD-2411-1]. The following list includes some commonly supported values (note that any 2-letter code is supported):
    • GN - 1:5M Scale GNC (Global Navigation Chart)
    • JN - 1:2M Scale JNC (Jet Navigation Chart)
    • TP - 1:500K Scale TPC (Tactical Pilotage Chart)
    • I1 - 10m Resolution CIB Imagery
    • I2 - 5m Resolution CIB Imagery
    • I3 - 2m Resolution CIB Imagery
    • I4 - 1m Resolution CIB Imagery
    • I5 - 0.5m Resolution CIB Imagery
  • SCALE - The scale to export at. In most cases the SERIES implies the scale so this value is ignored, but it you use a SERIES with a variable scale this is required.
  • PRODUCER_CODE - The numeric producer code ID from [MIL-STD-2411-1, Section 5.2.1), like 1 for AFACC (Air Force Air Combat Command).
  • SECURITY_CLASS - The 1-character security classification from [MIL-STD-2411-1, Section 5.1.8). The default is SECURITY_CLASS=U for unclassified.
  • SECURITY_COUNTRY - The 2-character security country code from [MIL-STD-2411-1, Section 5.1.7). The default is SECURITY_COUNTRY=US for the US.
  • SECURITY_MARKING - The 2-character security markingfrom [MIL-STD-2411-1, Section 5.1.9). The default is SECURITY_MARKING=uu for unclassified.
  • VERSION - The file version. The default is 1 if you don't provide a value.

For exmaple to export a 1:500k scale TPC CADRG from the DMAAC you could pass the following extra flags string:

"MAP_NAME=ABC123 SERIES=TP PRODUCER_CODE=3 SECURITY_CLASS=U SECURITY_COUNTRY=US SECURITY_MARKING=uu VERSION=1"

GM_ExportVector
GM_Error_t32 __stdcall GM_ExportVector
    (
    const char*                     aFilename,      // Name of new file to create
    GM_VectorExportFormat_t32       aFormat,        // Format to export
    GM_LayerHandle_t32              aLayer,         // Layer to export or NULL for all
    const GM_Rectangle_t*           aWorldBounds,   // World bounds to export or NULL for all
    GM_VectorExportFlags_t32        aFlags,         // Export flags
    void*                           aFormatOptions  // Format-specific options (NULL for defaults)
    );

GM_ExportVectorEx
GM_Error_t32 __stdcall GM_ExportVectorEx
    (
    const char*                     aFilename,      // Name of new file to create
    GM_VectorExportFormat_t32       aFormat,        // Format to export
    GM_LayerHandle_t32              aLayer,         // Layer to export or NULL for all
    const GM_Rectangle_t*           aWorldBounds,   // World bounds to export or NULL for all
    GM_VectorExportFlags_t32        aFlags,         // Export flags
    void*                           aFormatOptions, // Format-specific options (NULL for defaults)
	const char*                     aExtraFlags     // Additional text-based flags for some formats (use NULL for defaults)
    );

GM_ExportVectorList
GM_Error_t32 __stdcall GM_ExportVectorList
    (
    const char*                     aFilename,      // Name of new file to create
    GM_VectorExportFormat_t32       aFormat,        // Format to export
    GM_LayerHandle_t32*             aLayerList,     // List of layers to export or NULL for all
    uint32                          aLayerCount,    // Number of layers in list (0 for all)
    const GM_Rectangle_t*           aWorldBounds,   // World bounds to export or NULL for all
    GM_VectorExportFlags_t32        aFlags,         // Export flags
    void*                           aFormatOptions, // Format-specific options (NULL for defaults)
    const char*                     aExtraFlags,    // Additional text-based flags for some formats (use NULL for defaults)
    void*                           aReserved       // Reserved for future use, must be NULL
    );

Exports one or more layers to a new vector file. If NULL is passed for the layer handle list, all vector layers will be saved to the new vector file, otherwise only the specified layer will be exported. If NULL is provided for the world bounds, all available data will be exported, otherwise only data within the specified bounds will be exported.

The new vector file create will be in the current view projection as returned by the GM_GetProjection function. You can change the view projection, and thus the export projection, by calling the GM_SetProjection function.


GM_ExportWebFormat
GM_Error_t32 __stdcall GM_ExportWebFormat
    (
    const char*                     aFilename,      // Name of HTML/XML file to create
    GM_WebExportFormat_t32          aWebFormat,     // Format to export
    GM_LayerHandle_t32*             aLayerList,     // List of layers to export or NULL for all
    uint32                          aLayerCount,    // Number of layers in list (0 for all)
    const GM_Rectangle_t*           aWorldBounds,   // World bounds to export or NULL for all
    const GM_WebFormatExportOpts_t* aExportOpts,    // Export options
    const char*                     aExtraFlags     // Additional text-based flags for some formats (use NULL for defaults)
    );

Exports one or more layers to a files to a web format for display in a web browser or other web-based tool. If NULL is passed for the layer handle list, all layers will be saved to the new data set, otherwise only the specified layers will be exported. If NULL is provided for the world bounds, all available data will be exported, otherwise only data within the specified bounds will be exported.

The aExtraFlags parameter allows the specification of any extra options not supports in the aExportOpts parameter. The options should be specified with the option name, followed by an equal sign, followed by the option value. Most users will pass NULL or an empty string for this value unless they need a non-default value for an extra option. Currently the following extra options are supported:

  • QUALITY (JPG or GeoTIFF formats only) - specifies the export quality value. Values should range from 1 to 100. The default is 75. Higher values result in a higher quality, but larger result. For example, to set the quality to 90, use "QUALITY=90" as your extra flags value. For GeoTIFF exports this is only used for an export using JPG-in-TIFF compression.

GM_ExportRasterFromBitmap
GM_Error_t32 GM_ExportRasterFromBitmap
    (
    const char*                 aFilename,      // Name of new file to create
    HBITMAP                     aBitmap,        // Handle to bitmap to export
    HDC                         aDC,            // Handle to compatible device context
    GM_RasterExportFormat_t32   aFormat,        // Format to export
    const GM_Rectangle_t*       aWorldBounds,   // World bounds of bitmap or NULL for empty
    GM_RasterExportFlags_t32    aFlags          // Export flags
    );

Generates a new raster image from a bitmap handle. The new raster image will have the same number of pixels as the bitmap. The aFormat parameter specifies what image format to use for the new raster. If aWorldBounds is not NULL, the provided bounds will be used to fill in the spatial information for the new file, if supported by the new file format.


GM_FindFeaturesInArea
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_FindFeaturesInArea
    (
    GM_LayerHandle_t32*         aLayerList,         // IN: List of layers to search for points or NULL for all vector layers
    uint32                      aLayerCount,        // IN: Number of layers in list (0 for all)
    GM_FindFlags_t32            aFindFlags,         // IN: Flags controlling how the find is performed
    const GM_AreaFeature_t*     aAreaToSearch,      // IN: Area feature to search (use GM_GetAreaFeature to get from loaded layer)
    const GM_Projection_t*      aAreaProj,          // IN: Projection of coordinates in area feature (use GM_GetLayerInfo()->mNativeProj to get layer projection)
    GM_FoundFeatureResults_t**  aResultList,        // OUT: Results of find operation (use GM_FreeFeatureResultList to free when done)
    void*                       aReserved           // IN: Reserved for future use, must be NULL
    )

Searches the provided list of layers for any visible vector features within the provided area feature. You can find area, line, and/or point features that are completely within the provided area feature.

The results are returned in the aResultList value. After you are done with the result list, use GM_FreeFeatureResultList to free the result list.


GM_FindNearestAddress
GM_Error_t32 __stdcall GM_FindNearestAddress
    (
    const GM_Point_t*       aSearchPt,          // IN: Search location in current view projection (as returned by GM_SetProjection)
    GM_LayerHandle_t32*     aLayerList,         // IN: List of layers to search or NULL for all vector layers
    uint32                  aLayerCount,        // IN: Number of layers in list (0 for all)
    char*                   aAddressStr,        // I/O: Buffer to hold string for nearest address
    uint32                  aMaxAddressLen,     // IN: Maximum length of string to store in output
    double                  aMaxDistMeters,     // IN: Maximum distance in meters to search around search point
    void*                   aReserved           // IN: Reserved for later use, must be NULL (0)
    );

Searches the provided list of layers for any visible vector line feature within the provided search distance (aMaxDistMeters) which has addressing information in a supported format (i.e. Tiger/Line data).


GM_FindNearestFeatures
GM_Error_t32 __stdcall GM_FindNearestFeatures
    (
    const GM_Point_t*       aPixelSearchPt,     // IN: Search location in pixel coordinates
    GM_LayerHandle_t32*     aLayerList,         // IN: List of layers to search or NULL for all vector layers
    uint32                  aLayerCount,        // IN: Number of layers in list (0 for all)
    GM_FindFlags_t32        aFindFlags,         // IN: Flags controlling how the find is performed
    const GM_Rectangle_t*   aWorldBounds,       // IN: World bounds for search space or NULL for last drawn
    const GM_PixelRect_t*   aPixelRect,         // IN: Pixel bounds for search space or NULL for last drawn 
    GM_FoundFeature_t*      aNearestFeatures,   // OUT: List of nearest features
    uint32                  aMaxFeatures,       // IN: Max number of nearest features to find
    uint32*                 aFoundFeatureCnt,   // OUT: Number of nearest features returned in list
    uint32                  aMaxDistPixels      // IN: Max distance in pixels to search
    );

Searches the provided list of layers for any visible vector features within the provided search distance (aMaxDistPixels) of the pixel search location (aPixelSearchPt). The aFindFlags parameter specifies what types of features to search on.


GM_FlushLayerCache
GM_Error_t32 __stdcall GM_FlushLayerCache
    ( 
    GM_LayerHandle_t32  aLayer
    )

Flushes any in-memory cache for the layer. This is mainly useful in low-memory environments like Windows CE and typically only does anything for raster formats like GeoTIFF files. Most users will never need to call this.


GM_FreeAreaFeature
void GM_FreeAreaFeature
    (
    GM_AreaFeature_t*   aAreaFeature            // Area feature to free
    )

Frees the resources used by the given area feature. This should be called on each area feature returned by GM_GetAreaFeature.


GM_FreeFeatureResultList
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_FreeFeatureResultList
    (
    GM_FoundFeatureResults_t*   aResultList     // IN: Previously fetched result set
    )

Frees the resources associated with a results list returned by a search function, like GM_FindFeaturesInArea.


GM_FreeLineFeature
void GM_FreeLineFeature
    (
    GM_LineFeature_t*   aLineFeature            // Line feature to free
    )

Frees the resources used by the given line feature. This should be called on each line feature returned by GM_GetLineFeature.


GM_FreePointFeature
void GM_FreePointFeature
    (
    GM_PointFeature_t*	aPointFeature			// Point feature to free
    )

Frees the resources used by the given point feature. This should be called on each point feature returned by GM_GetPointFeature.


GM_GenerateContours
GM_GenerateContoursEx
GM_Error_t32 __stdcall GM_GenerateContours
    (
    GM_LayerHandle_t32          aLayer,         // IN: Layer to get elevations from or NULL for topmost layer at each point
    const GM_ContourParams_t*   aContourParms,  // IN: Parameters for generating contours
    GM_LayerHandle_t32*         aContourLayer   // OUT: Created contour layer
    );
GM_Error_t32 __stdcall GM_GenerateContoursEx
    (
    GM_LayerHandle_t32*         aLayerList,     // IN: List of layers to use or NULL for all
    uint32                      aLayerCount,    // IN: Number of layers in list (0 for all)
    const GM_ContourParams_t*   aContourParms,  // IN: Parameters for generating contours
    GM_LayerHandle_t32*         aContourLayer   // OUT: Created contour layer
    );

Generates contours from loaded elevation data and creates a new vector layer with the results. The layer handle returned in aContourLayer must be closed with GM_CloseLayer when you are done with it.

See the definition of the GM_ContourParams_t type in the GlobalMapperInterface.h header file for a description of what options are available when generating the contour lines, iso-height areas, and/or min/max spot elevations.


GM_GenerateDensityGrid
GM_Error_t32 __stdcall GM_GenerateDensityGrid
    (
    GM_LayerHandle_t32              aPointLayer,    // IN: Layer to get points from
    const GM_DensityGridParams_t*   aGridParms,     // IN: Parameters for generating density grid
    GM_LayerHandle_t32*             aGridLayer      // OUT: Created density grid layer
    )

Generates a density (heat) grid from the point features in a layer. The values will be based on either just the count of point features or the value of some attribute. The layer handle returned in aGridLayer must be closed with GM_CloseLayer when you are done with it.

See the definition of the GM_DensityGridParams_t type in the GlobalMapperInterface.h header file for a description of what options are available when generating the density grid. The default options are all a value of zero so you can just pass in a zero'd out structure to get the defaults if you want.


GM_GenerateElevationGrid
GM_Error_t32 __stdcall GM_GenerateElevationGrid
    (
    GM_LayerHandle_t32*         aLayerList,     // IN: List of layers to use or NULL for all
    uint32                      aLayerCount,    // IN: Number of layers in list (0 for all)
    const GM_GridGenSetup_t*    aGridSetup,     // IN: Grid setup parameters (pass NULL for default options)
    GM_LayerHandle_t32*         aGridLayer,     // OUT: Created grid layer
    GM_LayerHandle_t32*         aTinLayer       // OUT: Created TIN area layer (optional, set to NULL if you don't want)
    );

Generates an elevation grid and optionally a 3D area TIN layer from loaded 3D vector data. The layer handle(s) returned in aGridLayer and (optionally) aTinLayer must be closed with GM_CloseLayer when you are done with them.

See the definition of the GM_GridGenSetup_t type in the GlobalMapperInterface.h header file for a description of what options are available when generating the elevation grid. The default options are all a value of zero, or you can just pass NULL for the aGridSetup parameter to get the default options.


GM_GenerateRoughnessGrid
GM_Error_t32 __stdcall GM_GenerateRoughnessGrid
    (
    GM_LayerHandle_t32              aLandCoverLayer,// IN: Raster land-use Layer to generate roughness from
    const GM_RoughnessGridParams_t* aGridParms,     // IN: Parameters for generating roughness grid
    GM_LayerHandle_t32*             aGridLayer,     // OUT: Created roughness grid layer
    void*                           aReserved       // IN: Reserved for later use, must be NULL
    );

Generates a roughness length grid from the provided raster land cover layer. The layer handle returned in aGridLayer must be closed with GM_CloseLayer when you are done with it. It will be an "elevation" grid layer so any elevation related functions will work on it.

The roughness values are generated based on a provided table of land cover to roughness length values to use. There are several built-in roughness tables, but if you have provided a roughness_tables.txt file in your application folder then you can provide that roughness table. The first roughness table in that file will have an index of GM_Roughness_NumTypes with subsequent custom tables increasing by one.

See the definition of the GM_RoughnessGridParams_t type in the GlobalMapperInterface.h header file for a description of what options are available when generating the roughness grid. The default options are all a value of zero so you can just pass in a zero'd out structure to get the defaults if you want, although you should at least make sure to set the correct roughness table to use.


GM_GenerateWatershed
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GenerateWatershed
    (
    GM_LayerHandle_t32*         aLayerList,         // IN: List of elevation layers to use or NULL for all
    uint32                      aLayerCount,        // IN: Number of layers in list (0 for all)
    const GM_WatershedParams_t* aWatershedParms,    // IN: Parameters for generating watershed
    GM_LayerHandle_t32*         aStreamLayer,       // OUT: Created stream layer
    GM_LayerHandle_t32*         aDrainageAreaLayer, // OUT: Created drainage area layer (if created)
    void*                       aReserved           // IN: Reserved for later use, must be NULL
    )

Performs a watershed calculation on the loaded terrain layers, generating a stream network and optionally a set of drainage area features for each stream. There is also a way to find ridge lines rather than generating a stream network.

The layer handles returned in aStreamLayer and aDrainageAreaLayer must be closed with GM_CloseLayer when you are done with them.

See the definition of the GM_WatershedParams_t type in the GlobalMapperInterface.h header file for a description of what options are available when generating the watershed. The default options are all a value of zero so you can just pass in a zero'd out structure to get the defaults if you want, but at a minimum you typically do want to setup the mMaxDepressionDepth value unless your terrain has the depressions filled up front. Usually a value of 5 meters or so is good for most data sets.

If you would rather find ridge lines rather than a drainage network, pass in the GM_Watershed_FindRidgeLines flag in the GM_WatershedParams_t.mFlags parameter. The ridge line calculation is the same as a stream calculation on an inverted terrain, so the parameters have basically the same meaning.


GM_GetAreaFeature
GM_AreaFeature_t* GM_GetAreaFeature
    (
    GM_LayerHandle_t32  aLayer,                 // Layer to get area from
    uint32              aAreaIndex              // Index of area feature to retrieve
    )

Returns the area feature at the given index in the layer. Returns NULL if the layer does not contain an area at the given index or if a registration key was not found and aAreaIndex was greater than GM_MAX_NON_REGISTERED_VECTOR_IDX.

Any features returned from this function must be freed using a call to GM_FreeAreaFeature when you are done accessing the the feature.


GM_GetAreaFeatureEx
GM_DLL_EXPORTED GM_AreaFeature_t* __stdcall GM_GetAreaFeatureEx
    (
    GM_LayerHandle_t32      aLayer,             // Layer to get area from
    uint32                  aAreaIndex,         // Index of area feature to retrieve
    GM_GetFeatureFlags_t32  aFlags,             // Flags for getting feature
    void*                   aReserved           // Reserved for future use, must be 0
    );

Returns the area feature at the given index in the layer. Returns NULL if the layer does not contain an area at the given index or if a registration key was not found and aAreaIndex was greater than GM_MAX_NON_REGISTERED_VECTOR_IDX.

Using the aFlags parameter you can control whether the coordinates for the features are returned in the native projection of the layer or in the current set projection. You can also indicate that you don't want the coordinates at all.

Any features returned from this function must be freed using a call to GM_FreeAreaFeature when you are done accessing the the feature.


GM_GetAreaFeatureClassDrawStyle
GM_Error_t32 GM_GetAreaFeatureClassDrawStyle
    (
    AreaFeatureClass_t16    aFeatureClass,      // IN: Feature class to get draw style for
    GM_AreaStyle_t*         aAreaStyle          // OUT: Current draw style for area classification
    );

Sets the default drawing style to use for a given area feature classification.


GM_GetAvailableOnlineSourceList
const GM_OnlineSourceInfo_t* __stdcall GM_GetAvailableOnlineSourceList
    (
    uint32*                 aSourceCnt        // OUT: Number of sources returned in list
    )

Returns the list of available online sources. This will be an array of GM_OnlineSourceInfo_t structures. The number of entries in the returned list will be returned in the aSourceCnt parameter.


GM_GetAvailableProjectionList
const GM_ProjectionInfo_t* __stdcall GM_GetAvailableProjectionList
    (
    uint32*             aProjCnt        // OUT: Number of projections returned in list
    )

Retrieves a list of all available projections and their available parameters, datums, units, etc, including the names of said values. The number of entries in the returned list will be returned in the aProjCnt parameter. The returned pointer will remain valid for the remainder of the program operation or until this function is called again, at which time a new pointer may be returned.


GM_GetAvailableSymbolNames
char** __stdcall GM_GetAvailableSymbolNames
    (
    uint32* aNumSymbols                         // OUT: Number of symbols in returned list
    );

Returns the list of available symbol names. This will be an array of const char* values. The number of entries in the returned list will be returned in the aNumSymbols parameter. The symbol name list is also NULL-terminated if you don't want to keep track of the size of the list separately.


GM_GetDatumInfo
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetDatumInfo
    (
    DATUM           aDatumCode,     // IN: Datum code to get information about
    GM_DatumInfo_t* aDatumInfo      // OUT: Information about datum transformation for datum
    );

Retrieves information about the datum transformation used for a given datum.


GM_GetElevationOverrides
GM_Error_t32 __stdcall GM_GetElevationOverrides
    (
    GM_LayerHandle_t32          aLayer,     // in: layer to get options for
    GM_ElevationOverrides_t*    aOptions    // out: elevation adjustments
    );

Retrieves the elevation adjustment options that are currently being applied to a given elevation layer.


GM_GetFeatureClassInfo
GM_Error_t32 GM_GetFeatureClassInfo
    (
    FeatureClass_t16        aFeatureClass,      // IN: Feature class to get info for
    GM_FeatureClassType_t8  aFeatureClassType,  // IN: Type of feature class (area, point, line)
    GM_FeatureClassInfo_t*  aFeatureClassInfo   // OUT: Info about the feature class
    )

Retrieves information about the given feature class.


GM_GetFeatureElevation
GM_Error_t32 __stdcall GM_GetFeatureElevation
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer the point is in
    GM_FeatureClassType_t8  aFeatureClassType,  // IN: Type of feature class (area, point, line)
    uint32                  aFeatureIndex,      // IN: Index of feature in layer
    float*                  aElev               // OUT: Elevation of feature (in meters)
    )

Retrieves the elevation of this feature in meters. Returns an error code if there is not just a single elevation value that applies to this feature.


GM_GetFilterString
GM_DLL_EXPORTED const char* GM_GetFilterString
    (
    void
    );

Returns a const pointer to a string containing the filter for all of the types supported by this DLL. This filter string can be used as input to the standard Windows open file dialog.


GM_GetLastDrawnScale
double GM_GetLastDrawnScale
    (
    HDC                     aDC             // Device context that was drawn to
    );

Returns the last drawn scale (i.e. the XXXX portion of 1:XXXX). If nothing has been drawn, 0.0 is returned.


GM_GetLastDrawnMapBounds
GM_Error_t32 GM_GetLastDrawnMapBounds
    (
	GM_Rectangle_t*   aWorldBounds,   // OUT: World bounds of last drawn view
	GM_PixelRect_t*   aPixelRect      // OUT: Pixel bounds of last drawn view
    );

Gets the most recently drawn map bounds (only supported in Global Mapper Extension SDK)


GM_GetLastDrawnMapBoundsEx
GM_Error_t32 GM_GetLastDrawnMapBoundsEx
    (
	GM_Rectangle_t*   aWorldBounds,         // OUT: World bounds of last drawn view
	GM_PixelRect_t*   aPixelRect,           // OUT: Pixel bounds of last drawn view
    GM_RotatedRect_t* aWorldBoundsRotated,  // OUT: World bounds of last drawn view rotated
    void*             aReserved             // Reserved for future use, must be NULL
    );

Gets the most recently drawn map bounds, including rotation (only supported in Global Mapper Extension SDK)


GM_GetLayerInfo
const GM_LayerInfo_t* GM_GetLayerInfo
    (
    GM_LayerHandle_t32    aLayer
    );

Retrieves information about the given layer. If the layer is not loaded, NULL is returned. Otherwise, a const pointer to the layer metadata is returned. See the GM_LayerInfo_t definition in the header file for details.


GM_GetLayerLidarStats
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetLayerLidarStats
    (
    GM_LayerHandle_t32      aLayer,         // IN: Lidar point cloud layer to get stats from
    GM_LidarStats_t*        aLidarStats,    // OUT: Buffer to hold stats in
    void*                   aReserved       // IN: Reserved for future use, must be NULL
    )

Retrieves Lidar statistics for a layer with lidar data.


GM_GetLidarClassInfo
GM_Error_t32 GM_GetLidarClassInfo
    (
    GM_LidarClass_t8        aLidarClass,        // IN: Lidar class to set info for
    GM_LidarClassInfo_t*    aClassInfo,         // OUT: New type info to use for Lidar class
    boolean                 aGetDefault         // IN: Return default class info rather than current settings?
    );

Retrieves information (name, color, group mask) for the given Lidar classification. You can optionally get the default information for the class.


GM_GetLidarPoint
GM_Error_t32 GM_GetLidarPoint
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer to get point from
    uint64                  aPointIndex,        // IN: Index of Lidar point feature to retrieve
    GM_LidarPoint_t*        aLidarPoint,        // OUT: Lidar point to fill in
    GM_GetFeatureFlags_t32  aFlags,             // IN: Flags for fetching Lidar point
    void*                   aReserved           // IN: Reserved for future use, must be NULL
    )

Retrieves a Lidar point feature from the given layer. The indexes should be in the range [0, GM_LayerInfo_t.mNumLidarPoints). Returns an error if the layer does not contain a Lidar point feature at the given index or if a valid license was not found and aPointIndex was greater than GM_MAX_NON_REGISTERED_VECTOR_IDX.


GM_GetLineFeature
GM_LineFeature_t* GM_GetLineFeature
    (
    GM_LayerHandle_t32  aLayer,                 // Layer to get line from
    uint32              aLineIndex              // Index of line feature to retrieve
    )

Returns the line feature at the given index in the layer. Returns NULL if the layer does not contain a line at the given index or if a registration key was not found and aLineIndex was greater than GM_MAX_NON_REGISTERED_VECTOR_IDX.

Any features returned from this function must be freed using a call to GM_FreeLineFeature when you are done accessing the the feature.


GM_GetLineFeatureEx
GM_DLL_EXPORTED GM_LineFeature_t* __stdcall GM_GetLineFeatureEx
    (
    GM_LayerHandle_t32      aLayer,             // Layer to get line from
    uint32                  aLineIndex,         // Index of line feature to retrieve
    GM_GetFeatureFlags_t32  aFlags,             // Flags for getting feature
    void*                   aReserved           // Reserved for future use, must be 0
    );

Returns the line feature at the given index in the layer. Returns NULL if the layer does not contain a line at the given index or if a registration key was not found and aLineIndex was greater than GM_MAX_NON_REGISTERED_VECTOR_IDX.

Using the aFlags parameter you can control whether the coordinates for the features are returned in the native projection of the layer or in the current set projection. You can also indicate that you don't want the coordinates at all.

Any features returned from this function must be freed using a call to GM_FreeLineFeature when you are done accessing the the feature.


GM_GetLineFeatureClassDrawStyle
GM_Error_t32 GM_GetLineFeatureClassDrawStyle
    (
    LineFeatureClass_t16    aFeatureClass,      // IN: Feature class to get draw style for
    GM_LineStyle_t*         aLineStyle          // OUT: Current draw style for line classification
    );

Sets the default drawing style to use for a given line feature classification.


GM_GetLoadedLayerList
const GM_LayerHandle_t32* __stdcall GM_GetLoadedLayerList
    (
    uint32* aLayerCount // OUT: count of layers in returned list
    )

Returns a list of loaded layers. You should copy the list into your own local structure after calling as the pointer could become invalid the next time you call this. If you are using the GM_MapWindow class in the C++ sample application there is no need to use this as that keeps track of the layers itself.


GM_GetLocationColor
GM_DLL_EXPORTED GM_Error_t32 GM_GetLocationColor
    (
    GM_LayerHandle_t32      aLayer,     // IN: Layer to get color from or NULL for topmost
    double                  aXCoord,    // IN: X coord in current projection
    double                  aYCoord,    // IN: Y coord in current projection
    GM_Color_t*             aColor      // OUT: Color of pixel at location    
    );

Retrieves the color at a given location from a provided layer or from the list of currently loaded raster and elevation layers (topmost layer first).


GM_GetLocationElevation
GM_DLL_EXPORTED GM_Error_t32 GM_GetLocationElevation
    (
    GM_LayerHandle_t32      aLayer,     // IN: Layer to get elevation from or NULL for topmost
    double                  aXCoord,    // IN: X coord in current projection
    double                  aYCoord,    // IN: Y coord in current projection
    float*                  aElev       // OUT: Elevation at location in meters
    );

Retrieves the elevation at a given location from a provided layer or from the list of currently loaded elevation layers (topmost elevation layer first).


GM_GetMACAddress
const char* GM_GetMACAddress
    (
    void
    );

Returns the unique machine ID (MAC address) of the current computer. This is used for license file generation and you may have to call this in order to provide the MAC address for generating a .lic file for your product.


GM_GetMGRSCoordinates
GM_Error_t32 __stdcall GM_GetMGRSCoordinates
    (
    double  aX,         // IN: point X/longitude coordinate
    double  aY,         // IN: point Y/latitude coordinate
    boolean aLatLon,    // IN: TRUE - coordinates are lat/lon, FALSE - coordinates are in the current projection?
    char*   aMgrsStr    // OUT: buffer to store MGRS coordinate text in
    );

Retrieves the MGRS coordinate string for a given coordinate provided in either the current projection or as lat/lon degree coordinates. The MGRS coordinate string will be stored in the <aMgrsStr> variable, which should be a pointer to a string buffer large enough for a complete MGRS coordinates (typically 30 or so will be plenty).


GM_GetOnlineLayerZoomScale
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetOnlineLayerZoomScale
    ( 
    GM_LayerHandle_t32      aLayer,         // IN: Tiled online layer to query
    const GM_Rectangle_t*   aWorldBounds,   // IN: World bounds to convert from or NULL for last drawn
    const GM_PixelRect_t*   aPixelRect,     // IN: Pixel bounds to convert from or NULL for last drawn 
    boolean                 aForExport,     // IN: Get zoom scale for an export (TRUE) or draw (FALSE)
    const char*             aExtraOpts,     // IN: String with extra options, like RES_MULT
    uint32*                 aZoomScale,     // OUT: Zoom scale that will be used
    void*                   aReserved       // IN: Reserved for future use
    );

Determine the zoom scale that will be used to draw/export from a provided tiled online layer for a given bounds. Very few people will need this function. It would really only be used if you were going to pre-fetch some tiles for a local tiled "online" source so you wanted to know the zoom scale prior to draw/export.


GM_GetOnlineSourceInfo
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetOnlineSourceInfo
    (
    const char*             aSourceName,    // IN: Name of online source to get detail info for
    GM_OnlineSourceInfo_t*  aSourceInfo,    // OUT: Detailed information about provided source, mostly in attributes
    void*                   aReserved       // IN: Reserved for future use, must be NULL
    );

Retrieves detailed information about a source by name and also determines if the source is available. You can use this to tell if a source is not usable due to something like the China firewall. Returns GM_Error_OnlineConnect if the source cannot be connected to. Returns GM_Error_OnlineUnknownSource if the source cannot be found.


GM_GetPackageLayerList
GM_LayerHandle_t32* GM_GetPackageLayerList
    (
    GM_PackageHandle_t32    aPackage,   // IN: package to get list of layers from
    uint32*                 aLayerCount // OUT: Number of layers in returned list
    );

Returns a list of the layers that are in a given package. The pointer returned is temporary and will become invalid with the next call to this function. The package must have been opened with the GM_LoadPackage function.


GM_GetPathProfile
GM_DLL_EXPORTED GM_Error_t32 GM_GetPathProfile
    (
    GM_LayerHandle_t32      aLayer,     // IN: Layer to get elevation from or NULL for topmost
    double                  aStartX,    // IN: Start X coord in current projection
    double                  aStartY,    // IN: Start Y coord in current projection
    double                  aEndX,      // IN: End X coord in current projection
    double                  aEndY,      // IN: End Y coord in current projection
    float*                  aElevList,  // OUT: Buffer to hold list of elevations
    uint32                  aListSize,  // IN: Number of elevations to retrieve
    float                   aDfltElev   // IN: Elev to use when none could be found
    );

Retrieves a list of elevations along a path in the provided layer or from the list of currently loaded elevation layers (topmost elevation layer first).


GM_GetPathProfileLOS
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetPathProfileLOS
    (
    GM_LayerHandle_t32          aLayer, // IN: Layer to get elevation from or NULL for topmost
    GM_PathProfileLOSParams_t*  aParams // IN/OUT: Calculation parameters
    );

Retrieves a list of elevations along a path in the provided layer or from the list of currently loaded elevation layers (topmost elevation layer first). Can also perform a line-of-sight calculation and return additional information about a 3D path.

NOTE: Use GM_GetPathProfileLOSEx if you need to pass in a list of layers to consider for the path profile.


GM_GetPathProfileLOSEx
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetPathProfileLOSEx
    (
    GM_LayerHandle_t32*         aLayerList,     // IN: List of layers to get elevation from or NULL for topmost
    uint32                      aLayerCount,    // IN: Number of layers in list
    GM_PathProfileLOSParams_t*  aParams         // IN/OUT: Calculation parameters
    );

Retrieves a list of elevations along a path in the provided layer list or from the list of currently loaded elevation layers (topmost elevation layer first). Can also perform a line-of-sight calculation and return additional information about a 3D path.


GM_GetPixelBandValue
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetPixelBandValue
    (
    GM_LayerHandle_t32      aLayer,     // IN: Layer to get color from
    sint32                  aRow,       // IN: Y coord of pixel (0 is topmost)
    sint32                  aCol,       // IN: X coord of pixel (0 is leftmost)
    sint32                  aBand,      // IN: Band to get value for (0-based, so first band is 1)
    sint32*                 aVal        // OUT: Color of pixel at location    
    )

Retrieves the raw band value at a given pixel location from the provided raster layer. If the layer does not contain a valid sample at the provided pixel location (i.e. it is a "no data" or transparent value), GM_Error_NoDataAtLocation will be returned. Use this to access the raw values from high-bit depth and multi-band imagery layers.


GM_GetPixelColor
GM_DLL_EXPORTED GM_Error_t32 GM_GetPixelColor
    (
    GM_LayerHandle_t32      aLayer,     // IN: Layer to get color from or NULL for topmost
    sint32                  aRow,       // IN: Y coord of pixel (0 is topmost)
    sint32                  aCol,       // IN: X coord of pixel (0 is leftmost)
    GM_Color_t*             aColor      // OUT: Color of pixel at location    
    );

Retrieves the color at a given pixel location from the provided raster layer. If the layer does not contain a valid color value at the provided pixel location (i.e. it is a "no data" or transparent value), GM_Error_NoDataAtLocation will be returned.


GM_GetPixelColorRow
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetPixelColorRow
    (
    GM_LayerHandle_t32      aLayer,     // IN: Layer to get color from
    sint32                  aRow,       // IN: Y coord of pixel (0 is topmost)
    COLORREF*               aColorRow,  // OUT: Buffer to hold color values
    COLORREF                aInvalidVal // IN: Value to use for invalid pixels
    );

Retrieves the color values for an entire row of the provided layer. If any pixels don't have valid values they will be replaced by aInvalidVal. This function is much faster than individually getting the color value for individual pixels using the GM_GetPixelColor function, so use this to access large portions of a loaded layer.


GM_GetPixelElevation
GM_DLL_EXPORTED GM_Error_t32 GM_GetPixelElevation
    (
    GM_LayerHandle_t32      aLayer,     // IN: Layer to get elevation from or NULL for topmost
    sint32                  aRow,       // IN: Y coord of pixel (0 is topmost)
    sint32                  aCol,       // IN: X coord of pixel (0 is leftmost)
    float*                  aElev       // OUT: Elevation at location in meters
    );

Retrieves the elevation at a given pixel location from a provided elevation layer. If the layer does not contain a valid elevation sample at the provided pixel location (i.e. it is a "no data" value), GM_Error_NoDataAtLocation will be returned.


GM_GetPixelElevationRow
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetPixelElevationRow
    (
    GM_LayerHandle_t32      aLayer,     // IN: Layer to get elevation from
    sint32                  aRow,       // IN: Y coord of pixel (0 is topmost)
    float*                  aElevRow,   // OUT: Buffer to hold elevation values for row in meters
    float                   aInvalidVal // IN: Value to use for invalid samples (i.e. -9999.9)
    );

Retrieves the elevation values for an entire row of the provided layer. If any elevations don't have valid values they will be replaced byy aInvalidVal. This function is much faster than individually getting the elevation value for individual pixels using the GM_GetPixelElevation function, so use this to access large portions of a loaded layer.


GM_GetPointFeature
GM_PointFeature_t* GM_GetPointFeature
    (
    GM_LayerHandle_t32  aLayer,                 // Layer to get point from
    uint32              aPointIndex             // Index of point feature to retrieve
    )

Returns the point feature at the given index in the layer. Returns NULL if the layer does not contain an point at the given index or if a registration key was not found and aPointIndex was greater than GM_MAX_NON_REGISTERED_VECTOR_IDX.

Any features returned from this function must be freed using a call to GM_FreePointFeature when you are done accessing the the feature.


GM_GetPointFeatureEx
GM_DLL_EXPORTED GM_PointFeature_t* __stdcall GM_GetPointFeatureEx
    (
    GM_LayerHandle_t32      aLayer,             // Layer to get point from
    uint32                  aPointIndex,        // Index of point feature to retrieve
    GM_GetFeatureFlags_t32  aFlags,             // Flags for getting feature
    void*                   aReserved           // Reserved for future use, must be 0
    );

Returns the point feature at the given index in the layer. Returns NULL if the layer does not contain an point at the given index or if a registration key was not found and aPointIndex was greater than GM_MAX_NON_REGISTERED_VECTOR_IDX.

Using the aFlags parameter you can control whether the coordinates for the features are returned in the native projection of the layer or in the current set projection. You can also indicate that you don't want the coordinates at all.

Any features returned from this function must be freed using a call to GM_FreePointFeature when you are done accessing the the feature.


GM_GetSelectedFeatures

This function is only supported in a Global Mapper Extension DLL.

GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetSelectedFeatures
(
	GM_FoundFeatureResults_t* aResults,         // OUT: Structure that will get list of selected features
	GM_SelectFlags_t32        aFlags,           // IN: Flags controlling what to select (like areas, lines, points, etc.)
	void*                     aReserved         // Reserved for future use; must be 0.
 );

TODO: Describe this function and its parameters

Any features returned from this function must be freed using a call to GM_FreeFeatureResultList when you are done using them.


GM_GetPointFeatureClassDrawStyle
GM_Error_t32 GM_GetPointFeatureClassDrawStyle
    (
    PointFeatureClass_t16	aFeatureClass,      // IN: Feature class to get draw style for
    GM_PointStyle_t*        aPointStyle         // OUT: Current draw style for point classification
    );

Sets the default drawing style to use for a given point feature classification.


GM_GetProjection
GM_Error_t32 GM_GetProjection
    (
    GM_Projection_t*    aProj           // OUT: Current view/export projection
    );

Retrieves the global projection that is being used for all rendering and exporting.


GM_GetRasterDisplayOptions
GM_Error_t32 GM_GetRasterDisplayOptions
    (
    GM_LayerHandle_t32          aLayer,     // in: layer to get options for
    GM_RasterDisplayOptions_t*  aOptions    // out: display options for raster layer
    );

Retrieves the options that are used when displaying the given raster layer. This includes things like the translucency and transparency (if any) of the layer, the color intensity of the layer, and whether or not to crop the collar of the layer.


GM_GetSDKBuildDate
GM_DLL_EXPORTED time_t __stdcall GM_GetSDKBuildDate
    (
    void
    )

Returns the date that this SDK was built. Use this to provide more resolution for beta releases than GM_GetSDKVersion provides.


GM_GetSDKVersion
uint32 GM_GetSDKVersion
    (
    void
    );

Returns the version of this SDK. The version is obtained by taking the major version number times 100 and adding the minor version number. For example, version 1.04 would be returned as 104.


GM_GetShaderDisplayOptions
const GM_ShaderOptions_t* GM_GetShaderDisplayOptions
    (
    void
    );

Returns a pointer to the current shader display options that are used when rendering gridded elevation data. The returned pointer is temporary and should be copied if it will be used for an extended period of time on the client side.


GM_GetVerticalDisplayOptions
const GM_VerticalDisplayOptions_t* GM_GetVerticalDisplayOptions
    (
    void
    );

Returns a pointer to the current vertical display options that are used when rendering gridded elevation data. The returned pointer is temporary and should be copied if it will be used for an extended period of time on the client side.


GM_GPSGetAltitude
GM_Error_t32 GM_GPSGetAltitude
    (
    float*                  aAltitude       // out: current GPS altitude in meters
    );

Retrieves the current GPS altitude value in meters. Will return GM_Error_GPSDataNotValid if there if a GPS device is not being tracked with a 3D fix.


GM_GPSGetBearing
GM_Error_t32 GM_GPSGetBearing
    (
    float*                  aBearing        // out: current GPS bearing in radians from due north
    );

Retrieves the current GPS bearing value. Will return GM_Error_GPSDataNotValid if there if either we are not tracking a GPS device or the bearing is not known.


GM_GPSGetFixInfo
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GPSGetFixInfo
    (
    float*                  aHorzPosError,  // out: current horizontal position error in meters (0.0 if unknown)
    float*                  aVertPosError,  // out: current vertical position error in meters (0.0 if unknown)
    float*                  aPDOP,          // out: current position DOP in meters (0.0 if unknown)
    uint32*                 aNumSats        // out: number of satellites used in fix (0 if unknown)
    );

Retrieves the current GPS fix accuracy statistics.


GM_GPSGetFixType
GM_gps_fix_t8 GM_GPSGetFixType
    (
    void
    );

Returns the current GPS fix type.


GM_GPSGetLocation
GM_Error_t32 GM_GPSGetLocation
    (
    GM_Point_t*             aCurPos,        // out: current GPS location
    boolean                 aGetLatLon      // in: retrieve coordinates in lat/lon/WGS84 rather than global coords
    );

Retrieves the current GPS location value. Will return GM_Error_GPSDataNotValid if there we are not tracking a GPS device or we do not have a position fix.

If aGetLatLon is TRUE, the position returned will be in decimal degrees latitude and longitude in the WGS84 datum. If aGetLatLon is FALSE, the position will be returned in the current global coordinate system, as returned by GM_GetProjection and modified by GM_SetProjection.


GM_GPSGetTime
GM_Error_t32 __stdcall GM_GPSGetTime
    (
    time_t*                 aFixTime
    );

Retrieves the UTC time of the last GPS fix, Will return GM_Error_GPSDataNotValid if there if either we are not tracking a GPS device or the time is not known.


GM_GPSGetTimeEx
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GPSGetTimeEx
    (
    time_t*                 aFixTime,           // out: fix time
    double*                 aFractionalSeconds  // out: fractional seconds to add to fix time
    );

Retrieves the UTC time of the last GPS fix along with optionally any fractions of a second with the time. Most device will report positions every second so this would be 0.0 for most devices, but some high-frequency reporting devices will provide updates multiple times a second, in which case the fractional seconds value will be non-zero. Will return GM_Error_GPSDataNotValid if there if either we are not tracking a GPS device or the time is not known.


GM_GPSGetVelocity
GM_Error_t32 GM_GPSGetVelocity
    (
    float*                  aVelocity       // out: current GPS velocity in m/s
    );

Retrieves the current GPS velocity value in meters/second. Will return GM_Error_GPSDataNotValid if there if either we are not tracking a GPS device or the velocity is not known.


GM_GPSRenderVessel
GM_Error_t32 GM_GPSRenderVessel
    (
    HDC                     aDC,            // Device context to draw to
    const GM_Rectangle_t*   aWorldBounds,   // IN: World bounds to convert from or NULL for last drawn
    const GM_PixelRect_t*   aPixelRect,     // IN: Pixel bounds to convert from or NULL for last drawn 
    uint32                  aVesselHeight,  // IN: The vessel height in pixels
    uint32                  aVesselWidth,   // IN: The vessel width in pixels
    COLORREF                aVesselColor    // IN: The color to render the vessel in
    );

Renders a GPS vessel to the provided device context at the current GPS location.


GM_GPSStartTrackingNMEAFile
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GPSStartTrackingNMEAFile
    ( 
    const char*             aFilename,      // full path to NMEA file to use
    GM_gps_nmea_flags_t32   aNmeaFlags,     // flags controlling NMEA playback
    GM_GPSCallbackFunc      aCallbackFunc,  // optional callback function
    void*                   aReserved       // reserved value (must be NULL)
    );

Starts simulation of tracking a GPS device from a file containing a stream of NMEA sentences.

If a callback function is provided, it will be called on the GPS thread whenever new GPS locations are decoded from the file and when the GPS tracking state changes based on the sentences in the file.


GM_GPSStartTrackingSerial
GM_Error_t32 GM_GPSStartTrackingSerial
    ( 
    GM_gps_format_t8        aFormat,        // format (NMEA or Garmin)
    uint8                   aPort,          // COM port for serial connections
    uint32                  aBaud,          // baud rate for serial port
    GM_GPSCallbackFunc      aCallbackFunc,  // optional callback function
    uint32                  aReserved       // 32-bit reserved value (must be 0)
    );

Starts tracking a GPS device connected to a serial port. The GPS will actually be tracked on a background thread, so this function will return quickly and possibly before a connection is established.

If a callback function is provided, it will be called on the GPS thread whenever new GPS locations are received and when the GPS tracking state changes.

If you provide a format value of GPS_FORMAT_AUTODETECT, a GPS connection will automatically be checked for on connected serial and USB devices.


GPS_StartTrackingUSB
GM_Error_t32 GM_GPSStartTrackingUSB
    ( 
    GM_GPSCallbackFunc      aCallbackFunc,  // optional callback function
    uint32                  aReserved       // 32-bit reserved value (must be 0)
    );

Starts tracking a GPS device connected to a USB port. The GPS will actually be tracked on a background thread, so this function will return quickly and possibly before a connection is established.

If a callback function is provided, it will be called on the GPS thread whenever new GPS locations are received and when the GPS tracking state changes.

NOTE: Currently only Garmin USB devices are supported.


GM_GPSStopTracking
GM_Error_t32 GM_GPSStopTracking
    (
    void
    );

Stops tracking any currently connected GPS device.


GM_IsFeatureDeleted
GM_Error_t32 __stdcall GM_IsFeatureDeleted
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer the point is in
    GM_FeatureClassType_t8  aFeatureClassType,  // IN: Type of feature class (area, point, line)
    uint32                  aFeatureIndex,      // IN: Index of feature in layer
    boolean*                aIsDeleted          // OUT: Returns TRUE if marked as deleted, FALSE if not
    )

Queries the delete status of the area, line, or point feature at the given index in the layer. Use the GM_DeleteFeature function to change the delete status of a feature.


GM_LoadGenericAsciiTextLayer
GM_Error_t32 GM_LoadGenericAsciiTextLayer
    ( 
    const char*                 aFilename,  // IN: filename of ASCII file to load
    GM_LayerHandle_t32*         aLayer,     // OUT: layer handle for loaded layer
    GM_LoadFlags_t32            aLoadFlags, // IN: load flags
    const GM_AsciiFormatInfo_t* aFormatInfo,// IN: optional format info (use NULL to prompt user)
    const GM_Projection_t*      aProj       // IN: optional projection to use for file (use NULL to prompt user)
    );

Loads the given ASCII text file and fills in aLayer with the handle to the layer. The layer handle can be used in other calls into the library. The layer must be closed by calling GM_CloseLayer when the caller is done using it.

The format of the ASCII text file being loaded is described with the aFormatInfo structure provided. If NULL is passed for that structure, a dialog will appear prompting the user for the layout information.


GM_LoadLayer
GM_Error_t32 GM_LoadLayer
    ( 
    const char*         aFilename,
    GM_LayerHandle_t32* aLayer,
    GM_LoadFlags_t32    aLoadFlags
    );

Loads the given file and fills in aLayer with the handle to the layer. The layer handle can be used in other calls into the library. The layer must be closed by calling GM_CloseLayer when the caller is done using it.

This function is deprecated. You should use GM_LoadLayerList as it supports multiple layers being loaded from a single file (this is common with archive files like .zip and .tar.gz as well as multi-map formats like CADRG).


GM_LoadLayerList
GM_Error_t32 GM_LoadLayerList
    ( 
    const char*             aFilename,
    GM_LayerHandle_t32**    aLayerList,
    uint32*                 aNumLoadedLayers,
    GM_LoadFlags_t32        aLoadFlags
    );

Loads the given file and fills in aLayerList with a pointer to a list of layer handles. The number of layers returned in the list is placed in aNumLoadedLayers.

The layer handles can be used in other calls into the library. Each layer handle must be closed by calling GM_CloseLayer when the caller is done using it.

Note that the pointer returned in aLayerList is a temporary pointer that will be invalidated the next time that GM_LoadLayerList is called. The layer handles should be copied out of the returned layer list into local storage of some kind.


GM_LoadLayerListEx
GM_Error_t32 GM_LoadLayerListEx
    ( 
    const char*             aFilename,
    GM_LayerHandle_t32**    aLayerList,
    uint32*                 aNumLoadedLayers,
    GM_LoadFlags_t32        aLoadFlags,
    const char*             aExtraLoadOptions
    );

Loads the given file and fills in aLayerList with a pointer to a list of layer handles. The number of layers returned in the list is placed in aNumLoadedLayers.

The layer handles can be used in other calls into the library. Each layer handle must be closed by calling GM_CloseLayer when the caller is done using it.

Note that the pointer returned in aLayerList is a temporary pointer that will be invalidated the next time that GM_LoadLayerList is called. The layer handles should be copied out of the returned layer list into local storage of some kind.

The aExtraLoadOptions value allows you to provide a string containing additional type-specific load options to the load operation. The formats supported for the various import types are specified below.

Supported Extra Load Options
  • Any Format - Format Specification - the type for a layer can be manually specified rather than the automatic detection mechanism used by providing a string for the aExtraLoadFlags parameter than includes the text "LAYER_TYPE=type name here", such as "LAYER_TYPE=BIL" for a BIL-format file. See the documentation for the TYPE parmeter of the IMPORT command in the Global Mapper scripting language to get a list of the valid type names. This is useful if you want to use a non-standard extension for a file type.
  • DBDB-v5 HDF5 Data - specifies flags for loading the DBDB-v5 bathymetry data set, witht he following format: geo,<resolution_index>,<left_lon>,<bottom_lat>,<right_lon>,<top_lat>,<flags>
  • . The <flags> are optional. If set to 1 then data from lower resolution layers than what is specified will not be used when no data at the specified resolution can be found.
  • VPF Data (VMAP, DNC, etc.) - you can specify a comma-delimited quoted list of coverages to load as well as a library name to load if the dht file that you are loading references multiple libraries. For example, to load just the boundary and transportation coverages from a layer, specify a load flags of COVERAGES="Boundaries,Transportation". Note that this will also cause the coverage/tile selection dialog to not be shown. You can also supply a list of FACC codes to load in the extra load string. It's formatted like FACC_LIST="<FACC_Code1>,...,<FACC_CodeN>". Finally, if you just want to load either area, line, and/or point features, you can specify that the other types are to be ignored by adding a substring of format FEATURE_TYPE="AREAS,LINES,POINTS". Just leave out the types that you don't want to load, so to just load lines, you would use FEATURE_TYPE="LINES". If you want to hide the dialog that shows and just load everything, use COVERAGES="*". This works as the coverage names support wildcard (* and ?) characters.
  • Spatial Database - You can specify the name of the spatial database table name and the bounding box for data to be loaded.The format is:

    <table_name>,<minX>,<minY>,<maxX>,<maxY>

    The values are separated by commas. <table_name> is the name of the table to be loaded. <minX> and <minY> are the easting/longitude and northing/latitude for the lower, left corner of the bounging box. <maxX> and <maxY> are the easting/longitude and northing/latitude for the upper, right corner of the bounding box. The bounds are assumed to be in the same projection as the table being loaded. If the projection has an angular unit, the values must be in decimal degrees. For example, to load a table called ROADS with data in a geodetic projection (e.g., WGS84), you could use the following:

    ROADS,-70.5,40.0,-65.0,45.0

    If you want to read the entire contents of a table, specify the name of the table by itself, with no bounds, as shown below:

    ROADS

GM_LoadOnlineLayer
GM_Error_t32 __stdcall GM_LoadOnlineLayer
    (
    const char*             aSourceName,        // in: source to load or NULL to ask user
    const GM_Rectangle_t*   aLatLonRect,        // in: lat/lon rect to import (NULL to ask user)
    GM_LayerHandle_t32*     aLayer,             // out: handle to loaded layer
    const char*             aExtraLoadOptions   // in: string of extra load options
    )

Loads data from an online source, like WMS, OSM, TMS, or Google Maps tiles. This includes data sources providing terrain, imagery, and street maps for the entire world. If the aSourceName value is NULL, a dialog will be displayed asking the user which online data source and bounds to load. If the aSourceName is the full path and name of a local file that contains new source definitions, rather than loading a new layer those sources are added to the source list. You can then call back in to GM_LoadOnlineLayer to load a layer from the new added sources.

Valid theme names are any name that shows up in the dialog when calling this with a NULL theme name, such as the following examples (any match will do though):

  • "OpenStreetMap.org Global Street Maps"
  • "World Imagery"
  • "United States Elevation Data (NED) (10m Resolution)"
  • "ASTER GDEM v2 Worldwide Elevation Data"
  • "SRTM Worldwide Elevation Data (3-arc-second Resolution) [Use http://srtm.csi.cgiar.org/ if fails]"
  • "Landsat7 Global Imagery Mosaic (Natural Color, Pan-Sharpened)"
  • "Landsat7 Global Imagery Mosaic (Psuedo-Color, Pan-Sharpened)"

The layer handle returned in aLayer must be freed with a call to GM_CloseLayer when the caller is done using it.

The aLatLonRect can be used to provide the bounding box to load. If provided, the bounding box shall be lat/lon degree bounds using the datum of the current projection. If no current view/export projection is available WGS84 will be the datum for the lat/lon values. If you would like to provide the bounds in some other projection, specify the projection using a BOUNDS_PROJ value in aExtraLoadOptions (see below).

The aExtraLoadOptions string can contain additional options as a space-separated string. Currently the following are supported:

  • BOUNDS_PROJ - Specifies the projection for the coordinates in the aLatLonBounds parameter. See Script Reference for a description of the allowed values. For example, you could specify the bounds are lat/lon WGS84 using the EPSG code by passing "BOUNDS_PROJ=EPSG:4326" for aExtraLoadOptions.
  • CLAMP_TO_BOUNDS - Specifies whether or not the layer bounds should be clamped to the specified bounding box or if panning over the entire data set should be allowed. The default is to clamp to the bounds. Use CLAMP_TO_BOUNDS=NO to disable the clamping behavior.
  • ZOOM_OFFSET - Specifies an offset to apply to the calculated optimal zoom level to use for a particular draw or export. For example, adding ZOOM_OFFSET=-1 would cause every draw/export to use one lower zoom level (i.e. half resolution) than would otherwise by used for the resolution of the draw/export.
  • INC_LAYER - specify name of layer/group to include. Can include wildcards. Multiple values allowed. If present only those layers that match an INC_LAYER value will be added. You can also include group names before the name, separated with ' --> ' or '<sub>'. For example, to add only those sources in the *** POPULAR SOURCES *** or TERRAIN DATA groups, use "\"INC_LAYER=*POPULAR SOURCES*-->*\" \"INC_LAYER=TERRAIN DATA --> *\"" (the escape sequences match what C/C++ code would use. To only add the NAIP imagery, use "\"INC_LAYER=NAIP Color Imagery*\"".
  • EXC_LAYER - specify name of layer/group to exclude. See the INC_LAYER definition above for information about formatting. If present any layers that match an EXC_LAYER value will not be added.

GM_LoadMapLayoutFile
GM_Error_t32 GM_LoadMapLayoutFile
    (
    const char* aFilename,  // in: name of map layout filename
    void*       aReserved   // reserved for later use, must be NULL
    )

Loads a map layout from a file. The map layout text file sets up the display of elevation legend, distance scale, vector feature legend, and north arrow. If you provide the flag GM_DrawFlags_DrawMapLayoutLayers when drawing then any configured map layout layers will be displayed.

The map layout file is a simple text file. While there is not a document describing its format, you can setup a map layout on the Map Layout dialog in the Global Mapper application and save it to a file, then examine and edit that in a text editor to determine the format.


GM_LoadPackage
GM_Error_t32 GM_LoadPackage
    ( 
    const char*             aFilename,
    GM_PackageHandle_t32*   aPackage,
    GM_LoadFlags_t32        aLoadFlags
    );

Loads a new Global Mapper package (.gmp) file. You can also load package files with the GM_LoadLayerList command if you don't need to operate on the package as a whole.

A handle to the package is returned in aPackage. This package handle can be used in package-specific routines like GM_DrawPackageList. Each package handle must be closed by calling GM_ClosePackage when the caller is done using it.


GM_LoadProjectionFile
GM_Error_t32 __stdcall GM_LoadProjectionFile
    (
    const char*             aFilename,  // filename of projection file to load
    GM_Projection_t*        aProj       // buffer in which to place decoded projection.
    );

Initializes a GM_Projection_t structure from a projection (PRJ, Ozi .map, etc.) file.


GM_LoadProjectionFromEPSGCode
GM_Error_t32 __stdcall GM_LoadProjectionFromEPSGCode
    (
    uint32                  aEpsgCode,  // IN: EPSG code to get projection from
    GM_Projection_t*        aProj       // OUT: buffer in which to place decoded projection.
    );

Initializes a GM_Projection_t structure from an EPSG projection code.


GM_LoadProjectionFromWKTString
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_LoadProjectionFromWKTString
    (
    const char*             aStr,       // IN: String to decode projection from
    GM_Projection_t*        aProj       // OUT: buffer in which to place decoded projection.
    )

Initializes a GM_Projection_t structure from a WKT projection string (like would be found in a PRJ file).


GM_LoadRectifiedLayer
GM_DLL_EXPORTED GM_Error_t32 GM_LoadRectifiedLayer
    ( 
    const char*                     aFilename,
    GM_LayerHandle_t32*             aLayer,
    GM_LoadFlags_t32                aLoadFlags,
    const GM_GroundControlPoint_t*  aGCPList,
    uint32                          aNumGCPs,
    const GM_Projection_t*          aProj
    );

Loads the given file and fills in aLayer with the handle to the layer. The layer handle can be used in other calls into the library. The layer must be closed by calling GM_CloseLayer when the caller is done using it.

The layer will be positioned according to the ground control point (GCP) list provided. The ground coordinates in the GCP list must be given in the projection specified by aProj.


GM_LoadTerraServerLayer
GM_DLL_EXPORTED GM_Error_t32 GM_LoadTerraServerLayer
    (
    const char*             aThemeName, // in: name of the theme to load ("drg", "doq", etc.) or NULL to ask user
    const GM_Rectangle_t*   aLatLonRect,// in: lat/lon rect to import (NULL to ask user)
    GM_LayerHandle_t32*     aLayer      // out: handle to loaded TerraServer layer
    );

NOTE: This function is now DEPRECATED. Please use GM_LoadOnlineLayer instead.

Loads data from the TerraServer, including DRG, DOQ, and urban area imagery. If either the aThemeName or aLatLonRect values are NULL, a dialog will be displayed asking the user which theme and bounds to load.

Valid theme names are as follows:

  • "DRG" - USGS DRG scanned topographic maps
  • "DOQ" - USGS DOQ grayscale aerial imagery with 1 meter resolution
  • "UrbanArea" - NIMA/USGS high resolution color imagery

The layer handle returned in aLayer must be freed with a call to GM_CloseLayer when the caller is done using it.


GM_MapCatalogAddFile
GM_Error_t32 GM_MapCatalogAddFile
    (
    GM_LayerHandle_t32      aCatalogLayer,  // IN: Handle to map catalog layer (either from loading or GM_CreateMapCatalog)
    const char*             aFilename       // IN: Filename of map to add to the catalog
    );

Adds a new map to the map catalog from a file on disk. The aCatalogLayer parameter should have either been created using GM_MapCatalogCreate or loaded with one of the GM_LoadLayer* functions.


GM_MapCatalogAddLayer
GM_Error_t32 GM_MapCatalogAddLayer
    (
    GM_LayerHandle_t32      aCatalogLayer,  // IN: Handle to map catalog layer (either from loading or GM_CreateMapCatalog)
    GM_LayerHandle_t32      aMapLayer       // IN: Handle of loaded map layer to add to the catalog
    );

Adds a new map to the map catalog from a layer that has already been loaded. The aCatalogLayer parameter should have either been created using GM_MapCatalogCreate or loaded with one of the GM_LoadLayer* functions.

Note that the layer provided will remain open as a separate layer as well. If this is not the desired behavior, simply call GM_CloseLayer on the map layer after adding it to the catalog layer.


GM_MapCatalogChangeMapOrder
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_MapCatalogChangeMapOrder
    (
    GM_LayerHandle_t32      aCatalogLayer,  // IN: Handle to map catalog layer (either from loading or GM_CreateMapCatalog)
    uint32                  aCurMapIndex,   // IN: Current index of map (0-based) to move
    uint32                  aNewMapIndex,   // IN: New index of map (0-based) 
    sint32                  aNumMapsToMove, // IN: Number of maps to move (-1 for everything from aCurMapIndex to end of list)
    void*                   aReserved       // Reserved for future use, must be NULL
    );

Moves 'aNumMapsToMove' maps starting at 'aCurMapIndex' in the map list to 'aNewMapIndex'. If you use -1 for 'aNumMapsToMove', all maps from 'aNumMapsToMove' to the end of the list will be moved to 'aNewMapIndex'. In that case, 'aNewMapIndex' must be smaller than 'aCurMapIndex'.


GM_MapCatalogCreate
GM_LayerHandle_t32 GM_MapCatalogCreate
    (
    const char*             aDescription,   // IN: Description to use for layer (can be NULL to use default)
    const GM_Projection_t*  aProj           // IN: Native projection of new layer (NULL for Geographic/WGS84/Arc Degrees)
    );

Creates a new map catalog layer with the given description and native projection. Once you have created a new map catalog, use the handle returned in calls to GM_MapCatalogAddFile or GM_MapCatalogAddLayer to add new maps to the catalog. Use GM_MapCatalogSave to save the map catalog to a disk file that can later be loaded using any of the GM_LoadLayer* functions.


GM_MapCatalogDisableMap
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_MapCatalogDisableMap
    (
    GM_LayerHandle_t32      aCatalogLayer,  // IN: Handle to map catalog layer (either from loading or GM_CreateMapCatalog)
    uint32                  aMapIndex,      // IN: Index of map (0-based) to disable/enable
    boolean                 aDisable        // IN: Pass TRUE to disable map or FALSE to re-enable it
    );

Disables (or re-enables) a map inside a map catalog. Use GM_MapCatalogGetInfo to get the count of maps in a layer.


GM_MapCatalogGetInfo
GM_Error_t32 GM_MapCatalogGetInfo
    (
    GM_LayerHandle_t32      aCatalogLayer,  // IN: Handle to map catalog layer (either from loading or GM_CreateMapCatalog)
    GM_MapCatalogInfo_t*    aCatalogInfo    // OUT: Structure holding catalog information
    );

Retrieves information and statistics about the catalog (use GM_GetLayerInfo for generic information).


GM_MapCatalogGetMapInfo
const GM_LayerInfo_t* GM_MapCatalogGetMapInfo
    (
    GM_LayerHandle_t32      aCatalogLayer,  // IN: Handle to map catalog layer (either from loading or GM_CreateMapCatalog)
    uint32                  aMapIndex       // IN: Index of map (0-based) to get info about
    );

Retrieves information about a map in a catalog (use GM_GetMapCatalogInfo to get the map count). Returns NULL if the catalog is not valid or no map exists in the catalog at the given index. Otherwise, consider the returned pointer temporary. It will become invalid after the next call to this function.


GM_MapCatalogRemoveMap
GM_Error_t32 GM_MapCatalogRemoveMap
    (
    GM_LayerHandle_t32      aCatalogLayer,  // IN: Handle to map catalog layer (either from loading or GM_CreateMapCatalog)
    uint32                  aMapIndex       // IN: Index of map (0-based) to remove from map catalog
    );

Removes the map at the given index from the map catalog.


GM_MapCatalogSave
GM_Error_t32 GM_MapCatalogSave
    (
    GM_LayerHandle_t32      aCatalogLayer,  // IN: Handle to map catalog layer (either from loading or GM_CreateMapCatalog)
    const char*             aFilename       // IN: Filename to save map catalog to
    );

Saves the given map catalog to the given file on disk.


GM_MapCatalogSetDisplayInfo
GM_Error_t32 GM_MapCatalogSetDisplayInfo
    (
    GM_LayerHandle_t32          aCatalogLayer,  // IN: Handle to map catalog layer (either from loading or GM_CreateMapCatalog)
    GM_MapCatalogDisplayType_t8 aDisplayType,   // IN: Controls when layers in catalog are displayed
    double                      aDisplayValue,  // IN: First value related to display type
    double                      aDisplayValue2, // IN: Optional econd value for range of scales (use 0.0 if doesn't apply)
    boolean                     aHideBounds     // IN: Hide layer bounds when not drawing a layer?
    );

Sets when the layers in a map catalog should be displayed. The aDisplayValue and aDisplayValue2 parameters have the following meanings based on the value of aDisplayType:

  • GM_MapCatalog_DisplayTypePercent - aDisplayValue is percent of view window that a layer has to take up before it is shown
  • GM_MapCatalog_DisplayTypePixelSize - aDisplayValue is the size in meters that a single pixel in the display window should be before any layers are displayed
  • GM_MapCatalog_DisplayTypeScale - aDisplayValue is the denominator of the scale value (e.g. 100000.0 for 1:100K). Layers in the catalog will be drawn whenever the calculated scale value for the draw window is at or below the specified value.
  • GM_MapCatalog_DisplayTypeScaleRange - aDisplayValue and aDisplayValue2 specify a range of scales between which to draw the layers in the catalog. For example, to draw the layers when the scale for the draw window is between 1:50K and 1:250K, use values of 50000.0 and 250000.0.

GM_MapCatalogSetMapOption
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_MapCatalogSetMapOption
    (
    GM_LayerHandle_t32      aCatalogLayer,  // IN: Handle to map catalog layer (either from loading or GM_CreateMapCatalog)
    uint32                  aMapIndex,      // IN: Index of map (0-based) to disable/enable
    GM_MapCatalogMapOpt_t8  aMapOpt,        // IN: Option to set. This determines what type you should pass in for <aOptData>
    const void*             aOptData        // IN: Data to use for option. The value of <aMapOpt> controls what this should be.
    )

Sets an option for a map in the map catalog, like the native projection. The option type determines what type of data to pass in for the aOptData parameter. The following types of options can be set:

  • GM_MapCatalog_SetMapProjection - set the native projection to use for the map. The aOptData should be a GM_Projection_t*

GM_ProjectionGetBase
GM_Error_t32 GM_ProjectionGetBase
    (
    const GM_Projection_t*  aProjIn,    // IN: projection to convert from (NULL for current)
    GM_Projection_t*        aProjBase   // OUT: projection on which the input projection is based
    );

Retrieves the underlying base projection that forms the basis for a given projection. For example, the underlying Transverse Mercator projection will be returned for a UTM projection. For core projections, like Transverse Mercator, the output will just match the input.


GM_ProjectPoint
GM_Error_t32 GM_ProjectPoint
    (
    double                  aXIn,       // IN: X coordinate of input point
    double                  aYIn,       // IN: Y coordinate of input point
    double*                 aXOut,      // OUT: X coordinate of output point
    double*                 aYOut,      // OUT: Y coordinate of output point
    const GM_Projection_t*  aProjIn,    // IN: projection to convert from (NULL for current)
    const GM_Projection_t*  aProjOut    // IN: projection to convert to (NULL for current)
    );

This function projects a point from one coordinate system to another. If NULL is passed for either projection parameter, the current view/export projection will be used. This function provides an easy way to convert from latitude/longitude coordinates (or coordinates in any other supported projection) to any other projection, including the current view projection.

For examples on how to set up projection definitions, see the documentation for the GM_SetProjection function.


GM_ProjectPointAtElev
GM_Error_t32 GM_ProjectPointAtElev
    (
    double                  aXIn,       // IN: X coordinate of input point
    double                  aYIn,       // IN: Y coordinate of input point
    double*                 aXOut,      // OUT: X coordinate of output point
    double*                 aYOut,      // OUT: Y coordinate of output point
    const GM_Projection_t*  aProjIn,    // IN: projection to convert from (NULL for current)
    const GM_Projection_t*  aProjOut,   // IN: projection to convert to (NULL for current)
    double                  aElev       // IN: elevation in meters above ellipsoid surface to do conversion at
    );

This function projects a point from one coordinate system to another at some elevation above the ellipsoid. Use this instead of GM_ProjectPoint if you need to do extremely precise conversions at some height above the ellipsoid. The typical difference between conversions at the ellipsoid surface and within a few thousand meters of the surface is less than 1 meter. If NULL is passed for either projection parameter, the current view/export projection will be used. This function provides an easy way to convert from latitude/longitude coordinates (or coordinates in any other supported projection) to any other projection, including the current view projection.

For examples on how to set up projection definitions, see the documentation for the GM_SetProjection function.


GM_ProjectPointFromECEF
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_ProjectPointFromECEF
    (
    double                  aX,         // IN: ECEF X coordinate of input
    double                  aY,         // IN: ECEF Y coordinate of input
    double                  aZ,         // IN: ECEF Z coordinate of input
    double*                 aXOut,      // OUT: X coordinate of output point
    double*                 aYOut,      // OUT: Y coordinate of output point
    double*                 aZOut,      // OUT: Z coordinate of output point (meters above ellipsoid)
    DATUM                   aDatum,     // IN: datum of ECEF coordinate (normally GM_DATUM_WGS_84)
    const GM_Projection_t*  aProjOut    // IN: projection to convert to (NULL for current)
    )

Projects a point from ECEF (earth-centered earth-fixed) coordinates referenced to some datum (normally WGS84) to coordinates in some projection. See GM_ProjectPointToECEF for a sample.


GM_ProjectPointList
GM_Error_t32 __stdcall GM_ProjectPointList
    (
    GM_Point_t*             aPointList, // IN/OUT: List of points to convert and buffer to hold converted points
    uint32                  aNumPoints, // IN: Number of points to convert
    float*                  aElevList,  // IN: Optional list of elevations (in meeters above ellipsoid surface) to do conversions at. Use NULL for default conversion at ellipsoid surface
    const GM_Projection_t*  aProjIn,    // IN: projection to convert from (NULL for current)
    const GM_Projection_t*  aProjOut    // IN: projection to convert to (NULL for current)
    )

Projects a list of points from one coordinate system to another. By default each conversion is done at the ellipsoid surface, but if you provide a list of elevation values (one for each point) you can have the calculation done at some arbitrary height relative to the ellipsoid surface. If NULL is passed for either projection parameter, the current view projection will be used. If any of the reprojections fail, GM_Error_Projection will be returned.

If you need to reproject a large number of points this is much faster than making separate calls to GM_ProjectPoint for each point feature.

For examples on how to set up projection definitions, see the documentation for the GM_SetProjection function.


GM_ProjectPointToECEF
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_ProjectPointToECEF
    (
    double                  aXIn,       // IN: X coordinate of input point
    double                  aYIn,       // IN: Y coordinate of input point
    double                  aZIn,       // IN: Z coordinate of input point (meters above ellipsoid), usually 0
    double*                 aX,         // OUT: ECEF X coordinate of input
    double*                 aY,         // OUT: ECEF Y coordinate of input
    double*                 aZ,         // OUT: ECEF Z coordinate of input
    DATUM                   aDatum,     // IN: datum for ECEF conversion (normally GM_DATUM_WGS_84)
    const GM_Projection_t*  aProjIn     // IN: projection of input point (NULL for current projection)
    )

Projects a point to ECEF (earth-centered earth-fixed) coordinates referenced to some datum (normally WGS84) from coordinates in some projection.

SAMPLE:

// Convert a sample lat/lon point to ECEF
GM_Projection_t theGeoProj;
::memset( &theGeoProj, 0, sizeof theGeoProj );
theGeoProj.mProjSys = GM_PRJ_GEO;
theGeoProj.mDatum = GM_DATUM_WGS_84;
theGeoProj.mUnit = GM_PRJ_UNIT_ARC_DEGREES;
double theLat = 39.0;
double theLon = -90.0;
double theX, theY, theZ;
GM_Error_t32 theErr = GM_ProjectPointToECEF( theLon, theLat, &theX, &theY, &theZ, GM_DATUM_WGS_84, &theGeoProj );

// Convert back, yielding the same point as you started with
double theRevLat, theRevLon;
theErr = GM_ProjectPointFromECEF( theX, theY, theZ, &theRevLon, &theRevLat, GM_DATUM_WGS_84, &theGeoProj );

GM_ProjectRectangle
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_ProjectRectangle
    (
    const GM_Rectangle_t*   aRectIn,    // IN: Rectangle to convert in input projection
    GM_Rectangle_t*         aRectOut,   // OUT: Rectangle in output projection
    const GM_Projection_t*  aProjIn,    // IN: projection to convert from (NULL for current)
    const GM_Projection_t*  aProjOut    // IN: projection to convert to (NULL for current)
    );

Projects a rectangle from one coordinate system to another. If NULL is passed for either projection parameter, the current view projection will be used.

Note that this should be used rather than simply calling GM_ProjectPoint on the corners of a rectangle because many rectangles will NOT be rectangular in other projections, resulting in min/max values along on edge, or in some cases, like polar stereographic, the min/max values may be interior to the rectangle.

For examples on how to set up projection definitions, see the documentation for the GM_SetProjection function.


GM_RemoveCustomBrushStyle
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_RemoveCustomBrushStyle
    (
    const char* aBrushName // IN: Text name to use when referring to the brush style
    )

Removes a custom brush style that was previously added with the GM_AddCustomBrushStyle function.


GM_RemoveCustomShader
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_RemoveCustomShader
    (
    const char* aShaderName // in: name of custom shader to remove
    );

Removes the custom shader with the given name. Note that you can only remove custom shaders and not the built-in shaders.


GM_RemoveCustomSymbol
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_RemoveCustomSymbol
    (
    const char* aSymbolName // IN: Text name to use when referring to the symbol
    );

Removes a custom symbol that was previously added with the GM_AddCustomSymbol function.


GM_RepositionLayer
GM_DLL_EXPORTED GM_Error_t32 GM_RepositionLayer
    ( 
    GM_LayerHandle_t32              aLayer,
    const GM_GroundControlPoint_t*  aGCPList,
    uint32                          aNumGCPs,
    const GM_Projection_t*          aProj
    );

Repositions/reprojects the given layer.

The layer will be positioned according to the ground control point (GCP) list provided. The ground coordinates in the GCP list must be given in the projection specified by aProj. If you just want to change the native projection of the layer, provide NULL for the aGCPList parameter and provide the new native projection with the aProj parameter.


GM_RunScript
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_RunScript
    ( 
    const char*             aFilenameOrText,    // IN: string with full path of script or the actual text of the script
    GM_LayerHandle_t32**    aLayerList,         // OUT: list of layer handles loaded by the script (NULL if you don't want to keep them around)
    uint32*                 aNumLoadedLayers,   // OUT: number of layer handles in aLayerList (NULL if you don't want to keep the list)
    GM_LoadFlags_t32        aLoadFlags,         // IN: Extra flags for load behavior
    void*                   aReserved           // IN: Reserved for future use, must be NULL
    );

Runs a Global Mapper script (.gms) or workspace (.gmw). You can provide the filename of the script to run or you can provide script as raw text. If you provide non-NULL aLayerList and aNumLoadedLayers values then the script will be run in the context of the currently loaded data and any data left loaded by the script will be available after it completes. Otherwise the script will run in its own sandbox.


GM_SaveProjectionToFile
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SaveProjectionToFile
    (
    const char*             aFilename,  // filename of projection file to save to
    const GM_Projection_t*  aProj,      // projection to save
    uint32                  aReserved   // reserved for future use, must be 0
    );

Saves a GM_Projection_t structure to a projection (PRJ) file.


GM_SaveProjectionToString
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SaveProjectionToString
    (
    const GM_Projection_t*  aProj,      // projection to save
    char*                   aStrBuf,    // buffer to store string in
    uint32                  aBufSize,   // size of string buffer
    uint32                  aReserved   // reserved for future use, must be 0
    )

Saves a GM_Projection_t structure to a WKT projection string.


GM_SaveWorkspace
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SaveWorkspace
    (
    const char* aFilename,  // IN: name of workspace file to save
    void*       aReserved   // IN: reserved for later use, must be NULL
    );

Saves the current list of loaded layers and display options to a workspace (GMW) file. You can load a workspace file using any of the GM_LoadLayer* functions.


GM_SaveWorkspaceEx
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SaveWorkspaceEx
    (
    const char*             aFilename,      // IN: name of workspace file to save
    GM_LayerHandle_t32*     aLayerList,     // IN: List of layers in order to save to workspace or NULL for all in order they were loaded
    uint32                  aLayerCount,    // IN: Number of layers in list (0 for all)
    void*                   aReserved       // IN: reserved for later use, must be NULL
    );

Saves the provided list of loaded layers and display options to a workspace (GMW) file. If you don't provide a custom list then the current loaded list is used. Use this instead of GM_SaveWorkspace if you want to save your loaded layers in an order other than the load order or you just want a workspace for a subset of the files. You can load a workspace file using any of the GM_LoadLayer* functions.


GM_SelectAreaStyle
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SelectAreaStyle
    (
    GM_AreaStyle_t* aAreaStyle	// IN/OUT: Area style buffer - make sure to initialize before passing in
    );

Displays a dialog allowing the user to graphically select an area style.


GM_SelectFile
GM_Error_t32 GM_SelectFile
    ( 
    char*       aFilename,  // buffer in which to place selected filename (must be at least _MAX_PATH characters in length)
    const char* aFilterStr, // filter string for open dialog (NULL for default)
    const char* aInitialDir,// initial directory to start in (NULL for current)
    HWND        aParentWnd  // handle to parent window for file selection dialog
    );

Displays a file dialog that allows the user to select a file to load.


GM_SelectFont
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SelectFont
    (
    GM_FontDef_t*   aFontDef    // IN/OUT: Font buffer - make sure to initialize before passing in
    );

Displays a dialog allowing the user to graphically select an font. Make sure to initialize the font definition that is provided.


GM_SelectLineStyle
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SelectLineStyle
    (
    GM_LineStyle_t* aLineStyle	// IN/OUT: Line style buffer - make sure to initialize before passing in
    );

Displays a dialog allowing the user to graphically select a line style.


GM_SelectProjection
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SelectProjection
    (
    GM_Projection_t*        aSelProj,   // out: projection selected by user
    const GM_Projection_t*  aInitProj   // in: initial projection to use (NULL for default)
    );

Displays the projection selection dialog to allow the user to select a projection. If aInitProj is provided, the projection dialog is initialized to that projection.


GM_SelectProjectionEx
GM_Error_t32 __stdcall GM_SelectProjectionEx
    (
    GM_Projection_t*        aSelProj,   // out: projection selected by user
    const GM_Projection_t*  aInitProj,  // in: initial projection to use (NULL for default)
    const POINT*            aDlgPos,    // in: position of top left corner (in screen coordinates) for projection dialog (NULL for default)
    GM_SelectProjFlags_t32  aFlags,     // in: additional flags for projection selection
    void*                   aReserved   // in: reserved for future use (must be NULL)
    )

Displays the projection selection dialog to allow the user to select a projection. If aInitProj is provided, the projection dialog is initialized to that projection. The caller can also optionally provide an initial location for the projection dialog on the screen as well as flags controlling the selection of the projection.


GM_SetAreaFeatureClassDrawStyle
GM_Error_t32 GM_SetAreaFeatureClassDrawStyle
    (
    AreaFeatureClass_t16    aFeatureClass,      // IN: Feature class to set draw style for
    const GM_AreaStyle_t*   aAreaStyle          // IN: New style to use for area (NULL to reset to default)
    );

Sets the default style and font to use for drawing areas with the given area classification. Pass NULL for the area style to reset the default drawing style to the default style for that classification of area.

Typically, when modifying the drawing style of a area class you'll want to call GM_GetAreaFeatureClassDrawStyle to get the current drawing style, then just change what you need, then pass your copy in to this function.


GM_SetAreaFeatureDrawStyle
GM_Error_t32 GM_SetAreaFeatureDrawStyle
    (
    GM_LayerHandle_t32      aLayer,             // Layer the area is in
    uint32                  aAreaIndex,         // Index of area in layer
    const GM_AreaStyle_t*   aAreaStyle          // New style to use for area
    );

Sets the style and font to use for drawing the given area object. Pass NULL for the area style to reset the drawing style to the default style for the classification of the area.

Typically, when modifying the drawing style of an area you'll want to call GM_GetAreaFeature to get the current drawing style, then copy the mAreaStyle member of the GM_AreaFeature_t and just change what you need, then pass your copy in to this function.


GM_SetAreaFeaturePointList
GM_Error_t32 GM_SetAreaFeaturePointList
    (
    GM_LayerHandle_t32      aLayer,             // Layer the area is in
    uint32                  aAreaIndex,         // Index of area in layer
    uint32                  aHoleIndex,         // Index of hole to apply locations to (0 for main parent area, 1 for first hole, etc.)
    const GM_Point_t*       aPointList,         // New list of points for area
    uint32                  aPointCount,        // Number of points in list (must be >= 3)
    boolean                 aPosInLayerCoords   // Are the position in the layer coordinate system or the current coordinate system?
    );

Sets the list of point locations to use for the given area feature. The positions can either be specified in the native projection system of the layer (aPosInLayerCoords is TRUE) or in the current projection as returned by GM_GetProjection (aPosInLayerCoords is FALSE).

The aHoleIndex parameter allows you to set the position list for holes within an area as well as the main parent area. To set the position list for the main parent area, use a value of 0 for aHoleIndex. To set the position of one of the holes in the area, set aHoleIndex to the 1-based index of the hole in the area.


GM_SetChildLayerOpCallback
GM_DLL_EXPORTED void __stdcall GM_SetChildLayerOpCallback
    (
    GM_ChildLayerOpCallbackFunc aCallbackFunc,
    void*                       aUserData       // IN: User data that will be passed back to callback function
    );

Sets the function to call to report the load or close of a child layer. This happens during draw or export of a map catalog or online layer. The layer handle provided via the callback can then be used in other function calls that take a layer handle so you can do things like customize vector styles. You can get the parent layer handle by calling GM_GetLayerInfo.

The callback function itself should match the following declaration:

typedef void (__stdcall *GM_ChildLayerOpCallbackFunc)
    ( 
    GM_LayerHandle_t32  aChildLayer,    // IN: Handle to new loaded layer
    GM_ChildLayerOp_t8  aChildLayerOp,  // IN: The operation (i.e. load or close) that just happened
    GM_LayerHandle_t32  aParentLayer,   // IN: Handle to new loaded layer's parent
    void*               aUserData,      // IN: User data original provided in call to set this callback
    void*               aReserved       // IN: Reserved for future use
    );

GM_SetAreaFeaturePointListEx
GM_Error_t32 GM_SetAreaFeaturePointListEx
    (
    GM_LayerHandle_t32      aLayer,             // Layer the area is in
    uint32                  aAreaIndex,         // Index of area in layer
    uint32                  aHoleIndex,         // Index of hole to apply locations to (0 for main parent area, 1 for first hole, etc.)
    const GM_Point_t*       aPointList,         // New list of points for area
    uint32                  aPointCount,        // Number of points in list (must be >= 3)
    boolean                 aPosInLayerCoords,  // Are the position in the layer coordinate system or the current coordinate system?
    const float*            aElevList           // IN: Per-vertex elevations for area feature, or NULL for none
    );

Same as GM_SetAreaFeaturePointList except that you can now also pass a list of per-vertex elevations to use for the area.


GM_SetBackgroundColor
COLORREF GM_SetBackgroundColor
    (
    COLORREF                aBgColor
    );

Sets the background color to use when drawing and exporting layers. The old background color is returned.


GM_SetElevationOverrides
GM_Error_t32 __stdcall GM_SetElevationOverrides
    (
    GM_LayerHandle_t32                  aLayer,     // in: layer to set options for
    const GM_ElevationOverrides_t*      aOptions    // in: elevation adjustment options for raster layer
    )

Sets the elevation adjustment options that are currently being applied to a given elevation layer. You should typically first call GM_GetElevationOverrides to get the current elevation adjustments for a layer, then change the appropriate options, then call this to modify the adjustments for the layer.


GM_SetExportCropAreas
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetExportCropAreas
    (
    const GM_AreaFeature_t* aAreaList,  // IN: List of areas to crop to (NULL to reset to default crop)
    uint32                  aNumAreas,  // IN: Number of areas in aAreaList
    const GM_Projection_t*  aAreaProj   // IN: Projection system the area coordinates are in (use NULL for current projection)
    );

Sets the list of crop areas to use when exporting using the export functions. If you set a crop area, then any subsequent exports will be cropped to those areas. If you pass in NULL for the crop area list, the crop area list will reset and the default rectangle-based cropping will be used.


GM_SetFeatureAttrList
GM_Error_t32 __stdcall GM_SetFeatureAttrList
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer the feature is in
    GM_FeatureClassType_t8  aFeatureClassType,  // IN: Type of feature class (area, point, line)
    uint32                  aFeatureIndex,      // IN: Index of feature in layer
    const GM_AttrValue_t*   aAttrList,          // IN: New list of attributes to associate with feature
    uint16                  aNumAttrs           // IN: Number of attributes in aAttrList
    );

Sets the attribute list to use for a given area, line, or point feature in the given layer.


GM_SetFeatureClass
GM_Error_t32 __stdcall GM_SetFeatureClass
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer the feature is in
    GM_FeatureClassType_t8  aFeatureClassType,  // IN: Type of feature class (area, point, line)
    uint32                  aFeatureIndex,      // IN: Index of feature in layer
    FeatureClass_t16        aFeatureClass       // IN: New feature class to assign to feature
    );

Sets the feature class for the given area, line, or point feature in the given layer.


GM_SetFeatureClassEnabled
boolean GM_SetFeatureClassEnabled
    (
    FeatureClass_t16        aFeatureClass,      // IN: Feature class to get info for
    GM_FeatureClassType_t8  aFeatureClassType,  // IN: Type of feature class (area, point, line)
    boolean                 aEnable             // IN: Enable or disable the feature class
    )

Enables or disables the display of the given feature class. The previous enable/disable state is returned.


GM_SetFeatureDescription
GM_Error_t32 __stdcall GM_SetFeatureDescription
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer the feature is in
    GM_FeatureClassType_t8  aFeatureClassType,  // IN: Type of feature class (area, point, line)
    uint32                  aFeatureIndex,      // IN: Index of feature in layer
    const char*             aDesc               // IN: New description for feature (NULL to reset to default)
    )

Sets the description for the given area, line, or point feature in the given layer. Pass in NULL for the description to reset to the original description for the feature (typically the feature classification).


GM_SetFeatureLabel
GM_Error_t32 __stdcall GM_SetFeatureLabel
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer the feature is in
    GM_FeatureClassType_t8  aFeatureClassType,  // IN: Type of feature class (area, point, line)
    uint32                  aFeatureIndex,      // IN: Index of feature in layer
    const char*             aLabel              // IN: New display label for feature.
    )

Sets the display label for the given area, line, or point feature in the given layer.


GM_SetLayerDescription
GM_Error_t32 __stdcall GM_SetLayerDescription
    (
    GM_LayerHandle_t32  aLayer,         // layer to set description for
    const char*         aDesc           // description to use (pass NULL to restore default)
    );

Sets the description to use for this layer in the GM_LayerInfo_t structure and when adding it to a map catalog.


GM_SetLayerEnabled
GM_Error_t32 GM_SetLayerEnabled
    (
    GM_LayerHandle_t32  aLayer,         // layer to enable or disable
    boolean             aEnable         // enable or disable the layer?
    );

Sets whether or not a given layer is enabled for display. If disabled, the layer will never be drawn or used as input for other translucent or texture-mapped layers.

All layers are enabled by default when initially loaded.


GM_SetLayerElevationAttribute
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetLayerElevationAttribute
    (
    GM_LayerHandle_t32      aLayer,             // Layer to modify
    const char*             aAttrName,          // Name of attribute to use for elevations
    uint32                  aReserved           // Reserved value for future expansion (must be zero)
    );

Sets the name of the feature attribute to use for when determining the elevation of a feature. Provide an empty string to reset this to the default behavior which searches for any number of known elevation attributes and also checks the display name for elevation-based types, like contour lines and spot elevations.


GM_SetLayerElevationUnits
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetLayerElevationUnits
    (
    GM_LayerHandle_t32      aLayer,             // Layer to modify
    GM_ElevUnits_t8         aElevUnits          // Elevation units to interpret values as
    )

Sets the elevation units to use for 3D vector features without an elevation unit in the elevation attribute.


GM_SetLayerHeightAttribute
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetLayerElevationAttribute
    (
    GM_LayerHandle_t32      aLayer,             // Layer to modify
    const char*             aAttrName,          // Name of attribute to use for height values
    uint32                  aReserved           // Reserved value for future expansion (must be zero)
    );

Sets the name of the feature attribute to use for determining the height of a feature point. Provide an empty string to reset this to the default behavior which searches for any number of known height attributes and also checks the display name for height-based types


GM_SetLayerHeightUnits
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetLayerHeightUnits
    (
    GM_LayerHandle_t32      aLayer,             // Layer to modify
    GM_ElevUnits_t8         aHeightUnits        // Height units to interpret values as
    )

Sets the height units to use for 3D vector features without a height unit in the height attribute.


GM_SetLayerLabelAttribute
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetLayerLabelAttribute
    (
    GM_LayerHandle_t32      aLayer,             // Layer to modify labels for
    const char*             aAttrName,          // Name of attribute to use for naming labels
    uint32                  aReserved           // Reserved value for future expansion (must be zero)
    );

Sets the name of the feature attribute to use for the display label for features that don't already have a display label.


GM_SetLayerPalette
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetLayerPalette
    (
    GM_LayerHandle_t32          aLayer,         // IN: layer to set palette for
    const GM_PaletteEntry_t*    aNewPalette,    // IN: pointer to list of palette entries to use for layer or NULL to reset palette to original palette
    uint32                      aNumPalEntries, // IN: number of palette entries in list
    void*                       aReserved       // IN: reserved for future use, must be NULL
    )

Sets the color palette for a given layer. The layer must be a palette-based image. The mPalette and mPaletteSize values in GM_LayerInfo_t for the layer will indicate the size and values in the current palette. You can restore the original palette for a layer by passing NULL. If you pass in less colors than in the original palette, only those colors that you provide will be updated.


GM_SetLayerUserData
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetLayerUserData
    (
    GM_LayerHandle_t32  aLayer,         // layer to set user data for
    void*               aUserData       // user data pointer/value to associate with layer
    )

Sets the user data to associate with the layer. This value can be retrieved by calling GM_GetLayerInfo. This is useful if you want to tie some structure or value to a particular layer without maintaining your own separate layer to value mapping.


GM_SetLayerUserText
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetLayerUserText
    (
    GM_LayerHandle_t32  aLayer,         // layer to set user text for
    const char*         aUserText       // user text to associate with layer
    )

Sets a text string to associate with the layer. This value can be retrieved by calling GM_GetLayerInfo. This text string will persist through a save to a workspace with GM_SaveWorkspace so if you reload that workspace the same text string will be available. This is useful if you want to tie some text to the layer that persists through a save.


GM_SetLicenseKey
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetLicenseKey
    (
    const char* aXmlKeyStr, // IN: full XML string with distribution license key
    void*       aReserved   // reserved for future use, must be NULL
    );

Use to provide the distribution license XML key that you were provided when purchasing a distribution license. Will return GM_Error_NotRegistered if the key could not be validated.

Note that this is different than a developer license file. A developer license file is good only on a single machine. You provide that via a 'GlobalMapper SDK.lic' file in your application folder on the test machine. You provide the distribution license key programmatically at application startup via this function. Do not provide the distribution license with your application as a file, make sure to embed it in the application source code itself to prevent unauthorized usage of your distribution licenses for your SDK-based application.


GM_SetLidarClassInfo
GM_Error_t32 GM_SetLidarClassInfo
    (
    GM_LidarClass_t8            aLidarClass,    // IN: Lidar class to set info for
    const GM_LidarClassInfo_t*  aClassInfo      // IN: New type info to use for Lidar class (NULL to reset to default)
    )

Sets information (name, color, group mask) for the given Lidar classification. To restore the class information to the default, pass in NULL for the class information structure. To just change one piece of information (i.e. color), you should first call GM_GetLidarClassInfo to get the existing class info, then just change the piece you want and call GM_SetLidarClassInfo with the update class info structure.


GM_SetLidarPoint
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetLidarPoint
    (
    GM_LayerHandle_t32      aLayer,             // IN: Layer to get point from
    uint64                  aPointIndex,        // IN: Index of Lidar point feature to update
    const GM_LidarPoint_t*  aLidarPoint,        // IN: Lidar point to update
    void*                   aReserved           // IN: Reserved for future use, must be NULL
    )

Sets a Lidar point feature in the given layer. The indexes should be in the range [0, GM_LayerInfo_t.mNumLidarPoints). You should use GM_GetLidarPoint to first get the values for a Lidar point before updating the values in the structure.

Note this could be extremely slow if you are modifying very large numbers of Lidar points. If you need to do that, contact us and we can add a new mechanism for editing Lidar data that is efficient for large sets.


GM_SetLineFeatureClassDrawStyle
GM_Error_t32 GM_SetLineFeatureClassDrawStyle
    (
    LineFeatureClass_t16    aFeatureClass,      // IN: Feature class to set draw style for
    const GM_LineStyle_t*   aLineStyle          // IN: New style to use for line (NULL to reset to default)
    );

Sets the default style and font to use for drawing lines with the given line classification. Pass NULL for the line style to reset the default drawing style to the default style for that classification of line.

Typically, when modifying the drawing style of a line class you'll want to call GM_GetLineFeatureClassDrawStyle to get the current drawing style, then just change what you need, then pass your copy in to this function.


GM_SetLineFeatureDrawStyle
GM_Error_t32 GM_SetLineFeatureDrawStyle
    (
    GM_LayerHandle_t32      aLayer,             // Layer the line is in
    uint32                  aLineIndex,         // Index of line in layer
    const GM_LineStyle_t*   aLineStyle          // New style to use for line
    );

Sets the pen style and font to use for drawing the given line object. Pass NULL for the line style to reset the drawing style to the default style for the classification of the line.

Typically, when modifying the drawing style of a line you'll want to call GM_GetLineFeature to get the current drawing style, then copy the mLineStyle member of the GM_LineFeature_t and just change what you need, then pass your copy in to this function.


GM_SetLineFeaturePointList
GM_Error_t32 GM_SetLineFeaturePointList
    (
    GM_LayerHandle_t32      aLayer,             // Layer the line is in
    uint32                  aLineIndex,         // Index of line in layer
    const GM_Point_t*       aPointList,         // New list of points for line
    uint32                  aPointCount,        // Number of points in list (must be >= 2)
    boolean                 aPosInLayerCoords   // Are the position in the layer coordinate system or the current coordinate system?
    );

Sets the list of point locations to use for the given line feature. The positions can either be specified in the native projection system of the layer (aPosInLayerCoords is TRUE) or in the current projection as returned by GM_GetProjection (aPosInLayerCoords is FALSE).


GM_SetLineFeaturePointListEx
GM_Error_t32 GM_SetLineFeaturePointListEx
    (
    GM_LayerHandle_t32      aLayer,             // Layer the line is in
    uint32                  aLineIndex,         // Index of line in layer
    const GM_Point_t*       aPointList,         // New list of points for line
    uint32                  aPointCount,        // Number of points in list (must be >= 2)
    boolean                 aPosInLayerCoords,  // Are the position in the layer coordinate system or the current coordinate system?
    const float*            aElevList           // IN: List of per-vertex elevations. Use NULL if no elevation list
    );

Same as GM_SetLineFeaturePointList except that you can now also pass a list of per-vertex elevations to use for the line.


GM_SetOrientation
GM_Error_t32 GM_SetOrientation
    (
    double              aOrientation    // Orientation of bitmap (0 is north up, 90 is east up, 180 is south up, 270 is west up)
    );

Allows for drawing data with a direction other than north to the top of the screen for most projections. A value of 0.0 is the default and implies no rotation. Technically, the orientation value is the number of degrees to rotate the rendered data counter-clockwise.


GM_SetPointFeatureClassDrawStyle
GM_Error_t32 GM_SetPointFeatureClassDrawStyle
    (
    PointFeatureClass_t16   aFeatureClass,      // IN: Feature class to set draw style for
    const GM_PointStyle_t*	aPointStyle         // IN: New style to use for point (NULL to reset to default)
    );

Sets the default style and font to use for drawing points with the given point classification. Pass NULL for the point style to reset the default drawing style to the default style for that classification of point.

Typically, when modifying the drawing style of a point class you'll want to call GM_GetPointFeatureClassDrawStyle to get the current drawing style, then just change what you need, then pass your copy in to this function.


GM_SetPointFeatureDrawStyle
GM_Error_t32 GM_SetPointFeatureDrawStyle
    (
    GM_LayerHandle_t32      aLayer,             // Layer the point is in
    uint32                  aPointIndex,        // Index of point in layer
    const GM_PointStyle_t*  aPointStyle         // New style to use for point
    );

Sets the symbol and font to use for drawing the given point feature. Pass NULL for the point style to reset the drawing style to the default style for the classification of the point.

Typically, when modifying the drawing style of a point you'll want to call GM_GetPointFeature to get the current drawing style, then copy the mPointStyle member of the GM_PointFeature_t and just change what you need, then pass your copy in to this function. You can add new symbols using the GM_AddCustomSymbol function.

There are some custom symbols built in and you can use a string with the following form: ShapeName + "_CUSTOM_" + size_R_G_B.

Example: you if you wanted a red Diamond with a scale of 5 pixels. You would use the string: "DIAMOND_CUSTOM_5_255_0_0"

The built in custom shapes include: DOT, SQUARE, DOT_EMPTY, VERT_BAR, CROSS, DIAG_CROSS, STAR, STAR_EMPTY, TRIANGLE, TRIANGLE_EMPTY, DIAMOND, DIAMOND_EMPTY, SQUARE_EMPTY, HALF_PIE and HALF_PIE_EMPTY.


GM_SetMessageCallback
void GM_SetMessageCallback
    (
    GM_MessageCallbackFunc aCallbackFunc
    );

Sets the function to call to display error and warning messages generated during SDK operations. If a message callback is provided, a message dialog will not be shown, instead the callback function will be called with the error or warning message that would have been displayed. The callback is then free to do whatever they'd like, including just ignore the message, in which case the error code will still be returned from the function generating the message like normal.


GM_GetMiscOption
GM_DLL_EXPORTED void* _stdcall GM_GetMiscOption
    (
    GM_MiscOpt_t32  aOpt,       // IN: Option to get
    void*           aReserved   // IN: Reserved for future use
    )

Gets the current value of an advanced/miscellaneous option. Typically the returned value is a GM_MiscOptVal_t8, but for options that use a string value it will be a const char*.


GM_SetMiscOption and GM_SetMiscOptionEx
GM_DLL_EXPORTED uint8 __stdcall GM_SetMiscOption
    (
    GM_MiscOpt_t32  aOpt,       // IN: Option to set
    uint8           aNewValue   // IN: New value (i.e. 1 to enable or 0 to disable), or value of other setting
    );
GM_DLL_EXPORTED void* __stdcall GM_SetMiscOptionEx
    (
    GM_MiscOpt_t32  aOpt,       // IN: Option to set
    void*           aNewValue,  // IN: New value (i.e. 1 to enable or 0 to disable), or value of other setting, including possibly pointer
    void*           aReserved   // IN: Reserved for future use, must be NULL
    );

Sets an advanced/miscellaneous option to use during operation. Returns the previous value. See definition of GM_MiscOpt_t32 type for a list of available options and their descriptions. Note that the GM_SetMiscOption function is deprecated as it can't handle options that take values over 8 bits in length, like GM_MiscOpt_SetLogFilename and GM_MiscOpt_SetTimingsFileName. You can use GM_SetMiscOptionEx for all options, just cast them to void*. The filename values take a const char*. For on/off options you can also use the special value GM_MiscOptVal_Toggle to toggle the value to the opposite of the current value.

If you just want to get the current value of an option and not change it, use GM_GetMiscOption.


GM_SetPointFeaturePosition
GM_Error_t32 GM_SetPointFeaturePosition
    (
    GM_LayerHandle_t32      aLayer,             // Layer the point is in
    uint32                  aPointIndex,        // Index of point in layer
    const GM_Point_t*       aPosition,          // New location of point
    boolean                 aPosInLayerCoords   // Is the position in the layer coordinate system or the current coordinate system?
    );

Sets the position to use for the given point feature. The position can either be specified in the native projection system of the layer (aPosInLayerCoords is TRUE) or in the current projection as returned by GM_GetProjection (aPosInLayerCoords is FALSE).


GM_SetProgressCallback
void GM_SetProgressCallback
    (
    GM_ProgressCallbackFunc aCallbackFunc
    );

Sets the function to call to report the progress of an operation, like the loading of a file. If a progress callback is provided, a progress dialog will not be shown, instead the callback function will be called. Pass NULL in for the callback function to restore the standard progress reporting dialog.


GM_SetQueryProjectionCallback
GM_DLL_EXPORTED void __stdcall GM_SetQueryProjectionCallback
    (
    GM_QueryProjectionCallbackFunc  aCallbackFunc
    );

Sets the function to call to select a projection for a layer when being loaded if the projection for that layer cannot be automatically determined. If a callback is provided, it will be called rather than the projection selection dialog being displayed. Pass NULL in for the callback function to restore the standard projection selection dialog.


GM_SetProjection
GM_Error_t32 GM_SetProjection
    (
    const GM_Projection_t*  aProj
    );
GM_SetProjectionEx
GM_Error_t32 GM_SetProjectionEx
    (
    const GM_Projection_t*  aProj,
    const GM_Rectangle_t*   aLatLonRect, // IN: Optional lat/lon/degrees rectangle for automatic selection of zone for zoned projections
    void*                   aReserved    // IN: Reserved for future use, must be NULL
    );

Sets the new projection. This is the projection that all draws and exports will be done in. It is also the projection that all world bound rectangles will be in.

If you pass in a zoned projection, like UTM, with no ZONE attribute or a ZONE or 0, the lat/lon rectangle (if provided) will be used to automatically select the best zone for the provided bounds. If no rectangle is provided, the last drawn rectangle will be used.

EXAMPLE 1: - Set projection to UTM Zone 15
GM_Projection_t theUtmProj;
::memset( &theUtmProj, 0, sizeof theUtmProj );
theUtmProj.mProjSys = GM_PRJ_UTM;
theUtmProj.mDatum = GM_DATUM_WGS_84;
theUtmProj.mUnit = GM_PRJ_UNIT_METERS;
theUtmProj.mAttrList[0].mAttr = ZONE;
theUtmProj.mAttrList[0].mValue = 15;
theUtmProj.mNumAttrs = 1;
GM_SetProjection( &theUtmProj );
EXAMPLE 2: - Set projection to Geographic (unprojected lat/lon)
GM_Projection_t theGeoProj;
::memset( &theGeoProj, 0, sizeof theGeoProj );
theGeoProj.mProjSys = GM_PRJ_GEO;
theGeoProj.mDatum = GM_DATUM_WGS_84;
theGeoProj.mUnit = GM_PRJ_UNIT_ARC_DEGREES;
GM_SetProjection( &theGeoProj );
EXAMPLE 3: - Set projection to UTM with Best Zone Automatically Selected
GM_Projection_t theUtmProj;
::memset( &theUtmProj, 0, sizeof theUtmProj );
theUtmProj.mProjSys = GM_PRJ_UTM;
theUtmProj.mDatum = GM_DATUM_WGS_84;
theUtmProj.mUnit = GM_PRJ_UNIT_METERS;
theUtmProj.mAttrList[0].mAttr = ZONE;
theUtmProj.mAttrList[0].mValue = 0; // use 0 to automatically selected best UTM zone
theUtmProj.mNumAttrs = 1;
GM_SetProjection( &theUtmProj );
EXAMPLE 4: - Set projection to UTM with Best Zone Automatically Selected from Bounding Box
// Set up lat/lon bounds to select zone for
GM_Rectangle_t theLatLonRect;
theLatLonBounds.mMinX = 
theLatLonRect.mMinX = -90.0;
theLatLonRect.mMaxX = theLatLonRect.mMinX + 0.1;
theLatLonRect.mMinY = 35.0;
theLatLonRect.mMaxY = theLatLonRect.mMinY + 0.1;

// Set up UTM projection with no zone provided
GM_Projection_t theUtmProj;
::memset( &theUtmProj, 0, sizeof theUtmProj );
theUtmProj.mProjSys = GM_PRJ_UTM;
theUtmProj.mDatum = GM_DATUM_WGS_84;
theUtmProj.mUnit = GM_PRJ_UNIT_METERS;
theUtmProj.mNumAttrs = 0;
GM_SetProjectionEx( &theUtmProj, &theLatLonRect, NULL );
GM_SetQuickPDFUnlockCode
GM_Error_t32 __stdcall GM_SetQuickPDFUnlockCode
    (
    const char* aUnlockCode // IN: unlock key for QuickPDFDLL library
    )

Sets the QuickPDF library (http://www.quickpdflibrary.com/) unlock code (required for PDF support). You have to purchase a QuickPDF library license to get an unlock code which you can then provide to enable PDF functionality in the SDK.


GM_SetRasterDisplayOptions
GM_Error_t32 GM_SetRasterDisplayOptions
    (
    GM_LayerHandle_t32                  aLayer,     // in: layer to set options for
    const GM_RasterDisplayOptions_t*    aOptions    // in: display options for raster layer
    );

Sets the options to use when displaying the given raster layer. This includes things like the translucency and transparency (if any) of the layer, the color intensity of the layer, and whether or not to crop the collar of the layer.

Typically you'll want to first call the GM_GetRasterDisplayOptions function for a layer to retrieve the current display options, then modify the options that you want to change, then call GM_SetRasterDisplayOptions to change the options. This will prevent you from inadvertently chaning an option that you didn't mean to change.


GM_SetRegistrationInfo
GM_Error_t32 GM_SetRegistrationInfo
    (
    const char* aRegName,   // name provided for the registration information
    uint32      aRegKey     // registration key
    );

Sets the registration name and code to use for this instance of the DLL. This can be used rather than the GMDLL_regkey.txt file to supply the registration information. Will return GM_Error_NotRegistered if the key is not valid for the name.


GM_SetRegistryKey
GM_Error_t32 GM_SetRegistryKey
    (
    const char* aKeyName    // location in registry under which to store settings
    );

Sets the base registry key from which settings should be stored/read. Settings will be stored in and read from HKEY_CURRENT_USER\Software\aKeyName\Global Mapper". Passing an empty string will reset the settings back to the default location which is shared with the Global Mapper application.


GM_SetSettingsFilePath
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_SetSettingsFilePath
    (
    const char* aPathName   // full path in which to look for and store settings files
    )

Sets the path where to look for and store settings files, like the custom_datums.txt file and files for custom types and symbols. By default the path of the GlobalMapperInterface.dll file will be used, but to comply with Windows standards for not storing things in the Program Files folder you should probably call this to set the path to something that can be written to, like the Application Data folder for your application.


GM_SetShaderDisplayOptions
GM_Error_t32 GM_SetShaderDisplayOptions
    (
    const GM_ShaderOptions_t*           aOptions    // in: shader display options
    );

Sets the options to use for the elevation shaders used to render gridded elevation data. Usually you'll want to call GM_GetShaderDisplayOptions to first get the current shader display options, then modify the values you want, then call this to update the options.


GM_SetVectorDrawScale
float GM_SetVectorDrawScale
    (
    float   aDrawScale  // in: scale factor to apply to line widths, symbols, and fonts
    );

Specifies the extra scaling factor to apply to line widths, point symbols, and fonts when drawing. This is useful when printing to try and keep vector features the same size as displayed.

This returns the previous vector draw scale so that it can be restored if necessary.


GM_SetVerticalDisplayOptions
GM_Error_t32 GM_SetVerticalDisplayOptions
    (
    const GM_VerticalDisplayOptions_t*  aVertDispOpts
    );

Sets the options to use (i.e. shader, water, lighting) when rendering gridded elevation data.


GM_ShowLayerOptionsDialog
GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_ShowLayerOptionsDialog
    ( 
    GM_LayerHandle_t32*     aLayerList,     // List of layers to draw or NULL for all
    uint32                  aLayerCount     // Number of layers in list (0 for all)
    );

Shows the options dialog for the provide layer(s). Currently this only works for vector layer options, such as setting up attribute-based labeling, etc.