TSLOpenGLSurface Class Reference

Inheritance diagram for TSLOpenGLSurface:

Detailed Description

Common class for functionality shared between all platform drawing surfaces that draw using OpenGL.

Only one OpenGL context per thread is allowed. Therefore there is a one to one relationship between the drawing surface and a thread. If an application wishes to migrate a context and the associated drawing surface to a different thread it must call the makeContextCurrent method on the derived drawing surface class from that thread.

Additionally this means that any function calls that result in draws occurring (such as drawDU or any methods which have a redraw parameter) must originate in the thread associated with the OpenGL context.

The drawing surface internally tracks the OpenGL state for performance reasons. This means that applications that modify the OpenGL state may cause incorrect rendering if the drawing surface is not notified of the change. Access to the internal state tracker is provided through the stateTracker() method - applications can use this class to ensure the drawing surface maintains a consistent view of the current OpenGL state.

Rendering inside custom data layers can normally only be performed using Open GL or the TSLRenderingInterface. Any drawing performed using GDI or X11 will not display correctly. To use GDI or X11 in conjunction with the OpenGL drawing surface the layer must be marked as a non-native layer using the TSLPropertyNonNativeDrawing data layer property. Specific information on using non-native layers can be found in the class documentation for each of the drawing surface platform interface classes and the MapLink developer's guide.

Note that the TSLOptionDoubleBuffered drawing surface option has no effect on the drawing surface. Any OpenGL contexts created by the surface will automatically be double buffered.

GPU and device drivers

The MapLink Pro TSLOpenGLSurface works best with either NVIDIA or AMD GPUs.

The following should force the selection of either on Windows if the machine has multiple GPUs and the device drivers are sufficiently new enough.

extern "C" {
  __declspec(dllexport) int AmdPowerXpressRequestHighPerformance = 1;
  __declspec(dllexport) DWORD NvOptimusEnablement = 0x00000001;
}

The MapLink Pro TSLOpenGLSurface will work with Intel GPUs however you need the latest drivers directly from Intel on Windows and the latest Mesa drivers on Linux (potentially with patches for Haswell and older, ideally you should use newer GPUs from Intel).

If an application crashes inside of the OpenGL drivers then we would highly recommend you first upgrade with drivers directly from the GPU manufacturer and retest your application.

Realtime Reprojection

The OpenGL Drawing Surface supports the concept of reprojecting vector and raster at runtime on the GPU.

The following projections are currently supported:

• Mercator
• Transverse Mercator
• Stereographic
• Gnomonic

Additional projections can be added if necessary, please contact sales.nosp@m.@env.nosp@m.itia..nosp@m.com to discuss.

This functionality relies upon OpenGL extensions that require an up-to-date OpenGL driver and fairly modern hardware.

This extension has been implemented for the Haswell 4600 GPU on Linux. Extensive testing has been done with this GPU and a number of issues have been found and work-arounds were implemented. A number of issues were resolved at the driver or lower level. As such we would recommend that the developer tests the target hardware early enough to ensure that the GPU and drivers are sufficiently capable and robust for this extension. If necessary we can provide consultancy to help with this assessment or any necessary tailoring in MapLink to support a particular GPU.

OpenGL 3.3 is required with the following OpenGL extensions:

• ARB_transform_feedback2
• ARB_shading_language_420pack
• ARB_draw_indirect
• ARB_gpu_shader_fp64 (FP64)
• ARB_shader_subroutine

There are fallback mechanisms for all the above extensions, however the fallbacks have an impact on performance and complexity of the shaders.

The FP64 extension is one of the more critical extensions. Only a small number of the projections are supported if this extension is not present as we have to emulate the 64bit double maths. This significantly complicates the shader code.

The following extensions are used if present:

• ARB_texture_storage
• ARB_shader_image_load_store

DataLayers Supported

The following DataLayers are supported when this extension is enabled:

• TSLStandardDataLayer
• TSLStaticMapDataLayer
• TSLKMLDataLayer
• TSLDirectImportDataLayer
• TSLCustomDataLayer

The following layers should work but have not been validated:

• TSLRasterDataLayer
• TSLFilterDataLayer and associated layers
• TSLMapDataLayer - please use the Static version.

The following layers will not work:

• Any grid layer. This limitation is being looked at.
• TSLS63DataLayer. Some of the issues will be addressed when the grid layers are dealt with.

The TSLCustomDataLayer is known to work however there are limitations with how you can use a custom data-layer.

The TSLRenderingInterface does not support the drawing of all geometry. Only symbols and text can be drawn.

Layers can be drawn from a Custom data-layer. The contents of the layers can be automatically reprojected.

Data Conditioning

All data that is to be reprojected at runtime has to be in a Scaled WGS84 Latitude/Longitude coordinate system.

The data should have sufficent points to ensure that lines are projected correctly and as expected. Very long lines will not have additional points added. Only the points present in the data will be reprojected.

Limitations

Realtime reprojection has a number of limitations that limit how the data is drawn and have an impact on performance. Please contact suppo.nosp@m.rt@e.nosp@m.nviti.nosp@m.a.co.nosp@m.m for additional information or guidance.

• Custom datalayers can only draw text and symbols via the TSLRenderingInterface. Drawing with X11 or GDI is not supported when realtime reprojection is enabled for a Custom datalayer.
• Text and symbols are positioned on the CPU. This is an expensive operation and care should be given to minimise the amount displayed are each detail level.
• Text and symbol rotation is not currently corrected for the display projection.
• Arc and Ellipses are not drawn correctly when displayed with multi-pass linestyles.
• User geometry is not supported.
• The Geometry Rendering has to be Feature based. Geometry based rendering is ignored.
• If the Geometry is modified then you have to call notifyChanged() on the data-layer. This instructs MapLink to re-process the whole layer.
• Rendering attributes can change but can result in re-batching.
• Changing the FeatureID on a Geometry object (entity) will require notifyChanged() to be called.
• Changing the Feature rendering require notifyChanged() to be called.
• Decluttering on/off works TBC. Range decluttering is only evaluated on first draw.
• Custom linestyles are expensive to draw (Pen Up/Down style). The linestyles may be drawn stretched or compressed. This occurs due to the reprojection of the line segments such that they may be stretched or compressed.
• Lines will be drawn as single segments. Joins and end-caps will be square.
• Data should be prepared to ensure that sufficent points are present so that the lines/polygons are correctly warped. The term is densified. This is particularly important for overlay geometry. Geodetic primitives should be considered as additional points are added between the control points.
• Dynamic Renderers are excluded because this modifies the Tile contents. Please contact sales.nosp@m.@env.nosp@m.itia..nosp@m.com if you require this functionality as this will require additional development.
• You can not share layers that are realtime reprojected between instances of TSLDrawingSurface.

Howto setup a Map DataLater

A TSLStaticMapDataLayer is required to be added to the Drawing Surface. This is the coordinate providing layer.

Only a TSLStaticMapDataLayer can provide the data TSLCoordinateSystem and the Drawing TSLCoordinateSystem.

TSLStaticMapDataLayer's need to be marked as Realtime Reprojection layer as follows:

m_mapLayer = new TSLStaticMapDataLayer();
 
m_mapLayer->addLoader( m_mapLayerLoader1, NULL, NULL, NULL, NULL );
m_mapLayer->drawCacheSize( cacheSize );
if( !m_mapLayer->loadData( path.c_str() ) )
{
  TSLSimpleString message;
  TSLThreadedErrorStack::errorString( message );
  QMessageBox::critical( NULL, "Failed to load .map data", message.c_str(), QMessageBox::Ok );
  return false;
}
surface->addDataLayer( m_mapLayer, name.c_str() );
surface->setDataLayerProps( name.c_str(), TSLPropertyRealtimeReprojection, true );

The order shown above of the method calls is significant.

Reprojected layers must not be buffered (TSLPropertyBuffered). Reprojected layers can have an opacity value.

All other layers should use the coordinate providing layers 'data' coordinate system. This can be queried as follows:

const TSLCoordinateSystem *cs = NULL;
const TSLDataLayer* csLayer( m_surface->getCoordinateProvidingLayer() );
if( csLayer && csLayer->layerType() == TSLDataLayerTypeStaticMapDataLayer )
{
  const TSLStaticMapDataLayer* csLayerMap( reinterpret_cast<const TSLStaticMapDataLayer*>( csLayer ) );
  cs = csLayerMap->queryMapCoordinateSystem();
}

'cs' if not NULL will be the TSLCoordinateSystem to use. If it is NULL then you do not have a TSLCoordinateSystem.

The display projection is set using the following:

m_currentCoordinteSystem = TSLCoordinateSystem::createByDatumName( 10005, "CS", "World Geodetic System 1984" );
 
if( m_currentCoordinteSystem )
{
  setOK = m_currentCoordinteSystem->setProjectionMercator( newProjectionCentreLon, 0.0 );
}
 
//Minimum Map Unit width the surface will zoom to
minimumRange = 25000000;
greatCircleDistance = 9704000.0;
 
m_mapLayer->clearRuntimeProjection();
m_mapLayer->setRuntimeProjection( m_currentCoordinteSystem, greatCircleDistance, NULL, NULL );

The projection centre is set using the following:

m_mapLayer->setRuntimeProjectionOrigin( newProjectionCentreLat, newProjectionCentreLon, NULL, NULL );

When a projection is changed there will be a stall while the shaders are switched and the GPU data buffers are updated.

Note

The drawing surface will make all map-layer runtime coordinate system TMC per MU and offsets match. The TMC per MU will be the smallest value from all the layers.

The runtime coordinate system origins must all match.

Picking

The geometry that is displayed on the screen uses the Display TSLCoordinateSystem from the coordinate providing layer.

The pixel position should be converted to latitude and longitude using the Display TSLCoordinateSystem.

This latitude and longitude should then be converted to the TMC coordinate system of the layer that needs to be queried.

If the methods on the TSLDrawingSurface are used then the conversions occur internally using the coordinate providing layer.

Setting up a TSLStandardDataLayer

The geometry inside of a TSLStandardDataLayer must be in the Coordinate Providing layers TMC coordinate system.

Geodetic Primitives will automatically reproject and the positions of non-geodetic primitives will also be reprojected.

The TSLStandardDataLayer has to be marked to be included as part of the reprojection as follows:

surface->addDataLayer( m_stdDataLayer, layerName );
surface->setDataLayerProps( layerName, TSLPropertyRealtimeReprojection, true );

Coordinate Providing Layer and Coordinate Systems

The coordinate providing layer may be obtained using the following:

const TSLCoordinateSystem *cs = NULL;  // TSLCoordinateSystem to use for conversions
const TSLDataLayer *layer = m_surface->getCoordinateProvidingLayer();
if( csLayer && csLayer->layerType() == TSLDataLayerTypeStaticMapDataLayer )
{
  const TSLStaticMapDataLayer* csLayerMap( reinterpret_cast<const TSLStaticMapDataLayer*>( csLayer ) );
  cs = csLayerMap->queryMapCoordinateSystem();
}

The two types of TSLCoordinateSystem can be obtained via:

const TSLCoordinateSystem *dataCoordinateSystem = csLayerMap->queryMapCoordinateSystem();
TSLCoordinateSystem *displayCoordinateSystem = csLayerMap->queryRuntimeCoordinateSystem();

The 'dataCoordinateSystem' is the the coordinate system that the data is in. Any non-coordinate providing layer should use this to position the geometry correctly.

the 'displayCoordinateSystem' is used by the GPU for drawing the geometry. This should be used for converting positions on the screen to latitude and longitude.

Using a TSLCustomDataLayer

There are a number of limitations around using a custom datalayer. However custom datalayers are still a very powerful concept. The TSLKMLDataLayer has been implemented as a custom datalayer. The data is actually stored in a set of TSLStandardDataLayer and TSLRasterDataLayer which are drawn via the TSLRenderingInterface.

There are essentially three ways of drawing when using Realtime Reprojection:

• Draw symbols and text only via the TSLRenderingInterface
• Draw using OpenGL or TSLOpenGLTrackHelper.
• Draw using a datalayer.

The AdvancedSample shows how to draw using the first two uses of a TSLCustomDataLayer.

The TSLKMLDataLayer uses the third. Please refer to the TSLClientCustomDataLayer and TSLCustomDataLayerHandler documentation.

In essence if you are drawing using OpenGL, Text/Symbols, or a datalayer you need to position the geometry using the coordinate providing layers data coordinate system, not the display coordinate system.

Using a TSLKMLDataLayer

The TSLKMLDataLayer needs to be told what TSLCoordinateSystem to use before loading the KML data.

const TSLCoordinateSystem *cs = NULL;  // TSLCoordinateSystem to use for conversions
const TSLDataLayer *layer = m_surface->getCoordinateProvidingLayer();
if( csLayer && csLayer->layerType() == TSLDataLayerTypeStaticMapDataLayer )
{
  const TSLStaticMapDataLayer* csLayerMap( reinterpret_cast<const TSLStaticMapDataLayer*>( csLayer ) );
  cs = csLayerMap->queryMapCoordinateSystem();
}
 
kmlDataLayer->setCoordinateSystem( cs );

MapLink Studio Map Creation requirements

The following settings are guidelines for a Realtime reprojection map.

• Map Coordinate System - Realtime Reprojection
• TMC Per MU : 5 Million
• TMC offset : 0, 0
• Tiling : Manual, at least 4 tiles at the top-level (least detailed).
• Tiling Strategy : Range Based
• Perceptual Filter : Optional
• Raster Pyramid settings
  • Nugget Size 1024x1024
  • Optimise Pyramid off
  • 'Tiling only' should be checked if the map will only be displayed with the OpenGL drawing surface.
  • 'Maximum Pyramid depth' should be set to 4 if the map will also be displayed with other surfaces.
  • Raster format: TIFF (quickest) / PNG (next quickest) / JPEG (slowest)
• Number of Layers
  • The number of layers should be sufficent to ensure too much data is not displayed at each display range.
• Tile on Disk Size
  • The vector tiles on disk should not exceed 1Mb. The main impact is on load and display performance so you may be able to adjust the size based upon your application and hardware.
  • Raster tile size you have less control about.
• Optimisations
  • Map Generation Dialog - turn on Remove all unused features
  • Convert Colour index values to RGB

The realtime reprojection code will also use Optimised tile data. This will save time on loading data as we will have one less processing stage.

Cache Sizing

The cache size allocated to a layer needs to be at least double what you would normally assign. This is because there will be two copies of the data, one un-projected and the second projected.

Potential GPU issues

GPU FP64 support may not be present. We can implement the projections using FP65 emulation. Please contact sales.nosp@m.@env.nosp@m.itia..nosp@m.com to discuss.

GPU sin and cos may not be accurate or there may be issues with particular values or quadrants. This seems to be very dependent on GPU and may require specific work arounds in the shader. Please contact sales.nosp@m.@env.nosp@m.itia..nosp@m.com to discuss if you find a problem with the GPU you are using.

GPU atan2 and atan may have problems with particular values or quadrants. This seems to be a general issue and the work around is implemented generically.

Shader sub-routines may cause register spill warnings. You will need to update your drivers. On Linux this may require the building of Mesa with a set of specific patches or from a development branch. Please contact suppo.nosp@m.rt@e.nosp@m.nviti.nosp@m.a.co.nosp@m.m for more information.

Mercator display issues near the poles

The Mercator projection currently exhibits some display artifacts near the north and south poles, specifically missing fills in the displayed polygons. This is due to the tiling setup in the shipped maps, and the amount the data is warped near the poles.

Until these issues are fixed there are 2 workarounds. For more information please contact suppo.nosp@m.rt@e.nosp@m.nviti.nosp@m.a.co.nosp@m.m.

The first workaround is to increase the number of (vertical) tiles within the map. This will reduce the visible artifacts by inserting a tile border near the poles. This will not eliminate the artifacts, however will maintain compatibility with the other supported projections. For this workaround the recommended minimum tiling is 4 x 16. Note that the increased number of tiles will cause a performance reduction when viewing data near the poles.

The second workaround is to apply output clipping to the valid range of the Mercator projection (-80 to 84 degrees latitude). This will eliminate the artifacts when displaying Mercator, however will cause missing data over the poles for other projections.

Public Member Functions
virtual	~TSLOpenGLSurface ()
float	acquireDepthSlice ()
virtual TSLDrawingSurface *	clone (bool copyUserData=false)
double	coordinateCentreX () const
double	coordinateCentreY () const
TSLOpenGLSurface *	createChildSurface ()
float	currentDepthSlice () const
float	depthSliceIncrement () const
void	flushPendingDraws ()
void	enableRealtimeReprojection (const char *name, bool enable)
double	getSwitchRangeForFP64 () const
bool	getLayerStorageStrategy (const char *layerName, TSLOpenGLStorageStrategyEnum &strategy) const
bool	getLayerTransparencyHint (const char *layerName, TSLOpenGLTransparencyHintEnum &hint) const
float	incrementDepthSlice (uint32_t numDrawItems)
const float *	modelViewMatrix () const
const float *	projectionMatrix () const
bool	setAntialiasingMode (TSLOpenGLAntialiasModeEnum mode)
bool	targetFrameBuffer (GLuint fbo)
GLuint	targetFrameBuffer () const
float	setDepthSlice (uint32_t numDrawItems)
bool	setDisplayMetrics (double dpiX, double dpiY, int horizontalSizePixels, int verticalSizePixels)
void	setSwitchRangeForFP64 (double range)
bool	setLayerStorageStrategy (const char *layerName, TSLOpenGLStorageStrategyEnum strategy)
bool	setLayerTransparencyHint (const char *layerName, TSLOpenGLTransparencyHintEnum hint)
void	setRGBABackgroundColour (unsigned char r, unsigned char g, unsigned char b, unsigned char a)
TSLOpenGLStateTracker *	stateTracker ()
void	shaderPreloadEnabled (bool enabled)
bool	shaderPreloadEnabled () const
bool	preloadProjectionShaders (const TSLCoordinateSystem *cs, bool loadfp64Variant)
void	flushLoadedShaders ()
void	rasterProjectionControlPointParameters (unsigned int minPointsPerRaster, unsigned int maxPointsPerRaster, unsigned int gridSizePixels)
void	textRoundingEnabled (bool enabled)
bool	textRoundingEnabled () const
void	textRoundingAmount (unsigned int px)
unsigned int	textRoundingAmount () const
Public Member Functions inherited from TSLDrawingSurface
bool	clearAllRendering ()
bool	clearDynamicColours ()
TSLRasterBuffer *	createRasterBuffer (unsigned int width, unsigned int height, TSLRasterBuffer::Format format, TSLRasterBuffer::FilterMode filterMode=TSLRasterBuffer::Linear)
bool	declutterIsVisible (const char *feature_name, double resolution=0.0, const char *layer_name=0) const
bool	drawDU (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLDeviceUnits x2, TSLDeviceUnits y2, bool clear, bool updateExtentOnly=false)
bool	drawUU (double x1, double y1, double x2, double y2, bool clear, bool updateExtentOnly=false)
bool	DUToLatLong (TSLDeviceUnits x, TSLDeviceUnits y, double *latitude, double *longitude, bool local=false, bool boundCheck=true) const
bool	DUToMU (TSLDeviceUnits x1, TSLDeviceUnits y1, double *x2, double *y2) const
bool	DUToTMC (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLTMC *x2, TSLTMC *y2) const
bool	DUToUU (TSLDeviceUnits x1, TSLDeviceUnits y1, double *x2, double *y2) const
TSLEntity *	findEntityDU (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth, const char *feature_name=NULL)
TSLEntity *	findEntityUU (double x, double y, double aperture, int depth, const char *feature_name=NULL)
TSLEntity *	findSelectedEntityDU (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth=-1, bool ignoreMapDataLayers=false)
TSLEntity *	findSelectedEntityUU (double x, double y, double aperture, int depth=-1, bool ignoreMapDataLayers=false)
bool	getColourIndices (int **indices, int *num)
TSLDataLayer *	getCoordinateProvidingLayer ()
const TSLDataLayer *	getCoordinateProvidingLayer () const
bool	getDeclutterRange (const char *featureName, double *innerLimit, double *outerLimit, const char *dataLayerName=0, const char *detailLayerName=0)
bool	getDeviceCapabilities (int &horizontalSizeMM, int &verticalSizeMM, int &horizontalSizePixels, int &verticalSizePixels) const
bool	getDeviceCapabilities (TSLDeviceCapabilities &capabilities) const
void	getDUExtent (TSLDeviceUnits *x1, TSLDeviceUnits *y1, TSLDeviceUnits *x2, TSLDeviceUnits *y2) const
bool	getFillStyleIndices (int **indices, int *num)
bool	getFontStyleIndices (int **indices, int *num)
bool	getLineStyleIndices (int **indices, int *num)
void	getMUExtent (double *x1, double *y1, double *x2, double *y2) const
bool	getSymbolStyleIndices (int **indices, int *num)
TSLDrawingSurfaceTiledBufferControl *	getTiledBufferController ()
void	getTMCExtent (TSLEnvelope &extent) const
void	getUUExtent (double *x1, double *y1, double *x2, double *y2) const
bool	getViewedLatLongRange (double *latitude, double *longitude, double *range, bool local=false, bool boundCheck=true) const
bool	latLongToDU (double latitude, double longitude, TSLDeviceUnits *x, TSLDeviceUnits *y, bool local=false) const
bool	latLongToMU (double latitude, double longitude, double *x, double *y, bool local=false) const
bool	latLongToTMC (double latitude, double longitude, TSLTMC *x, TSLTMC *y, bool local=false) const
bool	latLongToUU (double latitude, double longitude, double *x, double *y, bool local=false) const
bool	MUToDU (double x1, double y1, TSLDeviceUnits *x2, TSLDeviceUnits *y2) const
bool	MUToLatLong (double x, double y, double *latitude, double *longitude, bool local=false, bool boundCheck=true) const
bool	MUToTMC (double x1, double y1, TSLTMC *x2, TSLTMC *y2) const
bool	MUToUU (double x1, double y1, double *x2, double *y2) const
bool	pan (double x1, double y1, bool auto_redraw=true)
bool	pan (double x1, double y1, TSLDeviceUnits xDU, TSLDeviceUnits yDU, bool auto_redraw=true)
TSLMapQuery *	query (const char *layerName, TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, int depth=-1, const char *feature_name=NULL) const
TSLMapQuery *	query (const char *layerName, TSLTMC x1, TSLTMC y1, TSLTMC x2, TSLTMC y2, TSLSelector *selector) const
bool	redraw ()
bool	reset (bool auto_redraw=true)
bool	resize (double x1, double y1, double x2, double y2, bool auto_redraw=true, bool keep_aspect=false)
bool	rotate (double angle)
double	rotation () const
bool	setDeclutterRange (const char *featureName, double innerLimit, double outerLimit, const char *dataLayerName=0, const char *detailLayerName=0)
bool	setDeviceCapabilities (const int horizontalSizeMM=0, const int verticalSizeMM=0, const int horizontalSizePixels=0, const int verticalSizePixels=0)
bool	setDeviceCapabilities (const TSLDeviceCapabilities &capabilities)
void	setRedrawCallback (TSLDrawingSurfaceDrawCallback *callback)
bool	setupDynamicColours (const char *filename)
bool	setViewedLatLongRange (double latitude, double longitude, double range, bool local=false, bool auto_redraw=true, bool keep_aspect=false)
void	TMCperDU (double &xr, double &yr)
double	TMCperUU ()
bool	TMCToDU (TSLTMC x1, TSLTMC y1, TSLDeviceUnits *x2, TSLDeviceUnits *y2) const
bool	TMCToLatLong (TSLTMC x, TSLTMC y, double *latitude, double *longitude, bool local=false, bool boundCheck=true) const
bool	TMCToMU (TSLTMC x1, TSLTMC y1, double *x2, double *y2) const
bool	TMCToUU (TSLTMC x1, TSLTMC y1, double *x2, double *y2) const
bool	updateEntityExtent (TSLEntity *entity, const char *layerName)
void	userUnitOrigin (double x_origin, double y_origin)
void	userUnitOrigin (TSLUUEnum origin_enum)
void	userUnits (double factor)
double	userUnits ()
bool	UUToDU (double x1, double y1, TSLDeviceUnits *x2, TSLDeviceUnits *y2) const
bool	UUToLatLong (double x, double y, double *latitude, double *longitude, bool local=false, bool boundCheck=true) const
bool	UUToMU (double x1, double y1, double *x2, double *y2) const
bool	UUToTMC (double x1, double y1, TSLTMC *x2, TSLTMC *y2) const
bool	wndResize (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLDeviceUnits x2, TSLDeviceUnits y2, bool auto_redraw=true, TSLResizeActionEnum action=TSLResizeActionNone)
bool	zoom (double percent, bool zoom_in, bool auto_redraw=true)
	TSLDrawingSurface ()
virtual	~TSLDrawingSurface ()
void	clearSymbolList ()
void	clearFontList ()
void	clearLineList ()
void	clearFillList ()
bool	removeFillStyle (TSLStyleID style)
bool	removeLineStyle (TSLStyleID style)
bool	removeSymbolStyle (TSLStyleID style)
bool	removeFontStyle (TSLStyleID style)
TSLStyleID	createFontID (const TSLSimpleString &name, TSLFontType meaningOfName, int fontWeight, bool italic=false, bool underline=false, bool antiAliased=false, const unsigned char *memoryBlock=NULL, TSLSize memoryBlockSize=0)
TSLStyleID	createStandardLineID (const unsigned char *pattern, TSLSize patternLength, int initialOffset, TSLLineScalingType scaleType)
TSLStyleID	createSymbolLineID (int symbolID, double size=0.0, TSLDimensionUnits sizeUnits=TSLDimensionUnitsUndefined, float rotation=0.0f, double anchorPointX=0.0, double anchorPointY=0.0, TSLDimensionUnits anchorPointUnits=TSLDimensionUnitsUndefined)
TSLStyleID	createStandardFillID (const unsigned char *pattern=NULL, TSLSize patternSizeInBytes=0, int patternXSize=0, int patternYSize=0)
TSLStyleID	createSymbolFillID (int symbolID, double size=0.0, TSLDimensionUnits sizeUnits=TSLDimensionUnitsUndefined, float rotation=0.0f, double anchorPointX=0.0, double anchorPointY=0.0, TSLDimensionUnits anchorPointUnits=TSLDimensionUnitsUndefined)
TSLStyleID	createSVGSymbolID (const TSLSimpleString &name, const unsigned char *memoryBlock=NULL, TSLSize memoryBlockSize=0)
TSLStyleID	createFontSymbolID (const TSLSimpleString &name, TSLFontType meaningOfName, const unsigned char *memoryBlock=NULL, TSLSize memoryBlockSize=0)
TSLStyleID	createRasterSymbolID (const TSLSimpleString &name, int xorigin, int yorigin, bool scaleable, const unsigned char *memoryBlock=NULL, TSLSize memoryBlockSize=0)
TSLStyleID	createSymbolIDFromSymbol (TSLStyleID symbolID, int numberofColourPairs, const int *colourFrom, const int *colourTo)
Public Member Functions inherited from TSLDrawingSurfaceBase
bool	addDataLayer (TSLDataLayer *data_layer_interface, const char *data_id)
bool	addDynamicRenderer (TSLDynamicRenderer *renderer, TSLFeatureID featureID=-1, const char *layerName=0)
bool	addFeatureRendering (const char *featureName, TSLFeatureID featureID)
void	attach (TSLDeviceContext handle)
void	attach (TSLWindowHandle handle)
void	attach (TSLDrawableHandle handle)
bool	bringInFrontof (const char *move_data_layer, const char *target_data_layer)
bool	bringToFront (const char *move_data_layer)
bool	clearAllDeclutterData (const char *layer_name=0)
void	clearAllDynamicRenderers ()
bool	clearBackgroundColour ()
bool	clearDeclutterData (const char *feature_name, const char *layer_name=0)
bool	clearDynamicRenderer (TSLFeatureID featureID=-1, const char *layerName=0)
bool	clearFeatureRendering (const char *featureName, TSLFeatureID featureID)
bool	clearFrame ()
bool	copyDeclutterData (const char *src_feature_name, const char *dest_feature_name, const char *src_layer_name=0, const char *dest_layer_name=0)
void	detach ()
void	detachAllDynamicRenderers ()
bool	detachDynamicRenderer (TSLFeatureID featureID=-1, const char *layerName=0)
const char *	featureClass (TSLFeatureID feature_id)
bool	forceLayer (const char *data_id, const char *detail_layer_name)
bool	getBackgroundColour (TSLStyleID *value)
bool	getColourValue (int colour, unsigned char &r, unsigned char &g, unsigned char &b)
TSLDataLayer *	getDataLayer (const char *data_id)
bool	getDataLayerInfo (int N, TSLDataLayer **dataLayer, const char **layerName) const
bool	getDataLayerProps (const char *data_id, TSLPropertyEnum property_id, TSLPropertyValue *old_value)
bool	getDeclutterStatus (const char *feature_name, TSLDeclutterStatusResultEnum *value, const char *dataLayerName=0, const char *detailLayerName=0)
bool	getDeclutterStatus (TSLFeatureID feature_id, TSLDeclutterStatusResultEnum *value, const char *dataLayerName, const char *detailLayerName=0)
TSLDynamicRenderer *	getDynamicRenderer (TSLFeatureID featureID=-1, const char *layerName=0)
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
int	getNumDataLayers () const
bool	getOption (TSLOptionEnum option)
void	id (int id_)
int	id () const
bool	idleProcess ()
bool	loadDeclutter (const char *filename)
bool	loadRendering (const char *filename)
TSLPickResultSet *	pick (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth, TSLPickSelector *selector=0)
TSLPickResultSet *	pick (const char *data_id, TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth=-1, TSLPickSelector *selector=0)
bool	queryActiveLayer (const char *data_id, char *detail_layer_name, int detail_layer_name_size)
bool	removeDataLayer (const char *data_id)
bool	saveDeclutter (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION)
bool	saveRendering (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION)
bool	sendToBack (const char *move_data_layer)
bool	sendToBackOf (const char *move_data_layer, const char *target_data_layer)
bool	setBackgroundColour (int value)
bool	setCoordinateProvidingLayer (const char *layer_name)
bool	setDataLayerProps (const char *data_id, TSLPropertyEnum property_id, TSLPropertyValue new_value)
bool	setDeclutterStatus (const char *feature_name, TSLDeclutterStatusEnum value, const char *dataLayerName=0, const char *detailLayerName=0)
bool	setDeclutterStatus (TSLFeatureID feature_id, TSLDeclutterStatusEnum value, const char *dataLayerName=0, const char *detailLayerName=0)
bool	setDeclutterStatusOnAllFeatures (TSLDeclutterStatusEnum value, const char *dataLayerName=0, const char *detailLayerName=0)
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	setFrame (int style, int colour, int thickness)
virtual void	setOption (TSLOptionEnum option, bool value)
double	TMCperMU ()
TSLDrawingSurfaceTypeEnum	type () const
void	userWord (void *ptr) const
void *	userWord () const
bool	cloneDynamicRenderersFrom (const TSLDrawingSurfaceBase *otherSurface)
void	addDuplicateLayers (bool value)
virtual	~TSLDrawingSurfaceBase ()

Protected Member Functions
	TSLOpenGLSurface ()
Protected Member Functions inherited from TSLDrawingSurfaceBase
	TSLDrawingSurfaceBase ()

Additional Inherited Members
Static Public Member Functions inherited from TSLDrawingSurface
static void	cleanup ()
static bool	copy (TSLDrawingSurface *copyTo, TSLDrawingSurface *copyFrom, bool copyUserData=false)
static TSLStyleID	getIDOfNearestColour (int r, int g, int b)
static bool	loadStandardConfig (const char *path=0, bool delayLoadIncludes=false)
static bool	setupColours (const char *filename)
static bool	setupFillStyles (const char *filename, bool delayLoadIncludes=false)
static bool	setupFonts (const char *filename, bool delayLoadIncludes=false)
static bool	setupLineStyles (const char *filename, bool delayLoadIncludes=false)
static bool	setupSymbols (const char *filename, bool delayLoadIncludes=false)
static void	disableAntiAliasFonts ()
static void	enableAntiAliasFonts ()
Static Public Member Functions inherited from TSLDrawingSurfaceBase
static bool	addLoader (TSLFileLoader *loader)
static bool	addPathList (TSLPathList *path_list)
static bool	findFile (const char *filename, TSLSimpleString &foundPath)
static TSLFileLoader *	getLoader ()
Protected Attributes inherited from TSLDrawingSurfaceBase
void *	m_classID

Constructor & Destructor Documentation

~TSLOpenGLSurface()

virtual TSLOpenGLSurface::~TSLOpenGLSurface ( )

virtual

TSLOpenGLSurface()

TSLOpenGLSurface::TSLOpenGLSurface ( )

protected

Member Function Documentation

acquireDepthSlice()

float TSLOpenGLSurface::acquireDepthSlice

(

)

When mixing custom OpenGL rendering with MapLink rendering inside a custom data layer, drawing may not give the expected results due to MapLink's use of the depth buffer to ensure ordering when issuing rendering commands out of back-to-front sequence.

This method asks the drawing surface to reserve the next available depth buffer value for the application to use for the current layer being drawn, and returns the value in clip space/normalised device coordinate space. This value can be used to ensure drawing appears in the correct order relative to MapLink rendering without the application having to issue all drawing commands from back to front.

See the OpenGL Drawing Surface - Interspersing Custom Rendering with MapLink Rendering section of the MapLink developer's guide for more information and code examples.

Returns the next available depth value in clip space/normalised device coordinate space. Each call reserves a new depth value for application use that is in front of any previous depth values.

clone()

virtual TSLDrawingSurface * TSLOpenGLSurface::clone ( bool copyUserData = false )

virtual

The OpenGL drawing surface cannot be cloned. This method always returns NULL.

Implements TSLDrawingSurface.

coordinateCentreX()

double TSLOpenGLSurface::coordinateCentreX

(

)

const

Returns the X coordinate in TMC space that the drawing surface mapped to the centre of the screen during the last or current draw. This can be used in custom data layers to assist in positioning items correctly on the display when performing rendering that does not use the MapLink TSLRendering Interface.

Subtracting this value from an item's TMC location gives the necessary translation in order to correctly position it on the drawing surface.

coordinateCentreY()

double TSLOpenGLSurface::coordinateCentreY

(

)

const

Returns the Y coordinate in TMC space that the drawing surface mapped to the centre of the screen during the last or current draw. This can be used in custom data layers to assist in positioning items correctly on the display when performing rendering that does not use the MapLink TSLRendering Interface.

Subtracting this value from an item's TMC location gives the necessary translation in order to correctly position it on the drawing surface.

createChildSurface()

TSLOpenGLSurface * TSLOpenGLSurface::createChildSurface

(

)

Creates a new drawing surface that shares the OpenGL context of this drawing surface.

A child drawing surface can be useful when performing offscreen rendering using MapLink, such as when drawing to an OpenGL framebuffer object. As a child surface is a separate drawing surface to its parent, it may use entirely different settings such as window size and contain different data layers to its parent without affecting the parent.

A child drawing surface may be created or deleted within a draw call of its parent, e.g. inside the implementation of TSLClientCustomDatalayer::drawLayer.

A child surface does not automatically include any of the data layers that were present in the parent surface at the time of its creation.

As the OpenGL context used by a child drawing surface is the same as the context used by its parent, a child drawing surface is bound to the same thread as its parent. Detaching or deleting the parent drawing surface automatically detaches any child surfaces that exist.

A child surface uses the same TSLOpenGLStateTracker as its parent, therefore changes made through the child's state tracker will automatically be reflected in its parent's state tracker and vice versa.

currentDepthSlice()

float TSLOpenGLSurface::currentDepthSlice

(

)

const

Returns the current depth value in clip space/normalised device coordinate space.

This method does not allocate a new depth slice.

depthSliceIncrement()

float TSLOpenGLSurface::depthSliceIncrement

(

)

const

Returns the amount that each draw of an object increments the depth value by.

The depth value has to be incremented by a sufficent amount to ensure that each object is drawn at a unique depth.

enableRealtimeReprojection()

void TSLOpenGLSurface::enableRealtimeReprojection	(	const char *	name,
		bool	enable )

flushLoadedShaders()

void TSLOpenGLSurface::flushLoadedShaders

(

)

Remove all loaded shader programs and flush all references to them

This method may be used by applications in combination with preloadProjectionShaders in order to manually flush the shader programs.

Applications may want to flush shader programs in order to slightly reduce GPU memory usage, however shader programs will typically be small compared to the data being displayed e.g large raster tiles.

Once shaders have been flushed they will automatically be reloaded when necessary, or may be preloaded again by the application.

The application must first call shaderPreloadEnabled(true) in order to use this method.

flushPendingDraws()

void TSLOpenGLSurface::flushPendingDraws

(

)

Instructs the drawing surface to issue OpenGL commands for any outstanding draws. This method is only useful when performing custom application rendering from inside a MapLink data layer, e.g. through a TSLCustomDataLayer or TSLDynamicRenderer when the layer's storage hint is not set to TSLOpenGLTransparencyHintAlways.

Applications should try to avoid calling this method frequently as it reduces the ability of the drawing surface to internally optimise rendering. If there are no pending drawing operations this method does nothing.

getLayerStorageStrategy()

bool TSLOpenGLSurface::getLayerStorageStrategy	(	const char *	layerName,
		TSLOpenGLStorageStrategyEnum &	strategy ) const

Queries the current storage strategy for the given data layer. See the documentation for TSLOpenGLStorageStrategyEnum for a description of the possible values.

By default all layers use the TSLOpenGLPerTileStrategy storage strategy.

Returns false if the given layer is not present in the drawing surface, otherwise returns true.

getLayerTransparencyHint()

bool TSLOpenGLSurface::getLayerTransparencyHint	(	const char *	layerName,
		TSLOpenGLTransparencyHintEnum &	hint ) const

Queries the current transparency hint for the given data layer. See the documentation for TSLOpenGLTransparencyHintEnum for a description of the possible values.

By default all layers use the TSLOpenGLTransparencyHintNever hint.

Returns false if the given layer is not present in the drawing surface, otherwise returns true.

getSwitchRangeForFP64()

double TSLOpenGLSurface::getSwitchRangeForFP64

(

)

const

Queries the range at which the drawing surface switches to FP64 calculations on the GPU to.

This is related to realtime reprojection.

Returns

range in Nautical Miles (default is 10NM)

incrementDepthSlice()

float TSLOpenGLSurface::incrementDepthSlice

(

uint32_t

numDrawItems

)

Increment the depth slice by the numDrawItems.

Parameters

numDrawItems

specifies the number of items that the current depth slice needs to be incremented by.

Returns

the new depth slice value in clip space/normalised device coordinate space.

modelViewMatrix()

const float * TSLOpenGLSurface::modelViewMatrix

(

)

const

Returns the 4x4 modelview matrix used by the drawing surface for the current or last draw. This can be used in custom data layers to assist in positioning items correctly on the display when performing rendering that does not use the MapLink TSLRenderingInterface.

If the drawing surface is not currently attached to an OpenGL context this method will return NULL.

preloadProjectionShaders()

bool TSLOpenGLSurface::preloadProjectionShaders	(	const TSLCoordinateSystem *	cs,
		bool	loadfp64Variant )

Preload shader programs for realtime reprojection.

When rendering MapLink will automatically load and compile shader programs as required, and in most cases this will not cause any visual impact.

In some scenarios however (specifically when the GL_ARB_shader_subroutine extension is not supported) the time needed to compile shaders with realtime reprojection enabled can cause a significant visual stall. This stall will happen when a type of geometry is first displayed, or when zooming in far enough to require 64-bit precision in the shaders (<10NM view range).

This method allows the application to preload the required shader programs, and move the stall to program initialisation. The application will need to wait for shader compilation to be performed however if preloaded the shaders will not need to be compiled during future draw calls, and will not cause visual stalls when zooming/panning the map.

The application should call this method multiple times for each required display projection (cs), and required floating point precision in the shaders.

Notes:

• Most applications should not need to call this method.
• This method will only preload shaders for realtime reprojection. Shaders used for unprojected drawing will be loaded when required.
• This method's functionality or signature may change in a future MapLink release. If you are using this method please contact Envitia support to discuss your use case.
• The application may manually flush shader programs by calling flushLoadedShaders.
• The application must first call shaderPreloadEnabled(true) in order to use this method.

Parameters

cs	The coordinate system (projection) to preload shader programs for.
loadfp64Variant	If true the 64-bit version of the shaders will be loaded, otherwise 32-bit versions will be loaded.

Returns

true if shaders were preloaded, false otherwise.

projectionMatrix()

const float * TSLOpenGLSurface::projectionMatrix

(

)

const

Returns the 4x4 projection matrix used by the drawing surface for the current or last draw. This can be used in custom data layers to assist in positioning items correctly on the display when performing rendering that does not use the MapLink TSLRenderingInterface.

If the drawing surface is not currently attached to an OpenGL context this method will return NULL.

rasterProjectionControlPointParameters()

void TSLOpenGLSurface::rasterProjectionControlPointParameters	(	unsigned int	minPointsPerRaster,
		unsigned int	maxPointsPerRaster,
		unsigned int	gridSizePixels )

Set the parameters for raster projection control points

When rasters are projected a grid of control points is used. This grid is defined by the following parameters:

• Minimum points per raster: The minimum number of points for any raster tile. Default 8, minimum 4.
• Maximum points per raster: The maximum number of points for any raster tile. Default 25.
• Grid Size: The distance between control points in pixels. Default 20. By specifying this value in pixels the accuracy of projection will be maintained while the view is zoomed in further, and reduced in order to maintain performance when zooming out.

The default values for these values have been chosen as appropriate for the largest number of scenarios, and as such the application may further tune these to a specific use case. These values may be changed at any time, and any changes will be reflected during subsequent redraws.

This tuning process should be as follows:

• Minimum points per raster should be set such that the data looks good enough when zoomed out a long way, without affecting performance.
• Maximum points per raster should be set such that performance is not greatly affected when zooming in a long way.
• Grid size should be set as small as possible while maintaining sufficient performance.

Parameters

minPointsPerRaster	The minimum number of control points for each raster tile.
maxPointsPerRaster	The maximum number of control points for each raster tile.
gridSizePixels	The distance between control points in pixels.

setAntialiasingMode()

bool TSLOpenGLSurface::setAntialiasingMode

(

TSLOpenGLAntialiasModeEnum

mode

)

Controls the type of antialiasing used by the drawing surface, if any. See the documentation for TSLOpenGLAntialiasModeEnum and the MapLink Developer's Guide for information on the available antialiasing types.

If the OpenGL context used by the drawing surface was created with multisampling then the only valid value that can be passed to this function is TSLOpenGLAntialiasModeDefault.

The postprocessing antialiasing modes can be enabled and disabled freely at runtime, however if sample buffers are present in the framebuffer configuration (GL_SAMPLE_BUFFERS is greater than 0) then the drawing surface will need to reload its shaders when enabling or disabling the antialiasing mode which will lead to a small delay on the next draw.

Returns true if the requested mode was set, or false if the requested mode is not valid given the framebuffer configuration used by the OpenGL context of the drawing surface.

setDepthSlice()

float TSLOpenGLSurface::setDepthSlice

(

uint32_t

numDrawItems

)

Allows the user to set the number of items that have been drawn.

This method should be used with care as it affects where in the depth buffer MapLink Pro draws geometry.

If the application calls glClear() for the depth buffer from within a TSLClientCustomDataLayer then this method should be called to reset the depth slice calculations.

Parameters

numDrawItems

is the number of items that are assumed to have been drawn.

Returns

the corresponding depth slice value in clip space/normalised device coordinate space.

setDisplayMetrics()

bool TSLOpenGLSurface::setDisplayMetrics	(	double	dpiX,
		double	dpiY,
		int	horizontalSizePixels,
		int	verticalSizePixels )

Provides an alternate method of specifying the physical properties of the display device. Aside from the different arguments this method is functionally identical to TSLDrawingSurface::setDeviceCapabilities.

Returns true if the display metrics were set, or false if the drawing surface is not currently attached.

setLayerStorageStrategy()

bool TSLOpenGLSurface::setLayerStorageStrategy	(	const char *	layerName,
		TSLOpenGLStorageStrategyEnum	strategy )

Sets the current storage strategy for the given data layer. See the documentation for TSLOpenGLStorageStrategyEnum for a description of the possible values.

Returns false if the given layer is not present in the drawing surface, otherwise returns true.

setLayerTransparencyHint()

bool TSLOpenGLSurface::setLayerTransparencyHint	(	const char *	layerName,
		TSLOpenGLTransparencyHintEnum	hint )

Sets the transparency hint for the given data layer. See the documentation for TSLOpenGLTransparencyHintEnum for a description of the possible values, and the OpenGL Drawing Surface - Transparency section of the MapLink Developer's Guide for more detail.

Returns false if the given layer is not present in the drawing surface, otherwise returns true.

setRGBABackgroundColour()

void TSLOpenGLSurface::setRGBABackgroundColour	(	unsigned char	r,
		unsigned char	g,
		unsigned char	b,
		unsigned char	a )

Sets the default background colour of the drawing surface. If the drawing surface is attached to a framebuffer with an alpha channel, the alpha channel will be cleared to the specified value.

setSwitchRangeForFP64()

void TSLOpenGLSurface::setSwitchRangeForFP64

(

double

range

)

Allows the range at which to switch to FP64 calculations on the GPU to be specified by the application.

This is related to realtime reprojection.

By default the projection shader maths is performed using 32bit float.

Depending on the accuracy required and the capability of the GPU we need to switch to using 64bit floating point.

Using FP64 is expensive and as such we only switch to FP64 shaders when necessary.

This method provides the ability to override the switch point.

Parameters

range

in Nautical Miles (default is 10NM)

shaderPreloadEnabled() [1/2]

bool TSLOpenGLSurface::shaderPreloadEnabled

(

)

const

Query whether shader preloading is enabled on the surface

Returns

true if shader preloading is enabled, false otherwise.

shaderPreloadEnabled() [2/2]

void TSLOpenGLSurface::shaderPreloadEnabled

(

bool

enabled

)

Enable shader preloading

If enabled this option will allow the application to pre-load OpenGL shaders prior to the point they are required.

This will also prevent the surface from flushing/deleting shader programs in most situations.

These options are provided in order to avoid visual stalls related to shader compilation when using realtime reprojection.

Most applications should not need to enable this feature as shader compilation is usually fast enough that no stalls will be observed. If you are using this method please contact Envitia support to discuss your use case.

If disabled (The default) the drawing surface will load shader programs as needed, and will flush loaded shaders when switching between display projections/floating point precision modes.

Parameters

enabled

Whether shader preloading should be enabled. By default shader preloading is disabled.

stateTracker()

TSLOpenGLStateTracker * TSLOpenGLSurface::stateTracker

(

)

Returns the internal OpenGL state tracker used by this drawing surface. If the drawing surface is not attached, this method returns NULL.

targetFrameBuffer() [1/2]

GLuint TSLOpenGLSurface::targetFrameBuffer

(

)

const

The framebuffer that MapLink will render into.

Returns

The framebuffer that MapLink will render into.

targetFrameBuffer() [2/2]

bool TSLOpenGLSurface::targetFrameBuffer

(

GLuint

fbo

)

Allows the user to set the framebuffer that MapLink will render into.

If the OpenGL drawing surface is attached to an existing OpenGL context, the FBO will be read from the context. Otherwise the FBO will default to zero.

The application may change the framebuffer target in order to render MapLink into a framebuffer.

Parameters

fbo	The target framebuffer to render into.

Returns

true if fbo was set, false otherwise.

textRoundingAmount() [1/2]

unsigned int TSLOpenGLSurface::textRoundingAmount

(

)

const

Query the amount of text rounding.

Returns

The text rounding amount.

textRoundingAmount() [2/2]

void TSLOpenGLSurface::textRoundingAmount

(

unsigned int

px

)

Set the amount of text rounding in pixels.

If textRoundingEnabled is true, text objects will be positioned to an aligned pixel position, based on this value. The position of text on the display will not move, until the text has moved more than this distance horizontally or vertically.

By default textRoundingAmount is set to 1 pixel.

Parameters

px	The text rounding amount in pixels.

textRoundingEnabled() [1/2]

bool TSLOpenGLSurface::textRoundingEnabled

(

)

const

Query whether text rounding is enabled on the surface.

Returns

true if text rounding is enabled, false otherwise.

textRoundingEnabled() [2/2]

void TSLOpenGLSurface::textRoundingEnabled

(

bool

enabled

)

Enable/Disable text rounding

By default text rounding is enabled, with a textRoundingAmount of 1 pixel.

If enabled the position of text objects on the display will be rounded to ensure the text aligns with pixels on the screen. This will affect any TSLText object drawn by the application, or data drawn by a TSLDataLayer. Text drawn through TSLRenderingInterface::drawText without providing a TSLText object will always be rounded to the nearest pixel.

When rounding is enabled, and realtime reprojection is enabled the text objects may jitter back/forth slightly on the display in situations where the projection origin is updated frequently.

In this scenario one of the following is recommended:

• Text rounding enabled, and textRoundingAmount increased to reduce the jitter. In this case the text will still visibly 'jump' on the display however as it will move by a larger amount will be more predictable/stable.
• Text rounding disabled in order to ensure text is always aligned with the underlying map. In this case the text will no longer be rounded, and may be slightly harder to read. We recommend the use of multisample anti-aliasing (at least 4x) in this case in order to improve text readability.

Parameters

enabled

true to enable text rounding, false to disable.