Provides a virtual machine- and operating system-independent mechanism for creating {@link GLDrawable}s.
The {@link javax.media.opengl.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 {@link GLCapabilitiesChooser}) is described in {@link DefaultGLCapabilitiesChooser}. Sophisticated applications needing to change the selection algorithm may pass in their own {@link 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 {@link GLCapabilities} as being unsupportable by
either returning null from the creation routines or
raising a {@link GLException}. The semantics of the rejection
process are (unfortunately) left unspecified for now. The current
implementation will cause a {@link GLException} to be raised
during the first repaint of the {@link GLCanvas} or {@link
GLJPanel} if the capabilities can not be met. Pbuffers are always
created immediately and their creation will fail with a {@link
GLException} if errors occur.
The concrete GLDrawableFactory subclass instantiated by {@link
#getFactory getFactory} can be changed by setting the system
property opengl.factory.class.name to the
fully-qualified name of the desired class.
* The native platform's chosen Capabilties are referenced within the target * NativeSurface's AbstractGraphicsConfiguration.
*
* In case {@link javax.media.nativewindow.Capabilities#isOnscreen()} is true,
* an onscreen GLDrawable will be realized.
*
* In case {@link javax.media.nativewindow.Capabilities#isOnscreen()} is false,
* either a Pbuffer drawable is created if {@link javax.media.opengl.GLCapabilities#isPBuffer()} is true,
* or a simple offscreen drawable is creates. The latter is unlikely to be hardware accelerated.
*
* * @throws IllegalArgumentException if the passed target is null * @throws GLException if any window system-specific errors caused * the creation of the GLDrawable to fail. * * @see javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen) */ public abstract GLDrawable createGLDrawable(NativeSurface target) throws IllegalArgumentException, GLException; /** * Creates a Offscreen GLDrawable with the given capabilites and dimensions.
* * @throws GLException if any window system-specific errors caused * the creation of the Offscreen to fail. */ public abstract GLDrawable createOffscreenDrawable(GLCapabilities capabilities, GLCapabilitiesChooser chooser, int width, int height) throws GLException; /** * Returns true if it is possible to create a GLPbuffer. Some older * graphics cards do not have this capability. * @param passing the device for the query, may be null */ public abstract boolean canCreateGLPbuffer(AbstractGraphicsDevice device); /** * Creates a Pbuffer GLDrawable with the given capabilites and dimensions.
* * @throws GLException if any window system-specific errors caused * the creation of the GLPbuffer to fail. */ public abstract GLDrawable createGLPbufferDrawable(GLCapabilities capabilities, GLCapabilitiesChooser chooser, int initialWidth, int initialHeight) 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. */ public abstract GLPbuffer createGLPbuffer(GLCapabilities capabilities, GLCapabilitiesChooser chooser, int initialWidth, int initialHeight, GLContext shareWith) throws GLException; //---------------------------------------------------------------------- // Methods for interacting with third-party OpenGL libraries /** *
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 {@link GL} and {@link * javax.media.opengl.glu.GLU} objects. New contexts created through * {@link 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.
*
* @throws GLException if any window system-specific errors caused
* the creation of the external GLContext to fail.
*/
public abstract GLContext createExternalGLContext()
throws GLException;
/**
* Returns true if it is possible to create an external GLDrawable
* object via {@link #createExternalGLDrawable}.
* @param passing the device for the query, may be null
*/
public abstract boolean canCreateExternalGLDrawable(AbstractGraphicsDevice device);
/**
*
Creates a {@link 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 {@link 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 {@link GLDrawable#createContext}, and the drawable * is deleted by the third-party library, the user is responsible * for calling {@link 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 * {@link #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. */ public abstract GLDrawable createExternalGLDrawable() throws GLException; }