Functions By category


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:


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.

With the exception of the Lidar Query functions, to use this functionality you will need to use Global Mapper Scripts Using GM_RunScript


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:

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:

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 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 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:

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:

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.

3rd Party Library Licensing

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.

Functions Alphabetically


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_AddLidarQueryToQuery


GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_AddLidarQueryToQuery
 (
 GM_LidarQueryHandle_t aAddToLidarQuery, // IN: Lidar query to update
 GM_LidarQueryHandle_t aAddFromLidarQuery, // IN: Lidar query to add points from
 void* aReserved // IN: Reserved for future use, must be NULL
 )

Adds one Lidar query to another. Note this will close any active iterator on the query, resetting the position of the GM_GetNextLidarQueryPoints call.


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_AddRemovePointToLidarQuery


GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_AddRemovePointToLidarQuery
 (
 GM_LidarQueryHandle_t aLidarQuery, // IN: Lidar query to update
 GM_LayerHandle_t32 aLayer, // IN: Layer point to add/remove
 uint64 aPointIndex, // IN: Index of Lidar point feature to update
 boolean aAddPoint // IN: Add or remove point?
 )

Adds or removes a Lidar point feature at the given index from the layer. Note this will close any active iterator on the query, resetting the position of the GM_GetNextLidarQueryPoints call. You can add/remove points from an existing Lidar query created with either the GM_CreateEmptyLidarQuery or GM_CreateLidarQuery functions.


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_CreateEmptyLidarQuery


GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_CreateEmptyLidarQuery
 (
 GM_LidarQueryHandle_t* aLidarQuery // OUT: Created Lidar query to be used in future calls
 )

Creates an empty Lidar query result that you can add individual Lidar points to or add entire queries, then perform operations on, like iterating through the points, modifying the points, etc. You can use the GM_AddRemovePointToLidarQuery or GM_AddLidarQueryToQuery to add/remove points in the query. You must call GM_FreeLidarQuery to free the memory used by the query once done with it.


GM_CreateLidarQuery


GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_CreateLidarQuery
 (
 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)
 const GM_Rectangle_t* aWorldBounds, // IN: World bounds for search space or NULL for all points in Lidar layers
 const GM_LidarQueryFilter_t* aFilter, // IN: Optional filter to apply to query (NULL if no extra filter)
 GM_LidarQueryHandle_t* aLidarQuery, // OUT: Created Lidar query to be used in future calls
 uint64* aQueryPoints // OUT: Number of points matching query
 )

Creates a Lidar query result that you can then perform operations on, like iterating through the points, modifying the points, etc. You must call GM_FreeLidarQuery to free the memory used by the query once done with it.


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:


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:

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:

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:


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_FreeLidarQuery


GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_FreeLidarQuery
 (
 GM_LidarQueryHandle_t aLidarQuery
 )

Frees a Lidar query created with GM_CreateLidarQuery.


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_GetLidarQueryInfo

GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetLidarQueryInfo
 (
 GM_LidarQueryHandle_t aLidarQuery, // IN: Lidar query to update
 GM_LidarQueryInfo_t* aQueryInfo // OUT: Information about query
 )

Retrieves information about the query, like the number of points and layer list.


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_GetNextLidarQueryPoints


GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_GetNextLidarQueryPoints
 (
 GM_LidarQueryHandle_t aLidarQuery, // IN: Lidar query to get data from
 GM_LidarPoint_t* aPointList, // OUT: Lidar point(s) to fill in
 uint32 aListSize, // IN: Max number of points to fetch
 GM_GetFeatureFlags_t32 aFlags, // IN: Flags for fetching Lidar point
 uint32* aNumPointsRead, // OUT: Number of points actually read
 void* aReserved // IN: Reserved for future use, must be NULL
 )

Retrieves the next block of points from the Lidar query. You should repeatedly call this function to iterate through all of the points matching the original Lidar query from the GM_CreateLidarQuery call. The returned aNumPointsRead value will match the aListSize value until you reach the end of the points.


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_GetProgressCallback

GM_ProgressCallbackFunc GM_GetProgressCallback
 (
 void
 );

Returns the current progress callback function, or NULL if no progress callback is set. Useful if you want to briefly change it.


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_InitLidarQueryFilter


GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_InitLidarQueryFilter
 (
 GM_LidarQueryFilter_t* aFilter,
 boolean aEmptyClassFilter // IN: should the class filter have all types disabled to start?
 )

Initializes a Lidar query filter. Call this before specifying your own query members.

A value of FALSE on aEmptyClassFilter indicates that all classes will be enabled by default. A value of TRUE indicates that all classes will be disabled by default. Update the member mClassFilter[aFilterClass] after initialization to set enable(1)/disable(0) status manually


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_LidarClassFilter_IsClassEnabled


GM_DLL_EXPORTED boolean __stdcall GM_LidarClassFilter_IsClassEnabled
 (
 const GM_LidarClassFilter_t* aClassFilter, // IN: Class filter to modify
 GM_LidarClass_t8 aClass // IN: Class to check
 )

Checks a Lidar class filter to see is a class is enabled in the filter. Returns TRUE if class in filter, FALSE otherwise.


GM_LidarClassFilter_SetClassEnabled


GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_LidarClassFilter_SetClassEnabled
 (
 GM_LidarClassFilter_t* aClassFilter, // IN: Class filter to modify
 GM_LidarClass_t8 aClass, // IN: Class to enable/disable
 boolean aEnable // IN: Enable the class?
 )

Enables or disables a Lidar class in a Lidar class filter.


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

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):

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:


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:

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_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_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_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.


GM_UpdateLidarQueryPoints


GM_DLL_EXPORTED GM_Error_t32 __stdcall GM_UpdateLidarQueryPoints
 (
 GM_LidarQueryHandle_t aLidarQuery, // IN: Lidar query to update points in
 GM_LidarFieldMask_t32 aValidFields, // IN: Which fields of data are valid to be updated
 const GM_LidarPoint_t* aNewPointData, // IN: Lidar point to update
 void* aReserved // IN: Reserved for future use, must be NULL
 )

Updates all of the points in the Lidar query with the new field values. Use this to edit the values for all points in a Lidar query created with a GM_CreateLidarQuery call.