TSLTrackDisplayManager Class Reference

Detailed Description

MapLink track display manager.

This class handles the display of TSLTrack objects, for one or more TSLDrawingSurfaceBase instances. By default all of the added tracks will be displayed on all of the attached drawing surfaces. Each track must be assigned a numerical ID when added to the manager. These IDs are used to identify the Tracks within the manager, and do not need to be sequential. Tracks will be drawn in in ID order, with lower IDs drawn on top of higher IDs.

The manager provides the following track operations:

  • Position update.
  • Label update (velocity, heading, altitude).
  • Track visibility, on a per-surface basis.
  • History point visibility, on a per-Track, and per-surface basis.
  • Track selection markers, on a per-Track, and per-surface basis.
  • Direction indicator visibility, on a per-surface basis.

The track operation methods have been designed for frequent updates, and allow these operations to be performed in batches.

The manager has two distinct concepts for time:

  1. Current time
  2. Display time

Current time always represents the most up to date information that the manager has. Changes to tracks, e.g. adding or removing tracks or changing track positions, always update the track information at the current time.

Display time represents the active view of the tracks at a given time interval, which can be in the past. Querying tracks or track information in this case will return the track information as it was at that point in time rather than the current values for the track.

By default current time and display time are the same. When history tracking is enabled in the manager through historicDataExpiry() the two time values can be set differently through currentTime() and displayTime().

The memory usage when recording track history is minimised, by only storing the individual position/appearance values which have changed. However if data is stored for a long time, and very frequent updates are made to a lot of objects, the application may use a significant amount of memory.

Configuration of history points is performed by the TSLTrackDisplayManager, which provides the following settings:

  • History display type (TSLTrackDisplayManager::HistoryPointType).
  • Distance between history points.
  • Maximum number of history points per-track.
  • History point visibility, on a per-surface basis.
  • History point colour.

Public Types

enum  HistoryPointType { HistoryPointTypeNone , HistoryPointTypeSquare , HistoryPointTypeSymbol }
 The type of history points to display. More...
 
enum  ViewRotation { RotationNorthUp , RotationTrackUp }
 

Public Member Functions

void destroy ()
 Delete the track display manager. More...
 
int addDrawingSurface (TSLDrawingSurfaceBase *surface, const char *name)
 
bool addTrack (TSLTrack::TrackID trackNumber, TSLTrack *track)
 
void currentTime (uint64_t time)
 
void cancelFollowTrack (int drawingSurfaceID)
 
void clearAllHistoryPoints ()
 Remove all history points, for all tracks. More...
 
void clearAllTracks ()
 Remove all tracks from the TSLTrackDisplayManager. More...
 
bool clearAllTrackSelections (int drawingSurfaceID)
 
bool cloneTrackInto (TSLTrack::TrackID trackNumber, TSLTrackDisplayManager *other)
 
bool headingIndicatorsVisible (int drawingSurfaceID, bool visible)
 
void historicDataExpiry (uint64_t time)
 
void displayTime (uint64_t time)
 
bool followTrack (int drawingSurfaceID, TSLTrack::TrackID trackNumber)
 
void historyPointDistance (uint32_t distance)
 
void numHistoryPoints (uint32_t size)
 
uint32_t numHistoryPoints () const
 
void historyPointType (HistoryPointType type)
 
void historyPointSymbol (TSLTrackHistorySymbol *symbol)
 
bool historyPointsVisible (int drawingSurfaceID, bool visibility)
 
bool moveTrack (TSLTrack::TrackID trackNumber, double latitude, double longitude)
 
bool moveTracks (uint32_t numberOfTracks, const TSLTrack::TrackID *trackNumbers, const double *latitudes, const double *longitudes)
 
uint32_t numberOfTracks () const
 
uint32_t numberOfCurrentTracks () const
 
TSLTrackqueryTrack (TSLTrack::TrackID trackNumber)
 
TSLTrackqueryTrackFromUserID (uint32_t id)
 
bool removeDrawingSurface (int drawingSurfaceID)
 
bool removeTrack (TSLTrack::TrackID trackNumber)
 
bool selectTrack (int drawingSurfaceID, TSLTrack::TrackID trackNumber, bool selection)
 
bool selectTracks (int drawingSurfaceID, uint32_t numberOfTracks, const TSLTrack::TrackID *trackNumbers, const bool *selections)
 
bool trackIDs (uint32_t numberOfTracks, TSLTrack::TrackID *trackNumbers) const
 
bool currentTrackIDs (uint32_t numberOfTracks, TSLTrack::TrackID *trackNumbers) const
 
bool trackVisibility (int drawingSurfaceID, bool visibility)
 
bool trackVisibility (int drawingSurfaceID, TSLTrack::TrackID trackNumber, bool visibility)
 
bool trackVisibility (int drawingSurfaceID, uint32_t numberOfTracks, const TSLTrack::TrackID *trackNumbers, const bool *visibilities)
 
bool updateTrackLabels (TSLTrack::TrackID trackNumber, double velocity, double heading, double altitude)
 
bool updateTrackLabels (uint32_t numberOfTracks, const TSLTrack::TrackID *trackNumbers, const double *velocities, const double *headings, const double *altitudes)
 
bool viewRotation (int drawingSurfaceID, ViewRotation viewRotation)
 
bool addGraphic (TSLTrack::TrackID graphicID, TSLTrackGraphic *graphic)
 
TSLTrackGraphicqueryGraphic (TSLTrack::TrackID graphicID) const
 
TSLTrackGraphicqueryGraphicFromUserID (uint32_t id) const
 
uint32_t numGraphics () const
 
TSLTrackGraphicgetGraphic (uint32_t index) const
 
bool updateGraphic (uint32_t index, TSLTrackGraphic *graphic)
 
bool removeGraphic (uint32_t index)
 
bool removeGraphic (TSLTrackGraphic *graphic)
 
void removeAllGraphics ()
 Remove all graphics. More...
 

Static Public Member Functions

static TSLTrackDisplayManagercreate ()
 Create a TSLTrackDisplayManager. More...
 

Member Enumeration Documentation

◆ HistoryPointType

The type of history points to display.

Enumerator
HistoryPointTypeNone 

History points will not be displayed.

HistoryPointTypeSquare 

History points will be displayed as a 3x3 pixel square.

HistoryPointTypeSymbol 

History points will be displayed as a specific symbol, defined by TSLTrackDisplayManager::historyPointSymbol.

◆ ViewRotation

Defines whether the view will rotate automatically, when a drawing surface is set to follow a specific track.

Enumerator
RotationNorthUp 

The view will not rotate.

RotationTrackUp 

The view will rotate, following the direction of the specified track. See TSLTrackDisplayManager::followTrack.

Member Function Documentation

◆ addDrawingSurface()

int TSLTrackDisplayManager::addDrawingSurface ( TSLDrawingSurfaceBase surface,
const char *  name 
)

Add a drawing surface to the TSLTrackDisplayManager

Parameters
surfaceThe drawing surface to add.
nameThe unique name for this drawing surface. A layer with this name will be created within the drawing surface, which can be used for decluttering/track query functionality. This name should be unique within the drawing surface, but multiple drawing surfaces may be added to the TSLTrackDisplayManager with the same name.
Returns
The numeric ID of the drawing surface, or -1 if the drawing surface was not added.

◆ addGraphic()

bool TSLTrackDisplayManager::addGraphic ( TSLTrack::TrackID  graphicID,
TSLTrackGraphic graphic 
)

Add a graphic to the track display

Parameters
graphicIDThe ID of the graphic. This must not be used by any other graphic or track within the manager
graphicThe graphic to add. The application retains ownership of this object
Returns
true if the graphic was added, false otherwise

◆ addTrack()

bool TSLTrackDisplayManager::addTrack ( TSLTrack::TrackID  trackNumber,
TSLTrack track 
)

Add a track to the manager.

The track manager will take a reference to the TSLTrack. The application may continue to use the track for as long as it holds a reference.

A track cannot be added to multiple track managers at once. This method will return false if the track has been added to anther TSLTrackDisplayManager. Tracks may however be copied into another manager via cloneTrackInto.

The draw order of tracks is defined by their respective TrackIDs. Tracks with lower IDs will be drawn on top of tracks with higher IDs.

If a track already exists with the given ID, the new track will not be added. Tracks will be removed from the manager once removeTrack has been called. If the manager is storing historic data a track will not be removed until the historic data expiry period has passed.

Parameters
trackNumberThe numeric ID of the track. These IDs do not need to be sequential.
trackThe track object to add.
Returns
true if the track was added, false otherwise.

◆ cancelFollowTrack()

void TSLTrackDisplayManager::cancelFollowTrack ( int  drawingSurfaceID)

Stops an attached drawing surface from following a track.

Parameters
drawingSurfaceIDthe ID of the drawing surface in which to stop following the currently followed track.

◆ clearAllHistoryPoints()

void TSLTrackDisplayManager::clearAllHistoryPoints ( )

Remove all history points, for all tracks.

◆ clearAllTracks()

void TSLTrackDisplayManager::clearAllTracks ( )

Remove all tracks from the TSLTrackDisplayManager.

◆ clearAllTrackSelections()

bool TSLTrackDisplayManager::clearAllTrackSelections ( int  drawingSurfaceID)

Clear all of the track selection markers for the given drawing surface

Parameters
drawingSurfaceIDThe ID of the DrawingSurface to clear the selection markers for.
Returns
true if the selections were cleared, false otherwise.

◆ cloneTrackInto()

bool TSLTrackDisplayManager::cloneTrackInto ( TSLTrack::TrackID  trackNumber,
TSLTrackDisplayManager other 
)

Copy a track into another TSLTrackDisplayManager.

This will clone the TSLTrack object, including all history point and per drawing surface information.

Parameters
trackNumberThe numeric ID of the track to clone.
otherThe TSLTrackDisplayManager to add the track to.
Returns
true if the track was added to the other manager, false otherwise.

◆ create()

static TSLTrackDisplayManager * TSLTrackDisplayManager::create ( )
static

◆ currentTime()

void TSLTrackDisplayManager::currentTime ( uint64_t  time)

Set the current time.

Any updates applied to the TSLTrackDisplayManager or TSLTrack objects will be registered at this time.

If the currentTime value has not been set, or is set to 0, the manager will not store historic data, and will display the data in its current state.

If the currentTime value has been set, the manager will store historic data, until the expiry period has passed.

The granularity of time values is defined by the application, and therefore can be any desired value such as seconds since epoch or milliseconds since application start.

Parameters
timeThe current time.

◆ currentTrackIDs()

bool TSLTrackDisplayManager::currentTrackIDs ( uint32_t  numberOfTracks,
TSLTrack::TrackID trackNumbers 
) const

Query the track numbers that exist in the manager at the current time.

Parameters
numberOfTracksThe number of track numbers to query. This specifies the size of the 'trackNumbers' argument.
trackNumbersAn array which will be populated with the Track IDs.
Returns
true if the trackNumbers array was populated, false if an error occurred.

◆ destroy()

void TSLTrackDisplayManager::destroy ( )

Delete the track display manager.

◆ displayTime()

void TSLTrackDisplayManager::displayTime ( uint64_t  time)

Set the display time for the manager.

When a display time is set, the manager will both display and return track data as it was at the given time interval. This means that tracks that did not exist at the given time interval will not be returned from queryTrack() and information methods on each TSLTrack object will return their values as they were at that time interval rather than the current values for the track.

If the display time is set to 0, the manager will display all track data in its current state.

Parameters
timeThe time to display track data at.
See also
historicDataExpiry()

◆ followTrack()

bool TSLTrackDisplayManager::followTrack ( int  drawingSurfaceID,
TSLTrack::TrackID  trackNumber 
)

Set an attached drawing surface to follow a specific track.

If a drawing surface is set to follow tracks from multiple track display managers, it will follow the last track set.

Parameters
drawingSurfaceIDThe ID of the drawing surface to modify.
trackNumberThe number of the track to follow
Returns
true of the drawing surface was set to follow the track, false otherwise.

◆ getGraphic()

TSLTrackGraphic * TSLTrackDisplayManager::getGraphic ( uint32_t  index) const

Query a graphic

Parameters
indexThe index of the graphic to query
Returns
The requested graphic or NULL on error

◆ headingIndicatorsVisible()

bool TSLTrackDisplayManager::headingIndicatorsVisible ( int  drawingSurfaceID,
bool  visible 
)

Set the visibility of all direction indicators, for a given drawing surface.

Parameters
drawingSurfaceIDThe ID of the drawing surface to modify.
visibleThe visibility of direction indicators.
Returns
true if the indicators were updated, false otherwise.

◆ historicDataExpiry()

void TSLTrackDisplayManager::historicDataExpiry ( uint64_t  time)

The maximum period to store historic Track data for.

Data older than (currentTime - historicDataExpiry) will be deleted.

Parameters
timeThe maximum period of time to store historic Track display data for.

◆ historyPointDistance()

void TSLTrackDisplayManager::historyPointDistance ( uint32_t  distance)

Set the minimum distance between history points.

Parameters
distanceThe distance between points, in map units

◆ historyPointsVisible()

bool TSLTrackDisplayManager::historyPointsVisible ( int  drawingSurfaceID,
bool  visibility 
)

Set the visibility of all history points, for a given drawing surface.

Parameters
drawingSurfaceIDThe drawing surface to modify.
visibilityThe visibility of history points.
Returns
true if the visibility was set, false otherwise.

◆ historyPointSymbol()

void TSLTrackDisplayManager::historyPointSymbol ( TSLTrackHistorySymbol symbol)

Set the symbol to use for history points.

This TSLTrackHistorySymbol object will be owned by the TSLTrackDisplayManager, and must not be deleted.

This will only be used if the history type is HistoryPointTypeSymbol.

Parameters
symbolThe HistorySymbol to display.

◆ historyPointType()

void TSLTrackDisplayManager::historyPointType ( HistoryPointType  type)

Set the type of history points to display.

Parameters
typeThe type of points to display.

◆ moveTrack()

bool TSLTrackDisplayManager::moveTrack ( TSLTrack::TrackID  trackNumber,
double  latitude,
double  longitude 
)

Update the position of a single track. This method always acts upon tracks at the current time.

All latitude and longitude values provided to the Track Manager SDK must be in the WGS84 datum.

Parameters
trackNumberThe track to modify.
latitudeThe new latitude value of the specified track.
longitudeThe new longitude value of the specified track.
Returns
true if the track was moved successfully, false otherwise.

◆ moveTracks()

bool TSLTrackDisplayManager::moveTracks ( uint32_t  numberOfTracks,
const TSLTrack::TrackID trackNumbers,
const double *  latitudes,
const double *  longitudes 
)

Update the positions of multiple tracks. This method always acts upon tracks at the current time.

All latitude and longitude values provided to the Track Manager SDK must be in the WGS84 datum.

Parameters
numberOfTracksThe number of tracks to set the position for. This specifies the size of the array arguments.
trackNumbersAn array of TrackIDs, which specify the tracks to modify.
latitudesAn array of doubles, which specify the latitude values for the corresponding track.
longitudesAn array of doubles, which specify the longitude values for the corresponding track.
Returns
true if all tracks were moved successfully, false otherwise.

◆ numberOfCurrentTracks()

uint32_t TSLTrackDisplayManager::numberOfCurrentTracks ( ) const

Query the number of tracks in the manager at the current time.

Returns
The number of tracks in the TSLTrackDisplayManager.
See also
numberOfTracks

◆ numberOfTracks()

uint32_t TSLTrackDisplayManager::numberOfTracks ( ) const

Query the number of tracks in the manager at the display time.

This can be different to the number of tracks that exist at the current time if tracks were removed from the manager after the active display time.

Returns
The number of tracks in the TSLTrackDisplayManager.
See also
numberOfCurrentTracks

◆ numGraphics()

uint32_t TSLTrackDisplayManager::numGraphics ( ) const

Query the number of graphics in the manager

Returns
The number of graphics

◆ numHistoryPoints() [1/2]

uint32_t TSLTrackDisplayManager::numHistoryPoints ( ) const

Get the number of history points which will be displayed per track.

Returns
The number of history points.

◆ numHistoryPoints() [2/2]

void TSLTrackDisplayManager::numHistoryPoints ( uint32_t  size)

Set the number of history points to display per track.

If the number of points reaches this limit, old points will be removed. This setting applies to all tracks within this manager.

Parameters
sizeThe number of history points.

◆ queryGraphic()

TSLTrackGraphic * TSLTrackDisplayManager::queryGraphic ( TSLTrack::TrackID  graphicID) const

Query a graphic from the manager

Parameters
graphicIDThe ID of the graphic
Returns
The requested graphic, or NULL on error

◆ queryGraphicFromUserID()

TSLTrackGraphic * TSLTrackDisplayManager::queryGraphicFromUserID ( uint32_t  id) const

Query a graphic using a user ID

Parameters
idThe user ID of the graphic
Returns
The requested graphic, or NULL on error

◆ queryTrack()

TSLTrack * TSLTrackDisplayManager::queryTrack ( TSLTrack::TrackID  trackNumber)

Query a track from the manager at the current display time.

Data queried from the returned TSLTrack object will be returned at the display time. If historic data is not being stored, it will be the current state of the object.

The returned track may be modified by the application however the application must not call release on the returned pointer

Parameters
trackNumberThe ID of the track to query.
Returns
The requested TSLTrack object, or NULL if an invalid ID was specified.

◆ queryTrackFromUserID()

TSLTrack * TSLTrackDisplayManager::queryTrackFromUserID ( uint32_t  id)

Query a track from the manager, using the given user ID.

If multiple tracks exist with the same user ID, the one with the lowest TrackID will be returned. This will be an expensive operation. If a fast query is required the queryTrack method should be used with the TrackID.

The returned track may be modified by the application however the application must not call release on the returned pointer

Parameters
idThe user ID of the track to query.
Returns
The Track with the specified id. NULL will be returned if the track was not found.

◆ removeAllGraphics()

void TSLTrackDisplayManager::removeAllGraphics ( )

Remove all graphics.

◆ removeDrawingSurface()

bool TSLTrackDisplayManager::removeDrawingSurface ( int  drawingSurfaceID)

Remove a drawing surface instance from the TSLTrackDisplayManager.

Parameters
drawingSurfaceIDThe ID of the drawing surface to remove.
Returns
true if the drawing surface was removed, or false if an invalid ID was provided.

◆ removeGraphic() [1/2]

bool TSLTrackDisplayManager::removeGraphic ( TSLTrackGraphic graphic)

Remove a graphic

Parameters
graphicThe graphic to remove
Returns
true if the graphic was removed, false otherwise

◆ removeGraphic() [2/2]

bool TSLTrackDisplayManager::removeGraphic ( uint32_t  index)

Remove a graphic

Parameters
indexThe index of the graphic to remove
Returns
true if the graphic was removed, false otherwise

◆ removeTrack()

bool TSLTrackDisplayManager::removeTrack ( TSLTrack::TrackID  trackNumber)

Remove a track from the manager. This method always acts upon tracks at the current time and not the display time.

If historic data is not being stored, the TrackID may be re-used immediately. Otherwise it may be re-used once the historic data expiry time has passed.

Parameters
trackNumberThe ID of the track to remove.
Returns
true if the track was removed, false otherwise.

◆ selectTrack()

bool TSLTrackDisplayManager::selectTrack ( int  drawingSurfaceID,
TSLTrack::TrackID  trackNumber,
bool  selection 
)

Set the selection marker status on a track for a given drawing surface at the display time.

Parameters
drawingSurfaceIDThe ID of the drawing surface.
trackNumberThe TrackID to modify.
selectionWhether to display the track selection marker.
Returns
true if the status was set successfully, false otherwise.

◆ selectTracks()

bool TSLTrackDisplayManager::selectTracks ( int  drawingSurfaceID,
uint32_t  numberOfTracks,
const TSLTrack::TrackID trackNumbers,
const bool *  selections 
)

Set the track selection marker status on multiple tracks for the given drawing surface at the display time.

Parameters
drawingSurfaceIDThe ID of the drawing surface.
numberOfTracksThe number of tracks to modify. This specifies the size of the array arguments.
trackNumbersAn array which specifies the Track IDs to modify.
selectionsAn array which specifies the selection marker status for the corresponding tracks.
Returns
true if the statuses were set successfully, false otherwise.

◆ trackIDs()

bool TSLTrackDisplayManager::trackIDs ( uint32_t  numberOfTracks,
TSLTrack::TrackID trackNumbers 
) const

Query the track numbers that exist in the manager at the display time.

Parameters
numberOfTracksThe number of track numbers to query. This specifies the size of the 'trackNumbers' argument.
trackNumbersAn array which will be populated with the Track IDs.
Returns
true if the trackNumbers array was populated, false if an error occurred.

◆ trackVisibility() [1/3]

bool TSLTrackDisplayManager::trackVisibility ( int  drawingSurfaceID,
bool  visibility 
)

Set the visibility of all tracks, for a given drawing surface.

Parameters
drawingSurfaceIDThe ID of the drawing surface.
visibilityThe new visibility setting for all tracks.
Returns
true if the visibility setting was applied, false otherwise.

◆ trackVisibility() [2/3]

bool TSLTrackDisplayManager::trackVisibility ( int  drawingSurfaceID,
TSLTrack::TrackID  trackNumber,
bool  visibility 
)

Set the visibility of a single track, for a given drawing surface.

Parameters
drawingSurfaceIDThe ID of the drawing surface.
trackNumberThe ID of the track to modify.
visibilityThe new visibility setting for the specified track.
Returns
true if the visibility setting was applied, false otherwise.

◆ trackVisibility() [3/3]

bool TSLTrackDisplayManager::trackVisibility ( int  drawingSurfaceID,
uint32_t  numberOfTracks,
const TSLTrack::TrackID trackNumbers,
const bool *  visibilities 
)

Set the visibility of multiple tracks, for a given drawing surface.

Parameters
drawingSurfaceIDThe ID of the drawing surface.
numberOfTracksThe number of tracks to update. The specifies the size of the array arguments.
trackNumbersAn array of TrackIDs, which specify the tracks to modify.
visibilitiesAn array of bools, which specify the visibility of the corresponding tracks.
Returns
true if all visibility settings were applied, false otherwise.

◆ updateGraphic()

bool TSLTrackDisplayManager::updateGraphic ( uint32_t  index,
TSLTrackGraphic graphic 
)

Update a graphic

Parameters
indexThe index of the graphic to update
graphicThe replacement graphic. The application retains ownership of this object
Returns
true if the graphic was updated, false otherwise

◆ updateTrackLabels() [1/2]

bool TSLTrackDisplayManager::updateTrackLabels ( TSLTrack::TrackID  trackNumber,
double  velocity,
double  heading,
double  altitude 
)

Update the labels for a single track. This method always acts upon tracks at the current time and not the display time.

Parameters
trackNumberThe TrackID to modify
velocityThe new velocity of the track.
headingThe new heading of the track.
altitudeThe new Altitude of the track.
Returns
true if the track labels were updated, false otherwise.

◆ updateTrackLabels() [2/2]

bool TSLTrackDisplayManager::updateTrackLabels ( uint32_t  numberOfTracks,
const TSLTrack::TrackID trackNumbers,
const double *  velocities,
const double *  headings,
const double *  altitudes 
)

Update the labels for multiple tracks. This method always acts upon tracks at the current time and not the display time.

Parameters
numberOfTracksThe number of tracks to modify. This specifies the size of the array arguments.
trackNumbersAn array which specifies the track IDs to modify.
velocitiesAn array which specifies the new velocities of the corresponding tracks.
headingsAn array which specifies the new headings of the corresponding tracks.
altitudesAn array which specifies the new altitudes of the corresponding tracks.
Returns
true if all track labels were updated, false otherwise.

◆ viewRotation()

bool TSLTrackDisplayManager::viewRotation ( int  drawingSurfaceID,
ViewRotation  viewRotation 
)

Set the view rotation mode for the given drawing surface.

Parameters
drawingSurfaceIDThe ID of the drawing surface to modify.
viewRotationThe rotation setting for the drawing surface.
Returns
true if the rotation was set, false otherwise.