TSLOpenGLTrackHelper Class Reference

Detailed Description

This class abstracts away efficient OpenGL mechanisms for Track Drawing

Tracks are defined here as a dynamic object, represented by a symbol, with optional additional information that could be displayed, such as an indication of heading or points to indicate history of position.

Basic Usage

It is envisaged that an object of this class is incorporated into a user-created custom layer, derived from a TSLClientCustomDataLayer. It requires initialisation with a pointer to the drawing surface the Tracks are to displayed on. The initialisation function also takes a parameter to tell it whether the position units are to be in lat/lon or TMCs.

Each different Track type should be added to the Track Helper via the addTrackReference. This adds the Track representation to an internal Texture Atlas.

Each instance of a Track should be added using the addTrackInstance function, providing the Track reference and current position. An instance ID is returned and this should be used each time the Track is updated.

A Track Heading Display can be added using the function addTrackInstanceHeading. The display consists of a line drawn from the centre of the Track, at the angle, length, colour provided.

History Points can be enabled for a Track via the function addTrackInstanceHistoryPoints. These are drawn as single point sprites. A new point is added when the Track is the distance specified from the last point. The number of History Points can be modified but is the same for all Tracks. The maximum number of History Points is 100. The default number of History Points is 5.

Two types of Labels can be added to a track, Fixed and Single Draw. A Fixed label is one that doesn't change over time, i.e. doesn't require updating. These labels are added to the track, maintained and drawn until removed. A Single Draw label is added/drawn for the next draw call only.

A Track instance can be selected. This results in a single line box being drawn around the Track. The colour of the box
can be specified.

Public Member Functions
	TSLOpenGLTrackHelper (void)
	~TSLOpenGLTrackHelper (void)
bool	addTrackReference (const TSLEntitySet &eSet, unsigned int &trackRefID)
bool	addTrackInstance (const unsigned int &trackRefID, const TSLTMC &x, const TSLTMC &y, unsigned int &instanceID)
bool	addTrackInstance (const unsigned int &trackRefID, const double &latitude, const double &longitude, unsigned int &instanceID)
bool	addTrackInstanceHeading (const unsigned int &instanceID, const unsigned int &colour, const unsigned int &lengthPixels, const double &headingAngleRadians)
bool	addTrackInstanceHistoryPoints (const unsigned int &instanceID, const unsigned int &colour, const unsigned int &distanceMetres)
bool	addTrackInstanceFixedLabel (const unsigned int &instanceID, TSLText *label)
bool	addTrackInstanceFixedLabels (const unsigned int &instanceID, TSLvector< TSLText * > *labels)
bool	addTrackInstanceSingleDrawLabel (const unsigned int &instanceID, TSLText *label)
bool	addTrackInstanceSingleDrawLabels (const unsigned int &instanceID, TSLvector< TSLText * > *labels)
bool	deselectTrackInstance (const unsigned int &instanceID)
bool	draw (TSLRenderingInterface *renderingInterface, const TSLEnvelope *extent)
bool	initialise (TSLOpenGLSurface *surface, bool positionsInTMCs=false)
bool	maximumNumberOfTrackHistoryPoints (const unsigned int historyPointLimit)
unsigned int	maximumNumberOfTrackHistoryPoints () const
void	positionsInTMCs (bool value)
bool	positionsInTMCs () const
bool	removeAllTracks ()
bool	removeTrackInstance (const unsigned int &instanceID)
bool	removeTrackInstanceHeading (const unsigned int &instanceID)
bool	removeTrackInstanceHistoryPoints (const unsigned int &instanceID)
bool	removeTrackInstanceLabels (const unsigned int &instanceID)
bool	selectTrackInstance (const unsigned int &instanceID)
bool	selectTrackInstance (const unsigned int &instanceID, const unsigned int &colour)
bool	updateTrackInstance (const unsigned int &instanceID, const TSLTMC &x, const TSLTMC &y)
bool	updateTrackInstance (const unsigned int &instanceID, const double &latitude, const double &longitude)
bool	updateTrackInstanceHeading (const unsigned int &instanceID, const double &headingAngleRadians)
bool	updateTrackInstanceHeadingColour (const unsigned int &instanceID, const unsigned int &colour)
bool	updateTrackInstanceHeadingLength (const unsigned int &instanceID, const unsigned int &lengthPixels)
bool	updateTrackInstanceHistoryPointsColour (const unsigned int &instanceID, const unsigned int &colour)
bool	updateTrackInstanceHistoryPointsDistance (const unsigned int &instanceID, const unsigned int &distanceMetres)

Constructor & Destructor Documentation

TSLOpenGLTrackHelper()

TSLOpenGLTrackHelper::TSLOpenGLTrackHelper

(

void

)

Constructor.

~TSLOpenGLTrackHelper()

TSLOpenGLTrackHelper::~TSLOpenGLTrackHelper

(

void

)

Destructor.

Member Function Documentation

addTrackInstance() [1/2]

bool TSLOpenGLTrackHelper::addTrackInstance	(	const unsigned int &	trackRefID,
		const double &	latitude,
		const double &	longitude,
		unsigned int &	instanceID )

This function adds an instance of a Track by using the previously added Track Reference.

Parameters

trackRefID	The Track Reference ID to use to add instances of the Track.
latitude	The latitude value at which to place the Track.
longitude	The longitude value at which to place the Track.
instanceID	The unique ID used to identify the added Track Instance.

Returns

true if the Track Reference was found and the Instance was added, false if an error occurred. Examine the ErrorStack for information about any error.

addTrackInstance() [2/2]

bool TSLOpenGLTrackHelper::addTrackInstance	(	const unsigned int &	trackRefID,
		const TSLTMC &	x,
		const TSLTMC &	y,
		unsigned int &	instanceID )

This function adds an instance of a Track by using the previously added Track Reference.

Parameters

trackRefID	The Track Reference ID to use to add instances of the Track.
x	The x value in TMCs at which to place the Track.
y	The y value in TMCs at which to place the Track.
instanceID	The unique ID used to identify the added Track Instance.

Returns

true if the Track Reference was found and the Instance was added, false if an error occurred. Examine the ErrorStack for information about any error.

addTrackInstanceFixedLabel()

bool TSLOpenGLTrackHelper::addTrackInstanceFixedLabel	(	const unsigned int &	instanceID,
		TSLText *	label )

This function adds the Text Label for the Track Instance provided. A fixed label is one that doesn't change over time, i.e. doesn't require updating. The Label is added to any already present. If the Track Instance contains any fixed Text Labels they will be drawn each pass, until removed.

If the labels position is zero then the Track position will be used. For labels extracted from APP6A symbols, e.g. speed or position, then the positions should be zeroed, the offsets applied in the APP6A symbol creation will be applied when drawn.

If the labels position is non-zero then it should be in the current coordinate system units.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
label	Pointer to a TSLText object defining the label.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

addTrackInstanceFixedLabels()

bool TSLOpenGLTrackHelper::addTrackInstanceFixedLabels	(	const unsigned int &	instanceID,
		TSLvector< TSLText * > *	labels )

This function adds the array of Text Labels for the Track Instance provided. A fixed label is one that doesn't change over time, i.e. doesn't require updating. These are added to any already present. If the Track Instance contains any fixed Text Labels they will be drawn each pass, until removed.

If the labels position is zero then the Track position will be used. For labels extracted from APP6A symbols, e.g. speed or position, then the positions should be zeroed, the offsets applied in the APP6A symbol creation will be applied when drawn.

If the labels position is non-zero then it should be in the current coordinate system units.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
label	Pointer to a vector of TSLText objects defining the labels.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

addTrackInstanceHeading()

bool TSLOpenGLTrackHelper::addTrackInstanceHeading	(	const unsigned int &	instanceID,
		const unsigned int &	colour,
		const unsigned int &	lengthPixels,
		const double &	headingAngleRadians )

This function enables display of a Track Heading for the Track Instance provided.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
colour	the RGBA colour value to set for the heading line.
lengthPixels	The length in pixels for the heading line.
headingAngleRadians	The Heading Angle in radians.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

addTrackInstanceHistoryPoints()

bool TSLOpenGLTrackHelper::addTrackInstanceHistoryPoints	(	const unsigned int &	instanceID,
		const unsigned int &	colour,
		const unsigned int &	distanceMetres )

This function enables display of Track Position History Points for the Track Instance provided. The distance, in metres, is that required from the last history point before a new history point is stored/displayed.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
colour	The RGBA colour value to set for the History Points.
distanceMetres	The distance in metres between History Points.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

addTrackInstanceSingleDrawLabel()

bool TSLOpenGLTrackHelper::addTrackInstanceSingleDrawLabel	(	const unsigned int &	instanceID,
		TSLText *	label )

This function adds the Text Label for the Track Instance provided for a single draw only. The Label is added to any Single-Draw labels already present for the current frame. If the Track Instance contains any Single-Draw Text Labels they will be drawn once in the frame received and then removed.

If the labels position is zero then the Track position will be used. For labels extracted from APP6A symbols, e.g. speed or position, then the positions should be zeroed, the offsets applied in the APP6A symbol creation will be applied when drawn.

If the labels position is non-zero then it should be in the current coordinate system units.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
label	Pointer to a TSLText object defining the label.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

addTrackInstanceSingleDrawLabels()

bool TSLOpenGLTrackHelper::addTrackInstanceSingleDrawLabels	(	const unsigned int &	instanceID,
		TSLvector< TSLText * > *	labels )

This function adds the array of Text Labels for the Track Instance provided for a single draw only. The Labels are added to any Single-Draw labels already present for the current frame. If the Track Instance contains any Single-Draw Text Labels they will be drawn once in the frame received and then removed.

If the labels position is zero then the Track position will be used. For labels extracted from APP6A symbols, e.g. speed or position, then the positions should be zeroed, the offsets applied in the APP6A symbol creation will be applied when drawn.

If the labels position is non-zero then it should be in the current coordinate system units.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
label	Pointer to a vector of TSLText objects defining the labels.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

addTrackReference()

bool TSLOpenGLTrackHelper::addTrackReference	(	const TSLEntitySet &	eSet,
		unsigned int &	trackRefID )

This function adds a Track Body. This function must be called for all unique Track representations. Once a Track Reference has been added, instances of the Track can be added using the Track reference ID.

Parameters

eSet	The Track as an Entity Set.
trackRefID	The Track Reference ID to use to add instances of the Track.

Returns

true if the Entity Set was added, false if an error occurred. Examine the ErrorStack for information about any error.

deselectTrackInstance()

bool TSLOpenGLTrackHelper::deselectTrackInstance

(

const unsigned int &

instanceID

)

This function disables selection of the Track Instance provided.

Parameters

instanceID

The unique Identifier for the Track Instance to be updated.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

draw()

bool TSLOpenGLTrackHelper::draw	(	TSLRenderingInterface *	renderingInterface,
		const TSLEnvelope *	extent )

This function draws all Track Instances including any Headings and History Points.

Parameters

renderingInterface	Provides a handle to the drawing operations within a layer
extent	Provides the extent of the area being drawn by the drawing surface in TMCs

Returns

true if no errors occurred, otherwise false. Examine the ErrorStack for information about any error.

initialise()

bool TSLOpenGLTrackHelper::initialise	(	TSLOpenGLSurface *	surface,
		bool	positionsInTMCs = false )

Called to create rendering resources that will be used for drawing

Parameters

surface	A pointer to the Drawing Surface that the Track Helper should use
positionsInTMCs	Sets the Positions Mode. If set all Track updates should be in TMCs, if not set all Track updates should be in Lat/Long.

Returns

true if no errors occurred, otherwise false. Examine the ErrorStack for information about any error.

maximumNumberOfTrackHistoryPoints() [1/2]

unsigned int TSLOpenGLTrackHelper::maximumNumberOfTrackHistoryPoints

(

)

const

Returns the maximum number of History points for a Track

Returns

the maximum number of History points for a Track.

maximumNumberOfTrackHistoryPoints() [2/2]

bool TSLOpenGLTrackHelper::maximumNumberOfTrackHistoryPoints

(

const unsigned int

historyPointLimit

)

Called to set the maximum number of History points for a Track. This limit is set for all points. There is a fixed maximum limit of 100 history points for a Track. The default maximum number of history Points is 5.

Parameters

historyPointLimit

Returns

true if no errors occurred, otherwise false. Examine the ErrorStack for information about any error.

positionsInTMCs() [1/2]

bool TSLOpenGLTrackHelper::positionsInTMCs

(

)

const

Called to get the Position Mode. If set, all positions are in TMCs. If not set, all positions are in Lat/Long

Returns

True positions are in TMCs, false positions are in Lat/Long

positionsInTMCs() [2/2]

void TSLOpenGLTrackHelper::positionsInTMCs

(

bool

value

)

Called to set the Position Mode. If set, all Track positions are in TMCs. If not set, all positions are in Lat/Long

Parameters

value

Value to set the Position Mode

removeAllTracks()

bool TSLOpenGLTrackHelper::removeAllTracks

(

)

This function removes all Track Instances (including Headings and History Points) and References. It is in essence a reset function.

Returns

true if no errors occurred, otherwise false. Examine the ErrorStack for information about any error.

removeTrackInstance()

bool TSLOpenGLTrackHelper::removeTrackInstance

(

const unsigned int &

instanceID

)

This function removes the Track Instance provided. Any Heading and History Points for the Track Instance are also removed. The Track reference is not effected.

Parameters

instanceID

The unique Identifier for the Track Instance to be removed.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

removeTrackInstanceHeading()

bool TSLOpenGLTrackHelper::removeTrackInstanceHeading

(

const unsigned int &

instanceID

)

This function disables display of the Track Heading for the Track Instance provided. The display of the Track Instance itself is not effected.

Parameters

instanceID

The unique Identifier for the Track Instance to be updated.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

removeTrackInstanceHistoryPoints()

bool TSLOpenGLTrackHelper::removeTrackInstanceHistoryPoints

(

const unsigned int &

instanceID

)

This function disables display of Track Position History Points for the Track Instance provided.

Parameters

instanceID

The unique Identifier for the Track Instance to be updated.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

removeTrackInstanceLabels()

bool TSLOpenGLTrackHelper::removeTrackInstanceLabels

(

const unsigned int &

instanceID

)

This function removes all previously added Text Labels (both fixed and current single-draw labels) for the Track Instance provided.

Parameters

instanceID

The unique Identifier for the Track Instance to be updated.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

selectTrackInstance() [1/2]

bool TSLOpenGLTrackHelper::selectTrackInstance

(

const unsigned int &

instanceID

)

This function enables selection of the Track Instance provided. If selected a rectangular box is drawn around the Track.

The default colour of the selection box is white.

Parameters

instanceID

The unique Identifier for the Track Instance to be updated.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

selectTrackInstance() [2/2]

bool TSLOpenGLTrackHelper::selectTrackInstance	(	const unsigned int &	instanceID,
		const unsigned int &	colour )

This function enables selection of the Track Instance provided. If selected a rectangular box, the colour provided, is drawn around the Track.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
colour	the RGBA colour value to set for the selection box lines.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

updateTrackInstance() [1/2]

bool TSLOpenGLTrackHelper::updateTrackInstance	(	const unsigned int &	instanceID,
		const double &	latitude,
		const double &	longitude )

This function updates the position of the Track Instance provided.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
latitude	The latitude value at which to place the Track.
longitude	The longitude value at which to place the Track.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

updateTrackInstance() [2/2]

bool TSLOpenGLTrackHelper::updateTrackInstance	(	const unsigned int &	instanceID,
		const TSLTMC &	x,
		const TSLTMC &	y )

This function updates the position of the Track Instance provided.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
x	The x value in TMCs at which to place the Track.
y	The y value in TMCs at which to place the Track.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

updateTrackInstanceHeading()

bool TSLOpenGLTrackHelper::updateTrackInstanceHeading	(	const unsigned int &	instanceID,
		const double &	headingAngleRadians )

This function updates the angle of the Track Heading for the Track Instance provided. Does not check or update whether the Track Heading is set to be displayed.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
headingAngleRadians	The Heading Angle in radians.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

updateTrackInstanceHeadingColour()

bool TSLOpenGLTrackHelper::updateTrackInstanceHeadingColour	(	const unsigned int &	instanceID,
		const unsigned int &	colour )

This function updates the colour of the Track Heading for the Track Instance provided. Does not check or update whether the Track Heading is set to be displayed.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
colour	the RGBA colour value to set for the heading line.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

updateTrackInstanceHeadingLength()

bool TSLOpenGLTrackHelper::updateTrackInstanceHeadingLength	(	const unsigned int &	instanceID,
		const unsigned int &	lengthPixels )

This function updates the length of the Track Heading for the Track Instance provided. The length is in pixels. Does not check or update whether the Track Heading is set to be displayed.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
lengthPixels	The length in pixels for the heading line.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

updateTrackInstanceHistoryPointsColour()

bool TSLOpenGLTrackHelper::updateTrackInstanceHistoryPointsColour	(	const unsigned int &	instanceID,
		const unsigned int &	colour )

This function updates the colour of the Track Position History Points for the Track Instance provided.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
colour	the RGBA colour value to set for the History Points.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.

updateTrackInstanceHistoryPointsDistance()

bool TSLOpenGLTrackHelper::updateTrackInstanceHistoryPointsDistance	(	const unsigned int &	instanceID,
		const unsigned int &	distanceMetres )

This function updates the distance between the Track Position History Points for the Track Instance provided. The distance, in metres, is that required from the last history point before a new history point is stored/displayed.

Parameters

instanceID	The unique Identifier for the Track Instance to be updated.
distanceMetres	The distance in metres between History Points.

Returns

true if the Track Instance was found, false if an error occurred. Examine the ErrorStack for information about any error.