Class 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.
    GLOffscreenAutoDrawable are created lazily, see createOffscreenAutoDrawable(..).

    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 Detail

      • initSingleton

        public static final void initSingleton()
        Instantiate singleton factories if available, EGLES1, EGLES2 and the OS native ones.
      • setDisplayGamma

        public abstract boolean setDisplayGamma​(NativeSurface surface,
                                                float gamma,
                                                float brightness,
                                                float contrast)
                                         throws IllegalArgumentException
        Sets the gamma, brightness, and contrast of the display associated with the given surface.

        This functionality is not available on all platforms and graphics hardware. Returns true if the settings were successfully changed, false if not. This method may return false for some values of the incoming arguments even on hardware which does support the underlying functionality.

        If this method returns true, the display settings will automatically be reset to their original values upon JVM exit (assuming the JVM does not crash); if the user wishes to change the display settings back to normal ahead of time, use resetDisplayGamma(NativeSurface) or resetAllDisplayGamma().

        It is recommended to call resetDisplayGamma(NativeSurface) or resetAllDisplayGamma() before calling e.g. System.exit() from the application rather than rely on the shutdown hook functionality due to inevitable race conditions and unspecified behavior during JVM teardown.

        This method may be called multiple times during the application's execution, but calling resetDisplayGamma(NativeSurface) will only reset the settings to the values before the first call to this method.

        Parameters:
        surface - denominates the display device
        gamma - The gamma value, typically > 1.0 (default values vary, but typically roughly 1.0)
        brightness - The brightness value between -1.0 and 1.0, inclusive (default values vary, but typically 0)
        contrast - The contrast, greater than 0.0 (default values vary, but typically 1)
        Returns:
        true if gamma settings were successfully changed, false if not
        Throws:
        IllegalArgumentException - if any of the parameters were out-of-bounds
        See Also:
        resetDisplayGamma(NativeSurface), resetAllDisplayGamma()
      • resetDisplayGamma

        public abstract void resetDisplayGamma​(NativeSurface surface)
        Resets the gamma, brightness and contrast values of the display associated with the given surface to its original values before setDisplayGamma was called the first time.

        While it is not explicitly required that this method be called before exiting manually, calling it is recommended because of the inevitable unspecified behavior during JVM teardown.

      • resetAllDisplayGamma

        public abstract void resetAllDisplayGamma()
        Resets the gamma, brightness and contrast values of all modified displays to their original values before setDisplayGamma was called the first time.

        While it is not explicitly required that this method be called before exiting manually, calling it is recommended because of the inevitable unspecified behavior during JVM teardown.

      • 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.

        This method shall return the default device if available even if the GLDrawableFactory is not functional and hence not compatible. The latter situation may happen because no native OpenGL implementation is available for the specific implementation.

        Returns:
        the default shared device for this factory, eg. :0.0 on X11 desktop.
        See Also:
        getIsDeviceCompatible(AbstractGraphicsDevice)
      • 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 GLDrawable creation. Otherwise false. This implies validation whether the implementation is functional.
        See Also:
        getDefaultDevice()
      • hasOpenGLDesktopSupport

        public abstract boolean hasOpenGLDesktopSupport()
        Method returns true if underlying implementation may support native desktop OpenGL, otherwise false.
      • hasOpenGLESSupport

        public abstract boolean hasOpenGLESSupport()
        Method returns true if underlying implementation may support native embedded OpenGL ES, otherwise false.
      • 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.
      • createDummyDrawable

        public abstract GLDrawable createDummyDrawable​(AbstractGraphicsDevice deviceReq,
                                                       boolean createNewDevice,
                                                       GLCapabilitiesImmutable capsRequested,
                                                       GLCapabilitiesChooser chooser)
        Creates an unrealized dummy GLDrawable. A dummy drawable is not visible on screen and will not be used to render directly to, it maybe on- or offscreen.

        It is used to allow the creation of a GLContext to query information. It also allows creation of framebuffer objects which are used for rendering or creating a shared GLContext w/o actually rendering to this dummy drawable's framebuffer.

        Parameters:
        deviceReq - which connection denotes the shared device to be used, may be null for the platform's default device.
        createNewDevice - if true a new independent device instance is created from the deviceReq, otherwise deviceReq is used as-is and must be valid!
        capsRequested - the desired GLCapabilitiesImmutable, incl. it's GLProfile. For shared context, same visual ID or caps across shared drawables will yield best compatibility.
        chooser - the custom chooser, may be null for default
        Returns:
        the created unrealized dummy GLDrawable
      • canCreateGLPbuffer

        public abstract boolean canCreateGLPbuffer​(AbstractGraphicsDevice device,
                                                   GLProfile glp)
        Returns true if it is possible to create an pbuffer surface.

        Some older graphics cards do not have this capability, as well as some new GL implementation, i.e. OpenGL 3 core on OSX.

        Parameters:
        device - which connection denotes the shared the target device, may be null for the platform's default device.
        glp - GLProfile to check for FBO capabilities
      • 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(com.jogamp.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(com.jogamp.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.