javax.media.nativewindow
Class NativeWindowFactory

java.lang.Object
  extended by 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
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
static void addCustomShutdownHook(boolean head, Runnable runnable)
          Add a custom shutdown hook to be performed at JVM shutdown before shutting down NativeWindowFactory instance.
static AbstractGraphicsScreen createScreen(AbstractGraphicsDevice device, int screen)
           
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 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 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


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.


getDefaultToolkitLock

public static ToolkitLock getDefaultToolkitLock(String type,
                                                long deviceHandle)
Provides the default ToolkitLock for type and deviceHandle.


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.



Copyright 2010 JogAmp Community.