Package gov.nasa.worldwind.util

Class TextureAtlasElement

  • All Implemented Interfaces:
    Disposable
    Direct Known Subclasses:
    AbstractTacticalSymbol.IconAtlasElement
    public class TextureAtlasElement
extends java.lang.Object
implements Disposable
    Represents a texture defined by a sub-image within a TextureAtlas.

    TextureAtlasElement performs lazy retrieval and loading of its image source into its texture atlas. This loads the image source and adds it to the atlas only when the load(gov.nasa.worldwind.render.DrawContext) method is called. If the image source is a BufferedImage it is added to the atlas immediately when load is called. If the image source is a local file or a remote stream (URL), retrieval and loading is performed on a separate thread from the EDT.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected static class  TextureAtlasElement.RequestTask
      RequestTask is an implementation of the Runnable interface who's run method retrieves and loads this element's image source.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected TextureAtlas atlas
      Indicates the texture atlas this element belongs to.
      protected java.awt.image.BufferedImage image
      The BufferedImage created as the image source is read.
      protected boolean imageInitializationFailed
      Indicates that image initialization failed.
      protected java.lang.Object imageSource
      Indicates the original image source associated with this element.
      protected java.beans.PropertyChangeListener listener
      The object to notify when the image is eventually loaded in memory.

    • Constructor Summary

      Constructors 
      Constructor Description
      TextureAtlasElement​(TextureAtlas atlas, java.lang.Object imageSource)
      Creates a new texture atlas element with the specified atlas and image source.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected boolean addAtlasImage()
      Adds this element's image source into its texture atlas.
      protected java.lang.Runnable createRequestTask()
      Returns an object that implements the Runnable interface, and who's run method retrieves and loads this element's image source.
      void dispose()
      Removes this element's image from its texture atlas and disposes of this element's image resource.
      boolean equals​(java.lang.Object o)
      Indicates whether another texture atlas element is equivalent to this one.
      protected java.awt.image.BufferedImage getImage()
      Indicates the image created as the image source is read.
      java.lang.Object getImageSource()
      Indicates the original image source associated with this element.
      java.awt.Dimension getSize()
      Returns the image dimensions associated with this texture atlas element.
      com.jogamp.opengl.util.texture.TextureCoords getTexCoords()
      Returns the OpenGL texture coordinates associated this texture atlas element.
      TextureAtlas getTextureAtlas()
      Indicates the texture atlas this element belongs to.
      int hashCode()
      Returns the hash code for this texture atlas element's image source.
      protected boolean isBufferedImageSource()
      Indicates whether this element's image source is a BufferedImage.
      boolean isImageInitializationFailed()
      Indicates whether this element's image failed to load.
      boolean load​(DrawContext dc)
      Loads this element's image and adds it to the texture atlas.
      protected boolean loadImage()
      Loads this element's image source into its image property.
      protected void notifyImageLoaded()
      Notifies this texture atlas element's listener that image loading has completed.
      protected java.awt.image.BufferedImage readImage​(java.net.URL fileUrl)
      Reads and returns the specified image URL as a BufferedImage.
      protected boolean requestImage​(DrawContext dc)
      Requests that this element's image source be loaded into its texture atlas.
      protected void setImage​(java.awt.image.BufferedImage image)
      Specifies the image created as the image source is read.
      java.lang.String toString()
      Returns the string representation of this texture atlas element's image source.

      • Methods inherited from class java.lang.Object

        clone, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • atlas

        protected TextureAtlas atlas
        Indicates the texture atlas this element belongs to. Specified during construction.

      • imageSource

        protected java.lang.Object imageSource
        Indicates the original image source associated with this element. Specified during construction.

      • image

        protected volatile java.awt.image.BufferedImage image
        The BufferedImage created as the image source is read. This intermediate field is necessary because the image source is read on a non-EDT thread, but changes to the texture atlas must be performed on the EDT. This is set to null once the image is loaded into the texture atlas. This field is volatile in order to synchronize atomic access among threads. This field is not used if the image source is BufferedImage.

      • imageInitializationFailed

        protected boolean imageInitializationFailed
        Indicates that image initialization failed. This element should not be used if true. Initially false.

      • listener

        protected java.beans.PropertyChangeListener listener
        The object to notify when the image is eventually loaded in memory. This is either the current layer or the layer list at the time the image source is requested. The latter is used when the image source is requested during ordered rendering mode, in which case the current layer is null. This set to null once the image is loaded into the texture atlas.

    • Constructor Detail

      • TextureAtlasElement

        public TextureAtlasElement​(TextureAtlas atlas,
                           java.lang.Object imageSource)
        Creates a new texture atlas element with the specified atlas and image source.
        Parameters:
        atlas - the texture atlas this element belongs to.
        imageSource - a general image source. The source type may be one of the following:
        • a URL
        • an InputStream
        • a File
        • a String containing a valid URL description or a file or resource name available on the classpath.
        Throws:
        java.lang.IllegalArgumentException - if either the atlas or the image source is null.

    • Method Detail

      • getTextureAtlas

        public TextureAtlas getTextureAtlas()
        Indicates the texture atlas this element belongs to.
        Returns:
        this element's texture atlas.

      • getImageSource

        public java.lang.Object getImageSource()
        Indicates the original image source associated with this element.
        Returns:
        this element's image source.

      • isBufferedImageSource

        protected boolean isBufferedImageSource()
        Indicates whether this element's image source is a BufferedImage.
        Returns:
        true if this element's image source is a BufferedImage, and false otherwise.

      • getImage

        protected java.awt.image.BufferedImage getImage()
        Indicates the image created as the image source is read.
        Returns:
        this element's image.
        See Also:
        setImage(java.awt.image.BufferedImage)

      • setImage

        protected void setImage​(java.awt.image.BufferedImage image)
        Specifies the image created as the image source is read. This intermediate field is necessary because the image source is read on a non-EDT thread, but changes to the texture atlas must be performed on the EDT. This field is volatile in order to synchronize atomic access among threads.
        Parameters:
        image - this element's image.

      • getSize

        public java.awt.Dimension getSize()
        Returns the image dimensions associated with this texture atlas element. Always call load before calling this method to ensure that the element is loaded into its texture atlas.
        Returns:
        the image dimensions associated with this texture atlas element, or null if this texture atlas element has not yet loaded or has failed to load.
        See Also:
        load(gov.nasa.worldwind.render.DrawContext)

      • getTexCoords

        public com.jogamp.opengl.util.texture.TextureCoords getTexCoords()
        Returns the OpenGL texture coordinates associated this texture atlas element. Always call load before calling this method to ensure that the element is loaded into its texture atlas.

        The returned texture coordinates can change any time an element is added or removed from this element's texture atlas, and therefore should not be cached unless the caller has explicit knowledge of when this element's texture atlas has changed.

        Returns:
        the OpenGL texture coordinates corresponding this texture atlas element, or null if this texture atlas element has not yet loaded or has failed to load.
        See Also:
        load(gov.nasa.worldwind.render.DrawContext)

      • isImageInitializationFailed

        public boolean isImageInitializationFailed()
        Indicates whether this element's image failed to load. This element should not be used if true.
        Returns:
        true if this element's image failed to load, and false otherwise.

      • load

        public boolean load​(DrawContext dc)
        Loads this element's image and adds it to the texture atlas. If the image is not yet loaded this initiates image source retrieval in a separate thread. This does nothing if the texture atlas already contains this element, or if this element's image failed to load in an earlier attempt.
        Parameters:
        dc - the current draw context. Used to generate a repaint event when the image source retrieval completes.
        Returns:
        true if this element's image is successfully loaded and added to the texture atlas, otherwise false.

      • dispose

        public void dispose()
        Removes this element's image from its texture atlas and disposes of this element's image resource. This does nothing if this element's image has not yet been loaded.
        Specified by:
        dispose in interface Disposable

      • equals

        public boolean equals​(java.lang.Object o)
        Indicates whether another texture atlas element is equivalent to this one. This tests equality using the image source of each element.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - the object to test.
        Returns:
        true if the specified object is a TextureAtlasElement and its image source is equivalent to this element's image source, otherwise false.

      • hashCode

        public int hashCode()
        Returns the hash code for this texture atlas element's image source.
        Overrides:
        hashCode in class java.lang.Object

      • toString

        public java.lang.String toString()
        Returns the string representation of this texture atlas element's image source.
        Overrides:
        toString in class java.lang.Object

      • requestImage

        protected boolean requestImage​(DrawContext dc)
        Requests that this element's image source be loaded into its texture atlas. If the image source is a BufferedImage, this immediately loads it into the texture atlas and returns true. Otherwise, this initiates the retrieval of this element's image source in a separate thread and returns false. Once the image source is retrieved, a subsequent invocation of this method loads it into the texture atlas and returns true.
        Parameters:
        dc - the current draw context. Used to generate a repaint event when the image source retrieval completes.
        Returns:
        true if this element's image is loaded into the texture atlas, and false otherwise.

      • addAtlasImage

        protected boolean addAtlasImage()
        Adds this element's image source into its texture atlas. This throws an exception if this element's image source is not loaded and stored in the image property.
        Returns:
        true if this element's image is successfully added to the texture atlas, and false otherwise.

      • createRequestTask

        protected java.lang.Runnable createRequestTask()
        Returns an object that implements the Runnable interface, and who's run method retrieves and loads this element's image source.
        Returns:
        a new request task that retrieves and loads this element's image source.

      • loadImage

        protected boolean loadImage()
        Loads this element's image source into its image property. If the image source is a remote resource, this initiates a request for it and returns null.
        Returns:
        true if the image source has been loaded successfully, and false otherwise.

      • readImage

        protected java.awt.image.BufferedImage readImage​(java.net.URL fileUrl)
        Reads and returns the specified image URL as a BufferedImage.
        Parameters:
        fileUrl - the image URL to read.
        Returns:
        the image URL as a BufferedImage, or null if the image could not be read.

      • notifyImageLoaded

        protected void notifyImageLoaded()
        Notifies this texture atlas element's listener that image loading has completed. This does nothing if this texture atlas element has no listener.