javax.media.nativewindow

## Class NativeWindowFactory

- java.lang.Object
- - javax.media.nativewindow.NativeWindowFactory

-     public abstract class NativeWindowFactory
      extends Object

  Provides a pluggable mechanism for arbitrary window toolkits to adapt their components to the `NativeWindow` interface, which provides a platform-independent mechanism of accessing the information required to perform operations like hardware-accelerated rendering using the OpenGL API.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `TYPE_ANDROID` Android/EGL type, as retrieved with `getNativeWindowType(boolean)`.
    `static String` | `TYPE_AWT` Generic AWT type, as retrieved with `getNativeWindowType(boolean)`.
    `static String` | `TYPE_BCM_VC_IV` Broadcom VC IV/EGL type, as retrieved with `getNativeWindowType(boolean)`.
    `static String` | `TYPE_DEFAULT` Generic DEFAULT type, where platform implementation don't care, as retrieved with `getNativeWindowType(boolean)`.
    `static String` | `TYPE_EGL` OpenKODE/EGL type, as retrieved with `getNativeWindowType(boolean)`.
    `static String` | `TYPE_MACOSX` Mac OS X type, as retrieved with `getNativeWindowType(boolean)`.
    `static String` | `TYPE_WINDOWS` Microsoft Windows type, as retrieved with `getNativeWindowType(boolean)`.
    `static String` | `TYPE_X11` X11 type, as retrieved with `getNativeWindowType(boolean)`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `addCustomShutdownHook(boolean head, Runnable runnable)` Add a custom shutdown hook to be performed at JVM shutdown before shutting down NativeWindowFactory instance.
    `static AbstractGraphicsDevice` | `createDevice(String displayConnection, boolean own)` Creates a native device type, following `getNativeWindowType(true)`.
    `static AbstractGraphicsScreen` | `createScreen(AbstractGraphicsDevice device, int screen)`
    `static NativeWindow` | `createWrappedWindow(AbstractGraphicsScreen aScreen, long surfaceHandle, long windowHandle, com.jogamp.nativewindow.UpstreamWindowHookMutableSizePos hook)` Creates a wrapped `NativeWindow` with given native handles and `AbstractGraphicsScreen`.
    `static ToolkitLock` | `getAWTToolkitLock()` Returns the AWT `ToolkitLock` (JAWT based) if `isAWTAvailable`, otherwise null.
    `static NativeWindowFactory` | `getDefaultFactory()` Gets the default NativeWindowFactory.
    `static ToolkitLock` | `getDefaultToolkitLock()` Provides the system default `ToolkitLock` for the default system windowing type.
    `static ToolkitLock` | `getDefaultToolkitLock(String type)` Provides the default `ToolkitLock` for `type`.
    `static ToolkitLock` | `getDefaultToolkitLock(String type, long deviceHandle)` Provides the default `ToolkitLock` for `type` and `deviceHandle`.
    `static NativeWindowFactory` | `getFactory(Class<?> windowClass)` Returns the appropriate NativeWindowFactory to handle window objects of the given type.
    `static PointImmutable` | `getLocationOnScreen(NativeWindow nw)`
    `static NativeWindow` | `getNativeWindow(Object winObj, AbstractGraphicsConfiguration config)` Converts the given window object and it's `AbstractGraphicsConfiguration` into a `NativeWindow` which can be operated upon by a custom toolkit, e.g.
    `static String` | `getNativeWindowType(boolean useCustom)`
    `static ToolkitLock` | `getNullToolkitLock()`
    `static OffscreenLayerSurface` | `getOffscreenLayerSurface(NativeSurface surface, boolean ifEnabled)` Returns the `OffscreenLayerSurface` instance of this `NativeSurface`.
    `static void` | `initSingleton()` Static one time initialization of this factory. This initialization method must be called once by the program or utilizing modules!
    `static boolean` | `isAWTAvailable()`
    `static boolean` | `isInitialized()` Returns true if `initSingleton()` has been called w/o subsequent `shutdown(boolean)`.
    `static boolean` | `isJVMShuttingDown()` Returns true if the JVM is shutting down, otherwise false.
    `static boolean` | `isNativeVisualIDValidForProcessing(int visualID)` Returns true if the given visualID is valid for further processing, i.e.
    `static boolean` | `requiresToolkitLock()`
    `static void` | `setDefaultFactory(NativeWindowFactory factory)` Sets the default NativeWindowFactory.
    `static void` | `shutdown(boolean _isJVMShuttingDown)` Cleanup resources at JVM shutdown

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### TYPE_EGL

          public static final String TYPE_EGL

      OpenKODE/EGL type, as retrieved with `getNativeWindowType(boolean)`. String is canonical via `String.intern()`.

    - #### TYPE_WINDOWS

          public static final String TYPE_WINDOWS

      Microsoft Windows type, as retrieved with `getNativeWindowType(boolean)`. String is canonical via `String.intern()`.

    - #### TYPE_X11

          public static final String TYPE_X11

      X11 type, as retrieved with `getNativeWindowType(boolean)`. String is canonical via `String.intern()`.

    - #### TYPE_BCM_VC_IV

          public static final String TYPE_BCM_VC_IV

      Broadcom VC IV/EGL type, as retrieved with `getNativeWindowType(boolean)`. String is canonical via `String.intern()`.

    - #### TYPE_ANDROID

          public static final String TYPE_ANDROID

      Android/EGL type, as retrieved with `getNativeWindowType(boolean)`. String is canonical via `String.intern()`.

    - #### TYPE_MACOSX

          public static final String TYPE_MACOSX

      Mac OS X type, as retrieved with `getNativeWindowType(boolean)`. String is canonical via `String.intern()`.

    - #### TYPE_AWT

          public static final String TYPE_AWT

      Generic AWT type, as retrieved with `getNativeWindowType(boolean)`. String is canonical via `String.intern()`.

    - #### TYPE_DEFAULT

          public static final String TYPE_DEFAULT

      Generic DEFAULT type, where platform implementation don't care, as retrieved with `getNativeWindowType(boolean)`. String is canonical via `String.intern()`.

  - ### Method Detail

    - #### isJVMShuttingDown

          public static final boolean isJVMShuttingDown()

      Returns true if the JVM is shutting down, otherwise false.

    - #### addCustomShutdownHook

          public static void addCustomShutdownHook(boolean head,
                                   Runnable runnable)

      Add a custom shutdown hook to be performed at JVM shutdown before shutting down NativeWindowFactory instance.
      Parameters:
        `head` - if true add runnable at the start, otherwise at the end
        `runnable` - runnable to be added.

    - #### shutdown

          public static void shutdown(boolean _isJVMShuttingDown)

      Cleanup resources at JVM shutdown

    - #### isInitialized

          public static boolean isInitialized()

      Returns true if `initSingleton()` has been called w/o subsequent `shutdown(boolean)`.

    - #### initSingleton

          public static void initSingleton()

      Static one time initialization of this factory.
      This initialization method must be called once by the program or utilizing modules!

    - #### requiresToolkitLock

          public static boolean requiresToolkitLock()

      Returns:
        true if the underlying toolkit requires locking, otherwise false.

    - #### isAWTAvailable

          public static boolean isAWTAvailable()

      Returns:
        true if not headless, AWT Component and NativeWindow's AWT part available

    - #### getNativeWindowType

          public static String getNativeWindowType(boolean useCustom)

      Parameters:
        `useCustom` - if false return the native value, if true return a custom value if set, otherwise fallback to the native value.
      Returns:
        the native window type, e.g. `TYPE_X11`, which is canonical via `String.intern()`. Hence `String.equals(Object)` and `==` produce the same result.

    - #### setDefaultFactory

          public static void setDefaultFactory(NativeWindowFactory factory)

      Sets the default NativeWindowFactory.

    - #### getDefaultFactory

          public static NativeWindowFactory getDefaultFactory()

      Gets the default NativeWindowFactory.

    - #### getAWTToolkitLock

          public static ToolkitLock getAWTToolkitLock()

      Returns the AWT `ToolkitLock` (JAWT based) if `isAWTAvailable`, otherwise null.

      The JAWT based `ToolkitLock` also locks the global lock, which matters if the latter is required.

    - #### getNullToolkitLock

          public static ToolkitLock getNullToolkitLock()

    - #### getDefaultToolkitLock

          public static ToolkitLock getDefaultToolkitLock()

      Provides the system default `ToolkitLock` for the default system windowing type.
      See Also:
        `getNativeWindowType(boolean)`, `getDefaultToolkitLock(java.lang.String)`

    - #### getDefaultToolkitLock

          public static ToolkitLock getDefaultToolkitLock(String type)

      Provides the default `ToolkitLock` for `type`.
      - JAWT `ToolkitLock` if required and `type` is of `TYPE_AWT` and AWT available,
      - `ResourceToolkitLock` if required, otherwise
      - `NullToolkitLock`

    - #### getDefaultToolkitLock

          public static ToolkitLock getDefaultToolkitLock(String type,
                                          long deviceHandle)

      Provides the default `ToolkitLock` for `type` and `deviceHandle`.
      - JAWT `ToolkitLock` if required and `type` is of `TYPE_AWT` and AWT available,
      - `ResourceToolkitLock` if required, otherwise
      - `NullToolkitLock`

    - #### createScreen

          public static AbstractGraphicsScreen createScreen(AbstractGraphicsDevice device,
                                            int screen)

      Parameters:
        `device` -
        `screen` - -1 is default screen of the given device, e.g. maybe 0 or determined by native API. >= 0 is specific screen
      Returns:
        newly created AbstractGraphicsScreen matching device's native type

    - #### getFactory

          public static NativeWindowFactory getFactory(Class<?> windowClass)
                                                throws IllegalArgumentException

      Returns the appropriate NativeWindowFactory to handle window objects of the given type. The windowClass might be `NativeWindow`, in which case the client has already assumed the responsibility of creating a compatible NativeWindow implementation, or it might be that of a toolkit class like `Component`.
      Throws:
        `IllegalArgumentException`

    - #### getNativeWindow

          public static NativeWindow getNativeWindow(Object winObj,
                                     AbstractGraphicsConfiguration config)
                                              throws IllegalArgumentException,
                                                     NativeWindowException

      Converts the given window object and it's `AbstractGraphicsConfiguration` into a `NativeWindow` which can be operated upon by a custom toolkit, e.g. `javax.media.opengl.GLDrawableFactory`.
      The object may be a component for a particular window toolkit, such as an AWT Canvas. It may also be a NativeWindow object itself.
      You shall utilize `GraphicsConfigurationFactory` to construct a proper `AbstractGraphicsConfiguration`.
      The particular implementation of the NativeWindowFactory is responsible for handling objects from a particular window toolkit. The built-in NativeWindowFactory handles NativeWindow instances as well as AWT Components.
      Throws:
        `IllegalArgumentException` - if the given window object could not be handled by any of the registered NativeWindowFactory instances
        `NativeWindowException`
      See Also:
        `javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)`

    - #### getOffscreenLayerSurface

          public static OffscreenLayerSurface getOffscreenLayerSurface(NativeSurface surface,
                                                       boolean ifEnabled)

      Returns the `OffscreenLayerSurface` instance of this `NativeSurface`.

      In case this surface is a `NativeWindow`, we traverse from the given surface up to root until an implementation of `OffscreenLayerSurface` is found. In case `ifEnabled` is true, the surface must also implement `OffscreenLayerOption` where `OffscreenLayerOption.isOffscreenLayerSurfaceEnabled()` is `true`.

      Parameters:
        `surface` - The surface to query.
        `ifEnabled` - If true, only return the enabled `OffscreenLayerSurface`, see `OffscreenLayerOption.isOffscreenLayerSurfaceEnabled()`.
      Returns:

    - #### isNativeVisualIDValidForProcessing

          public static boolean isNativeVisualIDValidForProcessing(int visualID)

      Returns true if the given visualID is valid for further processing, i.e. OpenGL usage, otherwise return false.

      On certain platforms, i.e. X11, a valid visualID is required at window creation. Other platforms may determine it later on, e.g. OSX and Windows.

      If the visualID is `VisualIDHolder.VID_UNDEFINED` and the platform requires it at creation time (see above), it is not valid for further processing.

    - #### createDevice

          public static AbstractGraphicsDevice createDevice(String displayConnection,
                                            boolean own)

      Creates a native device type, following `getNativeWindowType(true)`.

      The device will be opened if `own` is true, otherwise no native handle will ever be acquired.

    - #### createWrappedWindow

          public static NativeWindow createWrappedWindow(AbstractGraphicsScreen aScreen,
                                         long surfaceHandle,
                                         long windowHandle,
                                         com.jogamp.nativewindow.UpstreamWindowHookMutableSizePos hook)

      Creates a wrapped `NativeWindow` with given native handles and `AbstractGraphicsScreen`.

      The given `UpstreamWindowHookMutableSizePos` maybe used to reflect resizes and repositioning of the native window.

      The `AbstractGraphicsScreen` may be created via `createScreen(AbstractGraphicsDevice, int)`.

      The `AbstractGraphicsScreen` may have an underlying open `AbstractGraphicsDevice` or a simple dummy instance, see `createDevice(String, boolean)`.

    - #### getLocationOnScreen

          public static PointImmutable getLocationOnScreen(NativeWindow nw)

      Parameters:
        `nw` -
      Returns:
        top-left client-area position in window units

Copyright 2010 JogAmp Community.