TSLMapDataLayer Class Reference

Inheritance diagram for TSLMapDataLayer:

Detailed Description

Specialist data layer for the manipulation of map data.

The TSLMapDataLayer component handles map data manipulation. Map data is read-only and modification of this layer by the user is limited to changing the rendering of the entities within it.

The following capabilities are available through the TSLMapDataLayer component:

• Loading data
• Cache management
• Rendering
• Miscellaneous

The methods 'loadData' and 'removeData' (inherited from TSLDataLayer) allow complete maps to be loaded into and removed from the map layer.

Cache management is an important area for the map layer since it is not normally possible to hold a complete map in memory. The cache functions allows the user to fine tune the performance of a map layer by setting aside memory to hold recently accessed areas of the map so that they do not need to be loaded from disk when requested. The following cache properties are available:

• cacheSize , which determines how much memory to use for the cache
• cacheFlushLimit which determines how many map models to leave in memory when the cache needs to be flushed.
• clearCache method will clear all map models from memory.

Instances of this class should be destroyed using the destroy method.

Public Member Functions
	TSLMapDataLayer ()
void	cacheFlushLimit (int flush_limit)
int	cacheFlushLimit () const
void	cacheSize (int new_size)
int	cacheSize () const
bool	clearCache ()
bool	clearRuntimeProjection ()
bool	configurePersistentCache (const TSLPersistentCacheData *settings, TSLTileValidationFn validationFn=NULL, void *arg=NULL)
bool	copyRasterFeatures (TSLRasterDataLayer *rasterDataLayer, const char *destPath, const char *layerName=NULL, TSLFeatureID featureID=0, TSLEnvelope *envelope=NULL, TSLCopyFilesCallback progressCallback=NULL, void *arg=NULL)
TSLEntity *	findEntityID (TSLEntityID entityID, TSLSLMEntityRefHandler *handler)
TSLStyleID	getBackgroundColour () const
bool	getDetailLayerMUExtent (const char *layer_name, double *x1, double *y1, double *x2, double *y2) const
const char *	getDetailLayerName (int nth) const
bool	getDetailLayerTMCExtent (const char *layer_name, TSLTMC *x1, TSLTMC *y1, TSLTMC *x2, TSLTMC *y2) const
bool	getDynamicRendererFeatureBookSection (int indexOfRenderer, int indexOfFeatureBookSection, int &featureBookSectionNumber, const char *&featureBookSectionName) const
const char *	getDynamicRendererHint (int index) const
bool	getLayerLoadingThreshold (const char *layerName, double *upperThreshold, double *lowerThreshold) const
int	getNumDetailLayers () const
int	getNumDynamicRendererFeatureBookSections (int indexOfRenderer) const
int	getNumDynamicRendererHints () const
const char *	getOverviewLayer () const
bool	getPaletteFilename (TSLSimpleString &filename) const
bool	getPathlistFilename (TSLSimpleString &filename) const
bool	getSynchronousLoading () const
bool	isRuntimeProjected () const
int	metadata (int pos, char **fileName)
void	metadata (int sourceID, TSLSimpleString &filename) const
int	metadataCount () const
bool	MUToTMC (double x1, double y1, TSLTMC *x2, TSLTMC *y2) const
const TSLCoordinateSystem *	queryMapCoordinateSystem () const
TSLCoordinateSystem *	queryRuntimeCoordinateSystem () const
bool	removeLayer (const char *layer_name)
bool	setLayerLoadingThreshold (const char *layerName, double upperThreshold, double lowerThreshold=0.0)
bool	setOverrideCol (TSLStyleID override_colour=0)
bool	setRuntimeProjection (const TSLCoordinateSystem *projection, double greatCircleDistance, TSLRuntimeProjectionChangedCallback callback, void *arg)
bool	setRuntimeProjectionOrigin (double latitude, double longitude, TSLRuntimeProjectionChangedCallback callback, void *arg)
bool	setRuntimeProjectionParameters (TSLTMC initialTMCperMU=50, TSLTMC tmcPerMUFactor=10, bool detailedExtentCheck=false, int quickCheckGrid=3, int quickCheckPoints=32, int detailedCheckGrid=16, int detailedCheckPoints=128, double tileExtentGrowthScale=0.005)
void	setSynchronousLoading (bool synchronous)
bool	setTransparent (bool trans_mode=false, TSLStyleID trans_colour=0)
double	TMCperMU () const
bool	TMCToMU (TSLTMC x1, TSLTMC y1, double *x2, double *y2) const
bool	validateCache ()
void *	operator new (size_t size) TSL_NO_THROW
void *	operator new (size_t size, char *filename, int line)
Public Member Functions inherited from TSLDataLayer
void	addDrawingCallback (TSLDataLayerDrawingCallback *drawingCallback)
bool	addFeatureRendering (const char *featureName, TSLFeatureID featureID)
bool	addLoader (TSLFileLoader *loader, TSLLoaderAppCallback callback, void *arg, TSLAllLoadedCallback allLoadedCallback=0, void *arg2=0)
bool	addPathList (const TSLPathList *path_list)
void	cancelFlashback ()
bool	clearFeatureRendering (const char *featureName, TSLFeatureID featureID)
TSLDataHandler *	createDataHandler (const char *config_file=0)
TSLHistoryVersion	currentVersion () const
TSLDataHandler *	dataHandler ()
const TSLDataHandler *	dataHandler () const
void	destroy ()
bool	entityIsVisible (const TSLEntity *entity, const TSLDrawingSurface *drawingSurface) const
const TSLFeatureClassList *	featureList () const
const TSLFeatureClassList *	featureList (const char *detailLayerName) const
bool	fileModificationTime (const char *filename, TSLTimeType &lastModificationTime)
TSLEntity *	findEntity (TSLTMC x, TSLTMC y, TSLTMC aperture, int depth, const char *featureName=0, int drawingSurfaceID=-1)
bool	findFile (const char *filename, TSLSimpleString &foundPath) const
void	flashbackToTimestamp (TSLHistoryTimestamp timestamp, TSLLayerArchiveCallback archiveCallback, void *arg=0)
void	flashbackToTimestamp (TSLHistoryTimestamp timestamp, TSLLayerArchiveTileCallback archiveTileCallback, void *arg=0)
void	flashbackToVersion (TSLHistoryVersion version, TSLLayerArchiveCallback archiveCallback, void *arg=0)
void	flashbackToVersion (TSLHistoryVersion version, TSLLayerArchiveTileCallback archiveTileCallback, void *arg=0)
bool	getActiveLayerName (const TSLEnvelope &extent, double screenResolution, TSLSimpleString &activeLayerName) const
TSLEntityIterator *	getEntityIterator (const char *detailLayer, TSLSelector *selector=NULL, TSLEnvelope *extent=NULL, bool splitOptimisedPrimitives=true)
bool	getFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeInt attribute, int *result) const
bool	getFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeDouble attribute, double *result) const
bool	getFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeBool attribute, bool *result) const
bool	getFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributes *result) const
TSLFileLoader *	getLoader ()
bool	getMUExtent (double *x1, double *y1, double *x2, double *y2, int drawingSurfaceID=-1) const
bool	getTMCExtent (TSLTMC *x1, TSLTMC *y1, TSLTMC *x2, TSLTMC *y2, int drawingSurfaceID=-1) const
bool	getUUExtent (double *x1, double *y1, double *x2, double *y2, const TSLDrawingSurface *drawingSurface) const
bool	importHistory (TSLHistoryVersion mapVersion, TSLHistoryTimestamp timestamp, TSLHistoryImportSet *historySet)
bool	latLongToTMC (double latitude, double longitude, TSLTMC *x, TSLTMC *y, bool local=false) const
bool	latLongToTMC (int num, double *latitudes, double *longitudes, TSLTMC *xs, TSLTMC *ys, bool local=false) const
TSLDataLayerTypeEnum	layerType () const
bool	loadData (const char *filename)
bool	loadRendering (const char *filename)
void	notifyChanged (bool changed=true)
TSLMapQuery *	query (TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, int depth=-1, const char *featureName=NULL, int drawingSurfaceID=-1) const
TSLMapQuery *	query (TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, TSLSelector *selector, int drawingSurfaceID=-1) const
const TSLCoordinateSystem *	getCoordinateSystem () const
bool	queryVersionHistory (const TSLEnvelope &extent, TSLVersionHistorySet &history)
void	refreshFlashback ()
bool	removeData ()
void	releaseResources (int surfaceID)
bool	saveRendering (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION)
bool	setCoordinateSystem (const TSLCoordinateSystem *coordinateSystem)
bool	setFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeInt attribute, int value)
bool	setFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeDouble attribute, double value)
bool	setFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributeBool attribute, bool value)
bool	setFeatureRendering (const char *featureName, TSLFeatureID featureID, TSLRenderingAttributes *value)
bool	TMCToLatLong (TSLTMC x, TSLTMC y, double *latitude, double *longitude, bool local=false, bool boundCheck=true) const
bool	TMCToLatLong (int num, TSLTMC *xs, TSLTMC *ys, double *latitudes, double *longitudes, bool local=false) const
const TSLVersionHistorySet *	versionHistory () const

Protected Member Functions
	~TSLMapDataLayer ()

Constructor & Destructor Documentation

TSLMapDataLayer()

TSLMapDataLayer::TSLMapDataLayer

(

)

Default constructor.

~TSLMapDataLayer()

TSLMapDataLayer::~TSLMapDataLayer ( )

protected

Protected destructor to stop being instantiated on the stack Forces user to use new operator and destroy method.

Member Function Documentation

cacheFlushLimit() [1/2]

int TSLMapDataLayer::cacheFlushLimit

(

)

const

Query the current flush limit.

When the cache is full the system will remove the least recently used files to make room for the new data to load. The cache flush limit indicates the number of most recently used data files that the system will try keep in memory while flushing the cache. If the system cannot free enough memory and keep the flush limit number of files it will temporarily halve the flush limit until the cache memory usage is below 90% of the allowable cache size.

Returns the current flush limit.

cacheFlushLimit() [2/2]

void TSLMapDataLayer::cacheFlushLimit

(

int

flush_limit

)

Sets cache flush limit.

This method allows the user to set the cache flush limit for the TSLMapDataLayer. When the cache is full the system will remove the least recently used files to make room for the new data to load. The cache flush limit indicates the number of most recently used data files that the system will try keep in memory while flushing the cache. If the system cannot free enough memory and keep the flush limit number of files it will temporarily halve the flush limit until the cache memory usage is below 90% of the allowable cache size.

Parameters

flush_limit

Number of most recently used data files that the system will try to keep in memory while flushing the cache.

cacheSize() [1/2]

int TSLMapDataLayer::cacheSize

(

)

const

Query the amount of memory that the cache may currently use, in Kilobytes.

cacheSize() [2/2]

void TSLMapDataLayer::cacheSize

(

int

new_size

)

Set maximum size of the tile cache.

This method allows the user to set the amount of memory that the tile cache can use. To operate more efficiently the TSLMapDataLayer holds data in memory so that it does not need to reload data from disk every time a draw request is made. The larger the cache size the more data can be held in memory and draw requests are handled much more efficiently. However the client application must find a compromise between a large cache size and the memory requirements of the application itself.

The default tile cache is 32Mb (32768 KB)

Parameters

new_size

Size of the cache in kilobytes.

clearCache()

bool TSLMapDataLayer::clearCache

(

)

Clear the tile cache for this TSLMapDataLayer.

This method requests the TSLMapDataLayer to clear all cached data from memory and delete the files from the persistent cache (if used). After a call to clearCache any draw operation involving the TSLMapDataLayer will re-load all required map data from its original location.

Returns true on success, false otherwise.

clearRuntimeProjection()

bool TSLMapDataLayer::clearRuntimeProjection

(

)

Clears any runtime projection set with 'setRuntimeProjection'.

Returns true on success, false otherwise.

configurePersistentCache()

bool TSLMapDataLayer::configurePersistentCache	(	const TSLPersistentCacheData *	settings,
		TSLTileValidationFn	validationFn = NULL,
		void *	arg = NULL )

Adds and configures a persistent tile cache.

A persistent tile cache may be used to speed up the loading of tiles which have been downloaded via a slow connection, eg. web-based.

A persistent tile cache works in parallel to the memory tile cache. If a tile is not found in memory, then the persistent tile cache is searched. If it is found in the persistent tile cache, then the (optional) tile validation function is called to verify that the file is up-to-date. If so, then the tile is loaded and added to the memory tile cache. If the tile is not found in the persistent tile cache, then if configured, a local search may be performed using the TSLPathList added to the TSLDataLayer. If the tile is found locally or is invalid, it is added to the memory cache and optionally to the persistent cache. If the tile is not found locally, then it may be returned in the failure list of the draw function, if specified.

In releases of MapLink later than 4.6 SP1, the persistent cache will also store relevant configuration files for the map - e.g. the .map, .pal, .dtl and .pth files.

Parameters

settings	A TSLPersistentCacheData object containing the settings to use for the persistent cache.
validationFn	This is an optional function that may be used to validate any tiles that are in the cache, prior to them being used. If not specified, then all tiles in the cache are deemed to be valid.
arg	An optional argument that will be passed to the user's validation function.

copyRasterFeatures()

bool TSLMapDataLayer::copyRasterFeatures	(	TSLRasterDataLayer *	rasterDataLayer,
		const char *	destPath,
		const char *	layerName = NULL,
		TSLFeatureID	featureID = 0,
		TSLEnvelope *	envelope = NULL,
		TSLCopyFilesCallback	progressCallback = NULL,
		void *	arg = NULL )

Copies the raster files associated with a layer into the destination directory and then adds them to the supplied TSLRasterDataLayer.

Note: This method is not thread safe.

Parameters:

RasterDataLayer * - The layer to add the rasters to. NOTE this must have a pathlist set.

DestPath - the folder to copy the raster files into. If this does not exist it will be created. This folder gets added to the TSLRasterDataLayers pathlist

LayerName - name of the detail layer to copy from. If not set then the active layer is used.

featureID - only copy the rasters that match this feature ID. If not set then all are copied

envelope - only copy rasters that intersect the area. If not set then all are copied

progressCallback - optional callback to retrieve progress. If false is returned then copying is cancelled.

arg: user-defined argument, returned in callback.

findEntityID()

TSLEntity * TSLMapDataLayer::findEntityID	(	TSLEntityID	entityID,
		TSLSLMEntityRefHandler *	handler )

Find an entity in a seamless layer, given its ID.

This method returns a pointer to the first visible, selectable entity matching the given ID, If the map does not contain a seamless layer or if no such entity exists in the seamless layer, NULL is returned.

Entities are marked as visible or selectable via TSLRenderingAttributeVisible and TSLRenderingAttributeSelectable.

Parameters

entityID	the entity ID
handler	the entity reference handler

The entity reference handler must be configured appropriately otherwise this method will return NULL; in particular, if the handler has no associated seamless configuration object, then NULL will be returned.

getBackgroundColour()

TSLStyleID TSLMapDataLayer::getBackgroundColour

(

)

const

This method returns the background colour index for the loaded map.

Returns the background colour index of the map or -1 if the colour is not defined. The return value will either be a colour index or a composed RGB value. See tslcolourhelper.h for information on determining the type and in the case of an RGB value uncomposing it back into its respective components.

getDetailLayerMUExtent()

bool TSLMapDataLayer::getDetailLayerMUExtent	(	const char *	layer_name,
		double *	x1,
		double *	y1,
		double *	x2,
		double *	y2 ) const

Query extent of detail layer.

This method allows the user to get the extent of a particular detail layer of the map. The extent returned is in Map Unit co-ordinates.

Parameters

layer_name	Layer for which the extent are returned
(x1,y1)	Storage for bottom left corner
(x2,y2)	Storage for top right corner

Returns

true on success, false otherwise.

getDetailLayerName()

const char * TSLMapDataLayer::getDetailLayerName

(

int

nth

)

const

This method returns name of the 'nth' detail layer.

The name is stored in an internal buffer which may be overwritten by subsequent calls to this method.

Returns a pointer to the name of the 'nth' detail layer, NULL if no detail layers are loaded.

getDetailLayerTMCExtent()

bool TSLMapDataLayer::getDetailLayerTMCExtent	(	const char *	layer_name,
		TSLTMC *	x1,
		TSLTMC *	y1,
		TSLTMC *	x2,
		TSLTMC *	y2 ) const

Query extent of detail layer.

This method allows the user to get the extent of a particular detail layer of the map. The extent returned is in internal TMC co-ordinates.

Parameters

layer_name	Layer for which the extent are returned
(x1,y1)	Storage for bottom left corner
(x2,y2)	Storage for top right corner

Returns

true on success, false otherwise.

getDynamicRendererFeatureBookSection()

bool TSLMapDataLayer::getDynamicRendererFeatureBookSection	(	int	indexOfRenderer,
		int	indexOfFeatureBookSection,
		int &	featureBookSectionNumber,
		const char *&	featureBookSectionName ) const

The method returns the feature book section number and name for the dynamic renderer index and feature book index.

Parameters

indexOfRenderer	the index of the renderer.
indexOfFeatureBookSection	the index of the feature book section.
featureBookSectionNumber	returns for the feature book section number.
featureBookSectionName	returns the feature book section name.

Return false if the index values are invalid.

getDynamicRendererHint()

const char * TSLMapDataLayer::getDynamicRendererHint

(

int

index

)

const

This method returns the name of a TSLDynamicRenderer associated with the map.

The name can be used to workout which dynamic renderer to load.

Currently only a map created using the S-57 Dataset specifically configured for S-52 will have a TSLDynamicRenderer name.

Parameters

index

index to query

Returns

the name of the TSLDynamicRenderer or NULL if one does not exist.

getLayerLoadingThreshold()

bool TSLMapDataLayer::getLayerLoadingThreshold	(	const char *	layerName,
		double *	upperThreshold,
		double *	lowerThreshold ) const

Allows the top and bottom thresholds for which a particular layer is displayed to be queried at runtime.

Parameters

layerName	The name of the layer to query.
lowerThreshold	The lower value in Map Units per Pixel.
upperThreshold	The upper value in Map Units per Pixel.

Return true on success, false otherwise.

getNumDetailLayers()

int TSLMapDataLayer::getNumDetailLayers

(

)

const

This method returns the number of detail layers in the currently loaded map.

Returns number of detail layers in the currently loaded map. 0 if no map is loaded

getNumDynamicRendererFeatureBookSections()

int TSLMapDataLayer::getNumDynamicRendererFeatureBookSections

(

int

indexOfRenderer

)

const

The method getNumDynamicRendererFeatureBookSections returns the number of feature book sections for the given dynamic renderer index.

Parameters

indexOfRenderer

index of the dynamic renderer.

Returns

the number of feature book sections for the given dynamic renderer index.

getNumDynamicRendererHints()

int TSLMapDataLayer::getNumDynamicRendererHints

(

)

const

Returns the number of TSLDynamicRenderer names.

getOverviewLayer()

const char * TSLMapDataLayer::getOverviewLayer

(

)

const

This method returns name of a layer to be used for an overview.

At present, this method will return "thumbnail" or "overview" if those detail layers exist. Otherwise it returns that detail layer with the largest extent. In a future release, it may be possible to tag a detail layer to be used via MapLink Studio.

Returns a pointer to the name of the overview detail layer, NULL if no detail layers are loaded.

getPaletteFilename()

bool TSLMapDataLayer::getPaletteFilename

(

TSLSimpleString &

filename

)

const

This method queries the full path to the palette file associated with this map data layer if one exists.

Parameters

filename

This will be populated with the palette filename should one be associated

Return true if the filename parameter was populated with the paletted filename, false otherwise.

getPathlistFilename()

bool TSLMapDataLayer::getPathlistFilename

(

TSLSimpleString &

filename

)

const

This method queries the full path to the pathlist definition file associated with this map data layer if one exists.

Parameters

filename

This will be populated with the pathlist definition file path should one be associated

Return true if the filename parameter was populated with the pathlist filename, false otherwise.

getSynchronousLoading()

bool TSLMapDataLayer::getSynchronousLoading

(

)

const

Queries whether the layer is currently set to synchronous loading of its data. Synchronous loading is usually only required when printing as all data that is to be drawn must be loaded before the print draw occurs. Use the setSynchronousLoading method to alter the value of this setting.

isRuntimeProjected()

bool TSLMapDataLayer::isRuntimeProjected

(

)

const

Function that informs whether the Map was built with a coordinate system that requires the projection to be set at runtime by the user.

Returns

true if the map coordinate system requires a projection to be set at runtime, false otherwise.

metadata() [1/2]

int TSLMapDataLayer::metadata	(	int	pos,
		char **	fileName )

This method returns the source ID and the full path of the associated xml file for the given position.

Parameters

pos	the nth piece of metadata for which source ID and the xml file are required
fileName	the filename of the associated metadata (memory owned by the caller)

metadata() [2/2]

void TSLMapDataLayer::metadata	(	int	sourceID,
		TSLSimpleString &	filename ) const

The method returns the full path of the Envitia generated metadata xml file associated with the given source ID in the filename argument.

Parameters

sourceID	sourceID for which associated metadata xml file path should be returned
filename	The full path to the metadata file. An empty path is returned if there was no metadata file.

metadataCount()

int TSLMapDataLayer::metadataCount

(

)

const

This method returns a count of the number of metadata files associated with this layer.

MUToTMC()

bool TSLMapDataLayer::MUToTMC	(	double	x1,
		double	y1,
		TSLTMC *	x2,
		TSLTMC *	y2 ) const

Map unit to TMC conversion method.

Parameters

x1	input X (map units).
y1	input Y (map units).
x2	output X (TMC units).
y2	output Y (TMC units).

Return true on success, false otherwise.

operator new() [1/2]

void * TSLMapDataLayer::operator new

(

size_t

size

)

Overridden allocation to redirect to MapLink

operator new() [2/2]

void * TSLMapDataLayer::operator new	(	size_t	size,
		char *	filename,
		int	line )

When included in an MFC application in debug mode, the debug new expects this to be here. Override it and return the same as the normal one. The library must include it when compiled in release mode, since the user's application may be in debug mode.

queryMapCoordinateSystem()

const TSLCoordinateSystem * TSLMapDataLayer::queryMapCoordinateSystem

(

)

const

Query for the coordinate system associated with the map that is loaded in this layer.

This method requests the TSLMapDataLayer to return a TSLCoordinateSystem object which allows the user to access information concerning the transforms used to create the map. The TSLCoordinateSystem is only valid as long as no new map has been loaded into the layer since last obtaining the component.

If runtime projection is not in use, this will be the same object as returned from queryCoordinateSystem(). If runtime projection is in use, queryRuntimeCoordinateSystem() will return the transform given to setRuntimeProjection() and this method will return the transform associated with the loaded map.

queryRuntimeCoordinateSystem()

TSLCoordinateSystem * TSLMapDataLayer::queryRuntimeCoordinateSystem

(

)

const

Query for the runtime coordinate system added with setRuntimeProjection.

If runtime projection is not in use, this will return null.

removeLayer()

bool TSLMapDataLayer::removeLayer

(

const char *

layer_name

)

Remove existing detail layer.

This method requests the TSLMapDataLayer to remove the named detail layer. If the layer identified by input layer file name does not exist in the TSLMapDataLayer then this will have no effect. If the layer is currently on the display then nothing will happen until the data is redisplayed.

Parameters

layer_name

The name of the layer to be removed.

Returns

true if the layer is removed, false otherwise.

setLayerLoadingThreshold()

bool TSLMapDataLayer::setLayerLoadingThreshold	(	const char *	layerName,
		double	upperThreshold,
		double	lowerThreshold = 0.0 )

Allows the top and bottom thresholds for which a particular layer is displayed to be set at runtime, rather than relying on settings via MapLink studio.

Parameters

layerName	The name of the layer to apply the changes.
upperThreshold	The upper threshold in Map Units per pixel.
lowerThreshold	The lower threshold in Map Units per pixel. Defaulted to 0.0.

Return true on success, false otherwise.

setOverrideCol()

bool TSLMapDataLayer::setOverrideCol

(

TSLStyleID

override_colour = 0

)

Set the colour of monochrome raster images that may be displayed.

Parameters

override_colour

Colour to be used when drawing the set bits of the monochrome raster. This value is either an index in the colour table used by the TSLDrawingSurface or a composed RGB value. See tslcolourhelper.h for information on how to create this value.

Returns

true on success, false otherwise.

setRuntimeProjection()

bool TSLMapDataLayer::setRuntimeProjection	(	const TSLCoordinateSystem *	projection,
		double	greatCircleDistance,
		TSLRuntimeProjectionChangedCallback	callback,
		void *	arg )

Changes the current projection if using runtime projection.

If a callback is given, then the recalculation of the projection will happen in a background thread, and the callback will be called when it is complete. Drawing operations will fail if called during the time when the recalculation is being performed.

If the callback parameter is null then the calculations happen synchronously in the main thread, within this call.

The same callback pointer may be given to both setRuntimeProjection and setRuntimeProjectionOrigin. The reason parameter of the callback indicates the reason for the callback.

If the runtime projection is referenced against a different datum to that against which the map was created, then a suitable datum transform must be set on the projection before calling this method.

NOTE : The TMCperMU value for the specified coordinate system is currently ignored when the coordinate system is used for run-time projection. Under those circumstances the TMCperMU is calculated according to the input data extent.

Parameters

projection	the new coordinate system to use. This is copied, the pointer is not stored.
greatCircleDistance	a map tile will be projected if any part of the tile falls within this distance from the projection origin (metres). Set this value to the maximum geographical area the you need to view. Reducing the value makes setprojection and setProjectionOrigin work faster. Avoid values so large that the edge of the map projection becomes visible.
callback	callback to call when new projection calculated, or null if calculations to be synchronous
arg	user-defined argument, returned in callback.

Returns

true on success, false on failure.

setRuntimeProjectionOrigin()

bool TSLMapDataLayer::setRuntimeProjectionOrigin	(	double	latitude,
		double	longitude,
		TSLRuntimeProjectionChangedCallback	callback,
		void *	arg )

Changes the origin of the current projection if using runtime projection.

If a callback is given, then the recalculation of the projection will happen in a background thread, and the callback will be called when it is complete. Drawing operations will fail if called during the time when the recalculation is being performed.

If the callback parameter is null then the calculations happen synchronously in the main thread, within this call.

The same callback pointer may be given to both setRuntimeProjection and setRuntimeProjectionOrigin. The reason parameter of the callback indicates the reason for the callback.

Parameters

(latitude,longitude)	the new projection origin to be set, degrees
callback	callback to call when new projection calculated, or null if calculations to be synchronous
arg	user-defined argument, returned in callback.

Returns

true on success, false on failure.

setRuntimeProjectionParameters()

bool TSLMapDataLayer::setRuntimeProjectionParameters	(	TSLTMC	initialTMCperMU = 50,
		TSLTMC	tmcPerMUFactor = 10,
		bool	detailedExtentCheck = false,
		int	quickCheckGrid = 3,
		int	quickCheckPoints = 32,
		int	detailedCheckGrid = 16,
		int	detailedCheckPoints = 128,
		double	tileExtentGrowthScale = 0.005 )

This method is used for defining the parameters used for runtime projection of a compatible map generated from MapLink Studio. Tweaks to these settings may dramatically improve or degrade the performance of runtime projection but may cause a trade off in terms of the correctness of viewed areas.

These settings are used to decide which tiles in the map may potentially be displayed for the current centre of projection and the maximum great circle distance specified to the setRuntimeProjection method. This set of tiles is independent of the current view. For certain projections, this decision process may, depending on the parameters set, compile a list that does not completely include all tiles that should be visible. This will particularly be the case where certain tiles are dramatically warped such as around the edges of the world or poles. This calculation is only performed when the projection changes, not when the displayed area changes.

Once the set of potentially displayable tiles have been decided upon, the actual set of tiles for display is determined when the surface is redrawn and is dependent upon the viewing area. The relatively expensive process of projecting the features within those tiles takes place when the tiles are loaded for a draw, potentially in a background thread.

If an application uses a defined subset of projections, adjusting these settings may be advisable, assuming the new settings are tested against these projections and target areas. On the other hand, in an application where a variable set of projections may be used, it would usually be best to leave these settings at their defaults.

Customers upgrading from MapLink 5.4 and earlier - which do not include this method - may need to call this to pass the earlier defaults if the new values cause issues. The settings are now also stored per layer.

This decision process is split into two separate stages:

• Determining a valid TMC per MU for the output projection. As all MapLink drawing and calculations is dependent upon a TMC per MU value for the loaded data, this must be calculated first. This is an iterative process, seeded by the initialTMCperMU parameter, where the current value is tested to see if all the projected data will fit in that output TMC space. Should the current value not fit the data, then it is multiplied by the tmcPerMUFactor parameter and tested again. This will continue until a valid value is found. Tweaking these settings is usually not necessary but in certain cases may speed up this iterative process.
• Determining the extent of the projected map tiles. As the projection of map tile boundaries is expensive, MapLink tries to limit this process to only the tiles that may visible. It first does this by limiting the tested tiles to those that are within a Great Circle distance of the projection centre. Then it takes a small set of sample points from each tile, projects them and sees if they are within the output space. This small set is defined by the quickCheckGrid and quickCheckPoints parameters. If none of the projected points appear in the output space, then, if the detailedExtentCheck parameter is true, MapLink does a second more detailed check using a larger set of input tile points. The size of this larger set is defined by the detailedCheckGrid and detailedCheckPoints parameters. Once the projected extent has been calculated, it is expanded using the tileExtentGrowthScale value in order to cope with the situation where a tile boundary 'bulges'. The extent is then stored and during a redraw is used to decide if this particular tile intersects the display extent.

Parameters

initialTMCperMU	Seed value used for determining the TMC per MU value to be used in the output projection. Must be greater than 0. Current default value is 50. Earlier MapLink versions used 1 as the default.
tmcPerMUFactor	Value that the current TMC per MU value is multiplied by on each iteration of the process to find a valid TMC per MU value for the projected data. Must be greater than 1. Current default value is 10. Earlier MapLink versions used 100 as the default.
detailedExtentCheck	For tiles where the quick sampling of points to the output projection doesn't produce and points valid in the output projection, should a more detailed check take place. Current default value is false. Earlier MapLink versions used true as the default.
quickCheckGrid	The number of horizontal grid lines to used for the quick sampling. Must be greater than 0. Default value is 3.
quickCheckPoints	The number of sample points along each horizontal grid line to used for the quick sampling. Must be greater than 0. Default value is 32.
detailedCheckGrid	The number of horizontal grid lines to used for the detailed sampling. Must be greater than 0. Default value is 16.
detailedCheckPoints	The number of sample points along each horizontal grid line to used for the detailed sampling. Must be greater than 0. Default value is 128.
tileExtentGrowthScale	The fraction of the full tile height/width to added to the top and bottom/left and right of the tile extent when determining the sampling grid. Default value is 0.005

Returns

true on success, false otherwise.

setSynchronousLoading()

void TSLMapDataLayer::setSynchronousLoading

(

bool

synchronous

)

Call with the synchronous parameter set to true to load map data synchronously, it also inhibits callbacks after each map tile is loaded.

Call this during printing to ensure that all map data is loaded synchronously, as printing may use a different tile resolution from those displayed on the screen.

The allLoadedCallback callback (as passed in the addLoader() method) is always called at the end of loading all tiles, but the tile loaded callback (as passed in the addLoader() method) is only called for asynchronous loading.

setTransparent()

bool TSLMapDataLayer::setTransparent	(	bool	trans_mode = false,
		TSLStyleID	trans_colour = 0 )

Set transparency mode for raster.

This method allows the user to set the transparency mode for monochrome raster images loaded by the TSLMapDataLayer. The transparency mode is default to false when a raster is added to the TSLMapDataLayer.

Parameters

trans_mode	True for the raster image to be transparent. Default value is false.
trans_colour	Colour of the raster image to be transparent. This value is a colour index in the colour table used by the TSLDrawingSurface. Default value is 0, for no colour to be transparent.

Returns true on success, false otherwise.

TMCperMU()

double TSLMapDataLayer::TMCperMU

(

)

const

This method returns the number of TMCs per Map Unit for the loaded map.

Returns the number of TMCs per Map Unit if data is loaded, 0.0 if not.

TMCToMU()

bool TSLMapDataLayer::TMCToMU	(	TSLTMC	x1,
		TSLTMC	y1,
		double *	x2,
		double *	y2 ) const

TMC to map unit conversion method.

Parameters

x1	input X (TMC units).
y1	input Y (TMC units).
x2	output X (map units).
y2	output Y (map units).

Return true on success, false otherwise.

validateCache()

bool TSLMapDataLayer::validateCache

(

)

Validate the tiles in the persistent tile cache for this TSLMapDataLayer.

Returns true on success, false otherwise.