javax.media.opengl
Class GLDrawableFactory
public abstract class GLDrawableFactory
Provides a virtual machine- and operating system-independent
mechanism for creating
GLDrawable
s.
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.
GLDrawableFactory
protected GLDrawableFactory()
canCreateExternalGLDrawable
public abstract boolean canCreateExternalGLDrawable()
canCreateGLPbuffer
public abstract boolean canCreateGLPbuffer()
Returns true if it is possible to create a GLPbuffer. Some older
graphics cards do not have this capability.
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.
GLException
- if any window system-specific errors caused
the selection of the graphics configuration 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
GLDrawable
s 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.
GLException
- if any window system-specific errors caused
the creation of the external GLContext to fail.
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
GLContext
s 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(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.
GLException
- if any window system-specific errors caused
the creation of the external GLDrawable to fail.
getFactory
public static GLDrawableFactory getFactory()
Returns the sole GLDrawableFactory instance.
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.
GLException
- if any window system-specific errors caused
the creation of the GLDrawable to fail.
Copyright 2005 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.