gov.nasa.worldwind.render
Class LazilyLoadedTexture

java.lang.Object
  gov.nasa.worldwind.avlist.AVListImpl
      gov.nasa.worldwind.render.LazilyLoadedTexture

All Implemented Interfaces:

AVList, WWTexture

Direct Known Subclasses:

AbstractTacticalSymbol.IconTexture

public class LazilyLoadedTexture
extends AVListImpl
implements WWTexture

Represents a texture derived from a lazily loaded image source such as an image file or a BufferedImage.

The interface contains a method, isTextureInitializationFailed() to determine whether the instance failed to convert an image source to a texture. If such a failure occurs, the method returns true and no further attempts are made to create the texture.

This class performs lazy retrieval and loading of an image source, attempting to retrieve and load the image source only when the bind(DrawContext) or applyInternalTransform(DrawContext) methods are called. If the image source is a BufferedImage the associated Texture object is created and available immediately when bind or applyInternalTransform are called. If the image source is a local file or remote stream (URL), retrieval and loading is performed on a separate thread from the EDT.

Nested Class Summary

protected static class

LazilyLoadedTexture.RequestTask Attempts to find this texture's image file locally, and if that fails attempts to find it remotely.

Field Summary

protected Object	fileLock Provides a semaphore to synchronize access to the texture file if duplicate request tasks are active.
protected FileStore	fileStore Identifies the FileStore of the supporting file cache for this model.
protected boolean	hasMipmapData Indicates whether the image read from the image source has mip-map data.
protected Integer	height The texture height, if the height is known.
protected Object	imageSource The original image source specified at construction.
protected PropertyChangeListener	listener The object to notify when an image is eventually loaded in memory.
protected TextureCoords	texCoords The texture's texture coordinates, as determined by JOGL when the texture is created.
protected TextureData	textureData The texture data created as the image source is read.
protected boolean	textureInitializationFailed Indicates that texture initialization failed.
protected boolean	useAnisotropy The current anisotropy flag.
protected boolean	useMipMaps The mip-map flag specified at construction.
protected Integer	width The texture width, if the width is known.

Constructor Summary

LazilyLoadedTexture(Object imageSource)
Constructs a texture object for a specified image source.

LazilyLoadedTexture(Object imageSource, boolean useMipMaps)
Constructs a texture object for a specified image source.

Method Summary

void	applyInternalTransform(DrawContext dc) Applies any necessary transformations to the texture prior to its being rendered.
boolean	bind(DrawContext dc) Binds this instance's Texture to the GLContext if the texture has been created, otherwise initiates image source retrieval and texture creation in a separate thread.
protected Runnable	createRequestTask() Returns an object that implements the Runnable interface, and who's run method retrieves and loads this texture's image source.
boolean	equals(Object o)
int	getHeight() Indicates the texture's height, which is the same as the image source's height.
int	getHeight(DrawContext dc) Returns the texture's height
Object	getImageSource() Returns the texture's image source.
TextureCoords	getTexCoords() Returns the texture's texture coordinates, which may be other than [0,0],[1,1] if the texture size is not a power of two or the texture must be flipped when rendered.
protected Texture	getTexture(DrawContext dc) Returns the Texture associated with this instance.
protected TextureData	getTextureData() Returns this texture's texture data if it has been retrieved but a Texture has not yet been created for it.
int	getWidth() Indicates the texture's width, which is the same as the image source's width.
int	getWidth(DrawContext dc) Returns the texture's width.
int	hashCode()
protected void	initialize(Object imageSource, boolean useMipMaps, PropertyChangeListener listener) Initializes this object's fields during construction.
protected boolean	isBufferedImageSource() Indicates whether the image source is a BufferedImage
boolean	isTextureCurrent(DrawContext dc) Indicates whether the texture is currently available for use without regenerating it from its image source.
boolean	isTextureInitializationFailed() Indicates whether an attempt was made to retrieve and read the texture but it failed.
boolean	isUseAnisotropy() Indicates whether texture anisotropy is applied to the texture when rendered.
boolean	isUseMipMaps() Indicates whether the texture should use mip-maps.
protected boolean	loadTextureData(URL fileUrl) Loads the image from disk into memory.
protected Texture	makeBufferedImageTexture(DrawContext dc) Creates this instance's Texture if the image source is a BufferedImage.
protected Texture	makeTextureFromTextureData(DrawContext dc) Creates a Texture from this instance's TextureData if the TextureData exists.
protected void	notifyTextureLoaded()
protected TextureData	readImage(URL fileUrl) Reads and returns a TextureData for an image from a specified file URL.
protected Texture	requestTexture(DrawContext dc) If this instance's image source is a BufferedImage, creates and returns the texture, otherwise creates a task in a separate thread to retrieve it from its local or remote location.
protected void	setTextureData(TextureData textureData) Specifies texture data for the tile.
protected void	setTextureParameters(DrawContext dc, Texture texture) Sets a specified texture's OpenGL Texture parameters.
void	setUseAnisotropy(boolean useAnisotropy) Specifies whether texture anisotropy is applied to the texture when rendered.

Methods inherited from class gov.nasa.worldwind.avlist.AVListImpl

addPropertyChangeListener, addPropertyChangeListener, clearList, copy, firePropertyChange, firePropertyChange, getBooleanValue, getBooleanValue, getChangeSupport, getDoubleValue, getDoubleValue, getEntries, getIntegerValue, getIntegerValue, getLongValue, getLongValue, getRestorableStateForAVPair, getStringValue, getStringValue, getStringValue, getValue, getValues, hasKey, removeKey, removePropertyChangeListener, removePropertyChangeListener, setValue, setValues

Methods inherited from class java.lang.Object

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

Field Detail

fileLock

protected final Object fileLock

Provides a semaphore to synchronize access to the texture file if duplicate request tasks are active.

fileStore

protected FileStore fileStore

Identifies the FileStore of the supporting file cache for this model.

hasMipmapData

protected boolean hasMipmapData

Indicates whether the image read from the image source has mip-map data.

height

protected Integer height

The texture height, if the height is known. Otherwise it's -1.

imageSource

protected Object imageSource

The original image source specified at construction.

listener

protected PropertyChangeListener listener

The object to notify when an image is eventually loaded in memory. The current layer at the time the image source is requested is assigned to this field.

texCoords

protected TextureCoords texCoords

The texture's texture coordinates, as determined by JOGL when the texture is created.

textureData

protected volatile TextureData textureData

The texture data created as the image source is read. It's removed - set to null - once the textures is fully created. This intermediate texture data is necessary because the image source is read in a non-EDT thread. This field is volatile in order to synchronize atomic access among threads. This field is not used if the image source is BufferedImage.

textureInitializationFailed

protected boolean textureInitializationFailed

Indicates that texture initialization failed. This texture should not be used if true.

useAnisotropy

protected boolean useAnisotropy

The current anisotropy flag.

useMipMaps

protected boolean useMipMaps

The mip-map flag specified at construction.

width

protected Integer width

The texture width, if the width is known. Otherwise it's -1.

Constructor Detail

LazilyLoadedTexture

public LazilyLoadedTexture(Object imageSource)

Constructs a texture object for a specified image source. Requests that mip-maps be used.

Parameters:

imageSource - the source of the image, either a file path String or a BufferedImage.

Throws:

IllegalArgumentException - if the imageSource is null.

LazilyLoadedTexture

public LazilyLoadedTexture(Object imageSource,
                           boolean useMipMaps)

Constructs a texture object for a specified image source.

Parameters:

imageSource - the source of the image, either a file path String or a BufferedImage.

useMipMaps - Indicates whether to generate and use mip-maps for the image.

Throws:

IllegalArgumentException - if the imageSource is null.

Method Detail

applyInternalTransform

public void applyInternalTransform(DrawContext dc)

Description copied from interface: WWTexture

Applies any necessary transformations to the texture prior to its being rendered. A common transformation is mapping texture coordinates from a flipped or non-square state to conventionally oriented OpenGL values.

Specified by:

applyInternalTransform in interface WWTexture

Parameters:

dc - the current draw context.

bind

public boolean bind(DrawContext dc)

Binds this instance's Texture to the GLContext if the texture has been created, otherwise initiates image source retrieval and texture creation in a separate thread.

Specified by:

bind in interface WWTexture

Parameters:

dc - the current draw context.

Returns:

true if the texture was bound, otherwise false.

createRequestTask

protected Runnable createRequestTask()

Returns an object that implements the Runnable interface, and who's run method retrieves and loads this texture's image source.

Returns:

a new request task that retrieves and loads this texture's image source.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

getHeight

public int getHeight()

Indicates the texture's height, which is the same as the image source's height. The height is known only after the image source has been retrieved from disk or network and read as TextureData. It's value is -1 until then.

Returns:

the texture's height if the texture has been retrieved, otherwise -1.

getHeight

public int getHeight(DrawContext dc)

Returns the texture's height

This method behaves identically to getHeight(). The DrawContext argument is not used.

Specified by:

getHeight in interface WWTexture

Parameters:

dc - this parameter is not used by this class.

Returns:

the texture's height if the texture has been retrieved, otherwise -1.

getImageSource

public Object getImageSource()

Description copied from interface: WWTexture

Returns the texture's image source.

Specified by:

getImageSource in interface WWTexture

Returns:

the texture's image source.

getTexCoords

public TextureCoords getTexCoords()

Description copied from interface: WWTexture

Returns the texture's texture coordinates, which may be other than [0,0],[1,1] if the texture size is not a power of two or the texture must be flipped when rendered.

Specified by:

getTexCoords in interface WWTexture

Returns:

returns the texture's texture coordinates.

getTexture

protected Texture getTexture(DrawContext dc)

Returns the Texture associated with this instance.

Parameters:

dc - the current draw context.

Returns:

this instance's texture, or null if the texture does not currently exist.

getTextureData

protected TextureData getTextureData()

Returns this texture's texture data if it has been retrieved but a Texture has not yet been created for it.

If this object's texture data field is non-null, a new texture is created from the texture data when the tile is next bound or otherwise initialized. This object's texture data field is then set to null.

Returns:

the texture data, which may be null indicating that the image source has not been read or that a texture has been created.

getWidth

public int getWidth()

Indicates the texture's width, which is the same as the image source's width. The width is known only after the image source has been retrieved from disk or network and read as TextureData. It's value is -1 until then.

Returns:

the texture's width if the texture has been retrieved, otherwise -1.

getWidth

public int getWidth(DrawContext dc)

Returns the texture's width.

This method behaves identically to getWidth(). The DrawContext argument is not used.

Specified by:

getWidth in interface WWTexture

Parameters:

dc - this parameter is not used by this class.

Returns:

the texture's width if the texture has been retrieved, otherwise -1.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

initialize

protected void initialize(Object imageSource,
                          boolean useMipMaps,
                          PropertyChangeListener listener)

Initializes this object's fields during construction.

Parameters:

imageSource - the image source.

useMipMaps - the mip-map flag.

listener - the change listener.

Throws:

IllegalArgumentException - if the image source is null.

isBufferedImageSource

protected boolean isBufferedImageSource()

Indicates whether the image source is a BufferedImage

Returns:

true if the image source is a BufferedImage, otherwise false.

isTextureCurrent

public boolean isTextureCurrent(DrawContext dc)

Description copied from interface: WWTexture

Indicates whether the texture is currently available for use without regenerating it from its image source.

Specified by:

isTextureCurrent in interface WWTexture

Parameters:

dc - the current draw context

Returns:

true if the texture is available and consistent with its image source, otherwise false.

isTextureInitializationFailed

public boolean isTextureInitializationFailed()

Indicates whether an attempt was made to retrieve and read the texture but it failed. If this flag is true, this texture should not be used.

Specified by:

isTextureInitializationFailed in interface WWTexture

Returns:

true if texture retrieval or creation failed, otherwise true, even if the image source has not yet been retrieved.

isUseAnisotropy

public boolean isUseAnisotropy()

Indicates whether texture anisotropy is applied to the texture when rendered.

Returns:

useAnisotropy true if anisotropy is to be applied, otherwise false.

isUseMipMaps

public boolean isUseMipMaps()

Indicates whether the texture should use mip-maps. If they are not available in the source image they are created.

Returns:

true if mip-maps are used, false if not.

loadTextureData

protected boolean loadTextureData(URL fileUrl)

Loads the image from disk into memory. If successful, texture data is created and available via getTextureData().

Parameters:

fileUrl - the URL of the image file.

Returns:

true if the image was successfully loaded, otherwise false.

makeBufferedImageTexture

protected Texture makeBufferedImageTexture(DrawContext dc)

Creates this instance's Texture if the image source is a BufferedImage.

Parameters:

dc - the current draw context.

Returns:

the newly created texture, or null if the texture was not created.

Throws:

IllegalStateException - if the image source is null or not a BufferedImage.

makeTextureFromTextureData

protected Texture makeTextureFromTextureData(DrawContext dc)

Creates a Texture from this instance's TextureData if the TextureData exists.

Parameters:

dc - the current draw context.

Returns:

the newly created texture, or null if this instance has no current TextureData or if texture creation failed.

notifyTextureLoaded

protected void notifyTextureLoaded()

readImage

protected TextureData readImage(URL fileUrl)

Reads and returns a TextureData for an image from a specified file URL.

Parameters:

fileUrl - the URL of the image file to read.

Returns:

a TextureData instance for the image.

requestTexture

protected Texture requestTexture(DrawContext dc)

If this instance's image source is a BufferedImage, creates and returns the texture, otherwise creates a task in a separate thread to retrieve it from its local or remote location.

Parameters:

dc - the current draw context.

Returns:

the new texture, or null if the texture is not yet available.

setTextureData

protected void setTextureData(TextureData textureData)

Specifies texture data for the tile. If texture data is non-null, a new texture is created from the texture data when the tile is next bound.

When a texture is created from the texture data, the texture data field is set to null to indicate that the data has been converted to a texture and its resources may be released.

Parameters:

textureData - the texture data, which may be null.

setTextureParameters

protected void setTextureParameters(DrawContext dc,
                                    Texture texture)

Sets a specified texture's OpenGL Texture parameters.

Parameters:

dc - the current draw context.

texture - the texture whose parameters to set.

setUseAnisotropy

public void setUseAnisotropy(boolean useAnisotropy)

Specifies whether texture anisotropy is applied to the texture when rendered.

Parameters:

useAnisotropy - true if anisotropy is to be applied, otherwise false.