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 Abstract Window 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.
GLPbuffer 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.

Method Summary

abstract boolean	canCreateExternalGLDrawable(AbstractGraphicsDevice device) Returns true if it is possible to create an external GLDrawable object via createExternalGLDrawable().
abstract boolean	canCreateGLPbuffer(AbstractGraphicsDevice device) Returns true if it is possible to create a GLPbuffer.
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 GLDrawable	createGLDrawable(NativeSurface target) Returns a GLDrawable according to it's chosen Capabilities, which determines pixel format, on- and offscreen incl.
abstract GLPbuffer	createGLPbuffer(AbstractGraphicsDevice device, GLCapabilitiesImmutable capabilities, GLCapabilitiesChooser chooser, int initialWidth, int initialHeight, GLContext shareWith) Creates a GLPbuffer with the given capabilites and dimensions.
abstract GLDrawable	createOffscreenDrawable(AbstractGraphicsDevice device, GLCapabilitiesImmutable capabilities, GLCapabilitiesChooser chooser, int width, int height) Creates a Offscreen GLDrawable incl it's offscreen NativeSurface with the given capabilites and dimensions.
abstract NativeSurface	createOffscreenSurface(AbstractGraphicsDevice device, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser, int width, int height) Creates an offscreen NativeSurface. A Pbuffer surface is created if both caps.isPBuffer() and canCreateGLPbuffer(device) is true. Otherwise a simple pixmap/bitmap surface is created.
abstract ProxySurface	createProxySurface(AbstractGraphicsDevice device, long windowHandle, GLCapabilitiesImmutable caps, GLCapabilitiesChooser chooser) Highly experimental API entry, allowing developer of new windowing system bindings to leverage the native window handle to produce a NativeSurface implementation (ProxySurface), having the required GLCapabilities. Such surface can be used to instantiate a GLDrawable and hence test your new binding w/o the costs of providing a full set of abstraction like the AWT GLCanvas or even the native NEWT bindings.
List<GLCapabilitiesImmutable>	getAvailableCapabilities(AbstractGraphicsDevice device) Returns an array of available GLCapabilities for the device. The list is sorted by the native ID, ascending. The chosen GLProfile statement in the result may not refer to the maximum available profile due to implementation constraints, ie using the shared resource.
abstract AbstractGraphicsDevice	getDefaultDevice() Retrieve the default device connection, unit ID and unique ID name.
static GLDrawableFactory	getDesktopFactory() Returns the sole GLDrawableFactory instance for the desktop (X11, WGL, ..) if exist or null
static GLDrawableFactory	getEGLFactory() Returns the sole GLDrawableFactory instance for EGL if exist or null
static GLDrawableFactory	getFactory(GLProfile glProfile) Returns the sole GLDrawableFactory instance.
abstract boolean	getIsDeviceCompatible(AbstractGraphicsDevice device)
GLContext	getOrCreateSharedContext(AbstractGraphicsDevice device) Returns the shared context mapped to the device AbstractGraphicsDevice.getConnection(), either a pre-existing or newly created, or null if creation failed or not supported. Creation of the shared context is tried only once.
abstract boolean	getWasSharedContextCreated(AbstractGraphicsDevice device) Returns true if a shared context could be created while initialization of shared resources for device AbstractGraphicsDevice.getConnection(). This does not imply a shared context is mapped, but was available .

Methods inherited from class java.lang.Object

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

Method Detail

getDefaultDevice

public abstract AbstractGraphicsDevice getDefaultDevice()

Retrieve the default device connection, unit ID and unique ID name. for this factory
The implementation must return a non null default device, which must not be opened, ie. it's native handle is null.

Returns:

the default shared device for this factory, eg. :0.0 on X11 desktop.

getIsDeviceCompatible

public abstract boolean getIsDeviceCompatible(AbstractGraphicsDevice device)

Parameters:

device - which connection denotes the shared the target device, may be null for the platform's default device.

Returns:

true if the device is compatible with this factory, ie. if it can be used for creation. Otherwise false.

getWasSharedContextCreated

public abstract boolean getWasSharedContextCreated(AbstractGraphicsDevice device)

Returns true if a shared context could be created while initialization of shared resources for device AbstractGraphicsDevice.getConnection().
This does not imply a shared context is mapped, but was available
.

Parameters:

device - which connection denotes the shared the target device, may be null for the platform's default device.

getOrCreateSharedContext

public final GLContext getOrCreateSharedContext(AbstractGraphicsDevice device)

Returns the shared context mapped to the device AbstractGraphicsDevice.getConnection(), either a pre-existing or newly created, or null if creation failed or not supported.
Creation of the shared context is tried only once.

Parameters:

device - which connection denotes the shared the target device, may be null for the platform's default device.

getDesktopFactory

public static GLDrawableFactory getDesktopFactory()

Returns the sole GLDrawableFactory instance for the desktop (X11, WGL, ..) if exist or null

getEGLFactory

public static GLDrawableFactory getEGLFactory()

Returns the sole GLDrawableFactory instance for EGL if exist or null

getFactory

public static GLDrawableFactory getFactory(GLProfile glProfile)
                                    throws GLException

Returns the sole GLDrawableFactory instance.

Parameters:

glProfile - GLProfile to determine the factory type, ie EGLDrawableFactory, or one of the native GLDrawableFactory's, ie X11/GLX, Windows/WGL or MacOSX/CGL.

Throws:

GLException

getAvailableCapabilities

public final List<GLCapabilitiesImmutable> getAvailableCapabilities(AbstractGraphicsDevice device)

Returns an array of available GLCapabilities for the device.
The list is sorted by the native ID, ascending.
The chosen GLProfile statement in the result may not refer to the maximum available profile due to implementation constraints, ie using the shared resource.

Parameters:

device - which connection denotes the shared the target device, may be null for the platform's default device.

Returns:

A list of GLCapabilitiesImmutable's, maybe empty if none is available.

createGLDrawable

public abstract GLDrawable createGLDrawable(NativeSurface target)
                                     throws IllegalArgumentException,
                                            GLException

Returns a GLDrawable according to it's chosen Capabilities,
which determines pixel format, on- and offscreen incl. PBuffer type.

The native platform's chosen Capabilties are referenced within the target NativeSurface's AbstractGraphicsConfiguration.

In case target's Capabilities.isOnscreen() is true,
an onscreen GLDrawable will be realized.

In case target's Capabilities.isOnscreen() is false,
either a Pbuffer drawable is created if target's GLCapabilities.isPBuffer() is true,
or a simple pixmap/bitmap drawable is created. The latter is unlikely to be hardware accelerated.

Throws:

IllegalArgumentException - if the passed target is null

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

See Also:

javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)

createOffscreenDrawable

public abstract GLDrawable createOffscreenDrawable(AbstractGraphicsDevice device,
                                                   GLCapabilitiesImmutable capabilities,
                                                   GLCapabilitiesChooser chooser,
                                                   int width,
                                                   int height)
                                            throws GLException

Creates a Offscreen GLDrawable incl it's offscreen NativeSurface with the given capabilites and dimensions.

A Pbuffer drawable/surface is created if both caps.isPBuffer() and canCreateGLPbuffer(device) is true.
Otherwise a simple pixmap/bitmap drawable/surface is created, which is unlikely to be hardware accelerated.

Parameters:

device - which connection denotes the shared device to be used, may be null for the platform's default device.

caps - the requested GLCapabilties

chooser - the custom chooser, may be null for default

width - the requested offscreen width

height - the requested offscreen height

Returns:

the created offscreen GLDrawable

Throws:

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

createOffscreenSurface

public abstract NativeSurface createOffscreenSurface(AbstractGraphicsDevice device,
                                                     GLCapabilitiesImmutable caps,
                                                     GLCapabilitiesChooser chooser,
                                                     int width,
                                                     int height)

Creates an offscreen NativeSurface.
A Pbuffer surface is created if both caps.isPBuffer() and canCreateGLPbuffer(device) is true.
Otherwise a simple pixmap/bitmap surface is created. The latter is unlikely to be hardware accelerated.

Parameters:

device - which connection denotes the shared the target device, may be null for the platform's default device.

caps - the requested GLCapabilties

chooser - the custom chooser, may be null for default

width - the requested offscreen width

height - the requested offscreen height

Returns:

the created offscreen native surface

Throws:

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

createProxySurface

public abstract ProxySurface createProxySurface(AbstractGraphicsDevice device,
                                                long windowHandle,
                                                GLCapabilitiesImmutable caps,
                                                GLCapabilitiesChooser chooser)

Highly experimental API entry, allowing developer of new windowing system bindings to leverage the native window handle to produce a NativeSurface implementation (ProxySurface), having the required GLCapabilities.
Such surface can be used to instantiate a GLDrawable and hence test your new binding w/o the costs of providing a full set of abstraction like the AWT GLCanvas or even the native NEWT bindings.

Parameters:

device - the platform's target device, shall not be null

windowHandle - the native window handle

caps - the requested GLCapabilties

chooser - the custom chooser, may be null for default

Returns:

The proxy surface wrapping the windowHandle on the device

canCreateGLPbuffer

public abstract boolean canCreateGLPbuffer(AbstractGraphicsDevice device)

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

Parameters:

device - which connection denotes the shared the target device, may be null for the platform's default device.

createGLPbuffer

public abstract GLPbuffer createGLPbuffer(AbstractGraphicsDevice device,
                                          GLCapabilitiesImmutable 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.

Parameters:

device - which connection denotes the shared the target device, may be null for the platform's default device.

capabilities - the requested capabilities

chooser - the custom chooser, may be null for default

initialWidth - initial width of pbuffer

initialHeight - initial height of pbuffer

shareWith - a shared GLContext this GLPbuffer shall use

Returns:

the new GLPbuffer specific GLAutoDrawable

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(AbstractGraphicsDevice device)

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

Parameters:

device - which connection denotes the shared the target device, may be null for the platform's default device.

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(javax.media.nativewindow.AbstractGraphicsDevice) 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.