APIdia Launch Partner
Top Description Fields Constructors Methods
sun.java2d.opengl

pack-priv Class OGLUtilities

extends Object
Class Inheritance
Imports
java.awt.Graphics, .GraphicsConfiguration, .Rectangle, sun.java2d.SunGraphics2D, .SurfaceData, sun.java2d.pipe.Region
This class contains a number of static utility methods that may be called (via reflection) by a third-party library, such as JOGL, in order to interoperate with the OGL-based Java 2D pipeline.

Warning

These methods are being made available as a temporary measure until we offer a more complete, public solution. Like any sun.* class, this class is not an officially supported public API; it may be modified at will or removed completely in a future release.

Field Summary

Modifier and TypeField and Description
public static final int
FBOBJECT

public static final int
FLIP_BACKBUFFER

public static final int
TEXTURE

public static final int
UNDEFINED

These OGL-specific surface type constants are the same as those defined in the OGLSurfaceData class and are duplicated here so that clients of this API can access them more easily via reflection.

public static final int
WINDOW

Constructor Summary

AccessConstructor and Description
private
OGLUtilities()

Method Summary

Modifier and TypeMethod and Description
public static Rectangle

Returns:

a Rectangle describing the OpenGL scissor box for the given Graphics object and corresponding destination surface, or null if the given Graphics object is invalid or the clip region is non-rectangular
getOGLScissorBox(Graphics
the Graphics object for the corresponding destination surface; cannot be null
g)

Returns the Rectangle describing the OpenGL scissor box on the Java 2D surface associated with the given Graphics object.

public static Object

Returns:

an identifier for the surface associated with the given Graphics object, or null if the given Graphics object is invalid
getOGLSurfaceIdentifier(Graphics
the Graphics object for the corresponding destination surface; cannot be null
g)

Returns an Object identifier for the Java 2D surface associated with the given Graphics object.

public static int

Returns:

a constant that describes the surface associated with the given Graphics object; if the given Graphics object is invalid (i.e. is not associated with an OpenGL surface) this method will return OGLUtilities.UNDEFINED
getOGLSurfaceType(Graphics
the Graphics object for the corresponding destination surface; cannot be null
g)

Returns one of the OGL-specific surface type constants (defined in this class), which describes the surface associated with the given Graphics object.

public static int

Returns:

the texture target constant for the surface associated with the given Graphics object; if the given Graphics object is invalid (i.e. is not associated with an OpenGL surface), or the associated surface is not backed by an OpenGL texture, this method will return zero.
getOGLTextureType(Graphics
the Graphics object for the corresponding destination surface; cannot be null
g)

Returns the OpenGL texture target constant (either GL_TEXTURE_2D or GL_TEXTURE_RECTANGLE_ARB) for the surface associated with the given Graphics object.

public static Rectangle

Returns:

a Rectangle describing the OpenGL viewport for the given destination surface and component dimensions, or null if the given Graphics object is invalid
getOGLViewport(Graphics
the Graphics object for the corresponding destination surface; cannot be null
g, int
width of the component to be painted
componentWidth, int
height of the component to be painted
componentHeight)

Returns the Rectangle describing the OpenGL viewport on the Java 2D surface associated with the given Graphics object and component width and height.

public static boolean

Returns:

true if the operation completed successfully, or false if there was any problem making a context current to the surface associated with the given Graphics object
invokeWithOGLContextCurrent(Graphics
the Graphics object for the corresponding destination surface; if null, the step making a context current to the destination surface will be skipped
g, Runnable
the action to be performed on the QFT; cannot be null
r)

Invokes the given Runnable on the OGL QueueFlusher thread with the OpenGL context corresponding to the given Graphics object made current.

public static boolean

Returns:

true if the operation completed successfully, or false if there was any problem making the shared context current
invokeWithOGLSharedContextCurrent(GraphicsConfiguration
the GraphicsConfiguration object whose "shared" context will be made current during this operation; if this value is null or if OpenGL is not enabled for the GraphicsConfiguration, this method will return false
config, Runnable
the action to be performed on the QFT; cannot be null
r)

Invokes the given Runnable on the OGL QueueFlusher thread with the "shared" OpenGL context (corresponding to the given GraphicsConfiguration object) made current.

public static boolean
isQueueFlusherThread()

Returns true if the current thread is the OGL QueueFlusher thread.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

FBOBJECTback to summary
public static final int FBOBJECT
FLIP_BACKBUFFERback to summary
public static final int FLIP_BACKBUFFER
TEXTUREback to summary
public static final int TEXTURE
UNDEFINEDback to summary
public static final int UNDEFINED

These OGL-specific surface type constants are the same as those defined in the OGLSurfaceData class and are duplicated here so that clients of this API can access them more easily via reflection.

WINDOWback to summary
public static final int WINDOW

Constructor Detail

OGLUtilitiesback to summary
private OGLUtilities()

Method Detail

getOGLScissorBoxback to summary
public static Rectangle getOGLScissorBox(Graphics g)

Returns the Rectangle describing the OpenGL scissor box on the Java 2D surface associated with the given Graphics object. When a third-party library is performing OpenGL rendering directly into the visible region of the associated surface, this scissor box must be set to avoid drawing over existing rendering results. Note that the x/y values in the returned Rectangle object represent the lower-left corner of the scissor region, relative to the lower-left corner of the given surface.

Parameters
g:Graphics

the Graphics object for the corresponding destination surface; cannot be null

Returns:Rectangle

a Rectangle describing the OpenGL scissor box for the given Graphics object and corresponding destination surface, or null if the given Graphics object is invalid or the clip region is non-rectangular

getOGLSurfaceIdentifierback to summary
public static Object getOGLSurfaceIdentifier(Graphics g)

Returns an Object identifier for the Java 2D surface associated with the given Graphics object. This identifier may be used to determine whether the surface has changed since the last invocation of this operation, and thereby whether the OpenGL state corresponding to the old surface must be destroyed and recreated.

Parameters
g:Graphics

the Graphics object for the corresponding destination surface; cannot be null

Returns:Object

an identifier for the surface associated with the given Graphics object, or null if the given Graphics object is invalid

getOGLSurfaceTypeback to summary
public static int getOGLSurfaceType(Graphics g)

Returns one of the OGL-specific surface type constants (defined in this class), which describes the surface associated with the given Graphics object.

Parameters
g:Graphics

the Graphics object for the corresponding destination surface; cannot be null

Returns:int

a constant that describes the surface associated with the given Graphics object; if the given Graphics object is invalid (i.e. is not associated with an OpenGL surface) this method will return OGLUtilities.UNDEFINED

getOGLTextureTypeback to summary
public static int getOGLTextureType(Graphics g)

Returns the OpenGL texture target constant (either GL_TEXTURE_2D or GL_TEXTURE_RECTANGLE_ARB) for the surface associated with the given Graphics object. This method is only useful for those surface types that are backed by an OpenGL texture, namely TEXTURE, FBOBJECT, and (on Windows only) PBUFFER.

Parameters
g:Graphics

the Graphics object for the corresponding destination surface; cannot be null

Returns:int

the texture target constant for the surface associated with the given Graphics object; if the given Graphics object is invalid (i.e. is not associated with an OpenGL surface), or the associated surface is not backed by an OpenGL texture, this method will return zero.

getOGLViewportback to summary
public static Rectangle getOGLViewport(Graphics g, int componentWidth, int componentHeight)

Returns the Rectangle describing the OpenGL viewport on the Java 2D surface associated with the given Graphics object and component width and height. When a third-party library is performing OpenGL rendering directly into the visible region of the associated surface, this viewport helps the application position the OpenGL output correctly on that surface. Note that the x/y values in the returned Rectangle object represent the lower-left corner of the viewport region, relative to the lower-left corner of the given surface.

Parameters
g:Graphics

the Graphics object for the corresponding destination surface; cannot be null

componentWidth:int

width of the component to be painted

componentHeight:int

height of the component to be painted

Returns:Rectangle

a Rectangle describing the OpenGL viewport for the given destination surface and component dimensions, or null if the given Graphics object is invalid

invokeWithOGLContextCurrentback to summary
public static boolean invokeWithOGLContextCurrent(Graphics g, Runnable r)

Invokes the given Runnable on the OGL QueueFlusher thread with the OpenGL context corresponding to the given Graphics object made current. It is legal for OpenGL code executed in the given Runnable to change the current OpenGL context; it will be reset once the Runnable completes. No guarantees are made as to the state of the OpenGL context of the Graphics object; for example, calling code must set the scissor box using the return value from getOGLScissorBox to avoid drawing over other Swing components, and must typically set the OpenGL viewport using the return value from getOGLViewport to make the client's OpenGL rendering appear in the correct place relative to the scissor region. In order to avoid deadlock, it is important that the given Runnable does not attempt to acquire the AWT lock, as that will be handled automatically as part of the rq.flushAndInvokeNow() step.

Parameters
g:Graphics

the Graphics object for the corresponding destination surface; if null, the step making a context current to the destination surface will be skipped

r:Runnable

the action to be performed on the QFT; cannot be null

Returns:boolean

true if the operation completed successfully, or false if there was any problem making a context current to the surface associated with the given Graphics object

invokeWithOGLSharedContextCurrentback to summary
public static boolean invokeWithOGLSharedContextCurrent(GraphicsConfiguration config, Runnable r)

Invokes the given Runnable on the OGL QueueFlusher thread with the "shared" OpenGL context (corresponding to the given GraphicsConfiguration object) made current. This method is typically used when the Runnable needs a current context to complete its operation, but does not require that the context be made current to a particular surface. For example, an application may call this method so that the given Runnable can query the OpenGL capabilities of the given GraphicsConfiguration, without making a context current to a dummy surface (or similar hacky techniques). In order to avoid deadlock, it is important that the given Runnable does not attempt to acquire the AWT lock, as that will be handled automatically as part of the rq.flushAndInvokeNow() step.

Parameters
config:GraphicsConfiguration

the GraphicsConfiguration object whose "shared" context will be made current during this operation; if this value is null or if OpenGL is not enabled for the GraphicsConfiguration, this method will return false

r:Runnable

the action to be performed on the QFT; cannot be null

Returns:boolean

true if the operation completed successfully, or false if there was any problem making the shared context current

isQueueFlusherThreadback to summary
public static boolean isQueueFlusherThread()

Returns true if the current thread is the OGL QueueFlusher thread.