gov.nasa.worldwind.util

Class OGLRenderToTextureSupport

java.lang.Object

gov.nasa.worldwind.util.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 Summary

Fields

Modifier and Type	Field and Description
protected Texture	colorTarget
protected java.awt.Rectangle	drawRegion
protected int	framebufferObject
protected boolean	isFramebufferObjectEnabled
protected OGLStackHandler	stackHandler

Constructor Summary

Constructors

Constructor and Description
OGLRenderToTextureSupport() Constructs a new OGLRenderToTextureSupport, but otherwise does nothing.

Method Summary

Modifier and Type	Method and Description
protected void	beginFramebufferObjectRendering(DrawContext dc)
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.
protected void	bindFramebufferColorAttachment(DrawContext dc, Texture texture)
protected void	checkFramebufferStatus(DrawContext dc)
void	clear(DrawContext dc, java.awt.Color color) Clears the current texture target's pixels with the specified RGBA clear color.
protected void	copyScreenPixelsToTexture(DrawContext dc, int x, int y, int width, int height, Texture texture)
protected void	endFramebufferObjectRendering(DrawContext dc)
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.
void	flush(DrawContext dc) Flushes any buffered pixel values to the appropriate target textures.
protected void	flushColor(DrawContext dc)
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.
protected static java.lang.String	getFramebufferStatusString(int status)
boolean	isEnableFramebufferObject() Returns true if framebuffer objects are enabled for use (only applicable if the feature is available in the current GL runtime)
void	setColorTarget(DrawContext dc, Texture texture) Sets the specified texture as the color buffer target.
void	setEnableFramebufferObject(boolean enable) Specifies if framebuffer objects should be used if they are available in the current GL runtime.
protected void	updateMipmaps(DrawContext dc, Texture texture)
protected boolean	useFramebufferObject(DrawContext dc)

Methods inherited from class java.lang.Object

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

Field Detail

colorTarget

protected Texture colorTarget

drawRegion

protected java.awt.Rectangle drawRegion

framebufferObject

protected int framebufferObject

isFramebufferObjectEnabled

protected boolean isFramebufferObjectEnabled

stackHandler

protected OGLStackHandler stackHandler

Constructor Detail

OGLRenderToTextureSupport

public OGLRenderToTextureSupport()

Constructs a new OGLRenderToTextureSupport, but otherwise does nothing.

Method Detail

beginFramebufferObjectRendering

protected void beginFramebufferObjectRendering(DrawContext dc)

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.

bindFramebufferColorAttachment

protected void bindFramebufferColorAttachment(DrawContext dc,
                                              Texture texture)

checkFramebufferStatus

protected void checkFramebufferStatus(DrawContext dc)

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.

copyScreenPixelsToTexture

protected void copyScreenPixelsToTexture(DrawContext dc,
                                         int x,
                                         int y,
                                         int width,
                                         int height,
                                         Texture texture)

endFramebufferObjectRendering

protected void endFramebufferObjectRendering(DrawContext dc)

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.

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.

flushColor

protected void flushColor(DrawContext dc)

getColorTarget

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

getFramebufferStatusString

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

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.

setColorTarget

public void setColorTarget(DrawContext dc,
                           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.

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.

updateMipmaps

protected void updateMipmaps(DrawContext dc,
                             Texture texture)

useFramebufferObject

protected boolean useFramebufferObject(DrawContext dc)