NativeWindowFactory (NativeWindow API -- 2.3 Specification)

java.lang.Object
- com.jogamp.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.
FIXME: Bug 973 Needs service provider interface (SPI) for TK dependent implementation

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 AbstractGraphicsDevice`	`createDevice(String nwt, String displayConnection, boolean own)` Creates a native device type, following the given `native-window-type`.
`static AbstractGraphicsScreen`	`createScreen(AbstractGraphicsDevice device, int screen)`
`static NativeWindow`	`createWrappedWindow(AbstractGraphicsScreen aScreen, long surfaceHandle, long windowHandle, 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. com.jogamp.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:
    com.jogamp.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.
    
    FIXME: Bug 973 Needs service provider interface (SPI) for TK dependent implementation
  - 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.
  - createDevice
```
public static AbstractGraphicsDevice createDevice(String nwt,
                                  String displayConnection,
                                  boolean own)
```
    Creates a native device type, following the given native-window-type.
    The device will be opened if own is true, otherwise no native handle will ever be acquired.
    
    FIXME: Bug 973 Needs service provider interface (SPI) for TK dependent implementation
  - createWrappedWindow
```
public static NativeWindow createWrappedWindow(AbstractGraphicsScreen aScreen,
                               long surfaceHandle,
                               long windowHandle,
                               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
    FIXME: Bug 973 Needs service provider interface (SPI) for TK dependent implementation

Class NativeWindowFactory

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

TYPE_EGL

TYPE_WINDOWS

TYPE_X11

TYPE_BCM_VC_IV

TYPE_ANDROID

TYPE_MACOSX

TYPE_AWT

TYPE_DEFAULT

Method Detail

isJVMShuttingDown

addCustomShutdownHook

shutdown

isInitialized

initSingleton

requiresToolkitLock

isAWTAvailable

getNativeWindowType

setDefaultFactory

getDefaultFactory

getAWTToolkitLock

getNullToolkitLock

getDefaultToolkitLock

getDefaultToolkitLock

getDefaultToolkitLock

createScreen

getFactory

getNativeWindow

getOffscreenLayerSurface

isNativeVisualIDValidForProcessing

createDevice

createDevice

createWrappedWindow

getLocationOnScreen