Package gov.nasa.worldwind.util

Class OGLRenderToTextureSupport

  • public class OGLRenderToTextureSupport
extends java.lang.Object
    OGLRenderToTextureSupport encapsulates the pattern of rendering GL commands to a destination texture. Currently only the color pixel values are written to the destination texture, but other values (depth, stencil) should be possible with modification or extension.

    OGLRenderToTextureSupport is compatible with GL version 1.1 or greater, but it attempts to use more recent features whenever possible. Different GL feature sets result in different approaches to rendering to texture, therefore the caller cannot depend on the mechanism by which OGLRenderToTextureSupport will write pixel values to the destination texture. For this reason, OGLRenderToTextureSupport must be used when the contents of the windowing system buffer (likely the back framebuffer) can be freely modified by OGLRenderToTextureSupport. The WorldWind pre-render stage is a good example of when it is appropriate to use OGLRenderToTextureSupport. Fore more information on the pre-render stage, see PreRenderable and Layer.preRender(gov.nasa.worldwind.render.DrawContext). Note: In order to achieve consistent results across all platforms, it is essential to clear the texture's contents before rendering anything into the texture. Do this by invoking clear(gov.nasa.worldwind.render.DrawContext, java.awt.Color) immediately after any call to beginRendering(gov.nasa.worldwind.render.DrawContext, int, int, int, int).

    The common usage pattern for OGLRenderToTextureSupport is as follows:
    DrawContext dc = ...; // Typically passed in as an argument to the containing method.
    Texture texture = TextureIO.newTexture(new TextureData(...);

    // Setup the drawing rectangle to match the texture dimensions, and originate from the texture's lower left corner.
    OGLRenderToTextureSupport rttSupport = new OGLRenderToTextureSupport();
    rttSupport.beginRendering(dc, 0, 0, texture.getWidth(), texture.getHeight());
    try
    {
    // Bind the texture as the destination for color pixel writes.
    rttSupport.setColorTarget(dc, texture);
    // Clear the texture contents with transparent black.
    rttSupport.clear(dc, new Color(0, 0, 0, 0));
    // Invoke desired GL rendering commands.
    }
    finally
    {
    rttSupport.endRendering(dc);
    }

    • Field Detail

      • isFramebufferObjectEnabled

        protected boolean isFramebufferObjectEnabled

      • colorTarget

        protected com.jogamp.opengl.util.texture.Texture colorTarget

      • drawRegion

        protected java.awt.Rectangle drawRegion

      • framebufferObject

        protected int framebufferObject

    • Constructor Detail

      • OGLRenderToTextureSupport

        public OGLRenderToTextureSupport()
        Constructs a new OGLRenderToTextureSupport, but otherwise does nothing.

    • Method Detail

      • isEnableFramebufferObject

        public boolean isEnableFramebufferObject()
        Returns true if framebuffer objects are enabled for use (only applicable if the feature is available in the current GL runtime)
        Returns:
        true if framebuffer objects are enabled, and false otherwise.

      • setEnableFramebufferObject

        public void setEnableFramebufferObject​(boolean enable)
        Specifies if framebuffer objects should be used if they are available in the current GL runtime.
        Parameters:
        enable - true to enable framebuffer objects, false to disable them.

      • getColorTarget

        public com.jogamp.opengl.util.texture.Texture getColorTarget()
        Returns the texture currently set as the color buffer target, or null if no texture is currently bound as the color buffer target.
        Returns:
        the Texture currently set as the color buffer target, or null if none exists.

      • setColorTarget

        public void setColorTarget​(DrawContext dc,
                           com.jogamp.opengl.util.texture.Texture texture)
        Sets the specified texture as the color buffer target. This texture receives the output of all GL commands affecting the color buffer. Binding a null texture specifies that no texture should receive color values. If the current color target texture is the same reference as the specified texture, this does nothing. Otherwise this flushes any buffered pixel values to the current color target, and assigns the specified texture as the new color target.

        If isEnableFramebufferObject() is false, the supported texture formats for the color target are limited only by the OpenGL implementation's supported formats. If isEnableFramebufferObject() is true and the DrawContext supports OpenGL framebuffer objects, the supported texture formats for the color target are as follows:

        • RGB
        • RGBA
        • FLOAT_R_NV (on NVidia hardware)
        • FLOAT_RG_NV (on NVidia hardware)
        • FLOAT_RGB_NV (on NVidia hardware)
        • FLOAT_RGBA_NV (on NVidia hardware)
        Parameters:
        dc - the current DrawContext.
        texture - the Texture to use as the destination for GL commands affecting the color buffer. A null value is permitted.
        Throws:
        java.lang.IllegalArgumentException - if the DrawContext is null.

      • clear

        public void clear​(DrawContext dc,
                  java.awt.Color color)
        Clears the current texture target's pixels with the specified RGBA clear color. If the current color texture target is null, this does nothing.
        Parameters:
        dc - the current DrawContext.
        color - the RGBA clear color to write to the current color texture target.
        Throws:
        java.lang.IllegalArgumentException - if either the DrawContext or the color is null.

      • flush

        public void flush​(DrawContext dc)
        Flushes any buffered pixel values to the appropriate target textures.
        Parameters:
        dc - the current DrawContext.
        Throws:
        java.lang.IllegalArgumentException - if the DrawContext is null.

      • beginRendering

        public void beginRendering​(DrawContext dc,
                           int x,
                           int y,
                           int width,
                           int height)
        Configures the GL attached to the specified DrawContext for rendering a 2D model to a texture. The modelview matrix is set to the identity, the projection matrix is set to an orthographic projection aligned with the specified draw rectangle (x, y, width, height), the viewport and scissor boxes are set to the specified draw rectangle, and the depth test and depth write flags are disabled. Because the viewport and scissor boxes are set to the draw rectangle, only the texels intersecting the specified drawing rectangle (x, y, width, height) are affected by GL commands. Once rendering is complete, this should always be followed with a call to endRendering(gov.nasa.worldwind.render.DrawContext).
        Parameters:
        dc - the current DrawContext.
        x - the x-coordinate of the draw region's lower left corner.
        y - the y-coordinate of the draw region's lower left corner.
        width - the draw region width.
        height - the draw region height.
        Throws:
        java.lang.IllegalArgumentException - if the DrawContext is null.

      • endRendering

        public void endRendering​(DrawContext dc)
        Flushes any buffered pixel values to the appropriate texure targets, then restores the GL state to its previous configuration before beginRendering(gov.nasa.worldwind.render.DrawContext, int, int, int, int) was called. Finally, all texture targets associated with this OGLRenderToTextureSupport are unbound.
        Parameters:
        dc - the current DrawContext.
        Throws:
        java.lang.IllegalArgumentException - if the DrawContext is null.

      • flushColor

        protected void flushColor​(DrawContext dc)

      • copyScreenPixelsToTexture

        protected void copyScreenPixelsToTexture​(DrawContext dc,
                                         int x,
                                         int y,
                                         int width,
                                         int height,
                                         com.jogamp.opengl.util.texture.Texture texture)

      • updateMipmaps

        protected void updateMipmaps​(DrawContext dc,
                             com.jogamp.opengl.util.texture.Texture texture)

      • useFramebufferObject

        protected boolean useFramebufferObject​(DrawContext dc)

      • beginFramebufferObjectRendering

        protected void beginFramebufferObjectRendering​(DrawContext dc)

      • endFramebufferObjectRendering

        protected void endFramebufferObjectRendering​(DrawContext dc)

      • bindFramebufferColorAttachment

        protected void bindFramebufferColorAttachment​(DrawContext dc,
                                              com.jogamp.opengl.util.texture.Texture texture)

      • checkFramebufferStatus

        protected void checkFramebufferStatus​(DrawContext dc)

      • getFramebufferStatusString

        protected static java.lang.String getFramebufferStatusString​(int status)