Package gov.nasa.worldwind.render

Class AbstractAnnotation

  • All Implemented Interfaces:
    AVList, Disposable, Annotation, Renderable, Restorable
    Direct Known Subclasses:
    GlobeAnnotation, ScreenAnnotation
    public abstract class AbstractAnnotation
extends AVListImpl
implements Annotation
    An Annotation represent a text label and its rendering attributes. Annotations must be attached either to a globe Position (GlobeAnnotation) or a viewport Point (ScreenAnnotation). 
     GlobeAnnotation ga = new  GlobeAnnotation("Lat-Lon zero", Position.fromDegrees(0, 0, 0)));
 ScreenAnnotation sa = new ScreenAnnotation("Message...", new Point(10,10));

    Each Annotation refers to an AnnotationAttributes object which defines how the text will be rendered.

    Rendering attributes allow to set:
    • the size of the bounding rectangle into which the text will be displayed
    • its frame shape, border color, width and stippling pattern
    • the text font, size, style and color
    • the background color or image
    • how much an annotation scales and fades with distance
     ga.getAttributes().setTextColor(Color.WHITE);
 ga.getAttributes().setFont(Font.decode("Arial-BOLD-24");
 ...

    Annotations are usually handled by an AnnotationLayer. Although they also implement the Renderable interface and thus can be handled by a RenderableLayer too. 

     AnnotationLayer layer = new AnnotationLayer();
 layer.addAnnotation(new GlobeAnnotation("Text...", Position.fromDegrees(0, 0, 0)));

    Each Annotation starts its life with a fresh attribute set that can be altered to produce the desired effect. However, AnnotationAttributes can be set and shared between annotations allowing to control the rendering attributes of many annotations from a single AnnotationAttributes object. 

     AnnotationAttributes attr = new AnnotationAttributes();
 attr.setTextColor(Color.WHITE);
 attr.setFont(Font.decode("Arial-BOLD-24");
 ga.setAttributes(attr);

    In the above example changing the text color of the attributes set will affect all annotations referring it. However, changing the text color of one of those annotations will also affect all others since it will in fact change the common attributes set.

    To use an attributes object only as default values for a series of annotations use: 

     ga.getAttributes().setDefaults(attr);

    which can also be done in the Annotation constructor: 

     GlobeAnnotation ga = new GlobeAnnotation(text, position, attr);

    Finer control over attributes inheritance can be achieved using default or fallback attributes set.

    Most attributes can be set to a 'use default' value which is minus one for numeric values and null for attributes referring objects (colors, dimensions, insets..). In such a case the value of an attribute will be that of the default attribute set. New annotations have all their attributes set to use default values.

    Each AnnotationAttributes object points to a default static attributes set which is the fallback source for attributes with null or -1 values. This default attributes set can be set to any attributes object other than the static one. 

     AnnotationAttributes geoFeature = new AnnotationAttributes();
 geoFeature.setFrameShape(AVKey.SHAPE_ELLIPSE);
 geoFeature.setInsets(new Insets(12, 12, 12, 12));

 AnnotationAttributes waterBody = new AnnotationAttributes();
 waterBody.setTextColor(Color.BLUE);
 waterBoby.setDefaults(geoFeature);

 AnnotationAttributes mountain = new AnnotationAttributes();
 mountain.setTextColor(Color.GREEN);
 mountain.setDefaults(geoFeature);

 layer.addAnnotation(new GlobeAnnotation("Spirit Lake", Position.fromDegrees(46.26, -122.15), waterBody);
 layer.addAnnotation(new GlobeAnnotation("Mt St-Helens", Position.fromDegrees(46.20, -122.19), mountain);

    In the above example all geographic features have an ellipse shape, water bodies and mountains use that attributes set has defaults and have their own text colors. They are in turn used as defaults by the two annotations. Mount Saint Helens attributes could be changed without affecting other mountains. However, changes on the geoFeatures attributes would affect all mountains and lakes.

    Background images are specified by setting the Annotation attribute AnnotationAttributes.setImageSource(Object). The source can be either a path to a valid image file, or a BufferedImage. By default, background images are aligned with the annotation as follows: the image's upper left corner is aligned with the annotation's upper left corner, and the image's lower right corner is aligned with a point (imageWidth, imageHeight) pixels right and down from the annotation's upper left corner. Thus the background image coordinate system has its origin at the annotation's upper left corner, has the +X axis pointing to the right, and has the +Y axis pointing down. Units are in image pixels, where one image pixel corresponds to one screen pixel. The background image may be translated or scaled by setting the attributes AnnotationAttributes.setImageOffset(java.awt.Point) and AnnotationAttributes.setImageScale(double), respectively. The offset attribute defines an offset right and down in background image coordinates. The scale attribute is unitless, and defines the background image's magnification or minification factor relative to the annotation. For example, a scale of 0.5 indicates the image should be 1/2 its original size relative to the annotation, while a scale of 2.0 indicates the image should be 2x its original size.

    Warning: For compatibility across the myriad of graphics hardware, background images must have power-of-two dimensions. Non-power-of-two images are handled inconsistently by graphics hardware. Not all hardware supports them, and many that do lack full support for the features available when using power-of-two images. Proper conversion from a non-power-of-two image to a power-of-two image depends on the image's intended use. However, the following two step solution works for most applications:

    1. Create a transparent power-of-two image larger than the original image. The utility method WWMath.powerOfTwoCeiling(int) is useful for computing power-of-two dimensions:

      int newWidth = WWMath.powerOfTwoCeiling(originalWidth);
      int newHeight = WWMath.powerOfTwoCeiling(originalHeight);

    2. Copy the original image contents into the empty power-of-two image. Any pixels not covered by the original image are left completely transparent:

      BufferedImage newImage = new BufferedImage(newWidth, newHeight, BufferedImage.TYPE_INT_ARGB);
      Graphics2D g2d = newImage.createGraphics();
      try
      {
        g2d.drawImage(originalImage, 0, 0, null);
      }
      finally
      {
        g2d.dispose();
      }

    When used as an Annotation background image, the new power-of-two image appears identical to its original non-power-of-two counterpart, except that the new image is now compatible with most graphics hardware.
    See Also:
    AnnotationAttributes, AnnotationRenderer

    • Field Detail

      • alwaysOnTop

        protected boolean alwaysOnTop

      • pickEnabled

        protected boolean pickEnabled

      • text

        protected java.lang.String text

      • childList

        protected java.util.List<Annotation> childList

      • delegateOwner

        protected java.lang.Object delegateOwner

      • vertexBuffer

        protected static java.nio.DoubleBuffer vertexBuffer

      • wrappedTextMap

        protected java.util.Map<java.lang.Object,​java.lang.String> wrappedTextMap

      • textBoundsMap

        protected java.util.Map<java.lang.Object,​java.awt.Rectangle> textBoundsMap

      • minActiveAltitude

        protected double minActiveAltitude

      • maxActiveAltitude

        protected double maxActiveAltitude

    • Constructor Detail

      • AbstractAnnotation

        protected AbstractAnnotation()

    • Method Detail

      • setAlwaysOnTop

        public void setAlwaysOnTop​(boolean alwaysOnTop)
        Specified by:
        setAlwaysOnTop in interface Annotation

      • setPickEnabled

        public void setPickEnabled​(boolean enable)
        Specified by:
        setPickEnabled in interface Annotation

      • getText

        public java.lang.String getText()
        Specified by:
        getText in interface Annotation

      • setText

        public void setText​(java.lang.String text)
        Specified by:
        setText in interface Annotation

      • setDelegateOwner

        public void setDelegateOwner​(java.lang.Object delegateOwner)
        Specified by:
        setDelegateOwner in interface Annotation

      • render

        public void render​(DrawContext dc)
        Render the annotation. Called as a Renderable.
        Specified by:
        render in interface Renderable
        Parameters:
        dc - the current DrawContext.
        See Also:
        DrawContext

      • pick

        public void pick​(DrawContext dc,
                 java.awt.Point pickPoint)
        Pick at the annotation. Called as a Pickable.
        Parameters:
        dc - the current DrawContext.
        pickPoint - the screen coordinate point.

      • dispose

        public void dispose()
        Description copied from interface: Disposable
        Disposes of any internal resources allocated by the object.
        Specified by:
        dispose in interface Disposable

      • renderNow

        public void renderNow​(DrawContext dc)
        Description copied from interface: Annotation
        Draws the annotation immediately on the specified DrawContext. Rendering is not be delayed by use of the DrawContext's ordered mechanism, or any other delayed rendering mechanism. This is typically called by an AnnotationRenderer while batch rendering. The GL should have its model view set to the identity matrix.
        Specified by:
        renderNow in interface Annotation
        Parameters:
        dc - the current DrawContext.

      • draw

        public void draw​(DrawContext dc,
                 int width,
                 int height,
                 double opacity,
                 Position pickPosition)
        Description copied from interface: Annotation
        Draws the annotation without transforming to its screen position, or applying any scaling. This Annotation is draw with the specified width, height, and opacity. The GL should have its model view set to whatever transformation is desired.
        Specified by:
        draw in interface Annotation
        Parameters:
        dc - the current DrawContext.
        width - the width of the Annotation.
        height - the height of the Annotation.
        opacity - the opacity of the Annotation.
        pickPosition - the picked Position assigned to the Annotation, if picking is enabled.

      • drawTopLevelAnnotation

        protected void drawTopLevelAnnotation​(DrawContext dc,
                                      int x,
                                      int y,
                                      int width,
                                      int height,
                                      double scale,
                                      double opacity,
                                      Position pickPosition)

      • applyScreenTransform

        protected void applyScreenTransform​(DrawContext dc,
                                    int x,
                                    int y,
                                    int width,
                                    int height,
                                    double scale)

      • computeScale

        protected double computeScale​(DrawContext dc)

      • computeOpacity

        protected double computeOpacity​(DrawContext dc)

      • doRenderNow

        protected abstract void doRenderNow​(DrawContext dc)

      • computeBounds

        protected abstract java.awt.Rectangle computeBounds​(DrawContext dc)

      • getBounds

        public java.awt.Rectangle getBounds​(DrawContext dc)
        Get the annotation bounding Rectangle using OGL coordinates - bottom-left corner x and y relative to the WorldWindow bottom-left corner, and the annotation callout width and height.

        The annotation offset from it's reference point is factored in such that the callout leader shape and reference point are included in the bounding rectangle.

        Specified by:
        getBounds in interface Annotation
        Parameters:
        dc - the current DrawContext.
        Returns:
        the annotation bounding Rectangle using OGL viewport coordinates.
        Throws:
        java.lang.IllegalArgumentException - if dc is null.

      • doDraw

        protected void doDraw​(DrawContext dc,
                      int width,
                      int height,
                      double opacity,
                      Position pickPosition)
        Draws an annotation with the given dimensions and opacity. Current GL state has ortho identity model view active with origin at the screen point.
        Parameters:
        dc - current DrawContext.
        width - annotation callout width
        height - annotation callout height
        opacity - opacity to apply
        pickPosition - Position that will be associated with any PickedObject produced during picking.

      • drawContent

        protected void drawContent​(DrawContext dc,
                           int width,
                           int height,
                           double opacity,
                           Position pickPosition)

      • drawBackground

        protected void drawBackground​(DrawContext dc,
                              int width,
                              int height,
                              double opacity,
                              Position pickPosition)

      • drawBackgroundImage

        protected void drawBackgroundImage​(DrawContext dc,
                                   int width,
                                   int height,
                                   double opacity,
                                   Position pickPosition)

      • doDrawBackgroundTexture

        protected void doDrawBackgroundTexture​(DrawContext dc,
                                       int width,
                                       int height,
                                       double opacity,
                                       Position pickPosition,
                                       WWTexture texture)

      • applyBackgroundTextureState

        protected void applyBackgroundTextureState​(DrawContext dc,
                                           int width,
                                           int height,
                                           double opacity,
                                           WWTexture texture)

      • transformImageCoordsToBackgroundImageCoords

        protected void transformImageCoordsToBackgroundImageCoords​(DrawContext dc,
                                                           WWTexture texture)
        Transforms texture coordinates from standard GL image coordinates to Annotation background image coordinates. In standard GL image coordinates (0, 0) maps to the image's lower left corner, and (1, 1) maps to the image's upper right corner. In Annotation background image coordinates (0, 0) maps to the image's upper left corner, and (imageWidth, imageHeight) maps to the image's lower right corner. This assumes the current OGL matrix mode is GL_TEXTURE.
        Parameters:
        dc - the DrawContext to receive the texture coordinate transform.
        texture - the texture to transform from standard GL image coordinates to Annotation background image coordinates.

      • transformBackgroundImageCoordsToAnnotationCoords

        protected void transformBackgroundImageCoordsToAnnotationCoords​(DrawContext dc,
                                                                int width,
                                                                int height,
                                                                WWTexture texture)
        Transforms texture coordinates from Annotation background image coordinates to Annotation geometry coordinates (in screen pixels), and applies the Annotation's image scale and image offset attributes. In Annotation background image coordinates (0, 0) maps to the image's upper left corner, and (imageWidth, imageHeight) maps to the image's lower right corner. In Annotation geometry coordinates (0, 0) maps to the Annotation geometry's lower left corner (ignoring any leader geometry), and (width, height) maps to the Annotation's upper right corner in window coordinates (screen pixels). This assumes the current OGL matrix mode is GL_TEXTURE.
        Parameters:
        dc - the DrawContext to receive the texture coordinate transform.
        width - the Annotation's width, in window coordinates (screen pixels).
        height - the Annotation's height, in window coordinates (screen pixels).
        texture - the texture to transform from Annotation background image coordinates to Annotation geometry coordinates.

      • drawBorder

        protected void drawBorder​(DrawContext dc,
                          int width,
                          int height,
                          double opacity,
                          Position pickPosition)

      • drawText

        protected void drawText​(DrawContext dc,
                        int width,
                        int height,
                        double opacity,
                        Position pickPosition)

      • drawText

        protected void drawText​(DrawContext dc,
                        int x,
                        int y,
                        int lineHeight,
                        double opacity,
                        java.lang.Object pickObject,
                        Position pickPosition,
                        java.lang.String text)

      • drawPlainText

        protected void drawPlainText​(DrawContext dc,
                             int x,
                             int y,
                             int lineHeight,
                             double opacity,
                             java.lang.Object pickObject,
                             Position pickPosition,
                             java.lang.String text)

      • drawHTML

        protected void drawHTML​(DrawContext dc,
                        int x,
                        int y,
                        int lineHeight,
                        double opacity,
                        java.lang.Object pickObject,
                        Position pickPosition,
                        java.lang.String text)

      • drawChildren

        protected void drawChildren​(DrawContext dc,
                            int width,
                            int height,
                            double opacity,
                            Position pickPosition)

      • doDrawChildren

        protected void doDrawChildren​(DrawContext dc,
                              java.awt.Rectangle bounds,
                              double opacity,
                              Position pickPosition)

      • beginDrawChildren

        protected void beginDrawChildren​(DrawContext dc,
                                 java.awt.Rectangle bounds)

      • endDrawChildren

        protected void endDrawChildren​(DrawContext dc)

      • bindPickableObject

        protected void bindPickableObject​(DrawContext dc,
                                  Position position)

      • drawCallout

        protected void drawCallout​(DrawContext dc,
                           int mode,
                           int width,
                           int height,
                           boolean useTexCoords)

      • applyColor

        protected void applyColor​(DrawContext dc,
                          java.awt.Color color,
                          double opacity,
                          boolean premultiplyColors)

      • modulateColorOpacity

        protected java.awt.Color modulateColorOpacity​(java.awt.Color color,
                                              double opacity)

      • transformByModelview

        protected java.awt.Rectangle transformByModelview​(DrawContext dc,
                                                  java.awt.Rectangle rectangle)

      • glPointFromAWTPoint

        protected java.awt.Point glPointFromAWTPoint​(DrawContext dc,
                                             java.awt.Point awtPoint)

      • getWrappedText

        protected java.lang.String getWrappedText​(DrawContext dc,
                                          int width,
                                          int height,
                                          java.lang.String text,
                                          java.awt.Font font,
                                          java.lang.String align)

      • getTextBounds

        protected java.awt.Rectangle getTextBounds​(DrawContext dc,
                                           java.lang.String text,
                                           java.awt.Font font,
                                           java.lang.String align)

      • wrapText

        protected java.lang.String wrapText​(DrawContext dc,
                                    int width,
                                    int height,
                                    java.lang.String text,
                                    java.awt.Font font,
                                    java.lang.String align)

      • computeTextBounds

        protected java.awt.Rectangle computeTextBounds​(DrawContext dc,
                                               java.lang.String text,
                                               java.awt.Font font,
                                               java.lang.String align)

      • computeInsetBounds

        protected java.awt.Rectangle computeInsetBounds​(int width,
                                                int height)

      • computeFreeBounds

        protected java.awt.Rectangle computeFreeBounds​(DrawContext dc,
                                               int width,
                                               int height)

      • adjustSizeToText

        protected java.awt.Dimension adjustSizeToText​(DrawContext dc,
                                              int width,
                                              int height)

      • adjustSizeToChildren

        protected java.awt.Dimension adjustSizeToChildren​(DrawContext dc,
                                                  int width,
                                                  int height)

      • computeBoundingRectangle

        protected java.awt.Rectangle computeBoundingRectangle​(java.awt.Rectangle rect,
                                                      int px,
                                                      int py)

      • getRestorableState

        public java.lang.String getRestorableState()
        Returns an XML state document String describing the public attributes of this AbstractAnnotation.
        Specified by:
        getRestorableState in interface Restorable
        Returns:
        XML state document string describing this AbstractAnnotation.

      • restoreState

        public void restoreState​(java.lang.String stateInXml)
        Restores publicly settable attribute values found in the specified XML state document String. The document specified by stateInXml must be a well formed XML document String, or this will throw an IllegalArgumentException. Unknown structures in stateInXml are benign, because they will simply be ignored.
        Specified by:
        restoreState in interface Restorable
        Parameters:
        stateInXml - an XML document String describing an AbstractAnnotation.
        Throws:
        java.lang.IllegalArgumentException - If stateInXml is null, or if stateInXml is not a well formed XML document String.