javax.media.opengl
Class GLDrawableFactory

java.lang.Object
  javax.media.opengl.GLDrawableFactory

public abstract class GLDrawableFactory

extends Object

Provides a virtual machine- and operating system-independent mechanism for creating GLDrawables.

The GLCapabilities objects passed in to the various factory methods are used as a hint for the properties of the returned drawable. The default capabilities selection algorithm (equivalent to passing in a null GLCapabilitiesChooser) is described in DefaultGLCapabilitiesChooser. Sophisticated applications needing to change the selection algorithm may pass in their own GLCapabilitiesChooser which can select from the available pixel formats. The GLCapabilitiesChooser mechanism may not be supported by all implementations or on all platforms, in which case any passed GLCapabilitiesChooser will be ignored.

Because of the multithreaded nature of the Java platform's window system toolkit, it is typically not possible to immediately reject a given GLCapabilities as being unsupportable by either returning null from the creation routines or raising a GLException. The semantics of the rejection process are (unfortunately) left unspecified for now. The current implementation will cause a GLException to be raised during the first repaint of the GLCanvas or GLJPanel if the capabilities can not be met. Pbuffers are always created immediately and their creation will fail with a GLException if errors occur.

The concrete GLDrawableFactory subclass instantiated by getFactory can be changed by setting the system property opengl.factory.class.name to the fully-qualified name of the desired class.

Constructor Summary

protected

GLDrawableFactory()

Method Summary

abstract boolean	canCreateExternalGLDrawable() Returns true if it is possible to create an external GLDrawable object via createExternalGLDrawable().
abstract boolean	canCreateGLPbuffer() Returns true if it is possible to create a GLPbuffer.
abstract AbstractGraphicsConfiguration	chooseGraphicsConfiguration(GLCapabilities capabilities, GLCapabilitiesChooser chooser, AbstractGraphicsDevice device) Selects a graphics configuration on the specified graphics device compatible with the supplied GLCapabilities.
abstract GLContext	createExternalGLContext() Creates a GLContext object representing an existing OpenGL context in an external (third-party) OpenGL-based library.
abstract GLDrawable	createExternalGLDrawable() Creates a GLDrawable object representing an existing OpenGL drawable in an external (third-party) OpenGL-based library.
abstract GLPbuffer	createGLPbuffer(GLCapabilities capabilities, GLCapabilitiesChooser chooser, int initialWidth, int initialHeight, GLContext shareWith) Creates a GLPbuffer with the given capabilites and dimensions.
static GLDrawableFactory	getFactory() Returns the sole GLDrawableFactory instance.
abstract GLDrawable	getGLDrawable(Object target, GLCapabilities capabilities, GLCapabilitiesChooser chooser) Returns a GLDrawable that wraps a platform-specific window system object, such as an AWT or LCDUI Canvas.

Methods inherited from class java.lang.Object

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

Constructor Detail

GLDrawableFactory

protected GLDrawableFactory()

Method Detail

getFactory

public static GLDrawableFactory getFactory()

Returns the sole GLDrawableFactory instance.

chooseGraphicsConfiguration

public abstract AbstractGraphicsConfiguration chooseGraphicsConfiguration(GLCapabilities capabilities,
                                                                          GLCapabilitiesChooser chooser,
                                                                          AbstractGraphicsDevice device)
                                                                   throws IllegalArgumentException,
                                                                          GLException

Selects a graphics configuration on the specified graphics device compatible with the supplied GLCapabilities. This method is intended to be used by applications which do not use the supplied GLCanvas class but instead wrap their own Canvas or other window toolkit-specific object with a GLDrawable. Some platforms (specifically X11) require the graphics configuration to be specified when the window toolkit object is created. This method may return null on platforms on which the OpenGL pixel format selection process is performed later.

The concrete data type of the passed graphics device and returned graphics configuration must be specified in the documentation binding this particular API to the underlying window toolkit. The Reference Implementation accepts AWTGraphicsDevice objects and returns AWTGraphicsConfiguration objects.

Throws:

IllegalArgumentException - if the data type of the passed AbstractGraphicsDevice is not supported by this GLDrawableFactory.

GLException - if any window system-specific errors caused the selection of the graphics configuration to fail.

See Also:

Canvas.Canvas(java.awt.GraphicsConfiguration)

getGLDrawable

public abstract GLDrawable getGLDrawable(Object target,
                                         GLCapabilities capabilities,
                                         GLCapabilitiesChooser chooser)
                                  throws IllegalArgumentException,
                                         GLException

Returns a GLDrawable that wraps a platform-specific window system object, such as an AWT or LCDUI Canvas. On platforms which support it, selects a pixel format compatible with the supplied GLCapabilities, or if the passed GLCapabilities object is null, uses a default set of capabilities. On these platforms, uses either the supplied GLCapabilitiesChooser object, or if the passed GLCapabilitiesChooser object is null, uses a DefaultGLCapabilitiesChooser instance.

Throws:

IllegalArgumentException - if the passed target is either null or its data type is not supported by this GLDrawableFactory.

GLException - if any window system-specific errors caused the creation of the GLDrawable to fail.

canCreateGLPbuffer

public abstract boolean canCreateGLPbuffer()

Returns true if it is possible to create a GLPbuffer. Some older graphics cards do not have this capability.

createGLPbuffer

public abstract GLPbuffer createGLPbuffer(GLCapabilities capabilities,
                                          GLCapabilitiesChooser chooser,
                                          int initialWidth,
                                          int initialHeight,
                                          GLContext shareWith)
                                   throws GLException

Creates a GLPbuffer with the given capabilites and dimensions.

See the note in the overview documentation on context sharing.

Throws:

GLException - if any window system-specific errors caused the creation of the GLPbuffer to fail.

createExternalGLContext

public abstract GLContext createExternalGLContext()
                                           throws GLException

Creates a GLContext object representing an existing OpenGL context in an external (third-party) OpenGL-based library. This GLContext object may be used to draw into this preexisting context using its GL and GLU objects. New contexts created through GLDrawables may share textures and display lists with this external context.

The underlying OpenGL context must be current on the current thread at the time this method is called. The user is responsible for the maintenance of the underlying OpenGL context; calls to makeCurrent and release on the returned GLContext object have no effect. If the underlying OpenGL context is destroyed, the destroy method should be called on the GLContext. A new GLContext object should be created for each newly-created underlying OpenGL context.

Throws:

GLException - if any window system-specific errors caused the creation of the external GLContext to fail.

canCreateExternalGLDrawable

public abstract boolean canCreateExternalGLDrawable()

Returns true if it is possible to create an external GLDrawable object via createExternalGLDrawable().

createExternalGLDrawable

public abstract GLDrawable createExternalGLDrawable()
                                             throws GLException

Creates a GLDrawable object representing an existing OpenGL drawable in an external (third-party) OpenGL-based library. This GLDrawable object may be used to create new, fully-functional GLContexts on the OpenGL drawable. This is useful when interoperating with a third-party OpenGL-based library and it is essential to not perturb the state of the library's existing context, even to the point of not sharing textures or display lists with that context.

An underlying OpenGL context must be current on the desired drawable and the current thread at the time this method is called. The user is responsible for the maintenance of the underlying drawable. If one or more contexts are created on the drawable using GLDrawable.createContext(javax.media.opengl.GLContext), and the drawable is deleted by the third-party library, the user is responsible for calling GLContext.destroy() on these contexts.

Calls to setSize, getWidth and getHeight are illegal on the returned GLDrawable. If these operations are required by the user, they must be performed by the third-party library.

It is legal to create both an external GLContext and GLDrawable representing the same third-party OpenGL entities. This can be used, for example, to query current state information using the external GLContext and then create and set up new GLContexts using the external GLDrawable.

This functionality may not be available on all platforms and canCreateExternalGLDrawable() should be called first to see if it is present. For example, on X11 platforms, this API requires the presence of GLX 1.3 or later.

Throws:

GLException - if any window system-specific errors caused the creation of the external GLDrawable to fail.