Package com.luciad.view.lightspeed.painter.label

Class 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:

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

text layout

Optionally, you can also set:

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

  • Constructor Details

    • TLspLabelPainter

      public TLspLabelPainter()
      Creates a new label painter.

  • Method Details

    • 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

      public boolean isOverlayLabels()
      Indicates whether overlaying labels is enabled.
      Returns:
      the current setting
      See Also:

    • 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

      public long getDefaultOpacityFadeDuration()
      Returns the duration of label fade in/out animations.
      Returns:
      the current duration, in milliseconds.
      See Also:

    • 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:

    • 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:

    • 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:

      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