JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
com.jogamp.opengl.util.awt.TextureRenderer Class Reference

Provides the ability to render into an OpenGL Texture using the Java 2D APIs. More...

Collaboration diagram for com.jogamp.opengl.util.awt.TextureRenderer:

Public Member Functions

 TextureRenderer (final int width, final int height, final boolean alpha)
 Creates a new renderer with backing store of the specified width and height. More...
 
 TextureRenderer (final int width, final int height, final boolean alpha, final boolean mipmap)
 Creates a new renderer with backing store of the specified width and height. More...
 
int getWidth ()
 Returns the width of the backing store of this renderer. More...
 
int getHeight ()
 Returns the height of the backing store of this renderer. More...
 
Dimension getSize ()
 Returns the size of the backing store of this renderer in a newly-allocated Dimension object. More...
 
Dimension getSize (Dimension d)
 Returns the size of the backing store of this renderer. More...
 
void setSize (final int width, final int height) throws GLException
 Sets the size of the backing store of this renderer. More...
 
void setSize (final Dimension d) throws GLException
 Sets the size of the backing store of this renderer. More...
 
void setSmoothing (final boolean smoothing)
 Sets whether smoothing is enabled for the OpenGL texture; if so, uses GL_LINEAR interpolation for the minification and magnification filters. More...
 
boolean getSmoothing ()
 Returns whether smoothing is enabled for the OpenGL texture; see setSmoothing. More...
 
Graphics2D createGraphics ()
 Creates a Graphics2D instance for rendering to the backing store of this renderer. More...
 
Image getImage ()
 Returns the underlying Java 2D Image being rendered into. More...
 
void markDirty (final int x, final int y, final int width, final int height)
 Marks the given region of the TextureRenderer as dirty. More...
 
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. More...
 
void dispose () throws GLException
 Disposes all resources associated with this renderer. More...
 
void beginOrthoRendering (final int width, final 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. More...
 
void beginOrthoRendering (final int width, final int height, final 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. More...
 
void begin3DRendering () throws GLException
 Convenience method which assists in rendering portions of the OpenGL texture to the screen as 2D quads in 3D space. More...
 
void setColor (final float r, final float g, final float b, final float a) throws GLException
 Changes the color of the polygons, and therefore the drawn images, this TextureRenderer produces. More...
 
void setColor (final Color color) throws GLException
 Changes the current color of this TextureRenderer to the supplied one. More...
 
void drawOrthoRect (final int screenx, final int screeny) throws GLException
 Draws an orthographically projected rectangle containing all of the underlying texture to the specified location on the screen. More...
 
void drawOrthoRect (final int screenx, final int screeny, final int texturex, final int texturey, final int width, final int height) throws GLException
 Draws an orthographically projected rectangle of the underlying texture to the specified location on the screen. More...
 
void draw3DRect (final float x, final float y, final float z, final int texturex, final int texturey, final int width, final int height, final float scaleFactor) throws GLException
 Draws a rectangle of the underlying texture to the specified 3D location. More...
 
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. More...
 
void end3DRendering () throws GLException
 Convenience method which assists in rendering portions of the OpenGL texture to the screen as 2D quads in 3D space. More...
 
boolean isUsingAutoMipmapGeneration ()
 Indicates whether automatic mipmap generation is in use for this TextureRenderer. More...
 

Static Public Member Functions

static TextureRenderer createAlphaOnlyRenderer (final int width, final int height)
 Creates a new renderer with a special kind of backing store which acts only as an alpha channel. More...
 
static TextureRenderer createAlphaOnlyRenderer (final int width, final int height, final boolean mipmap)
 Creates a new renderer with a special kind of backing store which acts only as an alpha channel. More...
 

Detailed Description

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.

Definition at line 65 of file TextureRenderer.java.

Constructor & Destructor Documentation

◆ TextureRenderer() [1/2]

com.jogamp.opengl.util.awt.TextureRenderer.TextureRenderer ( final int  width,
final int  height,
final 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
widththe width of the texture to render into
heightthe height of the texture to render into
alphawhether to allocate an alpha channel for the texture

Definition at line 114 of file TextureRenderer.java.

Here is the caller graph for this function:

◆ TextureRenderer() [2/2]

com.jogamp.opengl.util.awt.TextureRenderer.TextureRenderer ( final int  width,
final int  height,
final boolean  alpha,
final 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
widththe width of the texture to render into
heightthe height of the texture to render into
alphawhether to allocate an alpha channel for the texture
mipmapwhether to attempt use of automatic mipmap generation

Definition at line 129 of file TextureRenderer.java.

Member Function Documentation

◆ begin3DRendering()

void com.jogamp.opengl.util.awt.TextureRenderer.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.

Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 378 of file TextureRenderer.java.

◆ beginOrthoRendering() [1/2]

void com.jogamp.opengl.util.awt.TextureRenderer.beginOrthoRendering ( final int  width,
final 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
widththe width of the current on-screen OpenGL drawable
heightthe height of the current on-screen OpenGL drawable
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 339 of file TextureRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ beginOrthoRendering() [2/2]

void com.jogamp.opengl.util.awt.TextureRenderer.beginOrthoRendering ( final int  width,
final int  height,
final 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
widththe width of the current on-screen OpenGL drawable
heightthe height of the current on-screen OpenGL drawable
disableDepthTestwhether the depth test should be disabled
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 361 of file TextureRenderer.java.

◆ createAlphaOnlyRenderer() [1/2]

static TextureRenderer com.jogamp.opengl.util.awt.TextureRenderer.createAlphaOnlyRenderer ( final int  width,
final int  height 
)
static

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.

Definition at line 146 of file TextureRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ createAlphaOnlyRenderer() [2/2]

static TextureRenderer com.jogamp.opengl.util.awt.TextureRenderer.createAlphaOnlyRenderer ( final int  width,
final int  height,
final boolean  mipmap 
)
static

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.

Definition at line 156 of file TextureRenderer.java.

Here is the call graph for this function:

◆ createGraphics()

Graphics2D com.jogamp.opengl.util.awt.TextureRenderer.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

Definition at line 257 of file TextureRenderer.java.

Here is the caller graph for this function:

◆ dispose()

void com.jogamp.opengl.util.awt.TextureRenderer.dispose ( ) throws GLException

Disposes all resources associated with this renderer.

It is not valid to use this renderer after calling this method.

Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 311 of file TextureRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ draw3DRect()

void com.jogamp.opengl.util.awt.TextureRenderer.draw3DRect ( final float  x,
final float  y,
final float  z,
final int  texturex,
final int  texturey,
final int  width,
final int  height,
final 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
xthe x coordinate at which to draw the rectangle
ythe y coordinate at which to draw the rectangle
zthe z coordinate at which to draw the rectangle
texturexthe x coordinate of the pixel in the texture of the lower left portion of the rectangle to draw
textureythe y coordinate of the pixel in the texture (relative to lower left) of the lower left portion of the rectangle to draw
widththe width in texels of the rectangle to draw
heightthe height in texels of the rectangle to draw
scaleFactorthe scale factor to apply (multiplicatively) to the size of the drawn rectangle
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 499 of file TextureRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ drawOrthoRect() [1/2]

void com.jogamp.opengl.util.awt.TextureRenderer.drawOrthoRect ( final int  screenx,
final 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
screenxthe on-screen x coordinate at which to draw the rectangle
screenythe on-screen y coordinate (relative to lower left) at which to draw the rectangle
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 446 of file TextureRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ drawOrthoRect() [2/2]

void com.jogamp.opengl.util.awt.TextureRenderer.drawOrthoRect ( final int  screenx,
final int  screeny,
final int  texturex,
final int  texturey,
final int  width,
final 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
screenxthe on-screen x coordinate at which to draw the rectangle
screenythe on-screen y coordinate (relative to lower left) at which to draw the rectangle
texturexthe x coordinate of the pixel in the texture of the lower left portion of the rectangle to draw
textureythe y coordinate of the pixel in the texture (relative to lower left) of the lower left portion of the rectangle to draw
widththe width of the rectangle to draw
heightthe height of the rectangle to draw
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 468 of file TextureRenderer.java.

Here is the call graph for this function:

◆ end3DRendering()

void com.jogamp.opengl.util.awt.TextureRenderer.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.

Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 539 of file TextureRenderer.java.

◆ endOrthoRendering()

void com.jogamp.opengl.util.awt.TextureRenderer.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 is used to set up the rendering stage for this overlay.

Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 528 of file TextureRenderer.java.

Here is the caller graph for this function:

◆ getHeight()

int com.jogamp.opengl.util.awt.TextureRenderer.getHeight ( )

Returns the height of the backing store of this renderer.

Returns
the height of the backing store of this renderer

Definition at line 172 of file TextureRenderer.java.

Here is the caller graph for this function:

◆ getImage()

Image com.jogamp.opengl.util.awt.TextureRenderer.getImage ( )

Returns the underlying Java 2D Image being rendered into.

Definition at line 263 of file TextureRenderer.java.

◆ getSize() [1/2]

Dimension com.jogamp.opengl.util.awt.TextureRenderer.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

Definition at line 181 of file TextureRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ getSize() [2/2]

Dimension com.jogamp.opengl.util.awt.TextureRenderer.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
da 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

Definition at line 194 of file TextureRenderer.java.

◆ getSmoothing()

boolean com.jogamp.opengl.util.awt.TextureRenderer.getSmoothing ( )

Returns whether smoothing is enabled for the OpenGL texture; see setSmoothing.

Defaults to true.

Returns
whether smoothing is enabled for the OpenGL texture

Definition at line 244 of file TextureRenderer.java.

◆ getTexture()

Texture com.jogamp.opengl.util.awt.TextureRenderer.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.

Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 296 of file TextureRenderer.java.

Here is the caller graph for this function:

◆ getWidth()

int com.jogamp.opengl.util.awt.TextureRenderer.getWidth ( )

Returns the width of the backing store of this renderer.

Returns
the width of the backing store of this renderer

Definition at line 164 of file TextureRenderer.java.

Here is the caller graph for this function:

◆ isUsingAutoMipmapGeneration()

boolean com.jogamp.opengl.util.awt.TextureRenderer.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.

Definition at line 548 of file TextureRenderer.java.

◆ markDirty()

void com.jogamp.opengl.util.awt.TextureRenderer.markDirty ( final int  x,
final int  y,
final int  width,
final 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
xthe x coordinate (in Java 2D coordinates – relative to upper left) of the region to update
ythe y coordinate (in Java 2D coordinates – relative to upper left) of the region to update
widththe width of the region to update
heightthe height of the region to update

Definition at line 281 of file TextureRenderer.java.

Here is the caller graph for this function:

◆ setColor() [1/2]

void com.jogamp.opengl.util.awt.TextureRenderer.setColor ( final 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
colorthe new color to use for rendering
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 423 of file TextureRenderer.java.

Here is the call graph for this function:

◆ setColor() [2/2]

void com.jogamp.opengl.util.awt.TextureRenderer.setColor ( final float  r,
final float  g,
final float  b,
final 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
rthe red component of the new color
gthe green component of the new color
bthe blue component of the new color
athe alpha component of the new color, 0.0f = completely transparent, 1.0f = completely opaque
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 405 of file TextureRenderer.java.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setSize() [1/2]

void com.jogamp.opengl.util.awt.TextureRenderer.setSize ( final 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
dthe new size of the backing store of this renderer
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 222 of file TextureRenderer.java.

Here is the call graph for this function:

◆ setSize() [2/2]

void com.jogamp.opengl.util.awt.TextureRenderer.setSize ( final int  width,
final 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
widththe new width of the backing store of this renderer
heightthe new height of the backing store of this renderer
Exceptions
GLExceptionIf an OpenGL context is not current when this method is called

Definition at line 211 of file TextureRenderer.java.

Here is the caller graph for this function:

◆ setSmoothing()

void com.jogamp.opengl.util.awt.TextureRenderer.setSmoothing ( final 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
smoothingwhether smoothing is enabled for the OpenGL texture

Definition at line 234 of file TextureRenderer.java.

Here is the caller graph for this function:

The documentation for this class was generated from the following file: