Package com.jogamp.opengl.util.awt

Class TextureRenderer

  • public class TextureRenderer
extends Object
    Provides the ability to render into an OpenGL Texture using the Java 2D APIs. This renderer class uses an internal Java 2D image (of unspecified type) for its backing store and flushes portions of that image to an OpenGL texture on demand. The resulting OpenGL texture can then be mapped on to a polygon for display.

    • Constructor Summary

      Constructors 
      Constructor Description
      TextureRenderer​(int width, int height, boolean alpha)
      Creates a new renderer with backing store of the specified width and height.
      TextureRenderer​(int width, int height, boolean alpha, boolean mipmap)
      Creates a new renderer with backing store of the specified width and height.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void begin3DRendering()
      Convenience method which assists in rendering portions of the OpenGL texture to the screen as 2D quads in 3D space.
      void beginOrthoRendering​(int width, int height)
      Convenience method which assists in rendering portions of the OpenGL texture to the screen, if the application intends to draw them as a flat overlay on to the screen.
      void beginOrthoRendering​(int width, int height, boolean disableDepthTest)
      Convenience method which assists in rendering portions of the OpenGL texture to the screen, if the application intends to draw them as a flat overlay on to the screen.
      static TextureRenderer createAlphaOnlyRenderer​(int width, int height)
      Creates a new renderer with a special kind of backing store which acts only as an alpha channel.
      static TextureRenderer createAlphaOnlyRenderer​(int width, int height, boolean mipmap)
      Creates a new renderer with a special kind of backing store which acts only as an alpha channel.
      Graphics2D createGraphics()
      Creates a Graphics2D instance for rendering to the backing store of this renderer.
      void dispose()
      Disposes all resources associated with this renderer.
      void draw3DRect​(float x, float y, float z, int texturex, int texturey, int width, int height, float scaleFactor)
      Draws a rectangle of the underlying texture to the specified 3D location.
      void drawOrthoRect​(int screenx, int screeny)
      Draws an orthographically projected rectangle containing all of the underlying texture to the specified location on the screen.
      void drawOrthoRect​(int screenx, int screeny, int texturex, int texturey, int width, int height)
      Draws an orthographically projected rectangle of the underlying texture to the specified location on the screen.
      void end3DRendering()
      Convenience method which assists in rendering portions of the OpenGL texture to the screen as 2D quads in 3D space.
      void endOrthoRendering()
      Convenience method which assists in rendering portions of the OpenGL texture to the screen, if the application intends to draw them as a flat overlay on to the screen.
      int getHeight()
      Returns the height of the backing store of this renderer.
      Image getImage()
      Returns the underlying Java 2D Image being rendered into.
      Dimension getSize()
      Returns the size of the backing store of this renderer in a newly-allocated Dimension object.
      Dimension getSize​(Dimension d)
      Returns the size of the backing store of this renderer.
      boolean getSmoothing()
      Returns whether smoothing is enabled for the OpenGL texture; see setSmoothing.
      Texture getTexture()
      Returns the underlying OpenGL Texture object associated with this renderer, synchronizing any dirty regions of the TextureRenderer with the underlying OpenGL texture.
      int getWidth()
      Returns the width of the backing store of this renderer.
      boolean isUsingAutoMipmapGeneration()
      Indicates whether automatic mipmap generation is in use for this TextureRenderer.
      void markDirty​(int x, int y, int width, int height)
      Marks the given region of the TextureRenderer as dirty.
      void setColor​(float r, float g, float b, float a)
      Changes the color of the polygons, and therefore the drawn images, this TextureRenderer produces.
      void setColor​(Color color)
      Changes the current color of this TextureRenderer to the supplied one.
      void setSize​(int width, int height)
      Sets the size of the backing store of this renderer.
      void setSize​(Dimension d)
      Sets the size of the backing store of this renderer.
      void setSmoothing​(boolean smoothing)
      Sets whether smoothing is enabled for the OpenGL texture; if so, uses GL_LINEAR interpolation for the minification and magnification filters.

    • Constructor Detail

      • TextureRenderer

        public TextureRenderer​(int width,
                       int height,
                       boolean alpha)
        Creates a new renderer with backing store of the specified width and height. If alpha is true, allocates an alpha channel in the backing store image. No mipmap support is requested.
        Parameters:
        width - the width of the texture to render into
        height - the height of the texture to render into
        alpha - whether to allocate an alpha channel for the texture

      • TextureRenderer

        public TextureRenderer​(int width,
                       int height,
                       boolean alpha,
                       boolean mipmap)
        Creates a new renderer with backing store of the specified width and height. If alpha is true, allocates an alpha channel in the backing store image. If mipmap is true, attempts to use OpenGL's automatic mipmap generation for better smoothing when rendering the TextureRenderer's contents at a distance.
        Parameters:
        width - the width of the texture to render into
        height - the height of the texture to render into
        alpha - whether to allocate an alpha channel for the texture
        mipmap - whether to attempt use of automatic mipmap generation

    • Method Detail

      • createAlphaOnlyRenderer

        public static TextureRenderer createAlphaOnlyRenderer​(int width,
                                                      int height)
        Creates a new renderer with a special kind of backing store which acts only as an alpha channel. No mipmap support is requested. Internally, this associates a GL_INTENSITY OpenGL texture with the backing store.

      • createAlphaOnlyRenderer

        public static TextureRenderer createAlphaOnlyRenderer​(int width,
                                                      int height,
                                                      boolean mipmap)
        Creates a new renderer with a special kind of backing store which acts only as an alpha channel. If mipmap is true, attempts to use OpenGL's automatic mipmap generation for better smoothing when rendering the TextureRenderer's contents at a distance. Internally, this associates a GL_INTENSITY OpenGL texture with the backing store.

      • getWidth

        public int getWidth()
        Returns the width of the backing store of this renderer.
        Returns:
        the width of the backing store of this renderer

      • getHeight

        public int getHeight()
        Returns the height of the backing store of this renderer.
        Returns:
        the height of the backing store of this renderer

      • getSize

        public Dimension getSize()
        Returns the size of the backing store of this renderer in a newly-allocated Dimension object.
        Returns:
        the size of the backing store of this renderer

      • getSize

        public Dimension getSize​(Dimension d)
        Returns the size of the backing store of this renderer. Uses the Dimension object if one is supplied, or allocates a new one if null is passed.
        Parameters:
        d - a Dimension object in which to store the results, or null to allocate a new one
        Returns:
        the size of the backing store of this renderer

      • setSize

        public void setSize​(int width,
                    int height)
             throws GLException
        Sets the size of the backing store of this renderer. This may cause the OpenGL texture object associated with this renderer to be invalidated; it is not recommended to cache this texture object outside this class but to instead call getTexture when it is needed.
        Parameters:
        width - the new width of the backing store of this renderer
        height - the new height of the backing store of this renderer
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • setSize

        public void setSize​(Dimension d)
             throws GLException
        Sets the size of the backing store of this renderer. This may cause the OpenGL texture object associated with this renderer to be invalidated.
        Parameters:
        d - the new size of the backing store of this renderer
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • setSmoothing

        public void setSmoothing​(boolean smoothing)
        Sets whether smoothing is enabled for the OpenGL texture; if so, uses GL_LINEAR interpolation for the minification and magnification filters. Defaults to true. Changes to this setting will not take effect until the next call to beginOrthoRendering.
        Parameters:
        smoothing - whether smoothing is enabled for the OpenGL texture

      • getSmoothing

        public boolean getSmoothing()
        Returns whether smoothing is enabled for the OpenGL texture; see setSmoothing. Defaults to true.
        Returns:
        whether smoothing is enabled for the OpenGL texture

      • createGraphics

        public Graphics2D createGraphics()
        Creates a Graphics2D instance for rendering to the backing store of this renderer. The returned object should be disposed of using the normal Graphics.dispose() method once it is no longer being used.
        Returns:
        a new Graphics2D object for rendering into the backing store of this renderer

      • getImage

        public Image getImage()
        Returns the underlying Java 2D Image being rendered into.

      • markDirty

        public void markDirty​(int x,
                      int y,
                      int width,
                      int height)
        Marks the given region of the TextureRenderer as dirty. This region, and any previously set dirty regions, will be automatically synchronized with the underlying Texture during the next getTexture operation, at which point the dirty region will be cleared. It is not necessary for an OpenGL context to be current when this method is called.
        Parameters:
        x - the x coordinate (in Java 2D coordinates -- relative to upper left) of the region to update
        y - the y coordinate (in Java 2D coordinates -- relative to upper left) of the region to update
        width - the width of the region to update
        height - the height of the region to update

      • getTexture

        public Texture getTexture()
                   throws GLException
        Returns the underlying OpenGL Texture object associated with this renderer, synchronizing any dirty regions of the TextureRenderer with the underlying OpenGL texture.
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • dispose

        public void dispose()
             throws GLException
        Disposes all resources associated with this renderer. It is not valid to use this renderer after calling this method.
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • beginOrthoRendering

        public void beginOrthoRendering​(int width,
                                int height)
                         throws GLException
        Convenience method which assists in rendering portions of the OpenGL texture to the screen, if the application intends to draw them as a flat overlay on to the screen. Pushes OpenGL state bits (GL_ENABLE_BIT, GL_DEPTH_BUFFER_BIT and GL_TRANSFORM_BIT); disables the depth test, back-face culling, and lighting; enables the texture in this renderer; and sets up the viewing matrices for orthographic rendering where the coordinates go from (0, 0) at the lower left to (width, height) at the upper right. Equivalent to beginOrthoRendering(width, height, true). endOrthoRendering() must be used in conjunction with this method to restore all OpenGL states.
        Parameters:
        width - the width of the current on-screen OpenGL drawable
        height - the height of the current on-screen OpenGL drawable
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • beginOrthoRendering

        public void beginOrthoRendering​(int width,
                                int height,
                                boolean disableDepthTest)
                         throws GLException
        Convenience method which assists in rendering portions of the OpenGL texture to the screen, if the application intends to draw them as a flat overlay on to the screen. Pushes OpenGL state bits (GL_ENABLE_BIT, GL_DEPTH_BUFFER_BIT and GL_TRANSFORM_BIT); disables the depth test (if the "disableDepthTest" argument is true), back-face culling, and lighting; enables the texture in this renderer; and sets up the viewing matrices for orthographic rendering where the coordinates go from (0, 0) at the lower left to (width, height) at the upper right. endOrthoRendering() must be used in conjunction with this method to restore all OpenGL states.
        Parameters:
        width - the width of the current on-screen OpenGL drawable
        height - the height of the current on-screen OpenGL drawable
        disableDepthTest - whether the depth test should be disabled
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • begin3DRendering

        public void begin3DRendering()
                      throws GLException
        Convenience method which assists in rendering portions of the OpenGL texture to the screen as 2D quads in 3D space. Pushes OpenGL state (GL_ENABLE_BIT); disables lighting; and enables the texture in this renderer. Unlike beginOrthoRendering, does not modify the depth test, back-face culling, lighting, or the modelview or projection matrices. The user is responsible for setting up the view matrices for correct results of draw3DRect. end3DRendering() must be used in conjunction with this method to restore all OpenGL states.
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • setColor

        public void setColor​(float r,
                     float g,
                     float b,
                     float a)
              throws GLException
        Changes the color of the polygons, and therefore the drawn images, this TextureRenderer produces. Use of this method is optional. The TextureRenderer uses the GL_MODULATE texture environment mode, which causes the portions of the rendered texture to be multiplied by the color of the rendered polygons. The polygon color can be varied to achieve effects like tinting of the overall output or fading in and out by changing the alpha of the color.

        Each component ranges from 0.0f - 1.0f. The alpha component, if used, does not need to be premultiplied into the color channels as described in the documentation for Texture, although premultiplied colors are used internally. The default color is opaque white.

        Parameters:
        r - the red component of the new color
        g - the green component of the new color
        b - the blue component of the new color
        a - the alpha component of the new color, 0.0f = completely transparent, 1.0f = completely opaque
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • setColor

        public void setColor​(Color color)
              throws GLException
        Changes the current color of this TextureRenderer to the supplied one. The default color is opaque white. See setColor for more details.
        Parameters:
        color - the new color to use for rendering
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • drawOrthoRect

        public void drawOrthoRect​(int screenx,
                          int screeny)
                   throws GLException
        Draws an orthographically projected rectangle containing all of the underlying texture to the specified location on the screen. All (x, y) coordinates are specified relative to the lower left corner of either the texture image or the current OpenGL drawable. This method is equivalent to drawOrthoRect(screenx, screeny, 0, 0, getWidth(), getHeight());.
        Parameters:
        screenx - the on-screen x coordinate at which to draw the rectangle
        screeny - the on-screen y coordinate (relative to lower left) at which to draw the rectangle
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • drawOrthoRect

        public void drawOrthoRect​(int screenx,
                          int screeny,
                          int texturex,
                          int texturey,
                          int width,
                          int height)
                   throws GLException
        Draws an orthographically projected rectangle of the underlying texture to the specified location on the screen. All (x, y) coordinates are specified relative to the lower left corner of either the texture image or the current OpenGL drawable.
        Parameters:
        screenx - the on-screen x coordinate at which to draw the rectangle
        screeny - the on-screen y coordinate (relative to lower left) at which to draw the rectangle
        texturex - the x coordinate of the pixel in the texture of the lower left portion of the rectangle to draw
        texturey - the y coordinate of the pixel in the texture (relative to lower left) of the lower left portion of the rectangle to draw
        width - the width of the rectangle to draw
        height - the height of the rectangle to draw
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • draw3DRect

        public void draw3DRect​(float x,
                       float y,
                       float z,
                       int texturex,
                       int texturey,
                       int width,
                       int height,
                       float scaleFactor)
                throws GLException
        Draws a rectangle of the underlying texture to the specified 3D location. In the current coordinate system, the lower left corner of the rectangle is placed at (x, y, z), and the upper right corner is placed at (x + width * scaleFactor, y + height * scaleFactor, z). The lower left corner of the sub-rectangle of the texture is (texturex, texturey) and the upper right corner is (texturex + width, texturey + height). For back-face culling purposes, the rectangle is drawn with counterclockwise orientation of the vertices when viewed from the front.
        Parameters:
        x - the x coordinate at which to draw the rectangle
        y - the y coordinate at which to draw the rectangle
        z - the z coordinate at which to draw the rectangle
        texturex - the x coordinate of the pixel in the texture of the lower left portion of the rectangle to draw
        texturey - the y coordinate of the pixel in the texture (relative to lower left) of the lower left portion of the rectangle to draw
        width - the width in texels of the rectangle to draw
        height - the height in texels of the rectangle to draw
        scaleFactor - the scale factor to apply (multiplicatively) to the size of the drawn rectangle
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • endOrthoRendering

        public void endOrthoRendering()
                       throws GLException
        Convenience method which assists in rendering portions of the OpenGL texture to the screen, if the application intends to draw them as a flat overlay on to the screen. Must be used if beginOrthoRendering(int, int) is used to set up the rendering stage for this overlay.
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • end3DRendering

        public void end3DRendering()
                    throws GLException
        Convenience method which assists in rendering portions of the OpenGL texture to the screen as 2D quads in 3D space. Must be used if begin3DRendering() is used to set up the rendering stage for this overlay.
        Throws:
        GLException - If an OpenGL context is not current when this method is called

      • isUsingAutoMipmapGeneration

        public boolean isUsingAutoMipmapGeneration()
        Indicates whether automatic mipmap generation is in use for this TextureRenderer. The result of this method may change from true to false if it is discovered during allocation of the TextureRenderer's backing store that automatic mipmap generation is not supported at the OpenGL level.