envitia::maplink::earth::TrackSymbol Class Reference

Detailed Description

The definition of a Track's visualisation on the display.

To specify the visualisation of a Track the application must setup a TrackSymbol, which contains one or more TSLEntity instances.

When configuring the visualisation the application should:

• Specify all rendering via entity rendering (TSLEntityBase::setRendering). Feature rendering is not supported as part of a TrackSymbol.
• Define geometry within the TMC range -1000,-1000 to 1000,1000 which will be mapped to cover the billboard's area.
• If required the application may change this area through the renderArea method.
• Call the billboardSize method to specify the width/height of the track's billboard in pixels. By default this is set to 50 pixels.

Based on these parameters the Track will be rendered as a 'billboard' within the 3D scene, positioned based on the location of the Track instance. The billboard will be rendered as a square region on the display, with a transparent background. Within this area the application may render any 2D TSLEntity based geometry including:

• Vector TSLSymbols.
• Raster TSLSymbols.
• Other entities such as polygons or polylines.

This symbol definition may include textual annotations, which may be configured by passing a populated AnnotationAttributes structure to addAnnotation. To configure an annotation the application must:

• Define a set of AnnotationAttributes, to specify how the annotation will be rendered.
• Call addAnnotation, providing the annotation's name and the attribute structure.
• Pass the visualisation to a track via the Track::symbol method.
• Set the value of the annotation via Track::setAttribute.

Once the track is added to the drawing surface the annotation/track attribute values may be updated at any time, along with the other visualisation parameters. After modifying the TrackSymbol the application must call Track::symbol in order to apply the visualisation to the track.

Classes
struct	AnnotationAttributes
	Definition of rendering attributes for an annotation. More...

Public Member Functions
	TrackSymbol ()
	Constructor.
	TrackSymbol (const TrackSymbol &other)
	Copy Constructor.
unsigned int	addEntity (const TSLEntity *entity)
bool	updateEntity (unsigned int id, const TSLEntity *entity)
bool	removeEntity (unsigned int id)
const TSLEntity *	getEntity (unsigned int id) const
unsigned int	numEntities () const
unsigned int	entityID (unsigned int index) const
void	billboardSize (unsigned int s)
	Set the size of the billboard in pixels.
unsigned int	billboardSize () const
	Query the size of the billboard in pixels.
void	renderArea (const TSLEnvelope &area)
const TSLEnvelope &	renderArea () const
	Query the render area of the billboard.
bool	addAnnotation (const char *attributeName, const AnnotationAttributes &renderingAttributes)
AnnotationAttributes	getAnnotation (const char *name) const
bool	removeAnnotation (const char *name)
unsigned int	numAnnotations () const
AnnotationAttributes	annotation (unsigned int index) const
const char *	annotationName (unsigned int index) const
bool	removeAnnotation (unsigned int index)

Constructor & Destructor Documentation

TrackSymbol() [1/2]

envitia::maplink::earth::TrackSymbol::TrackSymbol

(

)

Constructor.

TrackSymbol() [2/2]

envitia::maplink::earth::TrackSymbol::TrackSymbol

(

const TrackSymbol &

other

)

Copy Constructor.

Member Function Documentation

addAnnotation()

bool envitia::maplink::earth::TrackSymbol::addAnnotation	(	const char *	attributeName,
		const AnnotationAttributes &	renderingAttributes )

Add, or update an annotation definition.

If an annotation is already defined for the named attribute it will be updated to the new rendering attributes.

Parameters

attributeName	The name of the track attribute, which will be displayed.
renderingAttributes	The rendering attribute information for the annotation.

addEntity()

unsigned int envitia::maplink::earth::TrackSymbol::addEntity

(

const TSLEntity *

entity

)

Add an entity to the visualisation.

The ID returned from this method may be used to refer to the entity when using other entity access methods.

Note

The application retains ownership of the provided entity.

Parameters

entity

The entity to add.

Returns

An ID to identify the entity, or zero on error.

annotation()

AnnotationAttributes envitia::maplink::earth::TrackSymbol::annotation

(

unsigned int

index

)

const

Query an annotation definition.

Parameters

index

The index of the annotation.

Returns

The requested annotation definition, or an empty attribute set if index >= numAnnotations().

annotationName()

const char * envitia::maplink::earth::TrackSymbol::annotationName

(

unsigned int

index

)

const

Query the name of an annotation.

Parameters

index

The index to query.

Returns

The name of the annotation, or null if index >= numAnnotations().

billboardSize() [1/2]

unsigned int envitia::maplink::earth::TrackSymbol::billboardSize

(

)

const

Query the size of the billboard in pixels.

billboardSize() [2/2]

void envitia::maplink::earth::TrackSymbol::billboardSize

(

unsigned int

s

)

Set the size of the billboard in pixels.

entityID()

unsigned int envitia::maplink::earth::TrackSymbol::entityID

(

unsigned int

index

)

const

Query the id of an entity

Parameters

index

The index of the entity within the TrackSymbol.

Returns

The ID an the entity at index.

getAnnotation()

AnnotationAttributes envitia::maplink::earth::TrackSymbol::getAnnotation

(

const char *

name

)

const

Query details about an annotation definition.

Parameters

name	The name of the annotation (track attribute).

Returns

The annotation definition for the specified attribute.

getEntity()

const TSLEntity * envitia::maplink::earth::TrackSymbol::getEntity

(

unsigned int

id

)

const

Query an entity from the visualisation.

Parameters

id	The id of the entity to query.

Returns

The requested entity, or null on error.

numAnnotations()

unsigned int envitia::maplink::earth::TrackSymbol::numAnnotations

(

)

const

Query the number of annotation definitions.

In most cases applications should refer to annotations by name. The following methods are provided to allow applications to iterate through the annotation set:

• numAnnotations
• annotation(unsigned int)
• annotationName(unsigned int)
• removeAnnotation(unsigned int)

Returns

The number of annotations configured within the TrackSymbol.

numEntities()

unsigned int envitia::maplink::earth::TrackSymbol::numEntities

(

)

const

Query the number of entities in the visualisation.

In most cases applications should refer to attributes by ID, as returned from addEntity. The following methods are provided to allow applications to iterate through the entities:

• numEntities
• entityID

Returns

The number of entities within the track symbol.

removeAnnotation() [1/2]

bool envitia::maplink::earth::TrackSymbol::removeAnnotation

(

const char *

name

)

Remove an annotation definition.

Parameters

name	The name of the annotation to remove.

Returns

true if the annotation was removed, false otherwise.

removeAnnotation() [2/2]

bool envitia::maplink::earth::TrackSymbol::removeAnnotation

(

unsigned int

index

)

Remove an annotation definition.

Parameters

index

The index of the annotation to remove.

Returns

true if the annotation was removed, false otherwise.

removeEntity()

bool envitia::maplink::earth::TrackSymbol::removeEntity

(

unsigned int

id

)

Remove an entity from the visualisation.

Parameters

id	The index of the entity to remove, as returned from addEntity.

Returns

true if the entity was removed, false otherwise.

renderArea() [1/2]

const TSLEnvelope & envitia::maplink::earth::TrackSymbol::renderArea

(

)

const

Query the render area of the billboard.

renderArea() [2/2]

void envitia::maplink::earth::TrackSymbol::renderArea

(

const TSLEnvelope &

area

)

Set the render area of the billboard in TMCs.

The render area specifies the region in TMC space which will be rendered to the billboard. By default this region is from -1000,-1000 to 1000,1000.

In most cases the application should not need to modify this parameter, unless re-using a set of previous symbols or entity definitions.

Parameters

area	The region in TMC space to render onto the billboard.

updateEntity()

bool envitia::maplink::earth::TrackSymbol::updateEntity	(	unsigned int	id,
		const TSLEntity *	entity )

Update an entity in the visualisation.

Note

The application retains ownership of the provided entity.

Parameters

id	The id of the entity to update, as returned from addEntity.
entity	An entity, which will replace the previous version.