Package gov.nasa.worldwind.render

Class 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));
     }
 }

    • Field Detail

      • 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

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

      • nextUniqueId

        protected static long nextUniqueId
        The next unique ID. This property is shared by all instances of SurfaceObjectTileBuilder.

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

      • tileDimension

        protected java.awt.Dimension tileDimension
        Indicates the desired tile texture width and height, in pixels. Initially set to DEFAULT_TEXTURE_DIMENSION.

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

      • splitScale

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

    • 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

      • getTileDimension

        public java.awt.Dimension getTileDimension()
        Returns the surface tile dimension.
        Returns:
        the surface tile dimension, in pixels.

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

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

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

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

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

      • isUseMipmaps

        public boolean isUseMipmaps()
        Returns if mip-maps are generated for surface tile textures.
        Returns:
        true if mip-maps are generated; false otherwise.

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

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

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

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

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

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

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

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

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

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

      • 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 NameValue
        GL.GL_TEXTURE_MIN_FILTERGL_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_FILTERGL_LINEAR if useLinearFilter is true, GL_NEAREST if useLinearFilter is false.
        GL.GL_TEXTURE_WRAP_SGL_CLAMP_TO_EDGE
        GL.GL_TEXTURE_WRAP_TGL_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.

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

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

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

      • 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

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

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

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

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

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

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

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

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

      • uniqueCacheName

        protected java.lang.String uniqueCacheName()
        Returns a unique name appropriate for use as part of a cache name.
        Returns:
        a unique cache name.

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

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