com.luciad.view.lightspeed.painter.label

LuciadLightspeedClass TLspLabelPainter

java.lang.Object

com.luciad.view.lightspeed.painter.label.TLspLabelPainter

All Implemented Interfaces:

ILspPaintGroupsChangeListener, ILspEditableStyledPainter, ILspPainter, ILspLabelPainter, ILspPathLocationLabelPainter, ILspStampLocationLabelPainter

public class TLspLabelPainter
extends Object
implements ILspLabelPainter, ILspEditableStyledPainter, ILspPathLocationLabelPainter, ILspStampLocationLabelPainter

A label painter that draws a screen-aligned images for domain objects. These can be either images/icons or text.

To customize the look and content of your labels, add an ILspStyler to this painter. If you need control over other labeling aspects such as positioning or priorities, use an ALspLabelStyler.

The content of the labels can be determined by using the proper styles. Either use:

• TLspTextStyle to get text with a specific font, font color, size, halo etc.
• TLspIconStyle to get custom images.

When painting content using a TLspTextStyle, the layout of the text is as demonstrated in the following image:

Optionally, you can also set:

• a ALspLabelTextProviderStyle to specify which text to use (default is toString()). See for example TLspDataObjectLabelTextProviderStyle.
• a TLspLabelBoxStyle to specify fill color or frames. Note that it is possible to use multiple TLspLabelBoxStyle instances for the same label. See the TLspLabelBoxStyle class doc for more information.
• a TLspPinLineStyle to draw pins for the labels
• a TLspLabelOpacityStyle to specify a global opacity or modulation color.

It is possible to paint labels with or without an overlay option. Overlay determines if depth checking is used during painting. true means that (conceptually) the label is painted at depth 0 (and is always painted in front of the terrain and other objects). false means that it can be obscured by the terrain or other objects. This setting doesn't influence which labels are painted and which ones are not.

Performance considerations:

• Creating the images is a relatively heavy operation. Therefore the images are cached and only re-created when necessary. This is decided based on differences in style or text content.
• Note that this painter can efficiently handle transparency or a modulation color without having to re-create the image. You can change TLspLabelOpacityStyle.getColor() frequently with little impact.
• Avoid changing other style options though (for example: font, color, halo etc...).
• If possible, only fire style and/or model changes for objects that are actually affected.
• Styles are requested frequently, so make sure your styler is efficient.

Limitations:

• The label painter needs an ILcdShape to retrieve a focus point in order to paint the label correctly. This can be done by either making sure the domain object is a shape or has a shape, or that the specified (non-domain object) style target is a shape or has a shape.

Since:

2012.0

Nested Class Summary

Nested classes/interfaces inherited from interface com.luciad.view.lightspeed.layer.paintgroup.ILspPaintGroupsChangeListener

ILspPaintGroupsChangeListener.Callback

Constructor Summary

Constructors

Constructor and Description
TLspLabelPainter() Creates a new label painter.

Method Summary

Modifier and Type	Method and Description
void	addPropertyChangeListener(PropertyChangeListener aPropertyChangeListener) Adds a PropertyChangeListener to the list of listeners that must be notified when any of the properties of this ILspPainter changes.
void	commitChanges(Object aEventId) Called when the changes for a specified event should be committed.
Object	getAnchorObject(TLspLabelID aLabel, TLspPaintState aPaintState, TLspContext aContext) Returns the anchor object of the given label.
long	getDefaultOpacityFadeDuration() Returns the duration of label fade in/out animations.
Iterable<TLspLabelID>	getLabelIDs(Object aObject, TLspPaintRepresentationState aPaintRepresentationState, TLspContext aContext) Enumerates all the desired labels associated with a domain object.
TLspOpenGLProfile	getRequiredOpenGLProfile() Returns the minimum required OpenGL profile that a view must support in order to be compatible with this painter.
ILspStyler	getStyler(TLspPaintState aPaintState) Returns the styler used by this painter for the given PaintState.
boolean	isHorizonFading() Returns if horizon fading is enabled.
boolean	isOverlayLabels() Indicates whether overlaying labels is enabled.
boolean	isUseTerrainForCulling() Returns if culling based on the terrain is enabled in 3D
void	labelAnchorPointOffsetSFCT(TLspLabelID aLabel, Dimension2D aDimension, TLspPaintState aPaintState, TLspContext aContext, ILcd2DEditablePoint aOffsetSFCT) Returns the anchor point offset.
void	labelAnchorPointSFCT(TLspLabelID aLabel, ALspLabelLocation aLabelLocation, ALspLabelLocations aLabelLocations, TLspPaintState aPaintState, TLspContext aContext, ILcd3DEditablePoint aAnchorPointSFCT) Retrieves the anchor point of the given label.
double	labelBoundsSFCT(TLspLabelID aLabel, ALspLabelLocation aLabelLocation, ALspLabelLocations aLocations, TLspPaintState aPaintState, TLspContext aContext, ILcd3DEditableBounds aBoundsSFCT) Calculates the bounds of the given label for the given label location.
void	labelDimensionSFCT(TLspLabelID aLabelID, TLspPaintState aPaintState, TLspContext aContext, Dimension2D aDimensionSFCT) Returns the dimension of the given label.
TLspPaintProgress	paintObjects(ILcdGLDrawable aGLDrawable, List<TLspPaintGroup> aPaintGroups, TLspPaintPass aPass, TLspContext aContext) Paints the specified groups of objects into a view.
void	prepareChanges(List<TLspPaintGroupsChangedEvent> aEvents, Object aEventId, ILspPaintGroupsChangeListener.Callback aCallback) Called when the paint groups will change.
<T> boolean	query(List<TLspPaintGroup> aPaintGroups, ALspPaintQuery<T> aQuery, TLspPaintRepresentationState aPaintRepresentationState, TLspContext aContext) Retrieves a set of domain objects and data based on the parameters given by the query.
void	registerLayer(ILspInteractivePaintableLayer aLayer, TLspPaintRepresentation aPaintRepresentation) Registers a layer with this painter.
void	removePropertyChangeListener(PropertyChangeListener aPropertyChangeListener) Removes a PropertyChangeListener from the list of listeners.
void	setDefaultOpacityFadeDuration(long aDefaultOpacityFadeDuration) Sets the default duration of label fade in/out animations.
void	setHorizonFading(boolean aDistanceBasedFading) Sets if horizon fading is enabled.
void	setOverlayLabels(boolean aOverlayLabels) Enables overlaying labels above transparent objects.
void	setStyler(TLspPaintState aPaintState, ILspStyler aStyler) Sets the styler used by this object for the given PaintState.
void	setUseTerrainForCulling(boolean aUseTerrainForCulling) Sets if culling based on the terrain is enabled in 3D.
void	unregisterLayer(ILspInteractivePaintableLayer aLayer, TLspPaintRepresentation aPaintRepresentation) Unregisters a layer from this painter.
void	viewObjectAnchorPointSFCT(TLspLabelID aLabel, ALspLabelLocations aLabelLocations, TLspPaintState aPaintState, TLspContext aContext, ILcd3DEditablePoint aObjectAnchorPointSFCT) Calculates the object anchor point for the given label in view coordinates.
void	worldObjectAnchorPointSFCT(TLspLabelID aLabel, ALspLabelLocations aLabelLocations, TLspPaintState aPaintState, TLspContext aContext, ILcd3DEditablePoint aObjectAnchorPointSFCT) Calculates the object anchor point for the given label in world coordinates.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TLspLabelPainter

public TLspLabelPainter()

Creates a new label painter.

Method Detail

setOverlayLabels

public void setOverlayLabels(boolean aOverlayLabels)

Enables overlaying labels above transparent objects.

By default, this is disabled and is only necessary in specific cases.

In particular, it can be enabled if the labels need to be above other transparent objects without blending.

Parameters:

aOverlayLabels - whether labels should be overlayed.

See Also:

isOverlayLabels()

isOverlayLabels

public boolean isOverlayLabels()

Indicates whether overlaying labels is enabled.

Returns:

the current setting

See Also:

setOverlayLabels(boolean)

setDefaultOpacityFadeDuration

public void setDefaultOpacityFadeDuration(long aDefaultOpacityFadeDuration)

Sets the default duration of label fade in/out animations.

By default, this is 500 milliseconds. When set to 0, fade in/out animations are disabled.

Parameters:

aDefaultOpacityFadeDuration - a duration in milliseconds, use 0 to disable animations.

See Also:

getDefaultOpacityFadeDuration()

getDefaultOpacityFadeDuration

public long getDefaultOpacityFadeDuration()

Returns the duration of label fade in/out animations.

Returns:

the current duration, in milliseconds.

See Also:

setDefaultOpacityFadeDuration(long)

setHorizonFading

public void setHorizonFading(boolean aDistanceBasedFading)

Sets if horizon fading is enabled. When it is enabled, labels that are close to the horizon fade out (become more transparent) until they become invisible. This effect is only enabled:

• In 3D views
• For labels of domain objects that are not selected or edited.

Horizon fading is enabled by default.

Parameters:

aDistanceBasedFading - true to enable horizon fading.

isHorizonFading

public boolean isHorizonFading()

Returns if horizon fading is enabled.

Returns:

if horizon fading is enabled.

See Also:

setHorizonFading(boolean)

setUseTerrainForCulling

public void setUseTerrainForCulling(boolean aUseTerrainForCulling)

Sets if culling based on the terrain is enabled in 3D. If true, labels will be dropped when their anchor is hidden by terrain, or by the horizon. If false, labels will only be dropped when their anchor is behind the horizon.

The default is true.

Parameters:

aUseTerrainForCulling - true to enable using terrain for culling

Since:

2019.1

isUseTerrainForCulling

public boolean isUseTerrainForCulling()

Returns if culling based on the terrain is enabled in 3D

Returns:

if culling based on the terrain is enabled in 3D

Since:

2019.1

See Also:

setUseTerrainForCulling(boolean)

setStyler

public void setStyler(TLspPaintState aPaintState,
                      ILspStyler aStyler)

Description copied from interface: ILspEditableStyledPainter

Sets the styler used by this object for the given PaintState.

Specified by:

setStyler in interface ILspEditableStyledPainter

Parameters:

aPaintState - the paint state for which to set a styler

aStyler - the new styler for the painter

viewObjectAnchorPointSFCT

public void viewObjectAnchorPointSFCT(TLspLabelID aLabel,
                                      ALspLabelLocations aLabelLocations,
                                      TLspPaintState aPaintState,
                                      TLspContext aContext,
                                      ILcd3DEditablePoint aObjectAnchorPointSFCT)
                               throws TLcdNoBoundsException

Description copied from interface: ILspStampLocationLabelPainter

Calculates the object anchor point for the given label in view coordinates.

Note : the returned point should not depend on the given label location. I.e. it should be the same point for every stamp label location.

Specified by:

viewObjectAnchorPointSFCT in interface ILspStampLocationLabelPainter

Parameters:

aLabel - the identifier of the label for which to calculate the anchor point.

aLabelLocations - context information. Can be used when a label depends on an other label.

aPaintState - the paint state.

aContext - the context.

aObjectAnchorPointSFCT - the point in which to store the object anchor point.

Throws:

TLcdNoBoundsException - when the object anchor point could not be calculated.

worldObjectAnchorPointSFCT

public void worldObjectAnchorPointSFCT(TLspLabelID aLabel,
                                       ALspLabelLocations aLabelLocations,
                                       TLspPaintState aPaintState,
                                       TLspContext aContext,
                                       ILcd3DEditablePoint aObjectAnchorPointSFCT)
                                throws TLcdNoBoundsException

Description copied from interface: ILspStampLocationLabelPainter

Calculates the object anchor point for the given label in world coordinates.

Note : the returned point should not depend on the given label location. I.e. it should be the same point for every stamp label location.

If the given label is anchored to another label, i.e. getAnchorObject returns a TLspLabelID, this method will throw a TLcdNoBoundsException.

Specified by:

worldObjectAnchorPointSFCT in interface ILspStampLocationLabelPainter

Parameters:

aLabel - the identifier of the label for which to calculate the anchor point.

aLabelLocations - context information. Can be used when a label depends on an other label.

aPaintState - the paint state.

aContext - the context.

aObjectAnchorPointSFCT - the point in which to store the object anchor point.

Throws:

TLcdNoBoundsException - when the label is anchored to a TLspLabelID or when the object anchor point could not be calculated.

labelDimensionSFCT

public void labelDimensionSFCT(TLspLabelID aLabelID,
                               TLspPaintState aPaintState,
                               TLspContext aContext,
                               Dimension2D aDimensionSFCT)
                        throws TLcdNoBoundsException

Description copied from interface: ILspStampLocationLabelPainter

Returns the dimension of the given label. Since the dimension shouldn't depend on the location of the label, no ALspLabelLocation is passed in this method.

Specified by:

labelDimensionSFCT in interface ILspStampLocationLabelPainter

Parameters:

aLabelID - the identifier of the label for which to calculate the dimension.

aPaintState - the paint state.

aContext - the context.

aDimensionSFCT - the object in which to store the dimension.

Throws:

TLcdNoBoundsException - when the dimension of the label could not be calculated.

labelAnchorPointOffsetSFCT

public void labelAnchorPointOffsetSFCT(TLspLabelID aLabel,
                                       Dimension2D aDimension,
                                       TLspPaintState aPaintState,
                                       TLspContext aContext,
                                       ILcd2DEditablePoint aOffsetSFCT)

Description copied from interface: ILspStampLocationLabelPainter

Returns the anchor point offset. This value is the offset of the anchor point, relative to the upper left corner of the bounds, assuming the rotation is 0.

By default this method returns an offset of (width / 2, height / 2). Since the anchor offset shouldn't depend on the location of the label, no ALspLabelLocation is passed in this method.

Specified by:

labelAnchorPointOffsetSFCT in interface ILspStampLocationLabelPainter

Parameters:

aLabel - a label.

aDimension - the dimension of the label.

aPaintState - the paint state.

aContext - the context.

aOffsetSFCT - the point in which the anchor point offset will be stored.

getLabelIDs

public Iterable<TLspLabelID> getLabelIDs(Object aObject,
                                         TLspPaintRepresentationState aPaintRepresentationState,
                                         TLspContext aContext)

Description copied from interface: ILspLabelPainter

Enumerates all the desired labels associated with a domain object.

Specified by:

getLabelIDs in interface ILspLabelPainter

Parameters:

aObject - the domain object

aPaintRepresentationState - the paint representation

aContext - the context

Returns:

the label identifiers associated with the given domain object.

labelBoundsSFCT

public double labelBoundsSFCT(TLspLabelID aLabel,
                              ALspLabelLocation aLabelLocation,
                              ALspLabelLocations aLocations,
                              TLspPaintState aPaintState,
                              TLspContext aContext,
                              ILcd3DEditableBounds aBoundsSFCT)
                       throws TLcdNoBoundsException

Description copied from interface: ILspLabelPainter

Calculates the bounds of the given label for the given label location.

This method returns the axis aligned bounds using aBoundsSFCT and returns a rotation. This rotation rotates the bounds around its origin. The rotation of the bounds is defined in radians, clockwise, with 0 at 3 'o clock.

It is possible that the bounds of this label depends on the location of an other label. In that case, it is possible to use the given view locations to retrieve an other location. Note that the given ALspLabelLocations should not be modified in this method.

Specified by:

labelBoundsSFCT in interface ILspLabelPainter

Parameters:

aLabel - the label for which to calculate the bounds.

aLabelLocation - the location of the label.

aLocations - possible context information. This object can for example be used when these bounds depend on bounds of an other label.

aPaintState - the paint state.

aContext - the context.

aBoundsSFCT - the object in which to store the axis aligned bounds.

Returns:

the rotation of the bounds in radians, clockwise, with 0 at 3 'o clock.

Throws:

TLcdNoBoundsException - when the bounds could not be calculated.

labelAnchorPointSFCT

public final void labelAnchorPointSFCT(TLspLabelID aLabel,
                                       ALspLabelLocation aLabelLocation,
                                       ALspLabelLocations aLabelLocations,
                                       TLspPaintState aPaintState,
                                       TLspContext aContext,
                                       ILcd3DEditablePoint aAnchorPointSFCT)
                                throws TLcdNoBoundsException

Description copied from interface: ILspLabelPainter

Retrieves the anchor point of the given label. This point is usually a point on the label, e.g. in the middle of the bounds.

Specified by:

labelAnchorPointSFCT in interface ILspLabelPainter

Parameters:

aLabel - the label for which to calculate the bounds.

aLabelLocation - the location of the label.

aLabelLocations - possible context information. This object can for example be used when these bounds depend on bounds of an other label.

aPaintState - the paint state.

aContext - the context.

aAnchorPointSFCT - the point in which to store the anchor point.

Throws:

TLcdNoBoundsException - when the anchor point could not be calculated.

getAnchorObject

public final Object getAnchorObject(TLspLabelID aLabel,
                                    TLspPaintState aPaintState,
                                    TLspContext aContext)
                             throws TLcdNoBoundsException

Description copied from interface: ILspLabelPainter

Returns the anchor object of the given label. This can either be an other TLspLabelID, an ILcdShape, and ALspStyleTargetProvider or null. In the latter case, the painter interprets the anchor itself, i.e. by using the focus point of the domain object. In the latter case, the domain object must be an ILcdShape or it must have a shape.

The various labeling algorithms use this anchor object to determine the label's location.

You can specify this anchor object using a ALspLabelStyler:

• Use ALspLabelStyleCollector.anchorLabel(java.lang.Object) to make place label relative to another label.
• Use ALspLabelStyleCollector.geometry(ILcdShape) to specify a specific geometry to be used.
• Use ALspLabelStyleCollector.geometry(ALspStyleTargetProvider) to specify a style target provider to be used. Using this method has the advantage that it is possible to specify a different shape reference than the model reference.
• If neither is used, this method returns null, and the algorithms use the domain object itself to determine the location.

Specified by:

getAnchorObject in interface ILspLabelPainter

Parameters:

aLabel - the label.

aPaintState - the paint state.

aContext - the context.

Returns:

the anchor object of the given label.

Throws:

TLcdNoBoundsException - if there is no anchor object for the given label.

prepareChanges

public void prepareChanges(List<TLspPaintGroupsChangedEvent> aEvents,
                           Object aEventId,
                           ILspPaintGroupsChangeListener.Callback aCallback)

Description copied from interface: ILspPaintGroupsChangeListener

Called when the paint groups will change.

The listener should prepare the necessary changes for the events but not commit them yet. The ILspPaintGroupsChangeListener.Callback.changesReady(java.lang.Object) method must be invoked when the listener is ready to commit the changes.

If aEventId is null then the changes may be committed immediately. In this case there will be no call to ILspPaintGroupsChangeListener.commitChanges(Object).

Note that it is not mandatory to do this two-phased commit cycle. You may commit or apply the changes immediately, but you still must invoke the callback.

Specified by:

prepareChanges in interface ILspPaintGroupsChangeListener

Parameters:

aEvents - the changes

aEventId - the event id or null

aCallback - the callback or null

commitChanges

public void commitChanges(Object aEventId)

Description copied from interface: ILspPaintGroupsChangeListener

Called when the changes for a specified event should be committed.

Specified by:

commitChanges in interface ILspPaintGroupsChangeListener

Parameters:

aEventId - the event id

getStyler

public ILspStyler getStyler(TLspPaintState aPaintState)

Description copied from interface: ILspPainter

Returns the styler used by this painter for the given PaintState. Can return null in case the painter does not use or expose a styler.

Specified by:

getStyler in interface ILspPainter

Parameters:

aPaintState - the paint state for which a styler is requested

Returns:

the styler used by this object, or null.

registerLayer

public void registerLayer(ILspInteractivePaintableLayer aLayer,
                          TLspPaintRepresentation aPaintRepresentation)

Description copied from interface: ILspPainter

Registers a layer with this painter. This notifies the painter that it is going to be used in combination with the given layer, for the given paint representation. This allows it to implement setup code if necessary, or to keep track of all layers on which it is set.

Layers registered with this method must be unregistered when the layer stops using this painter, using ILspPainter.unregisterLayer(ILspInteractivePaintableLayer, com.luciad.view.lightspeed.layer.TLspPaintRepresentation).

Specified by:

registerLayer in interface ILspPainter

Parameters:

aLayer - A layer with which this painter will be used.

aPaintRepresentation - The paint representation for which this painter will be used.

unregisterLayer

public void unregisterLayer(ILspInteractivePaintableLayer aLayer,
                            TLspPaintRepresentation aPaintRepresentation)

Description copied from interface: ILspPainter

Unregisters a layer from this painter. This notifies the painter that it will no longer be used in combination with the given layer, for the given paint representation. This allows it to implement cleanup code if necessary.

Layers unregistered with this method must have been registered before calling this method with the method ILspPainter.registerLayer(ILspInteractivePaintableLayer, com.luciad.view.lightspeed.layer.TLspPaintRepresentation).

Specified by:

unregisterLayer in interface ILspPainter

Parameters:

aLayer - A layer that needs to be unregistered

aPaintRepresentation - The paint representation for which this painter was used with aLayer

paintObjects

public TLspPaintProgress paintObjects(ILcdGLDrawable aGLDrawable,
                                      List<TLspPaintGroup> aPaintGroups,
                                      TLspPaintPass aPass,
                                      TLspContext aContext)

Description copied from interface: ILspPainter

Paints the specified groups of objects into a view. The objects are partitioned into TLspPaintGroups, which are created by the layer which invoked this painter. Painters are advised to also implement ILspPaintGroupsChangeListener, which allows them to keep track of changes to the supplied list of paint groups. This way, the painter can exploit temporal coherence and perform its work in the most optimal way.

This method returns a TLspPaintProgress which describes the completeness of the paint operation. If the painter scheduled one or more tasks to be executed asynchronously, it may return from its paintObjects() method before having rendered all the objects it was given. In this case, the returned progress object can describe the amount of work that has been done and the work that is still remaining.

Specified by:

paintObjects in interface ILspPainter

Parameters:

aGLDrawable - the ILcdGLDrawable in which the objects are to be painted

aPaintGroups - the objects to be painted

aPass - the current paint pass

aContext - provides context information to the painter

Returns:

a TLspPaintProgress object describing the completeness of the paint operation

query

public <T> boolean query(List<TLspPaintGroup> aPaintGroups,
                         ALspPaintQuery<T> aQuery,
                         TLspPaintRepresentationState aPaintRepresentationState,
                         TLspContext aContext)

Description copied from interface: ILspPainter

Retrieves a set of domain objects and data based on the parameters given by the query.

Specified by:

query in interface ILspPainter

Parameters:

aPaintGroups - the paint groups

aQuery - the query

aPaintRepresentationState - the paint representation state for which the query should be performed

aContext - the context

Returns:

true if the query completed, false if it was aborted.

getRequiredOpenGLProfile

public TLspOpenGLProfile getRequiredOpenGLProfile()

Description copied from interface: ILspPainter

Returns the minimum required OpenGL profile that a view must support in order to be compatible with this painter.

Specified by:

getRequiredOpenGLProfile in interface ILspPainter

Returns:

a TLspGLProfile

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener aPropertyChangeListener)

Description copied from interface: ILspPainter

Adds a PropertyChangeListener to the list of listeners that must be notified when any of the properties of this ILspPainter changes.

Specified by:

addPropertyChangeListener in interface ILspPainter

Parameters:

aPropertyChangeListener - the listener that from now on will be notified of all changes to properties of this painter

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener aPropertyChangeListener)

Description copied from interface: ILspPainter

Removes a PropertyChangeListener from the list of listeners. This listener will no longer be notified of any changes to the properties of this ILspPainter

Specified by:

removePropertyChangeListener in interface ILspPainter

Parameters:

aPropertyChangeListener - the listener that no longer will be notified of any changes to properties of this painter