com.sun.opengl.util.awt
Class TextureRenderer

java.lang.Object
  com.sun.opengl.util.awt.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

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

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(Color color) Changes the current color of this TextureRenderer to the supplied one.
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	setSize(Dimension d) Sets the size of the backing store of this renderer.
void	setSize(int width, int height) 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.

Methods inherited from class java.lang.Object

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

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.