![]() |
MapLink Pro 11.1.1.0.
Envitia MapLink Pro: The Ultimate Mapping Application Toolkit
|
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:
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:
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:
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. | |
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. | |
void | clearAllTracks () |
Remove all tracks from the TSLTrackDisplayManager. | |
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 |
TSLTrack * | queryTrack (TSLTrack::TrackID trackNumber) |
TSLTrack * | queryTrackFromUserID (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) |
TSLTrackGraphic * | queryGraphic (TSLTrack::TrackID graphicID) const |
TSLTrackGraphic * | queryGraphicFromUserID (uint32_t id) const |
uint32_t | numGraphics () const |
TSLTrackGraphic * | getGraphic (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. | |
Static Public Member Functions | |
static TSLTrackDisplayManager * | create () |
Create a TSLTrackDisplayManager. | |
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. |
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. |
int TSLTrackDisplayManager::addDrawingSurface | ( | TSLDrawingSurfaceBase * | surface, |
const char * | name ) |
Add a drawing surface to the TSLTrackDisplayManager
surface | The drawing surface to add. |
name | The 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. |
bool TSLTrackDisplayManager::addGraphic | ( | TSLTrack::TrackID | graphicID, |
TSLTrackGraphic * | graphic ) |
Add a graphic to the track display
graphicID | The ID of the graphic. This must not be used by any other graphic or track within the manager |
graphic | The graphic to add. The application retains ownership of this object |
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.
trackNumber | The numeric ID of the track. These IDs do not need to be sequential. |
track | The track object to add. |
void TSLTrackDisplayManager::cancelFollowTrack | ( | int | drawingSurfaceID | ) |
Stops an attached drawing surface from following a track.
drawingSurfaceID | the ID of the drawing surface in which to stop following the currently followed track. |
void TSLTrackDisplayManager::clearAllHistoryPoints | ( | ) |
Remove all history points, for all tracks.
void TSLTrackDisplayManager::clearAllTracks | ( | ) |
Remove all tracks from the TSLTrackDisplayManager.
bool TSLTrackDisplayManager::clearAllTrackSelections | ( | int | drawingSurfaceID | ) |
Clear all of the track selection markers for the given drawing surface
drawingSurfaceID | The ID of the DrawingSurface to clear the selection markers for. |
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.
trackNumber | The numeric ID of the track to clone. |
other | The TSLTrackDisplayManager to add the track to. |
|
static |
Create a TSLTrackDisplayManager.
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.
time | The current time. |
bool TSLTrackDisplayManager::currentTrackIDs | ( | uint32_t | numberOfTracks, |
TSLTrack::TrackID * | trackNumbers ) const |
Query the track numbers that exist in the manager at the current time.
numberOfTracks | The number of track numbers to query. This specifies the size of the 'trackNumbers' argument. |
trackNumbers | An array which will be populated with the Track IDs. |
void TSLTrackDisplayManager::destroy | ( | ) |
Delete the track display manager.
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.
time | The time to display track data at. |
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.
drawingSurfaceID | The ID of the drawing surface to modify. |
trackNumber | The number of the track to follow |
TSLTrackGraphic * TSLTrackDisplayManager::getGraphic | ( | uint32_t | index | ) | const |
Query a graphic
index | The index of the graphic to query |
bool TSLTrackDisplayManager::headingIndicatorsVisible | ( | int | drawingSurfaceID, |
bool | visible ) |
Set the visibility of all direction indicators, for a given drawing surface.
drawingSurfaceID | The ID of the drawing surface to modify. |
visible | The visibility of direction indicators. |
void TSLTrackDisplayManager::historicDataExpiry | ( | uint64_t | time | ) |
The maximum period to store historic Track data for.
Data older than (currentTime - historicDataExpiry) will be deleted.
time | The maximum period of time to store historic Track display data for. |
void TSLTrackDisplayManager::historyPointDistance | ( | uint32_t | distance | ) |
Set the minimum distance between history points.
distance | The distance between points, in map units |
bool TSLTrackDisplayManager::historyPointsVisible | ( | int | drawingSurfaceID, |
bool | visibility ) |
Set the visibility of all history points, for a given drawing surface.
drawingSurfaceID | The drawing surface to modify. |
visibility | The visibility of history points. |
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.
symbol | The HistorySymbol to display. |
void TSLTrackDisplayManager::historyPointType | ( | HistoryPointType | type | ) |
Set the type of history points to display.
type | The type of points to display. |
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.
trackNumber | The track to modify. |
latitude | The new latitude value of the specified track. |
longitude | The new longitude value of the specified track. |
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.
numberOfTracks | The number of tracks to set the position for. This specifies the size of the array arguments. |
trackNumbers | An array of TrackIDs, which specify the tracks to modify. |
latitudes | An array of doubles, which specify the latitude values for the corresponding track. |
longitudes | An array of doubles, which specify the longitude values for the corresponding track. |
uint32_t TSLTrackDisplayManager::numberOfCurrentTracks | ( | ) | const |
Query the number of tracks in the manager at the current time.
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.
uint32_t TSLTrackDisplayManager::numGraphics | ( | ) | const |
Query the number of graphics in the manager
uint32_t TSLTrackDisplayManager::numHistoryPoints | ( | ) | const |
Get the number of history points which will be displayed per track.
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.
size | The number of history points. |
TSLTrackGraphic * TSLTrackDisplayManager::queryGraphic | ( | TSLTrack::TrackID | graphicID | ) | const |
Query a graphic from the manager
graphicID | The ID of the graphic |
TSLTrackGraphic * TSLTrackDisplayManager::queryGraphicFromUserID | ( | uint32_t | id | ) | const |
Query a graphic using a user ID
id | The user ID of the graphic |
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
trackNumber | The ID of the track to query. |
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
id | The user ID of the track to query. |
void TSLTrackDisplayManager::removeAllGraphics | ( | ) |
Remove all graphics.
bool TSLTrackDisplayManager::removeDrawingSurface | ( | int | drawingSurfaceID | ) |
Remove a drawing surface instance from the TSLTrackDisplayManager.
drawingSurfaceID | The ID of the drawing surface to remove. |
bool TSLTrackDisplayManager::removeGraphic | ( | TSLTrackGraphic * | graphic | ) |
Remove a graphic
graphic | The graphic to remove |
bool TSLTrackDisplayManager::removeGraphic | ( | uint32_t | index | ) |
Remove a graphic
index | The index of the graphic to remove |
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.
trackNumber | The ID of the track to remove. |
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.
drawingSurfaceID | The ID of the drawing surface. |
trackNumber | The TrackID to modify. |
selection | Whether to display the track selection marker. |
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.
drawingSurfaceID | The ID of the drawing surface. |
numberOfTracks | The number of tracks to modify. This specifies the size of the array arguments. |
trackNumbers | An array which specifies the Track IDs to modify. |
selections | An array which specifies the selection marker status for the corresponding tracks. |
bool TSLTrackDisplayManager::trackIDs | ( | uint32_t | numberOfTracks, |
TSLTrack::TrackID * | trackNumbers ) const |
Query the track numbers that exist in the manager at the display time.
numberOfTracks | The number of track numbers to query. This specifies the size of the 'trackNumbers' argument. |
trackNumbers | An array which will be populated with the Track IDs. |
bool TSLTrackDisplayManager::trackVisibility | ( | int | drawingSurfaceID, |
bool | visibility ) |
Set the visibility of all tracks, for a given drawing surface.
drawingSurfaceID | The ID of the drawing surface. |
visibility | The new visibility setting for all tracks. |
bool TSLTrackDisplayManager::trackVisibility | ( | int | drawingSurfaceID, |
TSLTrack::TrackID | trackNumber, | ||
bool | visibility ) |
Set the visibility of a single track, for a given drawing surface.
drawingSurfaceID | The ID of the drawing surface. |
trackNumber | The ID of the track to modify. |
visibility | The new visibility setting for the specified track. |
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.
drawingSurfaceID | The ID of the drawing surface. |
numberOfTracks | The number of tracks to update. The specifies the size of the array arguments. |
trackNumbers | An array of TrackIDs, which specify the tracks to modify. |
visibilities | An array of bools, which specify the visibility of the corresponding tracks. |
bool TSLTrackDisplayManager::updateGraphic | ( | uint32_t | index, |
TSLTrackGraphic * | graphic ) |
Update a graphic
index | The index of the graphic to update |
graphic | The replacement graphic. The application retains ownership of this object |
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.
trackNumber | The TrackID to modify |
velocity | The new velocity of the track. |
heading | The new heading of the track. |
altitude | The new Altitude of the track. |
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.
numberOfTracks | The number of tracks to modify. This specifies the size of the array arguments. |
trackNumbers | An array which specifies the track IDs to modify. |
velocities | An array which specifies the new velocities of the corresponding tracks. |
headings | An array which specifies the new headings of the corresponding tracks. |
altitudes | An array which specifies the new altitudes of the corresponding tracks. |
bool TSLTrackDisplayManager::viewRotation | ( | int | drawingSurfaceID, |
ViewRotation | viewRotation ) |
Set the view rotation mode for the given drawing surface.
drawingSurfaceID | The ID of the drawing surface to modify. |
viewRotation | The rotation setting for the drawing surface. |