Inheritance diagram for envitia::maplink::earth::Surface3D:

Detailed Description

A drawing surface implementation, which visualises data on a 3D earth model

The Surface3D class is responsible for displaying 2D and 3D data on an earth model, to a window/rendering handle provided by the application.

This class provides the following capabilities

Display of 2D data layers (TSLDataLayer), draped over terrain
Display of terrain data (TSLTerrainDataBase) as part of the earth model
Display of 3D geometry within the scene, from various sources.

Functionality contained within the base Surface class will mostly affect the display of draped 2D layers when using this drawing surface. Most 2D operations may be performed in the same fashion as a 2D-only surface, and will affect the view in a similar manner. setOption is a notable exception - Most options will not be supported as they do not apply within a 3D scene.

The main divergence from 2D concepts within this class is within the 3D Camera class, which allows a virtual camera to be moved around the scene.

Some 2D-focused methods such as setViewedLatLongRange may behave slightly differently.

Internally, the surface uses the WGS84 (EPSG ID: 4326) coordinate system (CS) with a TMCperMU value of 5 million. This is to enable non-CS providing layers to be positioned correctly. The surface coordinate conversion functions use this CS so if a loaded map has a different CS then the coordinate conversion functions on the data layer should be used.

Public Member Functions
	Surface3D ()
	Create a 3D drawing surface.

	Surface3D (TSLDeviceContext handle)

	Surface3D (TSLWindowHandle handle)

	Surface3D (Display *x11Display, Drawable handle)

virtual	~Surface3D ()
	Delete the surface.

Camera &	camera () const

bool	reset (bool auto_redraw=true)

bool	resize (double x1, double y1, double x2, double y2, bool auto_redraw=true)

bool	wndResize (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLDeviceUnits x2, TSLDeviceUnits y2, bool auto_redraw=true)

void	getDUExtent (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLDeviceUnits x2, TSLDeviceUnits y2) const

bool	redraw ()

bool	drawDU (TSLDeviceUnits x1, TSLDeviceUnits y1, TSLDeviceUnits x2, TSLDeviceUnits y2, bool clear, bool updateExtentOnly=false)

bool	DUToLatLong (TSLDeviceUnits x, TSLDeviceUnits y, double latitude, double longitude) const

bool	latLongToDU (double latitude, double longitude, TSLDeviceUnits x, TSLDeviceUnits y) const

bool	TMCToLatLong (TSLTMC x, TSLTMC y, double latitude, double longitude) const

bool	TMCToLatLong (const TSLCoord &coord, GeodeticPoint &latLon) const

bool	latLongToTMC (double latitude, double longitude, TSLTMC x, TSLTMC y) const

bool	latLongToTMC (const GeodeticPoint &latLon, TSLCoord &coord) const

bool	geocentricToGeodetic (double x, double y, double z, double &lat, double &lon, double &alt) const

GeodeticPoint	geocentricToGeodetic (GeocentricPoint coord) const

bool	geodeticToGeocentric (double lat, double lon, double alt, double &x, double &y, double &z) const

GeocentricPoint	geodeticToGeocentric (GeodeticPoint coord) const

GeocentricDirection	geodeticToUpVector (double latitude, double longitude) const

bool	getDeviceCapabilities (TSLDeviceCapabilities &capabilities) const

bool	setDeviceCapabilities (const TSLDeviceCapabilities &capabilities)

void	globeBackgroundColour (TSLRGBA colour)

TSLRGBA	globeBackgroundColour () const

void	antiAliasSamples (unsigned int samples)

unsigned int	antiAliasSamples () const

bool	addTerrainDatabase (TSLTerrainDatabase &database)

TSLTerrainDatabase *	getTerrainDatabase (unsigned int i)

unsigned int	numTerrainDatabases () const
	Query the number of terrain databases used by the surface.

bool	removeTerrainDatabase (unsigned int i)

bool	removeTerrainDatabase (TSLTerrainDatabase &database)

bool	getTerrainHeight (double latitude, double longitude, double &altitude) const

void	terrainExaggeration (double scalingFactor)

double	terrainExaggeration () const
	Query the terrain exaggeration factor.

void	lighting (bool enable)

bool	lighting () const
	Query whether lighting effects are enabled.

void	lightPosition (const GeodeticPoint &pos)

GeodeticPoint	lightPosition () const
	Query the position of the light.

void	lightDiffuse (const TSLRGBA &col)

TSLRGBA	lightDiffuse () const
	Query the diffuse colour for the scene's light.

void	lightAmbient (const TSLRGBA &col)

TSLRGBA	lightAmbient () const
	Query the ambient colour for the scene's light.

bool	addTrack (Track &t)

bool	removeTrack (Track &t)

void	removeAllTracks ()
	Remove all tracks from the surface.

unsigned int	numTracks () const

Track *	getTrack (unsigned int index) const

bool	removeTrack (unsigned int index)

void	dynamicDecluttering (bool enable)

bool	dynamicDecluttering () const
	Query whether dynamic decluttering is enabled.

Track *	pickTrack (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture) const

TSLPickResultSet *	pickTracks (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture) const

bool	addGeometry (geometry::Geometry &geom)

bool	removeGeometry (geometry::Geometry &f)

void	removeAllGeometry ()
	Remove all geometry from the surface.

unsigned int	numGeometries () const

geometry::Geometry *	getGeometry (unsigned int index) const

bool	removeGeometry (unsigned int index)

geometry::Geometry *	pickGeometry (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture) const

TSLPickResultSet *	pickGeometries (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture) const

bool	setStyle (const char *styleName, const geometry::Style &s)

geometry::Style	getStyle (const char *styleName) const

bool	removeStyle (const char *styleName)

unsigned int	numStyles () const

geometry::Style	getStyle (unsigned int index) const

const char *	styleName (unsigned int index) const

bool	removeStyle (unsigned int index)

bool	screenshot (const char *fileName)

bool	drawToHDC (TSLDeviceContext &hdc, TSLDeviceUnits width, TSLDeviceUnits height)

Public Member Functions inherited from envitia::maplink::earth::Surface
TSLDrawingSurfaceTypeEnum	type () const
	The type of the drawing surface.

void	attach (TSLDeviceContext handle)

void	attach (TSLWindowHandle handle)

void	attach (Display *x11Display, TSLDrawableHandle handle)

void	detach ()

bool	addDataLayer (TSLDataLayer layer, const char layerName)

bool	removeDataLayer (const char *layerName)

int	getNumDataLayers () const
	Query the number of data layers attached to this surface.

TSLDataLayer *	getDataLayer (const char *layerName)

bool	getDataLayerInfo (int layerIndex, TSLDataLayer layer, const char layerName) const

bool	bringToFront (const char *layerName)

bool	bringInFrontOf (const char layerName, const char targetLayerName)

bool	sendToBack (const char *layerName)

bool	sendToBackOf (const char layerName, const char targetLayerName)

bool	getDataLayerProps (const char layerName, TSLPropertyEnum propertyId, TSLPropertyValue value)

bool	setDataLayerProps (const char *layerName, TSLPropertyEnum propertyId, TSLPropertyValue value)

bool	forceLayer (const char dataLayerName, const char detailLayerName)

TSLSimpleString	queryActiveLayer (const char *dataLayerName) const

bool	queryActiveLayer (const char dataLayerName, char detailLayerName, int detailLayerNameSize)

bool	addFeatureRendering (const char *featureName, TSLFeatureID featureID)

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

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	clearFeatureRendering (const char *featureName, TSLFeatureID featureID)

bool	saveRendering (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION)

bool	loadRendering (const char *filename)

TSLPickResultSet *	pick (TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth, TSLPickSelector *selector=0)

TSLPickResultSet *	pick (const char layerName, TSLDeviceUnits x, TSLDeviceUnits y, TSLDeviceUnits aperture, int depth=-1, TSLPickSelector selector=0)

bool	clearAllDeclutterData (const char *layerName=0)

bool	clearDeclutterData (const char featureName, const char layerName=0)

bool	copyDeclutterData (const char srcFeatureName, const char dstFeatureName, const char srcLayerName=0, const char dstLayerName=0)

bool	getDeclutterStatus (const char featureName, TSLDeclutterStatusResultEnum value, const char dataLayerName=0, const char detailLayerName=0)

bool	getDeclutterStatus (TSLFeatureID featureId, TSLDeclutterStatusResultEnum value, const char dataLayerName, const char *detailLayerName=0)

bool	setDeclutterStatus (const char featureName, TSLDeclutterStatusEnum value, const char dataLayerName=0, const char *detailLayerName=0)

bool	setDeclutterStatus (TSLFeatureID featureId, TSLDeclutterStatusEnum value, const char dataLayerName=0, const char detailLayerName=0)

bool	setDeclutterStatusOnAllFeatures (TSLDeclutterStatusEnum value, const char dataLayerName=0, const char detailLayerName=0)

bool	loadDeclutter (const char *filename)

bool	saveDeclutter (const char *filename, TSLMapLinkVersion ver=TSL_CURRENT_MAPLINK_VERSION)

bool	clearBackgroundColour ()

bool	getBackgroundColour (TSLStyleID *value)

bool	setBackgroundColour (TSLStyleID value)

bool	setBackgroundColour (TSLRGBA colour)

TSLRGBA	getBackgroundColour () const

void	setOption (TSLOptionEnum option, bool value)

bool	getOption (TSLOptionEnum option)

TSLRGBA	getColourValue (TSLStyleID colour) const

bool	getColourValue (int colour, unsigned char &r, unsigned char &g, unsigned char &b) const

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)

bool	fontStyleValue (int index, int colour, TSLBitmapHandle bitmap, TSLSimpleString fontName=0, const char outputString=0, TSLSimpleString *section=0)

bool	getFontStyleIndices (int *indices, int num)

bool	getSymbolStyleIndices (int *indices, int num)

void	userWord (void *ptr) const

void *	userWord () const
	Returns a pointer to the user data stored on the drawing surface.

void	id (int id_)

int	id () const

virtual	~Surface ()

Additional Inherited Members
Static Public Member Functions inherited from envitia::maplink::earth::Surface
static TSLStyleID	getIDOfNearestColour (int r, int g, int b)

static bool	addLoader (TSLFileLoader *loader)

static TSLFileLoader *	getLoader ()

static bool	addPathList (TSLPathList *pathList)

static bool	loadStandardConfig (const char *path=0, bool delayLoadIncludes=false)

static bool	setupColours (const char *filename)

static bool	setupSymbols (const char *filename, bool delayLoadIncludes=false)

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 void	cleanup ()

Protected Member Functions inherited from envitia::maplink::earth::Surface
	Surface ()

Protected Attributes inherited from envitia::maplink::earth::Surface
void *	m_p

Constructor & Destructor Documentation

◆ Surface3D() [1/4]

envitia::maplink::earth::Surface3D::Surface3D ( )

Create a 3D drawing surface.

◆ Surface3D() [2/4]

envitia::maplink::earth::Surface3D::Surface3D ( TSLDeviceContext handle )

Create a 3D drawing surface, and attach it to a device context

Parameters

handle The device context (HDC) to attach the surface to.

◆ Surface3D() [3/4]

envitia::maplink::earth::Surface3D::Surface3D ( TSLWindowHandle handle )

Create a 3D drawing surface, and attach it to a window

Parameters

handle The window (HWND) to attach the surface to.

◆ Surface3D() [4/4]

envitia::maplink::earth::Surface3D::Surface3D	(	Display *	x11Display,
		Drawable	handle )

Create a 3D drawing surface, and attach it to a window

Parameters

display	X11 Display pointer to use.
handle	ID of X11 window or pixmap to attach to the surface.

◆ ~Surface3D()

virtual envitia::maplink::earth::Surface3D::~Surface3D ( )

virtual

Delete the surface.

Member Function Documentation

◆ addGeometry()

bool envitia::maplink::earth::Surface3D::addGeometry ( geometry::Geometry & geom )

Add geometry to the display.

Note: The application retains ownership of the geometry instance, and is responsible for management of all Geometry instances.

Parameters

geom	The geometry to add

Returns: true if the geometry was added, false otherwise.

◆ addTerrainDatabase()

bool envitia::maplink::earth::Surface3D::addTerrainDatabase ( TSLTerrainDatabase & database )

Add a maplink terrain database to the surface

The provided database will be used as a terrain data source for the 3D earth model, and any 2D layers will be automatically draped over the terrain.

If multiple terrain databases are added they will be queried in the reverse of the order they were added, i.e applications should first add any global, low resolution terrain database, and then add any higher resolution or smaller-extent databases. This will ensure that the highest resolution areas are used as a height source first, and that the lower resolutions will only be used where this data is unavailable.

Parameters

database The terrain database to add. The application retains ownership of the terrain database, and must ensure it is not deleted before the drawing surface.

◆ addTrack()

bool envitia::maplink::earth::Surface3D::addTrack ( Track & t )

Add a track to the display.

Note: The application retains ownership of the track instance, and is responsible for management of all track instances.

Parameters

t	The track to add.

Returns: true if the track was added, false otherwise.

◆ antiAliasSamples() [1/2]

unsigned int envitia::maplink::earth::Surface3D::antiAliasSamples ( ) const

Query the amount of anti-aliasing applied to the view

If set to zero anti-aliasing will be disabled on the drawing surface.

Returns: The number of anti-aliasing (MSAA) samples

◆ antiAliasSamples() [2/2]

void envitia::maplink::earth::Surface3D::antiAliasSamples ( unsigned int samples )

Set the amount of anti-aliasing applied to the view

If enabled anti-aliasing (MSAA) can dramatically improve the visual quality, for a moderate performance cost.

By default anti-aliasing will be set to 4 samples at minimum. There may be some cases where the graphics hardware cannot provide this level.

Applications may override this value as desired, and should provide values which are a power of 2. Setting this value to zero will disable anti-aliasing.

Note: This parameter will primarily affect the rendering of 3D data. Draped 2D layers may not respect this parameter.

Parameters

samples The minimum desired number of samples

◆ camera()

Camera & envitia::maplink::earth::Surface3D::camera ( ) const

Access the surface's camera.

The application may modify the camera in order to reposition the view and adjust other visual parameters within the application.

Returns: The camera used by the surface.

◆ drawDU()

bool envitia::maplink::earth::Surface3D::drawDU	(	TSLDeviceUnits	x1,
		TSLDeviceUnits	y1,
		TSLDeviceUnits	x2,
		TSLDeviceUnits	y2,
		bool	clear,
		bool	updateExtentOnly = false )

Redraw the surface to the window/rendering handle.

On Surface3D this method is present for compatibility with the 2D surfaces. If called this method will call redraw(), ignoring all arguments.

Calling this method will perform a draw operation on the surface, and should be called by the application any time the view needs to be refreshed.

For Surface3D the recommended approach is to call redraw regularly, using a rendering loop or timer system. This system may perform other operations such as data loading and event handling during a redraw operation, and is designed to operate primarily in a continuous-render mode.

When called any visible layers will be rendered, and any data within these layers will be rendered according to the current rendering set up.

Returns: true if the surface was redrawn, false otherwise.

◆ drawToHDC()

bool envitia::maplink::earth::Surface3D::drawToHDC	(	TSLDeviceContext &	hdc,
		TSLDeviceUnits	width,
		TSLDeviceUnits	height )

Render a screenshot of the surface to an HDC.

Calling this method will perform a redraw, and render the surface to the provided HDC.

Calling this method will not affect the surface state - The surface will remain attached to the window/render context, and will update the window as part of the call.

This method is only implemented on Windows - The screenshot method provides similar functionality in a platform-independent manner.

Parameters

hdc	The target HDC.
width	The target's width.
height	The target's height.

Returns: true if the render was successful, false otherwise.

◆ DUToLatLong()

bool envitia::maplink::earth::Surface3D::DUToLatLong	(	TSLDeviceUnits	x,
		TSLDeviceUnits	y,
		double *	latitude,
		double *	longitude ) const

Convert from device coordinates to latitude/longitude (WGS84).

Parameters

x	The DU coordinate to convert.
y	The DU coordinate to convert.
latitude	Will be set to the latitude of x,y on the display.
longitude	Will be set to the longitude of x,y on the display.

Returns: true if the conversion was performed, false otherwise.

◆ dynamicDecluttering() [1/2]

bool envitia::maplink::earth::Surface3D::dynamicDecluttering ( ) const

Query whether dynamic decluttering is enabled.

◆ dynamicDecluttering() [2/2]

void envitia::maplink::earth::Surface3D::dynamicDecluttering ( bool enable )

Enable or disable dynamic decluttering.

When dynamic decluttering is enabled the surface will automatically reduce the size and transparency of tracks, symbols, and text in order to reduce visual clutter.

This decluttering capability may be controlled further via:

geometry::Style::SymbolStyle::declutter - Symbols will only be decluttered if this flag is true.
geometry::Style::TextStyle::declutter - Text will only be decluttered if this flag is true.
Track::declutterPriority - Tracks will be decluttered if this value is not negative, and individual tracks may be assigned a relative priority.

Parameters

enable true to enable dynamic decluttering, false to disable.

◆ geocentricToGeodetic() [1/2]

bool envitia::maplink::earth::Surface3D::geocentricToGeodetic	(	double	x,
		double	y,
		double	z,
		double &	lat,
		double &	lon,
		double &	alt ) const

Convert from geocentric coordinates (x, y, z from the centre of the earth in metres) to geodetic coordinates (lat, lon, alt).

Parameters

x	Input geocentric coordinate.
y	Input geocentric coordinate.
z	Input geocentric coordinate.
lat	output for the converted latitude.
lon	output for the converted longitude.
alt	output for the converted altitude (in meters).

Returns: true if the conversion was performed, false otherwise.

◆ geocentricToGeodetic() [2/2]

GeodeticPoint envitia::maplink::earth::Surface3D::geocentricToGeodetic ( GeocentricPoint coord ) const

Convert from geocentric coordinates (x, y, z from the centre of the earth in metres) to geodetic coordinates (lat, lon, alt).

Parameters

coord Input geocentric coordinate.

Returns: The converted geographic coordinate.

◆ geodeticToGeocentric() [1/2]

bool envitia::maplink::earth::Surface3D::geodeticToGeocentric	(	double	lat,
		double	lon,
		double	alt,
		double &	x,
		double &	y,
		double &	z ) const

Convert from geodetic coordinates (lat, lon, alt) to geocentric coordinates (x, y, z from the centre of the earth in metres).

Parameters

lat	Input geodetic coordinate.
lon	Input geodetic coordinate.
alt	Input altitude in meters.
x	output for the converted geocentric coordinate.
y	output for the converted geocentric coordinate.
z	output for the converted geocentric coordinate.

Returns: true if the conversion was performed, false otherwise.

◆ geodeticToGeocentric() [2/2]

GeocentricPoint envitia::maplink::earth::Surface3D::geodeticToGeocentric ( GeodeticPoint coord ) const

Convert from geodetic coordinates (lat, lon, alt) to geocentric coordinates (x, y, z from the centre of the earth in metres).

Parameters

coord Input geodetic coordinate.

Returns: The converted geocentric coordinate.

◆ geodeticToUpVector()

GeocentricDirection envitia::maplink::earth::Surface3D::geodeticToUpVector	(	double	latitude,
		double	longitude ) const

Obtain an 'up' vector for a given geodetic point

This method will return a vector in geocentric coordinates, which corresponds to the positive Z axis in geographic space, at the provided lat/lon position.

Parameters

latitude	The latitude to calculate 'up' at.
longitude	The longitude to calculate 'up' at.

◆ getDeviceCapabilities()

bool envitia::maplink::earth::Surface3D::getDeviceCapabilities ( TSLDeviceCapabilities & capabilities ) const

Returns the device capabilities as determined by the drawing surface, or as passed to setDeviceCapabilities.

Parameters

capabilities Will be set to the surface's device capabilities.

Returns: true if the values were populated, false otherwise.

◆ getDUExtent()

void envitia::maplink::earth::Surface3D::getDUExtent	(	TSLDeviceUnits *	x1,
		TSLDeviceUnits *	y1,
		TSLDeviceUnits *	x2,
		TSLDeviceUnits *	y2 ) const

Query the extent of the surface within the window/rendering handle.

This method allows the user to query the extent of the window handle currently displayed in terms of device units. This is the same extent that will have been passed in the last call to 'wndResize'.

Parameters

x1	Storage for top left co-ordinate of the extent.
y1	Storage for top left co-ordinate of the extent.
x2	Storage for bottom right co-ordinate of the extent.
y2	Storage for bottom right co-ordinate of the extent.

◆ getGeometry()

geometry::Geometry * envitia::maplink::earth::Surface3D::getGeometry ( unsigned int index ) const

Query a geometry instance from the display.

Parameters

index The index of the geometry to query.

Returns: The requested geometry, or null if index >= numGeometries().

◆ getStyle() [1/2]

geometry::Style envitia::maplink::earth::Surface3D::getStyle ( const char * styleName ) const

Query a geometry style by name.

If the specified style has not yet been configured a default style will be returned.

Returns: The requested Style, or Style::Style() on error.

◆ getStyle() [2/2]

geometry::Style envitia::maplink::earth::Surface3D::getStyle ( unsigned int index ) const

Query a style by index.

Parameters

index The index of the style to query.

Returns: The requested Style, or the default style if index >= numStyles().

◆ getTerrainDatabase()

TSLTerrainDatabase * envitia::maplink::earth::Surface3D::getTerrainDatabase ( unsigned int i )

Query a terrain database used by the surface.

Parameters

i	The index of the database to query.

Returns: The requested terrain database, or null on error.

◆ getTerrainHeight()

bool envitia::maplink::earth::Surface3D::getTerrainHeight	(	double	latitude,
		double	longitude,
		double &	altitude ) const

Query the height of the terrain at a given location.

Note: If terrainExaggeration has been set this method will return the exaggerated values.

Parameters

latitude	The latitude to query (WGS84).
longitude	The longitude to query (WGS84).
altitude	Will be set to the terrain height in meters.

Returns: true if the height was queried, false otherwise.

◆ getTrack()

Track * envitia::maplink::earth::Surface3D::getTrack ( unsigned int index ) const

Query a track instance from the display.

Parameters

index The index of the track to query.

Returns: The requested track, or null if index >= numTracks().

◆ globeBackgroundColour() [1/2]

TSLRGBA envitia::maplink::earth::Surface3D::globeBackgroundColour ( ) const

Query the background colour of the globe.

Returns: The background colour of the 3D globe.

◆ globeBackgroundColour() [2/2]

void envitia::maplink::earth::Surface3D::globeBackgroundColour ( TSLRGBA colour )

Set the background colour of the globe.

This method will set the base colour of the 3D globe. This is provided primarily to allow applications to rendering the globe as transparent, or the same as the overall backgroundColour.

This method supports full 32-bit colour, including alpha.

Parameters

colour The background colour of the 3D globe.

◆ latLongToDU()

bool envitia::maplink::earth::Surface3D::latLongToDU	(	double	latitude,
		double	longitude,
		TSLDeviceUnits *	x,
		TSLDeviceUnits *	y ) const

Convert from latitude/longitude (WGS84) to device coordinates.

Parameters

latitude	The latitude to convert.
longitude	The longitude to convert.
x	Will be set to the DU position on the display.
y	Will be set to the DU position on the display.

Returns: true if the conversion was performed, false otherwise.

◆ latLongToTMC() [1/2]

bool envitia::maplink::earth::Surface3D::latLongToTMC	(	const GeodeticPoint &	latLon,
		TSLCoord &	coord ) const

Convert from latitude/longitude to TMCs.

Unlike the 2D drawing surfaces this surface does not use the concept of a 'coordinate providing layer'. However, internally, the surface uses the WGS84 (EPSG ID: 4326) coordinate system (CS) with a TMCperMU value of 5 million. In order to ensure TMC-based geometry (such as a TSLStandardDataLayer) aligns correctly on the 3D globe the application should perform all coordinate transforms through the Surface3D class. However, if a loaded map has a different CS and that layer is being queried then the application should use the coordinate conversion functions on the data layer instead.

Parameters

latLon	The latitude/longitude to convert. The altitude of this point will be ignored.
coord	Storage for the converted TMC coordinate.

Returns: true if the coordinate was converted, false otherwise.

◆ latLongToTMC() [2/2]

bool envitia::maplink::earth::Surface3D::latLongToTMC	(	double	latitude,
		double	longitude,
		TSLTMC *	x,
		TSLTMC *	y ) const

Convert from latitude/longitude to TMCs.

Unlike the 2D drawing surfaces this surface does not use the concept of a 'coordinate providing layer'. However, internally, the surface uses the WGS84 (EPSG ID: 4326) coordinate system (CS) with a TMCperMU value of 5 million. In order to ensure TMC-based geometry (such as a TSLStandardDataLayer) aligns correctly on the 3D globe the application should perform all coordinate transforms through the Surface3D class. However, if a loaded map has a different CS and that layer is being queried then the application should use the coordinate conversion functions on the data layer instead.

Parameters

latitude	The latitude to convert.
longitude	The longitude to convert.
x	Storage for the converted TMC coordinate.
y	Storage for the converted TMC coordinate.

Returns: true if the coordinate was converted, false otherwise.

◆ lightAmbient() [1/2]

TSLRGBA envitia::maplink::earth::Surface3D::lightAmbient ( ) const

Query the ambient colour for the scene's light.

◆ lightAmbient() [2/2]

void envitia::maplink::earth::Surface3D::lightAmbient ( const TSLRGBA & col )

Set the ambient colour for the scene's light.

Parameters

col	The new ambient colour to use.

◆ lightDiffuse() [1/2]

TSLRGBA envitia::maplink::earth::Surface3D::lightDiffuse ( ) const

Query the diffuse colour for the scene's light.

◆ lightDiffuse() [2/2]

void envitia::maplink::earth::Surface3D::lightDiffuse ( const TSLRGBA & col )

Set the diffuse colour for the scene's light.

Parameters

col	The new diffuse colour to use.

◆ lighting() [1/2]

bool envitia::maplink::earth::Surface3D::lighting ( ) const

Query whether lighting effects are enabled.

◆ lighting() [2/2]

void envitia::maplink::earth::Surface3D::lighting ( bool enable )

Enable or disable lighting effects.

Parameters

enable true to enable lighting effects, false to disable.

◆ lightPosition() [1/2]

GeodeticPoint envitia::maplink::earth::Surface3D::lightPosition ( ) const

Query the position of the light.

◆ lightPosition() [2/2]

void envitia::maplink::earth::Surface3D::lightPosition ( const GeodeticPoint & pos )

Set the light position for the scene.

Parameters

pos	The new position of the light, in geodetic space.

◆ numGeometries()

unsigned int envitia::maplink::earth::Surface3D::numGeometries ( ) const

Query the number of Geometry instances within the surface.

In most cases applications should add/remove geometry by reference, and should maintain a list of geometry within the application. The application is responsible for managing geometry instances, and adding them to surfaces. The surface will not take ownership of geometry primitives in order to allow them to be displayed in multiple surfaces.

The following methods are provided to allow applications to iterate through the geometry currently added to the surface:

numGeometries.
getGeometry(unsigned int).
removeGeometry(unsigned int).

Returns: The number of geometry instances currently added to the surface.

◆ numStyles()

unsigned int envitia::maplink::earth::Surface3D::numStyles ( ) const

Query the number of geometry styles configured on the surface.

In most cases applications should manage styles by name. The following methods are provided to allow applications to iterate through the styles on the surface:

numStyles.
getStyle(unsigned int).
styleName(unsigned int).
removeStyle(unsigned int).

Returns: The number of styles configured on the surface.

◆ numTerrainDatabases()

unsigned int envitia::maplink::earth::Surface3D::numTerrainDatabases ( ) const

Query the number of terrain databases used by the surface.

◆ numTracks()

unsigned int envitia::maplink::earth::Surface3D::numTracks ( ) const

Query the number of tracks within the surface.

In most cases applications should add/remove tracks by reference, and should maintain a list of tracks within the application. The application is responsible for managing track instances, and adding them to surfaces. The surface will not take ownership of tracks in order to allow them to be displayed in multiple surfaces.

The following methods are provided to allow applications to iterate through the tracks currently added to the surface:

numTracks.
getTrack(unsigned int).
removeTrack(unsigned int).

Returns: The number of tracks currently added to the surface.

◆ pickGeometries()

TSLPickResultSet * envitia::maplink::earth::Surface3D::pickGeometries	(	TSLDeviceUnits	x,
		TSLDeviceUnits	y,
		TSLDeviceUnits	aperture ) const

Pick geometry from the display.

Note: The returned result set will contain instances of the earth::PickResultGeometry class.

Parameters

x	The x component of the pick location, in display units.
y	The y component of the pick location, in display units.
aperture	The size of the area to pick, in display units.

Returns: A pick result set containing the results. The application must call TSLPickResultSet::destroy when the pick results are finished with.

◆ pickGeometry()

geometry::Geometry * envitia::maplink::earth::Surface3D::pickGeometry	(	TSLDeviceUnits	x,
		TSLDeviceUnits	y,
		TSLDeviceUnits	aperture ) const

Pick a single Geometry from the display.

Parameters

x	The x component of the pick location, in display units.
y	The y component of the pick location, in display units.
aperture	The size of the area to pick, in display units.

Returns: The geometry instance closest to the pick location, or null if no geometry is within the aperture.

◆ pickTrack()

Track * envitia::maplink::earth::Surface3D::pickTrack	(	TSLDeviceUnits	x,
		TSLDeviceUnits	y,
		TSLDeviceUnits	aperture ) const

Pick a single track from the display.

Parameters

x	The x component of the pick location, in display units.
y	The y component of the pick location, in display units.
aperture	The size of the area to pick, in display units.

Returns: The track instance closest to the pick location, or null if no tracks are within the aperture.

◆ pickTracks()

TSLPickResultSet * envitia::maplink::earth::Surface3D::pickTracks	(	TSLDeviceUnits	x,
		TSLDeviceUnits	y,
		TSLDeviceUnits	aperture ) const

Pick tracks from the display.

Note: The returned result set will contain instances of the earth::PickResultTrack class.

Parameters

x	The x component of the pick location, in display units.
y	The y component of the pick location, in display units.
aperture	The size of the area to pick, in display units.

Returns: A pick result set containing the results. The application must call TSLPickResultSet::destroy when the pick results are finished with.

◆ redraw()

bool envitia::maplink::earth::Surface3D::redraw ( )

Redraw the surface to the window/rendering handle.

Calling this method will perform a draw operation on the surface, and should be called by the application any time the view needs to be refreshed.

For Surface3D the recommended approach is to call redraw regularly, using a rendering loop or timer system. This system may perform other operations such as data loading and event handling during a redraw operation, and is designed to operate primarily in a continuous-render mode.

When called any visible layers will be rendered, and any data within these layers will be rendered according to the current rendering set up.

Returns: true if the surface was redrawn, false otherwise.

◆ removeAllGeometry()

void envitia::maplink::earth::Surface3D::removeAllGeometry ( )

Remove all geometry from the surface.

◆ removeAllTracks()

void envitia::maplink::earth::Surface3D::removeAllTracks ( )

Remove all tracks from the surface.

◆ removeGeometry() [1/2]

bool envitia::maplink::earth::Surface3D::removeGeometry ( geometry::Geometry & f )

Remove geometry from the display.

Parameters

geom	The Geometry to remove.

Returns: true if the geometry was removed, false otherwise.

◆ removeGeometry() [2/2]

bool envitia::maplink::earth::Surface3D::removeGeometry ( unsigned int index )

Remove a geometry from the display.

Parameters

index The index of the geometry to remove.

Returns: true if the geometry was removed, false otherwise.

◆ removeStyle() [1/2]

bool envitia::maplink::earth::Surface3D::removeStyle ( const char * styleName )

Remove/clear a geometry style.

Parameters

styleName The name of the style to remove

Returns: true if the style was cleared, false otherwise.

◆ removeStyle() [2/2]

bool envitia::maplink::earth::Surface3D::removeStyle ( unsigned int index )

Remove a style.

Parameters

index The index of the style to remove.

Returns: true if the style was removed, false if index >= numStyles().

◆ removeTerrainDatabase() [1/2]

bool envitia::maplink::earth::Surface3D::removeTerrainDatabase ( TSLTerrainDatabase & database )

Remove a terrain database from the surface.

Parameters

database The database to remove.

Returns: true if the database was removed, false otherwise.

◆ removeTerrainDatabase() [2/2]

bool envitia::maplink::earth::Surface3D::removeTerrainDatabase ( unsigned int i )

Remove a terrain database from the surface.

Parameters

i	The index of the database to remove.

Returns: true if the database was removed, false otherwise.

◆ removeTrack() [1/2]

bool envitia::maplink::earth::Surface3D::removeTrack ( Track & t )

Remove a track from the display.

Parameters

t	The track to remove.

Returns: true if the track was removed, false otherwise.

◆ removeTrack() [2/2]

bool envitia::maplink::earth::Surface3D::removeTrack ( unsigned int index )

Remove a track from the display.

Parameters

index The index of the track to remove.

Returns: true if the track was removed, false otherwise.

◆ reset()

bool envitia::maplink::earth::Surface3D::reset ( bool auto_redraw = true )

Reset to full view.

Calling this method will reset the view to display all available data within the surface.

For 3D this will zoom out to view the whole globe, and reset the camera's parameters to a default state.

Parameters

auto_redraw If true this method will also perform a redraw operation.

Returns: true if the view was reset, false otherwise.

◆ resize()

bool envitia::maplink::earth::Surface3D::resize	(	double	x1,
		double	y1,
		double	x2,
		double	y2,
		bool	auto_redraw = true )

Changes displayed extent of map.

When called on Surface3D the surface will mimic the behaviour of the 2D surfaces by pointing the camera towards the ground. Surface3D will represent the provided area as best as possible, however the view may not match the parameters exactly.

Also note that in Surface3D the coordinate provided are always in degrees latitude and longitude, whereas in the 2D surfaces this method handles user units.

Parameters

x1	The longitude of the bottom-left coordinate of the view area.
y1	The latitude of the bottom-left coordinate of the view area.
x2	The longitude of the top-right coordinate of the view area.
y2	The latitude of the top-right coordinate of the view area.
auto_redraw	If true this method will also perform a redraw operation.

Returns: true if the view was set, false otherwise.

◆ screenshot()

bool envitia::maplink::earth::Surface3D::screenshot ( const char * fileName )

Take a screenshot of the surface.

Calling this method will perform a redraw, and save a copy of the display to the specified filename.

The extension of the filename will be used to determine the output image format. Most common formats are supported including png, jpeg, and tiff.

Parameters

fileName the path to save the screenshot to.

Returns: true if the screenshot was successful, false otherwise.

◆ setDeviceCapabilities()

bool envitia::maplink::earth::Surface3D::setDeviceCapabilities ( const TSLDeviceCapabilities & capabilities )

Set the device capabilities.

The set values are used when drawing items whose dimensions are defined as TSLDimensionUnitsPoints, and may be used by the surface/layers to manage the display of detail layers/sub-layers within the data.

This method only needs to be called it the values need to be adjusted or reset to the default.

The set values will be discarded if attach is called.

Default values are obtained from the underlying drawing system.

On Windows the values can be obtained using the Windows SDK method: GetDeviceCaps.

On X11 targets the values can be obtained using the macros found in Xlib.h: DisplayWidthMM, DIsplayHeightMM, DisplayWidth, DisplayHeight.

If the parameters are all set to zero the method queries the System defaults and sets those values.

Parameters

capabilities The device capabilities to set.

Returns: true if device capabilities were set, false otherwise.

◆ setStyle()

bool envitia::maplink::earth::Surface3D::setStyle	(	const char *	styleName,
		const geometry::Style &	s )

Configure a geometry style.

Geometry styles are be specified on a per-surface basis, indexed by style name. When added to the surface Geometry will be rendered based on its styleName attribute.

If no style has been configured for the Geometry then a default style will be used (Style::Style()).

If a style is already configured with the provided name it will be updated.

Parameters

styleName	The name of the style to set.
s	The styling information.

Returns: true if the style was set, false otherwise.

◆ styleName()

const char * envitia::maplink::earth::Surface3D::styleName ( unsigned int index ) const

Query the name of a style.

Parameters

index The index of the style to query.

Returns: The name of the requested style, or null if index >= numStyles().

◆ terrainExaggeration() [1/2]

double envitia::maplink::earth::Surface3D::terrainExaggeration ( ) const

Query the terrain exaggeration factor.

◆ terrainExaggeration() [2/2]

void envitia::maplink::earth::Surface3D::terrainExaggeration ( double scalingFactor )

Set the terrain exaggeration factor.

This scaling factor will be applied to the terrain rendering and any height queries.

Parameters

scalingFactor The terrain scaling factor to set.

◆ TMCToLatLong() [1/2]

bool envitia::maplink::earth::Surface3D::TMCToLatLong	(	const TSLCoord &	coord,
		GeodeticPoint &	latLon ) const

Convert from TMCs to latitude/longitude.

Unlike the 2D drawing surfaces this surface does not use the concept of a 'coordinate providing layer'. However, internally, the surface uses the WGS84 (EPSG ID: 4326) coordinate system (CS) with a TMCperMU value of 5 million. In order to ensure TMC-based geometry (such as a TSLStandardDataLayer) aligns correctly on the 3D globe the application should perform all coordinate transforms through the Surface3D class. However, if a loaded map has a different CS and that layer is being queried then the application should use the coordinate conversion functions on the data layer instead.

Parameters

coord	The TMC coordinate to convert.
latLon	Storage for the converted latitude coordinate. The altitude of this point will be set to zero.

Returns: true if the coordinate was converted, false otherwise.

◆ TMCToLatLong() [2/2]

bool envitia::maplink::earth::Surface3D::TMCToLatLong	(	TSLTMC	x,
		TSLTMC	y,
		double *	latitude,
		double *	longitude ) const

Convert from TMCs to latitude/longitude.

Unlike the 2D drawing surfaces this surface does not use the concept of a 'coordinate providing layer'. However, internally, the surface uses the WGS84 (EPSG ID: 4326) coordinate system (CS) with a TMCperMU value of 5 million. In order to ensure TMC-based geometry (such as a TSLStandardDataLayer) aligns correctly on the 3D globe the application should perform all coordinate transforms through the Surface3D class. However, if a loaded map has a different CS and that layer is being queried then the application should use the coordinate conversion functions on the data layer instead.

Parameters

x	The TMC coordinate to convert.
y	The TMC coordinate to convert.
latitude	Storage for the converted latitude coordinate.
longitude	Storage for the converted longitude coordinate.

Returns: true if the coordinate was converted, false otherwise.

◆ wndResize()

bool envitia::maplink::earth::Surface3D::wndResize	(	TSLDeviceUnits	x1,
		TSLDeviceUnits	y1,
		TSLDeviceUnits	x2,
		TSLDeviceUnits	y2,
		bool	auto_redraw = true )

The user application should call this function on a window resize.

This methods informs the drawing surface of a change in size of the attached window handle. If the handle is resized and the surface is not informed then the displayed area may not cover the full window area.

Optionally, the view extent may be adjusted to fit the new window size. The action parameter determines what should happen.

Note: TSLDeviceUnits are typically pixels, however can vary based on platform. For the OpenGL surface 0,0 is the bottom left corner, y positive upwards. For all other drawing surfaces 0,0 is the top-left corner, y positive downwards.

Parameters

x1	The top left coordinate if the area to draw, in device units.
y1	The top left coordinate if the area to draw, in device units.
x2	The bottom right coordinate if the area to draw, in device units.
y2	The bottom right coordinate if the area to draw, in device units.
auto_redraw	If true this method will also perform a redraw operation.

Returns: true if the view was updated, false otherwise.

Detailed Description

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ Surface3D() [1/4]

◆ Surface3D() [2/4]

◆ Surface3D() [3/4]

◆ Surface3D() [4/4]

◆ ~Surface3D()

Member Function Documentation

◆ addGeometry()

◆ addTerrainDatabase()

◆ addTrack()

◆ antiAliasSamples() [1/2]

◆ antiAliasSamples() [2/2]

◆ camera()

◆ drawDU()

◆ drawToHDC()

◆ DUToLatLong()

◆ dynamicDecluttering() [1/2]

◆ dynamicDecluttering() [2/2]

◆ geocentricToGeodetic() [1/2]

◆ geocentricToGeodetic() [2/2]

◆ geodeticToGeocentric() [1/2]

◆ geodeticToGeocentric() [2/2]

◆ geodeticToUpVector()

◆ getDeviceCapabilities()

◆ getDUExtent()

◆ getGeometry()

◆ getStyle() [1/2]

◆ getStyle() [2/2]

◆ getTerrainDatabase()

◆ getTerrainHeight()

◆ getTrack()

◆ globeBackgroundColour() [1/2]

◆ globeBackgroundColour() [2/2]

◆ latLongToDU()

◆ latLongToTMC() [1/2]

◆ latLongToTMC() [2/2]

◆ lightAmbient() [1/2]

◆ lightAmbient() [2/2]

◆ lightDiffuse() [1/2]

◆ lightDiffuse() [2/2]

◆ lighting() [1/2]

◆ lighting() [2/2]

◆ lightPosition() [1/2]

◆ lightPosition() [2/2]

◆ numGeometries()

◆ numStyles()

◆ numTerrainDatabases()

◆ numTracks()

◆ pickGeometries()

◆ pickGeometry()

◆ pickTrack()

◆ pickTracks()

◆ redraw()

◆ removeAllGeometry()

◆ removeAllTracks()

◆ removeGeometry() [1/2]

◆ removeGeometry() [2/2]

◆ removeStyle() [1/2]

◆ removeStyle() [2/2]

◆ removeTerrainDatabase() [1/2]

◆ removeTerrainDatabase() [2/2]

◆ removeTrack() [1/2]

◆ removeTrack() [2/2]

◆ reset()

◆ resize()

◆ screenshot()

◆ setDeviceCapabilities()

◆ setStyle()

◆ styleName()

◆ terrainExaggeration() [1/2]

◆ terrainExaggeration() [2/2]

◆ TMCToLatLong() [1/2]

◆ TMCToLatLong() [2/2]

◆ wndResize()