Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `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 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. 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()` Creates a new GLDrawableFactory instance.

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 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(NativeWindow target)` Returns a GLDrawable that wraps a platform-specific window system object, such as an AWT or LCDUI Canvas.
`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(GLProfile glProfile)` Returns the sole GLDrawableFactory instance.
`protected static GLDrawableFactory` | `getFactoryImpl(String glProfileImplName)`
`void` | `shutdown()` Shuts down this GLDrawableFactory, releasing resources associated with it.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### GLDrawableFactory

    protected GLDrawableFactory()

  Creates a new GLDrawableFactory instance. End users do not need to call this method.

Method Detail

### 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`

### getFactoryImpl

    protected static GLDrawableFactory getFactoryImpl(String glProfileImplName)
                                               throws GLException

  Throws:
    `GLException`

### shutdown

    public void shutdown()

  Shuts down this GLDrawableFactory, releasing resources associated with it. Before calling this method you should first destroy any GLContexts and GLDrawables that have been created and are still in use. No further OpenGL calls may be made after shutting down the GLDrawableFactory.

### createGLDrawable

    public abstract GLDrawable createGLDrawable(NativeWindow target)
                                         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 pixel format, the NativeWindow's AbstractGraphicsConfiguration is being used. 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 null
    `GLException` - if any window system-specific errors caused the creation of the GLDrawable to fail.
  See Also:
    `GraphicsConfigurationFactory.chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)`

### 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 `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.

### 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 `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(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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2005 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.