## com.sun.opengl.util.j2d
Class TextureRenderer

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

Copyright 2005 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.