gov.nasa.worldwind.render

Class SurfaceObjectTileBuilder

java.lang.Object

gov.nasa.worldwind.render.SurfaceObjectTileBuilder

public class SurfaceObjectTileBuilder
extends java.lang.Object

Builds a list of SurfaceTile instances who's content is defined by a specified set of SurfaceRenderable instances. It's typically not necessary to use SurfaceObjectTileBuilder directly. WorldWind's default scene controller automatically batches instances of SurfaceRenderable in a single SurfaceObjectTileBuilder. Applications that need to draw basic surface shapes should use or extend SurfaceShape instead of using SurfaceObjectTileBuilder directly.

Surface tiles are built by calling buildTiles(DrawContext, Iterable) with an iterable of surface renderables. This assembles a set of surface tiles that meet the resolution requirements for the specified draw context, then draws the surface renderables into those offscreen surface tiles by calling render on each instance. This process may temporarily use the framebuffer to perform offscreen rendering, and therefore should be called during the preRender method of a WorldWind layer. See the PreRenderable interface for details. Once built, the surface tiles can be rendered by a SurfaceTileRenderer.

By default, SurfaceObjectTileBuilder creates texture tiles with a width and height of 512 pixels, and with internal format GL_RGBA. These parameters are configurable by calling setTileDimension(java.awt.Dimension) or setTileTextureFormat(int).

The most common usage pattern for SurfaceObjectTileBuilder is to build the surface tiles from a set of surface renderables during the preRender phase, then draw those surface tiles during the render phase. For example, a renderable can use SurfaceObjectTileBuilder to draw a set of surface renderables as follows:

  
 class MyRenderable implements Renderable, PreRenderable
 {
     protected SurfaceObjectTileBuilder tileBuilder = new SurfaceObjectTileBuilder();

     public void preRender(DrawContext dc)
     {
         List<?> surfaceRenderables = Arrays.asList(
             new SurfaceCircle(LatLon.fromDegrees(0, 100), 10000),
             new SurfaceSquare(LatLon.fromDegrees(0, 101), 10000));
         this.tileBuilder.buildSurfaceTiles(dc, surfaceRenderables);
     }

     public void render(DrawContext dc)
     {
         dc.getGeographicSurfaceTileRenderer().renderTiles(dc, this.tileBuilder.getTiles(dc));
     }
 }
 
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	SurfaceObjectTileBuilder.SurfaceObjectTile Represents a TextureTile who's contents is constructed by a set of surface objects.
protected static class	SurfaceObjectTileBuilder.SurfaceObjectTileStateKey Represents a surface renderable tile's current state.
protected static class	SurfaceObjectTileBuilder.TileInfo
protected static class	SurfaceObjectTileBuilder.TileInfoKey

Field Summary

Fields

Modifier and Type	Field and Description
protected SurfaceObjectTileBuilder.TileInfo	currentInfo The currently active TileInfo.
protected java.util.List<SurfaceRenderable>	currentSurfaceObjects List of currently assembled surface renderables.
protected static LatLon	DEFAULT_LEVEL_ZERO_TILE_DELTA The default level zero tile delta used to construct a LevelSet.
protected static int	DEFAULT_NUM_LEVELS The default number of levels used to construct a LevelSet.
protected static double	DEFAULT_SPLIT_SCALE The default split scale.
protected static int	DEFAULT_TEXTURE_DIMENSION The default surface tile texture dimension, in pixels.
protected static int	DEFAULT_TEXTURE_INTERNAL_FORMAT The default OpenGL internal format used to create surface tile textures.
protected static int	DEFAULT_TEXTURE_PIXEL_FORMAT The default OpenGL pixel format used to create surface tile textures.
protected boolean	forceTileUpdates Controls if tiles are forced to update during buildTiles(DrawContext, Iterable).
protected static java.util.Map<java.awt.Dimension,LevelSet>	levelSetMap Map associating a tile texture dimension to its corresponding LevelSet.
protected static long	nextUniqueId The next unique ID.
protected OGLRenderToTextureSupport	rttSupport Support class used to render to an offscreen surface tile.
protected double	splitScale Controls the tile resolution as distance changes between the globe's surface and the eye point.
protected java.awt.Dimension	tileDimension Indicates the desired tile texture width and height, in pixels.
protected java.util.Map<java.lang.Object,SurfaceObjectTileBuilder.TileInfo>	tileInfoMap List of currently assembled surface tiles.
protected int	tileTextureFormat The surface tile OpenGL texture format.
protected boolean	useLinearFilter Controls if surface tiles are rendered using a linear filter or a nearest-neighbor filter.
protected boolean	useMipmaps Controls if mip-maps are generated for surface tile textures.

Constructor Summary

Constructors

Constructor and Description
SurfaceObjectTileBuilder() Constructs a new SurfaceObjectTileBuilder with a tile width and height of 512, with the default tile texture format, with linear filtering enabled, and with mip-mapping disabled.
SurfaceObjectTileBuilder(java.awt.Dimension tileTextureDimension, int tileTextureFormat, boolean useLinearFilter, boolean useMipmaps) Constructs a new SurfaceObjectTileBuilder width the specified tile dimension, tile texture format, and flags specifying if linear filtering and mip-mapping are enabled.

Method Summary

Modifier and Type	Method and Description
protected void	addIntersectingObjects(DrawContext dc, SurfaceObjectTileBuilder.SurfaceObjectTile parent, SurfaceObjectTileBuilder.SurfaceObjectTile tile) Adds surface renderables from the parent's object list to the specified tile's object list.
protected void	addTile(SurfaceObjectTileBuilder.SurfaceObjectTile tile) Adds the specified tile to this tile builder's currentInfo and the TextureTile memory cache.
protected void	addTileOrDescendants(DrawContext dc, LevelSet levelSet, SurfaceObjectTileBuilder.SurfaceObjectTile parent, SurfaceObjectTileBuilder.SurfaceObjectTile tile) Potentially adds the specified tile or its descendants to the tile builder's currentInfo.
protected void	assembleSurfaceObjects(java.lang.Iterable<?> iterable) Adds any SurfaceRenderables in the specified Iterable to the tile builder's currentSurfaceObjects list.
protected void	assembleTiles(DrawContext dc) Assembles a set of surface tiles that are visible in the specified DrawContext and meet the tile builder's resolution criteria.
void	buildTiles(DrawContext dc, java.lang.Iterable<?> iterable) Assembles the surface tiles and draws any surface renderables in the iterable into those offscreen tiles.
protected boolean	canAssembleTiles(DrawContext dc) Returns true if the draw context's viewport width and height are greater than zero.
void	clearPickCandidates(DrawContext dc) Removes all entries from the list of pickable object candidates assembled during the last call to buildTiles(DrawContext, Iterable).
void	clearTiles(DrawContext dc) Removes all entries from the list of SurfaceTiles assembled during the last call to buildTiles(DrawContext, Iterable).
protected java.awt.Dimension	computeTextureTileDimension(DrawContext dc) Returns the tile dimension used to create the tile textures for the specified DrawContext.
protected static LevelSet	createLevelSet(int tileWidth, int tileHeight) Returns a new LevelSet with the specified tile width and height.
protected java.lang.Object	createSurfaceTileDrawContext(SurfaceObjectTileBuilder.SurfaceObjectTile tile) Returns a new Object representing the drawing context for the specified tile.
protected SurfaceObjectTileBuilder.SurfaceObjectTile	createTile(Sector sector, Level level, int row, int column, java.lang.String cacheName) Returns a new SurfaceObjectTile corresponding to the specified sector, level, row, column, and cacheName.
protected SurfaceObjectTileBuilder.TileInfo	createTileInfo(DrawContext dc) Creates a tile info associated with the specified draw context.
protected SurfaceObjectTileBuilder.TileInfoKey	createTileInfoKey(DrawContext dc) Creates a key to address the tile information associated with the specified draw context.
protected java.lang.Object	createTileKey(Level level, int row, int column, java.lang.String cacheName) Returns a new tile key corresponding to the tile with the specified level, row, column, and cacheName.
protected com.jogamp.opengl.util.texture.Texture	createTileTexture(DrawContext dc, int width, int height) Returns a new surface tile texture for use on the specified draw context with the specified width and height.
protected LevelSet	getLevelSet(int tileWidth, int tileHeight) Returns a shared LevelSet for the specified tileDimension.
java.util.Collection<PickedObject>	getPickCandidates(DrawContext dc) Returns the list of pickable object candidates associated with the SurfaceTiles assembled during the last call to buildTiles(DrawContext, Iterable).
double	getSplitScale() Returns the split scale value controlling the tile's surface texel resolution relative to the distance between the globe's surface at the image position and the eye point.
int	getTileCount(DrawContext dc) Returns the number of SurfaceTiles assembled during the last call to buildTiles(DrawContext, Iterable).
java.awt.Dimension	getTileDimension() Returns the surface tile dimension.
java.util.Collection<? extends SurfaceTile>	getTiles(DrawContext dc) Returns the list of SurfaceTiles assembled during the last call to buildTiles(DrawContext, Iterable).
int	getTileTextureFormat() Returns the surface tile's OpenGL texture format, or 0 to indicate that the default format is used.
protected boolean	intersectsFrustum(DrawContext dc, TextureTile tile) Test if the tile intersects the specified draw context's frustum.
protected boolean	intersectsVisibleSector(DrawContext dc, TextureTile tile) Test if the specified tile intersects the draw context's visible sector.
boolean	isForceTileUpdates() Indicates whether or not tiles textures are forced to update during buildTiles(DrawContext, Iterable).
boolean	isUseLinearFilter() Returns if linear filtering is used when rendering surface tiles.
boolean	isUseMipmaps() Returns if mip-maps are generated for surface tile textures.
protected boolean	meetsRenderCriteria(DrawContext dc, LevelSet levelSet, Tile tile) Tests if the specified tile meets the rendering criteria on the specified draw context.
protected boolean	needToSplit(DrawContext dc, Tile tile) Tests if the specified tile must be split to meets the desired resolution on the specified draw context.
void	setForceTileUpdates(boolean forceTileUpdates) Specifies whether or not tiles textures are forced to update during buildTiles(DrawContext, Iterable).
void	setSplitScale(double splitScale) Sets the parameter controlling the tile resolution as distance changes between the globe's surface and the eye point.
void	setTileDimension(java.awt.Dimension dimension) Specifies the preferred surface tile texture dimension.
void	setTileTextureFormat(int textureFormat) Specifies the surface tile's OpenGL texture format.
void	setUseLinearFilter(boolean useLinearFilter) Specifies if linear filtering should be used when rendering surface tiles.
void	setUseMipmaps(boolean useMipmaps) Specifies if mip-maps should be generated for surface tile textures.
protected java.lang.String	uniqueCacheName() Returns a unique name appropriate for use as part of a cache name.
protected void	updateTile(DrawContext dc, SurfaceObjectTileBuilder.SurfaceObjectTile tile) Draws the current list of surface renderables into the specified surface tile.
protected void	updateTiles(DrawContext dc) Updates each SurfaceObjectTileBuilder.SurfaceObjectTile in the currentInfo.

Methods inherited from class java.lang.Object

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

Field Detail

currentInfo

protected SurfaceObjectTileBuilder.TileInfo currentInfo

The currently active TileInfo. Valid only during the execution of buildTiles(DrawContext, Iterable).

currentSurfaceObjects

protected java.util.List<SurfaceRenderable> currentSurfaceObjects

List of currently assembled surface renderables. Valid only during the execution of buildTiles(DrawContext, Iterable).

DEFAULT_LEVEL_ZERO_TILE_DELTA

protected static final LatLon DEFAULT_LEVEL_ZERO_TILE_DELTA

The default level zero tile delta used to construct a LevelSet.

DEFAULT_NUM_LEVELS

protected static final int DEFAULT_NUM_LEVELS

The default number of levels used to construct a LevelSet. Approximately 0.1 meters per pixel at the Earth's equator.

See Also:

Constant Field Values

DEFAULT_SPLIT_SCALE

protected static final double DEFAULT_SPLIT_SCALE

The default split scale. The split scale 2.9 has been empirically determined to render sharp lines and edges with the SurfaceShapes such as SurfacePolyline and SurfacePolygon.

See Also:

Constant Field Values

DEFAULT_TEXTURE_DIMENSION

protected static final int DEFAULT_TEXTURE_DIMENSION

The default surface tile texture dimension, in pixels.

See Also:

Constant Field Values

DEFAULT_TEXTURE_INTERNAL_FORMAT

protected static final int DEFAULT_TEXTURE_INTERNAL_FORMAT

The default OpenGL internal format used to create surface tile textures.

See Also:

Constant Field Values

DEFAULT_TEXTURE_PIXEL_FORMAT

protected static final int DEFAULT_TEXTURE_PIXEL_FORMAT

The default OpenGL pixel format used to create surface tile textures.

See Also:

Constant Field Values

forceTileUpdates

protected boolean forceTileUpdates

Controls if tiles are forced to update during buildTiles(DrawContext, Iterable).

levelSetMap

protected static java.util.Map<java.awt.Dimension,LevelSet> levelSetMap

Map associating a tile texture dimension to its corresponding LevelSet. This map is a class property in order to share LevelSets across all instances of SurfaceObjectTileBuilder.

nextUniqueId

protected static long nextUniqueId

The next unique ID. This property is shared by all instances of SurfaceObjectTileBuilder.

rttSupport

protected OGLRenderToTextureSupport rttSupport

Support class used to render to an offscreen surface tile.

splitScale

protected double splitScale

Controls the tile resolution as distance changes between the globe's surface and the eye point.

tileDimension

protected java.awt.Dimension tileDimension

Indicates the desired tile texture width and height, in pixels. Initially set to DEFAULT_TEXTURE_DIMENSION.

tileInfoMap

protected java.util.Map<java.lang.Object,SurfaceObjectTileBuilder.TileInfo> tileInfoMap

List of currently assembled surface tiles.

tileTextureFormat

protected int tileTextureFormat

The surface tile OpenGL texture format. 0 indicates the default format is used.

useLinearFilter

protected boolean useLinearFilter

Controls if surface tiles are rendered using a linear filter or a nearest-neighbor filter.

useMipmaps

protected boolean useMipmaps

Controls if mip-maps are generated for surface tile textures.

Constructor Detail

SurfaceObjectTileBuilder

public SurfaceObjectTileBuilder()

Constructs a new SurfaceObjectTileBuilder with a tile width and height of 512, with the default tile texture format, with linear filtering enabled, and with mip-mapping disabled.

SurfaceObjectTileBuilder

public SurfaceObjectTileBuilder(java.awt.Dimension tileTextureDimension,
                                int tileTextureFormat,
                                boolean useLinearFilter,
                                boolean useMipmaps)

Constructs a new SurfaceObjectTileBuilder width the specified tile dimension, tile texture format, and flags specifying if linear filtering and mip-mapping are enabled.

Parameters:

tileTextureDimension - the surface tile texture dimension, in pixels.

tileTextureFormat - the surface tile OpenGL texture format, or 0 to use the default format.

useLinearFilter - true to use linear filtering while rendering surface tiles; false to use nearest-neighbor filtering.

useMipmaps - true to generate mip-maps for surface tile textures; false otherwise.

Throws:

java.lang.IllegalArgumentException - if the tile dimension is null.

Method Detail

addIntersectingObjects

protected void addIntersectingObjects(DrawContext dc,
                                      SurfaceObjectTileBuilder.SurfaceObjectTile parent,
                                      SurfaceObjectTileBuilder.SurfaceObjectTile tile)

Adds surface renderables from the parent's object list to the specified tile's object list. If the tile's sector does not intersect the sector bounding the parent's object list, this does nothing. Otherwise, this adds any of the parent's surface renderables that intersect the tile's sector to the tile's object list.

Parameters:

dc - the current DrawContext.

parent - the tile's parent.

tile - the tile to add intersecting surface renderables to.

addTile

protected void addTile(SurfaceObjectTileBuilder.SurfaceObjectTile tile)

Adds the specified tile to this tile builder's currentInfo and the TextureTile memory cache.

Parameters:

tile - the tile to add.

addTileOrDescendants

protected void addTileOrDescendants(DrawContext dc,
                                    LevelSet levelSet,
                                    SurfaceObjectTileBuilder.SurfaceObjectTile parent,
                                    SurfaceObjectTileBuilder.SurfaceObjectTile tile)

Potentially adds the specified tile or its descendants to the tile builder's currentInfo. The tile and its descendants are discarded if the tile is not visible or does not intersect any surface renderables in the parent's surface renderable list. See SurfaceObjectTileBuilder.SurfaceObjectTile.getObjectList().

If the tile meet the tile builder's resolution criteria it's added to the tile builder's currentTiles list. Otherwise, it's split into four sub-tiles and each tile is recursively processed. See meetsRenderCriteria(DrawContext, gov.nasa.worldwind.util.LevelSet, gov.nasa.worldwind.util.Tile).

Parameters:

dc - the current DrawContext.

levelSet - the tile's LevelSet.

parent - the tile's parent, or null if the tile is a top level tile.

tile - the tile to add.

assembleSurfaceObjects

protected void assembleSurfaceObjects(java.lang.Iterable<?> iterable)

Adds any SurfaceRenderables in the specified Iterable to the tile builder's currentSurfaceObjects list.

Parameters:

iterable - the Iterable to gather SurfaceRenderables from.

assembleTiles

protected void assembleTiles(DrawContext dc)

Assembles a set of surface tiles that are visible in the specified DrawContext and meet the tile builder's resolution criteria. Tiles are culled against the current surface renderable list, against the DrawContext's view frustum during rendering mode, and against the DrawContext's pick frustums during picking mode. If a tile does not meet the tile builder's resolution criteria, it's split into four sub-tiles and the process recursively repeated on the sub-tiles. Visible leaf tiles are added to the currentInfo.

During assembly each surface renderable in currentSurfaceObjects is sorted into the tiles they intersect. The top level tiles are used as an index to quickly determine which tiles each renderable intersects. Surface renderables are sorted into sub-tiles by simple intersection tests, and are added to each tile's surface renderable list at most once. See SurfaceObjectTileBuilder.SurfaceObjectTile.addSurfaceObject(SurfaceRenderable, gov.nasa.worldwind.geom.Sector). Tiles that don't intersect any surface renderables are discarded.

Parameters:

dc - the DrawContext to assemble tiles for.

buildTiles

public void buildTiles(DrawContext dc,
                       java.lang.Iterable<?> iterable)

Assembles the surface tiles and draws any surface renderables in the iterable into those offscreen tiles. The surface tiles are assembled to meet the necessary resolution of to the draw context's View. This may temporarily use the framebuffer to perform offscreen rendering, and therefore should be called during the preRender method of a WorldWind Layer.

This does nothing if the specified iterable is null, is empty or contains no surface renderables.

Parameters:

dc - the draw context to build tiles for.

iterable - the iterable to gather surface renderables from.

Throws:

java.lang.IllegalArgumentException - if the draw context is null.

canAssembleTiles

protected boolean canAssembleTiles(DrawContext dc)

Returns true if the draw context's viewport width and height are greater than zero.

Parameters:

dc - the DrawContext to test.

Returns:

true if the DrawContext's has a non-zero viewport; false otherwise.

clearPickCandidates

public void clearPickCandidates(DrawContext dc)

Removes all entries from the list of pickable object candidates assembled during the last call to buildTiles(DrawContext, Iterable).

Parameters:

dc - the draw context used to build tiles.

Throws:

java.lang.IllegalArgumentException - if the draw context is null.

clearTiles

public void clearTiles(DrawContext dc)

Removes all entries from the list of SurfaceTiles assembled during the last call to buildTiles(DrawContext, Iterable).

Parameters:

dc - the draw context used to build tiles.

Throws:

java.lang.IllegalArgumentException - if the draw context is null.

computeTextureTileDimension

protected java.awt.Dimension computeTextureTileDimension(DrawContext dc)

Returns the tile dimension used to create the tile textures for the specified DrawContext. This attempts to use this tile builder's tileDimension, but always returns a dimension that is is a power of two, is square, and fits in the DrawContext's viewport.

Parameters:

dc - the DrawContext to compute a texture tile dimension for.

Returns:

a texture tile dimension appropriate for the specified DrawContext.

createLevelSet

protected static LevelSet createLevelSet(int tileWidth,
                                         int tileHeight)

Returns a new LevelSet with the specified tile width and height. The LevelSet overs the full sphere, has a level zero tile delta of DEFAULT_LEVEL_ZERO_TILE_DELTA, has number of levels equal to DEFAULT_NUM_LEVELS (with no empty levels). The LevelSets' cache name and dataset name dummy values, and should not be used.

Parameters:

tileWidth - the LevelSet's tile width, in pixels.

tileHeight - the LevelSet's tile height, in pixels.

Returns:

a new LevelSet configured to with

createSurfaceTileDrawContext

protected java.lang.Object createSurfaceTileDrawContext(SurfaceObjectTileBuilder.SurfaceObjectTile tile)

Returns a new Object representing the drawing context for the specified tile. The returned object should represent the tile's sector and it's corresponding viewport in pixels.

Parameters:

tile - The tile to create a context for.

Returns:

a new drawing context for the specified tile.

createTile

protected SurfaceObjectTileBuilder.SurfaceObjectTile createTile(Sector sector,
                                                                Level level,
                                                                int row,
                                                                int column,
                                                                java.lang.String cacheName)

Returns a new SurfaceObjectTile corresponding to the specified sector, level, row, column, and cacheName.

Parameters:

sector - The tile's Sector.

level - The tile's Level in a LevelSet.

row - The tile's row in the Level, starting from 0 and increasing to the right.

column - The tile's column in the Level, starting from 0 and increasing upward.

cacheName - Tile tile's cache name.

Returns:

a new SurfaceObjectTile.

createTileInfo

protected SurfaceObjectTileBuilder.TileInfo createTileInfo(DrawContext dc)

Creates a tile info associated with the specified draw context.

Parameters:

dc - the draw context to create the tile info for.

Returns:

the tile info for the specified draw context.

createTileInfoKey

protected SurfaceObjectTileBuilder.TileInfoKey createTileInfoKey(DrawContext dc)

Creates a key to address the tile information associated with the specified draw context. Each key is unique to this instance, the tile dimensions that fit in the draw context's viewport, and the globe offset when a 2D globe is in use. Using a unique set of tile information ensures that

In practices, there are at most 10 dimensions we'll use (512, 256, 128, 64, 32, 16, 8, 4, 2, 1) and 3 globe offsets (-1, 0, 1). Therefore there are at most 30 sets of tile information for each instance of SurfaceObjectTileBuilder.

Parameters:

dc - the draw context to create the tile info key for.

Returns:

the tile info key for the specified draw context.

createTileKey

protected java.lang.Object createTileKey(Level level,
                                         int row,
                                         int column,
                                         java.lang.String cacheName)

Returns a new tile key corresponding to the tile with the specified level, row, column, and cacheName.

Parameters:

level - The tile's Level in a LevelSet.

row - The tile's row in the Level, starting from 0 and increasing to the right.

column - The tile's column in the Level, starting from 0 and increasing upward.

cacheName - Tile tile's cache name.

Returns:

a tile key.

createTileTexture

protected com.jogamp.opengl.util.texture.Texture createTileTexture(DrawContext dc,
                                                                   int width,
                                                                   int height)

Returns a new surface tile texture for use on the specified draw context with the specified width and height.

The returned texture's internal format is specified by tilePixelFormat. If tilePixelFormat is zero, this returns a texture with internal format GL_RGBA8.

The returned texture's parameters are configured as follows:

Parameters

Parameter Name	Value
GL.GL_TEXTURE_MIN_FILTER	GL_LINEAR_MIPMAP_LINEAR if useLinearFilter and useMipmaps are both true, GL_LINEAR if useLinearFilter is true and useMipmaps is false, and GL_NEAREST if useLinearFilter is false.
GL.GL_TEXTURE_MAG_FILTER	GL_LINEAR if useLinearFilter is true, GL_NEAREST if useLinearFilter is false.
GL.GL_TEXTURE_WRAP_S	GL_CLAMP_TO_EDGE
GL.GL_TEXTURE_WRAP_T	GL_CLAMP_TO_EDGE

Parameters:

dc - the draw context to create a texture for.

width - the texture's width, in pixels.

height - the texture's height, in pixels.

Returns:

a new texture with the specified width and height.

getLevelSet

protected LevelSet getLevelSet(int tileWidth,
                               int tileHeight)

Returns a shared LevelSet for the specified tileDimension. All instances of SurfaceObjectTileBuilder share common LevelSets to determine which tiles are visible, but create unique tile instances and uses a unique tile cache name. Since all instances use the same tile structure to determine visible tiles, this saves memory while ensuring that each instance stores its own tiles in the cache.

The returned LevelSet's cache name and dataset name are dummy values, and should not be used. Use this tile builder's cache name for the specified tileDimension instead.

In practice, there are at most 10 dimensions we use: 512, 256, 128, 64, 32, 16, 8, 4, 2, 1. Therefore keeping the LevelSets in a map requires little memory overhead, and ensures each LevelSet is retained once constructed. Retaining references to the LevelSets means we're able to re-use the texture resources associated with each LevelSet in the DrawContext's texture cache.

Subsequent calls are guaranteed to return the same LevelSet for the same tileDimension.

Parameters:

tileWidth - the tile width, in pixels.

tileHeight - the tile height, in pixels.

Returns:

a LevelSet with the specified tile dimensions.

getPickCandidates

public java.util.Collection<PickedObject> getPickCandidates(DrawContext dc)

Returns the list of pickable object candidates associated with the SurfaceTiles assembled during the last call to buildTiles(DrawContext, Iterable).

Parameters:

dc - the draw context used to build tiles.

Returns:

the pick candidates associated with the list of SurfaceTiles.

Throws:

java.lang.IllegalArgumentException - if the draw context is null.

getSplitScale

public double getSplitScale()

Returns the split scale value controlling the tile's surface texel resolution relative to the distance between the globe's surface at the image position and the eye point.

Returns:

the current split scale.

See Also:

setSplitScale(double)

getTileCount

public int getTileCount(DrawContext dc)

Returns the number of SurfaceTiles assembled during the last call to buildTiles(DrawContext, Iterable).

Parameters:

dc - the draw context used to build tiles.

Returns:

a count of SurfaceTiles containing a composite representation of the specified surface renderables.

Throws:

java.lang.IllegalArgumentException - if the draw context is null.

getTileDimension

public java.awt.Dimension getTileDimension()

Returns the surface tile dimension.

Returns:

the surface tile dimension, in pixels.

getTiles

public java.util.Collection<? extends SurfaceTile> getTiles(DrawContext dc)

Returns the list of SurfaceTiles assembled during the last call to buildTiles(DrawContext, Iterable).

Parameters:

dc - the draw context used to build tiles.

Returns:

a List of SurfaceTiles containing a composite representation of the specified surface renderables.

Throws:

java.lang.IllegalArgumentException - if the draw context is null.

getTileTextureFormat

public int getTileTextureFormat()

Returns the surface tile's OpenGL texture format, or 0 to indicate that the default format is used.

Returns:

the OpenGL texture format, or 0 if the default format is used.

See Also:

setTileTextureFormat(int)

intersectsFrustum

protected boolean intersectsFrustum(DrawContext dc,
                                    TextureTile tile)

Test if the tile intersects the specified draw context's frustum. During picking mode, this tests intersection against all of the draw context's pick frustums. During rendering mode, this tests intersection against the draw context's viewing frustum.

Parameters:

dc - the draw context the surface renderable is related to.

tile - the tile to test for intersection.

Returns:

true if the tile intersects the draw context's frustum; false otherwise.

intersectsVisibleSector

protected boolean intersectsVisibleSector(DrawContext dc,
                                          TextureTile tile)

Test if the specified tile intersects the draw context's visible sector. This returns false if the draw context's visible sector is null.

Parameters:

dc - the current draw context.

tile - the tile to test for intersection.

Returns:

true if the tile intersects the draw context's visible sector; false otherwise.

isForceTileUpdates

public boolean isForceTileUpdates()

Indicates whether or not tiles textures are forced to update during buildTiles(DrawContext, Iterable). When true, tile textures always update their contents with the current surface renderables. When false, tile textures only update their contents when the surface renderables change. Initially false.

Returns:

true if tile textures always update their contents, false if tile textures only update when the surface renderables change.

isUseLinearFilter

public boolean isUseLinearFilter()

Returns if linear filtering is used when rendering surface tiles.

Returns:

true if linear filtering is used; false if nearest-neighbor filtering is used.

isUseMipmaps

public boolean isUseMipmaps()

Returns if mip-maps are generated for surface tile textures.

Returns:

true if mip-maps are generated; false otherwise.

meetsRenderCriteria

protected boolean meetsRenderCriteria(DrawContext dc,
                                      LevelSet levelSet,
                                      Tile tile)

Tests if the specified tile meets the rendering criteria on the specified draw context. This returns true if the tile is from the level set's final level, or if the tile achieves the desired resolution on the draw context.

Parameters:

dc - the current draw context.

levelSet - the level set the tile belongs to.

tile - the tile to test.

Returns:

true if the tile meets the rendering criteria; false otherwise.

needToSplit

protected boolean needToSplit(DrawContext dc,
                              Tile tile)

Tests if the specified tile must be split to meets the desired resolution on the specified draw context. This compares the distance form the eye point to the tile to determine if the tile meets the desired resolution for the View attached to the draw context.

Parameters:

dc - the current draw context.

tile - the tile to test.

Returns:

true if the tile must be split; false otherwise.

setForceTileUpdates

public void setForceTileUpdates(boolean forceTileUpdates)

Specifies whether or not tiles textures are forced to update during buildTiles(DrawContext, Iterable). When true, tile textures always update their contents with the current surface renderables. When false, tile textures only update their contents when the surface renderables change.

Parameters:

forceTileUpdates - true if tile textures should always update their contents, false if tile textures should only update when the surface renderables change.

setSplitScale

public void setSplitScale(double splitScale)

Sets the parameter controlling the tile resolution as distance changes between the globe's surface and the eye point. Higher resolution is displayed as the split scale increases from 1.0. Lower resolution is displayed as the split scale decreases from 1.0. The default value is 2.9.

Parameters:

splitScale - a value near 1.0 that controls the tile's surface texel resolution as the distance between the globe's surface and the eye point change. Increasing values select higher resolution, decreasing values select lower resolution. The default value is 2.9.

setTileDimension

public void setTileDimension(java.awt.Dimension dimension)

Specifies the preferred surface tile texture dimension. If the dimension is larger than the viewport dimension, this uses a dimension with width and height set to the largest power of two that is less than or equal to the specified dimension and the viewport dimension.

Parameters:

dimension - the surface tile dimension, in pixels.

Throws:

java.lang.IllegalArgumentException - if the dimension is null.

setTileTextureFormat

public void setTileTextureFormat(int textureFormat)

Specifies the surface tile's OpenGL texture format. A value of 0 indicates that the default format should be used. Otherwise, the texture format may be one of the following:

• GL_ALPHA
• GL_ALPHA4
• GL_ALPHA8
• GL_ALPHA12
• GL_ALPHA16
• GL_COMPRESSED_ALPHA
• GL_COMPRESSED_LUMINANCE
• GL_COMPRESSED_LUMINANCE_ALPHA
• GL_COMPRESSED_INTENSITY
• GL_COMPRESSED_RGB
• GL_COMPRESSED_RGBA
• GL_DEPTH_COMPONENT
• GL_DEPTH_COMPONENT16
• GL_DEPTH_COMPONENT24
• GL_DEPTH_COMPONENT32
• GL_LUMINANCE
• GL_LUMINANCE4
• GL_LUMINANCE8
• GL_LUMINANCE12
• GL_LUMINANCE16
• GL_LUMINANCE_ALPHA
• GL_LUMINANCE4_ALPHA4
• GL_LUMINANCE6_ALPHA2
• GL_LUMINANCE8_ALPHA8
• GL_LUMINANCE12_ALPHA4
• GL_LUMINANCE12_ALPHA12
• GL_LUMINANCE16_ALPHA16
• GL_INTENSITY
• GL_INTENSITY4
• GL_INTENSITY8
• GL_INTENSITY12
• GL_INTENSITY16
• GL_R3_G3_B2
• GL_RGB
• GL_RGB4
• GL_RGB5
• GL_RGB8
• GL_RGB10
• GL_RGB12
• GL_RGB16
• GL_RGBA
• GL_RGBA2
• GL_RGBA4
• GL_RGB5_A1
• GL_RGBA8
• GL_RGB10_A2
• GL_RGBA12
• GL_RGBA16
• GL_SLUMINANCE
• GL_SLUMINANCE8
• GL_SLUMINANCE_ALPHA
• GL_SLUMINANCE8_ALPHA8
• GL_SRGB
• GL_SRGB8
• GL_SRGB_ALPHA
• GL_SRGB8_ALPHA8

If the texture format is any of GL_RGB, GL_RGB8, GL_RGBA, or GL_RGBA8, the tile builder attempts to use OpenGL framebuffer objects to render shapes to the texture tiles. Otherwise, this renders shapes to the framebuffer and copies the framebuffer contents to the texture tiles.

Parameters:

textureFormat - the OpenGL texture format, or 0 to use the default format.

setUseLinearFilter

public void setUseLinearFilter(boolean useLinearFilter)

Specifies if linear filtering should be used when rendering surface tiles.

Parameters:

useLinearFilter - true to use linear filtering; false to use nearest-neighbor filtering.

setUseMipmaps

public void setUseMipmaps(boolean useMipmaps)

Specifies if mip-maps should be generated for surface tile textures.

Parameters:

useMipmaps - true to generate mip-maps; false otherwise.

uniqueCacheName

protected java.lang.String uniqueCacheName()

Returns a unique name appropriate for use as part of a cache name.

Returns:

a unique cache name.

updateTile

protected void updateTile(DrawContext dc,
                          SurfaceObjectTileBuilder.SurfaceObjectTile tile)

Draws the current list of surface renderables into the specified surface tile. The surface tiles is updated only when necessary. The tile keeps track of the list of surface renderables rendered into it, and the state keys those objects. The tile is updated if the list changes, if any of the state keys change, or if the tile has no texture. Otherwise the tile is left unchanged and the update is skipped.

Parameters:

dc - the draw context the tile relates to.

tile - the tile to update.

updateTiles

protected void updateTiles(DrawContext dc)

Updates each SurfaceObjectTileBuilder.SurfaceObjectTile in the currentInfo. This is typically called after assembleTiles(DrawContext) to update the assembled tiles.

This method does nothing if currentTiles is empty.

Parameters:

dc - the draw context the tiles relate to.