TSLOpenGLDataOptimiser Class Reference

Detailed Description

A utility class that allows additional processing of MapLink maps and rasters for improved runtime performance when used in conjunction with the OpenGL 2D Drawing Surface.

Processing a map containing vector data significantly reduces the amount of work required at runtime when loading new map tiles for display with the TSLStaticMapDataLayer which results in substantially improved application responsiveness when zooming and panning around the map.

Processing either a map containing raster data or a standalone raster converts the raster data into one of several formats that can be directly understood by the graphics hardware. This results in both reduced data loading times and reduced application memory usage as the rasters do not need to be decoded in order to be displayed. Processed raster maps and rasters can be used with all data layers that accept the unprocessed versions.

Please refer to the MapLink Pro Developer's Guide for additional information.

Public Types
enum	RasterCompressionFormatEnum { RasterCompressionS3TC , RasterCompressionETC1 , RasterCompressionETC2 }

Static Public Member Functions
static bool	compressRaster (const char *inputRaster, const char *inputMask, const char *outputRaster, RasterCompressionFormatEnum format, const TSLOpenGLDataOptimiserOptions &options, TSLOpenGLDataOptimiserProgressCallback *progressCallback)
static bool	optimiseMap (const char *mapLocation, const TSLOpenGLDataOptimiserOptions &options, const TSLOpenGLDataOptimiserFormats &formats, TSLOpenGLDataOptimiserProgressCallback *progressCallback)
static bool	rasterETCCompressionAvailable ()

Member Enumeration Documentation

RasterCompressionFormatEnum

enum TSLOpenGLDataOptimiser::RasterCompressionFormatEnum

Enumeration defining the possible compressed formats that rasters may be converted into by the processor. Each format has different advantages and disadvantages, so an application should choose the format(s) most appropriate to their use cases.

All formats are lossy so it is recommended that rasters compressed into one of these formats are generated (such as through MapLnk Studio) in a lossless format such as PNG in order to to avoid introducing multiple sets of compression artifacts.

Enumerator
RasterCompressionS3TC	The S3 Texture Compression format. This format is widely supported by desktop hardware and is a safe choice when preparing maps or rasters for use on desktop systems. Support on mobile devices is limited. Rasters compressed in S3TC format will be in either DXT1, DXT3 or DXT5 format depending on the presence of an alpha channel or mask on the source raster.
RasterCompressionETC1	The Ericsson Texture Compression format. This format is widely supported on mobile devices and is a safe choice when preparing maps or rasters for use on mobile systems. Newer desktop graphics cards that support OpenGL 4.3 or later are required to support this format.
RasterCompressionETC2	The Ericsson Texture Compression format, version 2. Recent mobile and desktop devices support this format. Support is required for mobile devices implementing OpenGL ES 3.0 and desktop graphics cards supporting OpenGL 4.3 or later. When supported by the target device this format is normally the best choice.

Member Function Documentation

compressRaster()

static bool TSLOpenGLDataOptimiser::compressRaster ( const char * inputRaster, const char * inputMask, const char * outputRaster, RasterCompressionFormatEnum format, const TSLOpenGLDataOptimiserOptions & options, TSLOpenGLDataOptimiserProgressCallback * progressCallback )

static

Converts a raster into a compressed form for fast loading when used with the OpenGL 2D Drawing Surface. The compressed raster can be used instead of the input raster with any data layer that can load the original raster, such as the TSLRasterDataLayer.

This method is thread safe and may be called from multiple threads simultaneously.

Parameters

inputRaster	The full path to the raster to compress. This may either be a raster of any supported image type, or the output of TSLRasterUtility Functions::rasterToPyramid. If a MapLink TPF pyramid is given as the input raster, the output of this function will also be a TPF pyramid.
inputMask	Optional, may be NULL. If set, this should be the full path to a mask for the raster. The mask will be merged into the raster for compression. If the input raster contains an alpha channel, the compressed raster's alpha channel will be a combination of the input raster's alpha channel and the mask. Mask rasters should be either monochrome or greyscale (1 or 8 bpp) and the same size as the raster.
outputRaster	The full path to write the compressed raster to.
format	The format to write the compressed raster as.
options	General options that control common features of the processor. See the documentation for TSLOpenGLDataOptimiserOptions for details.
progressCallback	Optional. A callback object to receive progress callbacks. If the input raster is not a MapLink TPF pyramid then only one callback will be issued when the compression completes. Otherwise, one callback will be issued for each raster within the pyramid being compressed.

Returns

true if the raster was successfully compressed, false otherwise. Any errors encountered will be logged to the TSLThreadedErrorStack. Applications can use the error callback to receive notifications as errors occur during processing.

optimiseMap()

static bool TSLOpenGLDataOptimiser::optimiseMap ( const char * mapLocation, const TSLOpenGLDataOptimiserOptions & options, const TSLOpenGLDataOptimiserFormats & formats, TSLOpenGLDataOptimiserProgressCallback * progressCallback )

static

Processes the given MapLink map for fast loading and display when used with the OpenGL 2D Drawing Surface. The processing consists of converting any rasters in a map into formats natively supported by the graphics hardware, and pre-triangulating vector geometry so it does not need to be done at runtime.

This processing stage can also be done by at the time the map is created by MapLink Studio.

Vector maps that have been processed will have significantly reduced tile loading times when used with the TSLStaticMapDataLayer, and raster maps will have reduced tile loading times and memory usage when used with both the TSLStaticMapDataLayer and TSLMapDataLayer.

This method is thread safe and may be called from multiple threads simultaneously.

Parameters

mapLocation	The map to process.
options	General options that control common features of the processor. See the documentation for TSLOpenGLDataOptimiserOptions for details.
formats	Determines which compressed raster formats should be generated for maps containing rasters, and whether vector tiles within the map should be processed.
progressCallback	Optional. A callback object to receive progress callbacks on the state of the processing.

Returns

true if the map was successfully processed, false otherwise. Any errors encountered will be logged to the TSLThreadedErrorStack. Applications can use the error callback to receive notifications as errors occur during processing.

rasterETCCompressionAvailable()

static bool TSLOpenGLDataOptimiser::rasterETCCompressionAvailable ( )

static

Returns whether the processor can locate the external ETCpack executable necessary for creating ETC1 and ETC2 compressed rasters.

If this method returns false, application will need to provide the full path to the ETCpack executable when processing maps or rasters into ETC1 or ETC2 formats through the TSLOpenGLDataOptimiserOptions::etcPackLocation() method.

The use of ETCpack is subject to the terms listed in the appropriate section of the MapLink Pro 3rd Party Licences document. If these terms are incompatible with the application the ETCpack executable should be removed from the MapLink installation in order to prevent its use.