Package gov.nasa.worldwind.util

Class TextureAtlas

  • public class TextureAtlas
extends java.lang.Object
    Represents a texture composed of multiple independent images. The independent images are referred to as elements, and are packed into non-overlapping sub-rectangles within the texture atlas. The following NVIDIA document describes this technique: Improve Batching Using Texture Atlases

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      protected class  TextureAtlas.AtlasBackingStore
      Implementation of the JOGL BackingStoreManager interface for texture atlas.
      protected static class  TextureAtlas.Entry
      Represents an image element in a texture atlas.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.awt.Color clearColor
      Indicates the color used to fill regions of this texture atlas that do not contain a sub-image element.
      protected static double DEFAULT_MAX_VERTICAL_FRAGMENTATION
      The texture atlas' default maximum vertical fragmentation: 0.7.
      protected static boolean DEFAULT_USE_ANISOTROPY
      The texture atlas' default setting for the useAnisotropy property: true.
      protected static boolean DEFAULT_USE_MIP_MAPS
      The texture atlas' default setting for the useMipMaps property: true.
      protected java.awt.Rectangle dirtyRect
      Indicates the rectangle within this texture atlas' backing image that is currently out-of-sync with its corresponding OpenGL texture.
      protected java.util.Queue<java.lang.Object> disposedTextureKeys
      Queue of texture keys corresponding to disposed backing images.
      protected java.util.Map<java.lang.Object,​TextureAtlas.Entry> entryMap
      Maps element keys to their corresponding entry.
      protected boolean evictOldElements
      Indicates whether this texture atlas evicts old elements in order to make room for a new element when the atlas is full.
      protected java.awt.Graphics2D g
      Temporary AWT graphics instance used to move image elements during a beginMovement/endMovement block.
      protected int maxHeight
      Indicates this texture atlas' maximum total height, in pixels.
      protected double maxVerticalFragmentation
      Indicates the maximum amount of vertical fragmentation this texture atlas allows before compacting its elements.
      protected int maxWidth
      Indicates this texture atlas' maximum total width, in pixels.
      protected com.jogamp.opengl.util.packrect.RectanglePacker rectPacker
      The JOGL rectangle packer used by this texture atlas to determine how to pack the elements within this texture atlas' backing image.
      protected java.lang.Object textureKey
      Indicates the current key corresponding to this texture atlas' OpenGL texture in the GPU resource cache.
      protected boolean useAnisotropy
      Indicates whether this texture atlas applies an anisotropic filter to each atlas element.
      protected boolean useMipMaps
      Indicates whether this texture atlas generates mip-maps for each atlas element.

    • Constructor Summary

      Constructors 
      Constructor Description
      TextureAtlas​(int initialWidth, int initialHeight, int maxWidth, int maxHeight)
      Constructs a texture atlas with the specified initial and maximum dimensions.
      TextureAtlas​(int initialWidth, int initialHeight, int maxWidth, int maxHeight, boolean useMipMaps, boolean useAnisotropy)
      Constructs a texture atlas with the specified initial and maximum dimensions.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(java.lang.Object key, java.awt.image.BufferedImage image)
      Adds a new element to this texture atlas with the specified key and image.
      protected void beginMoveEntries​(java.awt.image.BufferedImage oldBackingImage, java.awt.image.BufferedImage newBackingImage)
      Called when the atlas is performing a full re-layout of its elements, just before the layout begins.
      boolean bind​(DrawContext dc)
      Binds this texture atlas' OpenGL texture to the GLContext attached to the draw context.
      void clear()
      Removes all elements from this texture atlas.
      protected void clearDirtyRect()
      Removes any regions in this texture atlas' backing image previously marked as needing to be synchronized with the OpenGL texture.
      protected void clearRect​(java.awt.image.BufferedImage backingImage, int x, int y, int width, int height)
      Fills the specified rectangle with the clear color in the backing image.
      boolean contains​(java.lang.Object key)
      Indicates whether this texture atlas contains an element with the specified key.
      protected java.awt.image.BufferedImage createBackingImage​(int width, int height)
      Creates and returns a BufferedImage with the specified dimensions to use as this texture atlas' backing image.
      protected com.jogamp.opengl.util.packrect.RectanglePacker createRectanglePacker​(int initialWidth, int initialHeight)
      Returns a new JOGL rectangle packer that is used by this texture atlas to determine how to pack the elements within this texture atlas' backing image.
      protected void disposeBackingImage()
      Disposes of this texture atlas' current backing image.
      protected void disposeOldTextures​(DrawContext dc)
      Removes textures corresponding to this texture atlas' disposed backing images from the draw context's GPU resource cache.
      protected void doAdd​(java.lang.Object key, java.awt.image.BufferedImage image)
      Adds a new element to this texture atlas with the specified key and image.
      protected void doRemove​(TextureAtlas.Entry entry)
      Removes the element corresponding to the specified entry from this texture atlas, freeing the space it occupied to be used by other elements.
      protected void drawImage​(java.awt.image.BufferedImage backingImage, java.awt.image.BufferedImage image, int x, int y, boolean drawBorder)
      Draws the specified image in the backing image at the specified (x, y) location.
      protected void endMoveEntries​(java.awt.image.BufferedImage oldBackingImage, java.awt.image.BufferedImage newBackingImage)
      Called when the atlas is performing a full re-layout of its elements, just after the layout ends.
      protected java.awt.Rectangle getDirtyRect()
      Returns the region of this texture atlas' backing image that is not currently synchronized with the OpenGL texture.
      int getHeight()
      Indicates this texture atlas' current height, in pixels.
      int getMaxHeight()
      Indicates this texture atlas' maximum height, in pixels.
      int getMaxWidth()
      Indicates this texture atlas' maximum width, in pixels.
      int getNumElements()
      Returns the number of elements currently in this texture atlas.
      java.awt.Dimension getSize​(java.lang.Object key)
      Returns the image dimensions associated with an element in this texture atlas.
      com.jogamp.opengl.util.texture.TextureCoords getTexCoords​(java.lang.Object key)
      Returns the OpenGL texture coordinates associated with an element in this texture atlas.
      protected com.jogamp.opengl.util.texture.Texture getTexture​(DrawContext dc)
      Indicates the OpenGL Texture associated with this texture atlas.
      int getWidth()
      Indicates this texture atlas' current width, in pixels.
      boolean isEmpty()
      Indicates whether this texture atlas contains any elements.
      boolean isEvictOldElements()
      Indicates whether this texture atlas evicts the oldest elements in order to make room for a new element when the atlas is full.
      boolean isUseAnisotropy()
      Indicates whether this texture atlas applies an anisotropic filter to each atlas element.
      boolean isUseMipMaps()
      Indicates whether this texture atlas generates mip-maps for each atlas element.
      protected com.jogamp.opengl.util.texture.Texture makeTextureWithBackingImage​(DrawContext dc)
      Creates an OpenGL texture by loading this texture atlas's backing image into a new texture with the same dimensions.
      protected void markDirty​(int x, int y, int width, int height)
      Marks a region of this texture atlas' backing image as needing to be synchronized with the OpenGL texture.
      protected void markUsed​(TextureAtlas.Entry entry)
      Marks the specified entry as used by setting its last used time to the current time in nanoseconds.
      protected void moveEntry​(java.awt.image.BufferedImage oldBackingImage, com.jogamp.opengl.util.packrect.Rect oldRect, java.awt.image.BufferedImage newBackingImage, com.jogamp.opengl.util.packrect.Rect newRect)
      Called for each atlas element when the atlas is performing a full re-layout of its elements.
      boolean remove​(java.lang.Object key)
      Removes the element with the specified key from this texture atlas, freeing the space it occupied to be used by other elements.
      protected boolean removeLeastRecentlyUsedEntry()
      Removes the oldest entry from this texture atlas.
      void setEvictOldElements​(boolean evictOldElements)
      Specifies whether this texture atlas should evict the oldest elements in order to make room for a new element when the atlas is full.
      protected void setTexture​(DrawContext dc, com.jogamp.opengl.util.texture.Texture texture)
      Specifies the OpenGL Texture associated with this texture atlas.
      protected void setTextureParameters​(DrawContext dc)
      Specifies the OpenGL texture parameters associated with this texture atlas' OpenGL texture.
      protected com.jogamp.opengl.util.texture.Texture syncTexture​(DrawContext dc)
      Synchronizes this texture atlas's backing image with its OpenGL texture, creating an OpenGL texture as necessary.
      protected com.jogamp.opengl.util.texture.Texture updateTextureWithSubImage​(DrawContext dc, java.awt.Rectangle rect)
      Loads a sub-region of this texture atlas' backing image into its OpenGL texture.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • DEFAULT_USE_MIP_MAPS

        protected static final boolean DEFAULT_USE_MIP_MAPS
        The texture atlas' default setting for the useMipMaps property: true.
        See Also:
        Constant Field Values

      • DEFAULT_USE_ANISOTROPY

        protected static final boolean DEFAULT_USE_ANISOTROPY
        The texture atlas' default setting for the useAnisotropy property: true.
        See Also:
        Constant Field Values

      • DEFAULT_MAX_VERTICAL_FRAGMENTATION

        protected static final double DEFAULT_MAX_VERTICAL_FRAGMENTATION
        The texture atlas' default maximum vertical fragmentation: 0.7.
        See Also:
        Constant Field Values

      • maxWidth

        protected int maxWidth
        Indicates this texture atlas' maximum total width, in pixels. This is specified during construction and is used to determine when an image is too large to fit in this texture atlas.

      • maxHeight

        protected int maxHeight
        Indicates this texture atlas' maximum total height, in pixels. This is specified during construction and is used to determine when an image is too large to fit in this texture atlas.

      • useMipMaps

        protected boolean useMipMaps
        Indicates whether this texture atlas generates mip-maps for each atlas element. true if this texture atlas generates mip-maps, and false otherwise. Specified during construction.

      • useAnisotropy

        protected boolean useAnisotropy
        Indicates whether this texture atlas applies an anisotropic filter to each atlas element. true if this texture atlas applies an anisotropic filter, and false otherwise. This has no effect if useMipMaps is false. Specified during construction.

      • evictOldElements

        protected boolean evictOldElements
        Indicates whether this texture atlas evicts old elements in order to make room for a new element when the atlas is full. true if this atlas evicts elements to make room for new elements, and false otherwise. Initially code false.

      • maxVerticalFragmentation

        protected double maxVerticalFragmentation
        Indicates the maximum amount of vertical fragmentation this texture atlas allows before compacting its elements. Initialized to DEFAULT_MAX_VERTICAL_FRAGMENTATION.

      • rectPacker

        protected com.jogamp.opengl.util.packrect.RectanglePacker rectPacker
        The JOGL rectangle packer used by this texture atlas to determine how to pack the elements within this texture atlas' backing image. Initialized during construction.

      • entryMap

        protected java.util.Map<java.lang.Object,​TextureAtlas.Entry> entryMap
        Maps element keys to their corresponding entry. This enables the texture atlas to access the information about each element in constant time using its key. Initialized to a new HashMap.

      • dirtyRect

        protected java.awt.Rectangle dirtyRect
        Indicates the rectangle within this texture atlas' backing image that is currently out-of-sync with its corresponding OpenGL texture. The dirty rectangle is null when this texture atlas' backing image is synchronized with its OpenGL texture. Initially null.

      • clearColor

        protected java.awt.Color clearColor
        Indicates the color used to fill regions of this texture atlas that do not contain a sub-image element. Initially transparent black (R=0, G=0, B=0, A=0).

      • g

        protected java.awt.Graphics2D g
        Temporary AWT graphics instance used to move image elements during a beginMovement/endMovement block. This property is assigned in beginMovement, used in move, then cleared in endMovement. Initially null.

      • textureKey

        protected java.lang.Object textureKey
        Indicates the current key corresponding to this texture atlas' OpenGL texture in the GPU resource cache. This key is assigned to a new instance whenever this texture atlas creates new backing image. Initialized to a new Object.

      • disposedTextureKeys

        protected java.util.Queue<java.lang.Object> disposedTextureKeys
        Queue of texture keys corresponding to disposed backing images. These keys are disposed during the next call to bind. While disposed backing textures would eventually be evicted by the GPU resource cache, explicitly disposing them avoids polluting the GPU resource cache with orphaned textures that are used only by this texture atlas.

    • Constructor Detail

      • TextureAtlas

        public TextureAtlas​(int initialWidth,
                    int initialHeight,
                    int maxWidth,
                    int maxHeight)
        Constructs a texture atlas with the specified initial and maximum dimensions. All dimensions must be greater than zero, and the maximum dimensions must be greater than or equal to the initial dimensions. The constructed texture atlas generates mip-maps and applies an anisotropic filter to each element.
        Parameters:
        initialWidth - the texture atlas' initial width, in pixels. Must be greater than zero.
        initialHeight - the texture atlas' initial height, in pixels. Must be greater than zero.
        maxWidth - the texture atlas' maximum width, in pixels. Must be greater than or equal to initialWidth.
        maxHeight - the texture atlas' maximum height, in pixels. Must be greater than or equal to initialHeight.
        Throws:
        java.lang.IllegalArgumentException - if any of initialWidth, initialHeight, maxWidth, or maxHeight are less than or equal to zero, if maxWidth is less than initialWidth, or if maxHeight is less than initialHeight.

      • TextureAtlas

        public TextureAtlas​(int initialWidth,
                    int initialHeight,
                    int maxWidth,
                    int maxHeight,
                    boolean useMipMaps,
                    boolean useAnisotropy)
        Constructs a texture atlas with the specified initial and maximum dimensions. All dimensions must be greater than zero, and the maximum dimensions must be greater than or equal to the initial dimensions. This constructor enables specification of whether the texture atlas generates mip-maps and applies an anisotropic filter to each element.
        Parameters:
        initialWidth - the texture atlas' initial width, in pixels. Must be greater than zero.
        initialHeight - the texture atlas' initial height, in pixels. Must be greater than zero.
        maxWidth - the texture atlas' maximum width, in pixels. Must be greater than or equal to initialWidth.
        maxHeight - the texture atlas' maximum height, in pixels. Must be greater than or equal to initialHeight.
        useMipMaps - whether to generate mip-maps for each atlas element. true to generate mip-maps, and false otherwise.
        useAnisotropy - whether to apply an anisotropic filter to each atlas element. true to apply an anisotropic filter, and false otherwise. This has no effect if useMipMaps is false.
        Throws:
        java.lang.IllegalArgumentException - if any of initialWidth, initialHeight, maxWidth, or maxHeight are less than or equal to zero, if maxWidth is less than initialWidth, or if maxHeight is less than initialHeight.

    • Method Detail

      • createRectanglePacker

        protected com.jogamp.opengl.util.packrect.RectanglePacker createRectanglePacker​(int initialWidth,
                                                                                int initialHeight)
        Returns a new JOGL rectangle packer that is used by this texture atlas to determine how to pack the elements within this texture atlas' backing image. By default, this returns a rectangle packer with an TextureAtlas.AtlasBackingStore as the backing store manager. Called during construction.
        Parameters:
        initialWidth - this texture atlas' initial width.
        initialHeight - this texture atlas' initial height.
        Returns:
        a new JOGL rectangle packer with the specified initial dimensions.

      • getWidth

        public int getWidth()
        Indicates this texture atlas' current width, in pixels.
        Returns:
        this texture atlas' current width.

      • getHeight

        public int getHeight()
        Indicates this texture atlas' current height, in pixels.
        Returns:
        this texture atlas' current height.

      • getMaxWidth

        public int getMaxWidth()
        Indicates this texture atlas' maximum width, in pixels.
        Returns:
        this texture atlas' maximum width.

      • getMaxHeight

        public int getMaxHeight()
        Indicates this texture atlas' maximum height, in pixels.
        Returns:
        this texture atlas' maximum height.

      • isUseMipMaps

        public boolean isUseMipMaps()
        Indicates whether this texture atlas generates mip-maps for each atlas element. Specified during construction.
        Returns:
        true if this texture atlas generates mip-maps, and false otherwise.

      • isUseAnisotropy

        public boolean isUseAnisotropy()
        Indicates whether this texture atlas applies an anisotropic filter to each atlas element. This has no effect if useMipMaps is false. Specified during construction.
        Returns:
        true if this texture atlas applies an anisotropic filter, and false otherwise.

      • isEvictOldElements

        public boolean isEvictOldElements()
        Indicates whether this texture atlas evicts the oldest elements in order to make room for a new element when the atlas is full.
        Returns:
        true if this atlas evicts old elements to make room for new elements, and false otherwise.
        See Also:
        setEvictOldElements(boolean)

      • setEvictOldElements

        public void setEvictOldElements​(boolean evictOldElements)
        Specifies whether this texture atlas should evict the oldest elements in order to make room for a new element when the atlas is full. When disabled, calling add with an element that does not fit in the current atlas layout causes this texture atlas to throw an exception if the atlas cannot be expanded. When enabled, the oldest elements are evicted until there is enough space to fit the element in the layout.
        Parameters:
        evictOldElements - true if this atlas should evict old elements to make room for new elements, and false otherwise.

      • getNumElements

        public int getNumElements()
        Returns the number of elements currently in this texture atlas.
        Returns:
        the number of elements in this texture atlas, or 0 if this atlas does not contain any elements.

      • isEmpty

        public boolean isEmpty()
        Indicates whether this texture atlas contains any elements.
        Returns:
        true if this texture atlas contains at least one element, and false otherwise.

      • add

        public void add​(java.lang.Object key,
                java.awt.image.BufferedImage image)
        Adds a new element to this texture atlas with the specified key and image. The image's dimensions must be less than or equal to this texture atlas' maximum dimensions. If this texture atlas is not configured to evict old entries, this throws an exception if the image does not fit in the current atlas layout and the atlas cannot be expanded.

        This adds a one pixel border around the specified image in this texture atlas' backing image by copying the image's outer pixels into a border surrounding the original image. This border avoids sampling pixels from neighboring atlas elements when an OpenGL box filter is applied to this image. This means that the atlas actually requires space for an image with dimensions (width + 2, height + 2), where width and height are the image's original dimensions.

        Parameters:
        key - an object used to reference the image.
        image - the image to add.
        Throws:
        java.lang.IllegalArgumentException - if either the key or image is null, or if the image dimensions are greater than this texture atlas' maximum dimensions.
        WWRuntimeException - if this texture atlas is too full to fit the image in its layout.

      • doAdd

        protected void doAdd​(java.lang.Object key,
                     java.awt.image.BufferedImage image)
        Adds a new element to this texture atlas with the specified key and image.
        Parameters:
        key - an object used to reference the image.
        image - the image to add.
        Throws:
        WWRuntimeException - if this texture atlas is too full to fit the image in its layout.

      • remove

        public boolean remove​(java.lang.Object key)
        Removes the element with the specified key from this texture atlas, freeing the space it occupied to be used by other elements. If this texture atlas does not contain an element with the specified key, this returns false but otherwise does nothing.
        Parameters:
        key - an object used to reference the element to remove.
        Returns:
        true if this texture atlas contained an element with the specified key, and false otherwise.
        Throws:
        java.lang.IllegalArgumentException - if the key is null.

      • doRemove

        protected void doRemove​(TextureAtlas.Entry entry)
        Removes the element corresponding to the specified entry from this texture atlas, freeing the space it occupied to be used by other elements.
        Parameters:
        entry - the entry to remove.

      • contains

        public boolean contains​(java.lang.Object key)
        Indicates whether this texture atlas contains an element with the specified key.
        Parameters:
        key - the key which the element is referenced by.
        Returns:
        true if this texture atlas contains an element with the specified key, and false otherwise.
        Throws:
        java.lang.IllegalArgumentException - if the key is null.

      • getSize

        public java.awt.Dimension getSize​(java.lang.Object key)
        Returns the image dimensions associated with an element in this texture atlas. This returns null this texture atlas does not contain the element.
        Parameters:
        key - the key which the element is referenced by.
        Returns:
        the image dimensions corresponding to the specified element, or null if this texture atlas does not contain the element.

      • getTexCoords

        public com.jogamp.opengl.util.texture.TextureCoords getTexCoords​(java.lang.Object key)
        Returns the OpenGL texture coordinates associated with an element in this texture atlas. This returns null if this texture atlas does not contain the element.

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

        Parameters:
        key - the key which the element is referenced by.
        Returns:
        the OpenGL texture coordinates corresponding to the specified element, or null if this texture atlas does not contain the element.

      • clear

        public void clear()
        Removes all elements from this texture atlas. The backing image retains its current dimensions after this call.

      • bind

        public boolean bind​(DrawContext dc)
        Binds this texture atlas' OpenGL texture to the GLContext attached to the draw context. Before binding, this updates the OpenGL texture as necessary to reflect changes in this texture atlas since the last call to bind.
        Parameters:
        dc - the current draw context.
        Returns:
        true if the texture is bound, and false otherwise.
        Throws:
        java.lang.IllegalArgumentException - if the draw context is null.

      • createBackingImage

        protected java.awt.image.BufferedImage createBackingImage​(int width,
                                                          int height)
        Creates and returns a BufferedImage with the specified dimensions to use as this texture atlas' backing image. The returned image must be at least as large as the specified dimensions, but may be larger. By default, this always returns an image with power-of-two dimensions in order to maximize compatibility with different graphics cards.
        Parameters:
        width - the backing image's minimum width, in pixels.
        height - the backing image's minimum height, in pixels.
        Returns:
        a new BufferedImage to use as this texture atlas' backing image.

      • disposeBackingImage

        protected void disposeBackingImage()
        Disposes of this texture atlas' current backing image.

      • clearRect

        protected void clearRect​(java.awt.image.BufferedImage backingImage,
                         int x,
                         int y,
                         int width,
                         int height)
        Fills the specified rectangle with the clear color in the backing image.
        Parameters:
        backingImage - the destination backing image to fill with the clear color.
        x - the X coordinate of the rectangle's upper-left corner, in pixels.
        y - the Y coordinates of the rectangle's upper-left corner, in pixels.
        width - the rectangle's width, in pixels.
        height - the rectangle's height, in pixels.

      • drawImage

        protected void drawImage​(java.awt.image.BufferedImage backingImage,
                         java.awt.image.BufferedImage image,
                         int x,
                         int y,
                         boolean drawBorder)
        Draws the specified image in the backing image at the specified (x, y) location. If drawBorder is true, this copies the image's outer pixels into 1 pixel border surrounding the original image. This border avoids sampling pixels from neighboring atlas elements when an OpenGL box filter is applied to this image.
        Parameters:
        backingImage - the destination backing image to draw into.
        image - the source image to draw.
        x - the X coordinate of the image's upper-left corner, in pixels.
        y - the Y coordinates of the image's upper-left corner, in pixels.
        drawBorder - true this copy the image's outer pixels into 1 pixel border surrounding the original image, or false to draw only the image.

      • beginMoveEntries

        protected void beginMoveEntries​(java.awt.image.BufferedImage oldBackingImage,
                                java.awt.image.BufferedImage newBackingImage)
        Called when the atlas is performing a full re-layout of its elements, just before the layout begins. If this texture atlas' dimensions are changing, the specified backing images refer to separate instances with different dimensions. If this texture atlas is performing a re-layout in place, the specified backing images refer to the same instance.
        Parameters:
        oldBackingImage - the backing image corresponding to the previous layout.
        newBackingImage - the backing image corresponding to the new layout.

      • endMoveEntries

        protected void endMoveEntries​(java.awt.image.BufferedImage oldBackingImage,
                              java.awt.image.BufferedImage newBackingImage)
        Called when the atlas is performing a full re-layout of its elements, just after the layout ends. If this texture atlas' dimensions have changed, the specified backing images refer to separate instances with different dimensions. If this texture atlas has performed a re-layout in place, the specified backing images refer to the same instance.
        Parameters:
        oldBackingImage - the backing image corresponding to the previous layout.
        newBackingImage - the backing image corresponding to the new layout.

      • moveEntry

        protected void moveEntry​(java.awt.image.BufferedImage oldBackingImage,
                         com.jogamp.opengl.util.packrect.Rect oldRect,
                         java.awt.image.BufferedImage newBackingImage,
                         com.jogamp.opengl.util.packrect.Rect newRect)
        Called for each atlas element when the atlas is performing a full re-layout of its elements. If this texture atlas' dimensions are changing, the specified backing images refer to separate instances with different dimensions. If this texture atlas is performing a re-layout in place, the specified backing images refer to the same instance. In either case, the specified rectangles correspond to the element's location in the old backing image and new backing image.
        Parameters:
        oldBackingImage - the backing image corresponding to the previous layout.
        oldRect - the element's location in oldBackingImage.
        newBackingImage - the backing image corresponding to the new layout.
        newRect - the element's location in newBackingImage.

      • markUsed

        protected void markUsed​(TextureAtlas.Entry entry)
        Marks the specified entry as used by setting its last used time to the current time in nanoseconds.
        Parameters:
        entry - the entry who's last used time is marked.

      • removeLeastRecentlyUsedEntry

        protected boolean removeLeastRecentlyUsedEntry()
        Removes the oldest entry from this texture atlas. This does nothing if this texture atlas is empty.
        Returns:
        true if this removed an entry, and false if there are no entries to remove.

      • getDirtyRect

        protected java.awt.Rectangle getDirtyRect()
        Returns the region of this texture atlas' backing image that is not currently synchronized with the OpenGL texture.
        Returns:
        the region of this texture atlas that must be synchronized.

      • markDirty

        protected void markDirty​(int x,
                         int y,
                         int width,
                         int height)
        Marks a region of this texture atlas' backing image as needing to be synchronized with the OpenGL texture. If there is already a dirty region, the final dirty region is the union of the two.
        Parameters:
        x - the X coordinate of the region's upper-left corner, in pixels.
        y - the Y coordinate of the region's upper-left corner, in pixels.
        width - the region's width, in pixels.
        height - the region's height, in pixels.

      • clearDirtyRect

        protected void clearDirtyRect()
        Removes any regions in this texture atlas' backing image previously marked as needing to be synchronized with the OpenGL texture.

      • getTexture

        protected com.jogamp.opengl.util.texture.Texture getTexture​(DrawContext dc)
        Indicates the OpenGL Texture associated with this texture atlas.
        Parameters:
        dc - the current draw context.
        Returns:
        this instance's OpenGL texture, or null if the texture does not currently exist.

      • setTexture

        protected void setTexture​(DrawContext dc,
                          com.jogamp.opengl.util.texture.Texture texture)
        Specifies the OpenGL Texture associated with this texture atlas.
        Parameters:
        dc - the current draw context.
        texture - this instance's OpenGL texture, or null to specify that this texture atlas has no texture.

      • disposeOldTextures

        protected void disposeOldTextures​(DrawContext dc)
        Removes textures corresponding to this texture atlas' disposed backing images from the draw context's GPU resource cache. While disposed backing textures would eventually be evicted by the GPU resource cache, explicitly removing them avoids polluting the GPU resource cache with orphaned textures that are used only by this texture atlas.
        Parameters:
        dc - the draw context containing the GPU resource cache to remove textures from.

      • syncTexture

        protected com.jogamp.opengl.util.texture.Texture syncTexture​(DrawContext dc)
        Synchronizes this texture atlas's backing image with its OpenGL texture, creating an OpenGL texture as necessary. This attempts to minimize transfer between Java and OpenGL by loading the smallest possible portion of the backing image into the OpenGL texture.
        Parameters:
        dc - the current draw context.
        Returns:
        this texture atlas' OpenGL texture.

      • makeTextureWithBackingImage

        protected com.jogamp.opengl.util.texture.Texture makeTextureWithBackingImage​(DrawContext dc)
        Creates an OpenGL texture by loading this texture atlas's backing image into a new texture with the same dimensions.
        Parameters:
        dc - the current draw context.
        Returns:
        a new OpenGL texture containing the data from this texture atlas' backing image.

      • updateTextureWithSubImage

        protected com.jogamp.opengl.util.texture.Texture updateTextureWithSubImage​(DrawContext dc,
                                                                           java.awt.Rectangle rect)
        Loads a sub-region of this texture atlas' backing image into its OpenGL texture. This does nothing and returns code null if this texture atlas' does not have an OpenGL texture.
        Parameters:
        dc - the current draw context.
        rect - the rectangle to load.
        Returns:
        this texture atlas' OpenGL texture, or null if this texture atlas' does not have an OpenGL texture.

      • setTextureParameters

        protected void setTextureParameters​(DrawContext dc)
        Specifies the OpenGL texture parameters associated with this texture atlas' OpenGL texture. Called after updating this texture atlas' OpenGL texture, when the OpenGL texture is bound to the draw context's GLContext.
        Parameters:
        dc - the current draw context.