com.jogamp.nativewindow.awt
Class JAWTWindow

java.lang.Object
  extended by com.jogamp.nativewindow.awt.JAWTWindow
All Implemented Interfaces:
NativeSurface, NativeWindow, OffscreenLayerOption, OffscreenLayerSurface, SurfaceUpdatedListener

public abstract class JAWTWindow
extends Object
implements NativeWindow, OffscreenLayerSurface, OffscreenLayerOption


Field Summary
 
Fields inherited from interface javax.media.nativewindow.NativeSurface
LOCK_SUCCESS, LOCK_SURFACE_CHANGED, LOCK_SURFACE_NOT_READY, LOCK_SURFACE_UNLOCKED
 
Method Summary
 void addSurfaceUpdatedListener(int index, SurfaceUpdatedListener l)
          Inserts the given SurfaceUpdatedListener at the specified position in the list.
 void addSurfaceUpdatedListener(SurfaceUpdatedListener l)
          Appends the given SurfaceUpdatedListener to the end of the list.
 void attachSurfaceLayer(long layerHandle)
          Attach the offscreen layer to this offscreen layer surface.
 void destroy()
          Destroys this window incl.
 void detachSurfaceLayer()
          Detaches a previously attached offscreen layer from this offscreen layer surface.
 long getAttachedSurfaceLayer()
          Returns the attached surface layer or null if none is attached.
 Component getAWTComponent()
           
 RectangleImmutable getBounds()
           
 long getDisplayHandle()
          Convenience: Get display handle from AbstractGraphicsConfiguration .
 AbstractGraphicsConfiguration getGraphicsConfiguration()
          Returns the graphics configuration corresponding to this window.
 int getHeight()
          Returns the height of the client area excluding insets (window decorations).
 InsetsImmutable getInsets()
          Returns the insets defined as the width and height of the window decoration on the left, right, top and bottom.
Insets are zero if the window is undecorated, including child windows.
 jogamp.nativewindow.jawt.JAWT getJAWT()
          Returns the underlying JAWT instance created @ lockSurface().
 Point getLocationOnScreen(Point storage)
          Returns the current position of the top-left corner of the client area in screen coordinates.
 com.jogamp.common.util.locks.RecursiveLock getLock()
          Returns the recursive lock object of this surface, which synchronizes multithreaded access.
 NativeWindow getParent()
           
 AWTGraphicsConfiguration getPrivateGraphicsConfiguration()
           
 int getScreenIndex()
          Convenience: Get display handle from AbstractGraphicsConfiguration .
 boolean getShallUseOffscreenLayer()
          Returns the property set by OffscreenLayerOption.setShallUseOffscreenLayer(boolean).
 long getSurfaceHandle()
          Returns the handle to the surface for this NativeSurface.
 Thread getSurfaceLockOwner()
          Return the locking owner's Thread, or null if not locked.
 int getWidth()
          Returns the width of the client area excluding insets (window decorations).
 long getWindowHandle()
          Returns the window handle for this NativeWindow.
 int getX()
           
 int getY()
           
 boolean hasFocus()
          Returns true if this native window owns the focus, otherwise false.
 boolean isApplet()
          Returns true if the AWT component is parented to an Applet, otherwise false.
 boolean isOffscreenLayerSurfaceEnabled()
          Returns true if this instance uses an offscreen layer, otherwise false.
 boolean isSurfaceLayerAttached()
          Returns true if a surface layer is attached, otherwise false.
 boolean isSurfaceLockedByOtherThread()
          Query if surface is locked by another thread, i.e.
 int lockSurface()
          Lock the surface of this native window.
 void removeSurfaceUpdatedListener(SurfaceUpdatedListener l)
          Remove the specified SurfaceUpdatedListener from the list.
 void setChosenCapabilities(CapabilitiesImmutable caps)
          Sets the capabilities of this instance, allowing upstream API's to refine it, i.e.
 void setShallUseOffscreenLayer(boolean v)
          Request an offscreen layer, if supported.
 boolean surfaceSwap()
          Provide a mechanism to utilize custom (pre-) swap surface code.
 void surfaceUpdated(Object updater, NativeSurface ns, long when)
          Notification of a surface update event, eg.
 String toString()
           
 void unlockSurface()
          Unlock the surface of this native window Shall not modify the surface handle, see NativeSurface.lockSurface()
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getBounds

public final RectangleImmutable getBounds()
Returns:
the JAWT_DrawingSurfaceInfo's (JAWT_Rectangle) bounds, updated with lock

getInsets

public final InsetsImmutable getInsets()
Description copied from interface: NativeWindow
Returns the insets defined as the width and height of the window decoration on the left, right, top and bottom.
Insets are zero if the window is undecorated, including child windows.

Insets are available only after the native window has been created, ie. the native window has been made visible.
The top-level window area's top-left corner is located at

   getX() - getInsets().getLeftWidth()
   getY() - getInsets().getTopHeight()
 
The top-level window size is
   getWidth()  + getInsets().getTotalWidth()
   getHeight() + getInsets().getTotalHeight()
 

Specified by:
getInsets in interface NativeWindow
Returns:
insets

getAWTComponent

public final Component getAWTComponent()

isApplet

public final boolean isApplet()
Returns true if the AWT component is parented to an Applet, otherwise false. This information is valid only after lockSurface().


getJAWT

public final jogamp.nativewindow.jawt.JAWT getJAWT()
Returns the underlying JAWT instance created @ lockSurface().


setShallUseOffscreenLayer

public void setShallUseOffscreenLayer(boolean v)
Description copied from interface: OffscreenLayerOption
Request an offscreen layer, if supported.

Shall be called before the first NativeSurface.lockSurface(), and hence before realization.

Specified by:
setShallUseOffscreenLayer in interface OffscreenLayerOption
See Also:
OffscreenLayerOption.getShallUseOffscreenLayer(), OffscreenLayerOption.isOffscreenLayerSurfaceEnabled()

getShallUseOffscreenLayer

public final boolean getShallUseOffscreenLayer()
Description copied from interface: OffscreenLayerOption
Returns the property set by OffscreenLayerOption.setShallUseOffscreenLayer(boolean).

Specified by:
getShallUseOffscreenLayer in interface OffscreenLayerOption

isOffscreenLayerSurfaceEnabled

public final boolean isOffscreenLayerSurfaceEnabled()
Description copied from interface: OffscreenLayerOption
Returns true if this instance uses an offscreen layer, otherwise false.

This instance is an offscreen layer, if setShallUseOffscreenLayer(true) has been called before it's realization and first lock and the underlying implementation supports it.

The return value is undefined before issuing the first NativeSurface.lockSurface().

Specified by:
isOffscreenLayerSurfaceEnabled in interface OffscreenLayerOption
See Also:
OffscreenLayerOption.setShallUseOffscreenLayer(boolean)

attachSurfaceLayer

public final void attachSurfaceLayer(long layerHandle)
                              throws NativeWindowException
Description copied from interface: OffscreenLayerSurface
Attach the offscreen layer to this offscreen layer surface.

Implementation may realize all required resources at this point.

Specified by:
attachSurfaceLayer in interface OffscreenLayerSurface
Throws:
NativeWindowException - if #isOffscreenLayerSurfaceEnabled() == false
See Also:
#isOffscreenLayerSurfaceEnabled()

detachSurfaceLayer

public final void detachSurfaceLayer()
                              throws NativeWindowException
Description copied from interface: OffscreenLayerSurface
Detaches a previously attached offscreen layer from this offscreen layer surface.

Specified by:
detachSurfaceLayer in interface OffscreenLayerSurface
Throws:
NativeWindowException - if #isOffscreenLayerSurfaceEnabled() == false or no surface layer is attached.
See Also:
OffscreenLayerSurface.attachSurfaceLayer(long), #isOffscreenLayerSurfaceEnabled()

getAttachedSurfaceLayer

public final long getAttachedSurfaceLayer()
Description copied from interface: OffscreenLayerSurface
Returns the attached surface layer or null if none is attached.

Specified by:
getAttachedSurfaceLayer in interface OffscreenLayerSurface

isSurfaceLayerAttached

public final boolean isSurfaceLayerAttached()
Description copied from interface: OffscreenLayerSurface
Returns true if a surface layer is attached, otherwise false.

Specified by:
isSurfaceLayerAttached in interface OffscreenLayerSurface

setChosenCapabilities

public final void setChosenCapabilities(CapabilitiesImmutable caps)
Description copied from interface: OffscreenLayerSurface
Sets the capabilities of this instance, allowing upstream API's to refine it, i.e. OpenGL related settings.

Specified by:
setChosenCapabilities in interface OffscreenLayerSurface

getLock

public final com.jogamp.common.util.locks.RecursiveLock getLock()
Description copied from interface: OffscreenLayerSurface
Returns the recursive lock object of this surface, which synchronizes multithreaded access.

Specified by:
getLock in interface OffscreenLayerSurface

addSurfaceUpdatedListener

public void addSurfaceUpdatedListener(SurfaceUpdatedListener l)
Description copied from interface: NativeSurface
Appends the given SurfaceUpdatedListener to the end of the list.

Specified by:
addSurfaceUpdatedListener in interface NativeSurface

addSurfaceUpdatedListener

public void addSurfaceUpdatedListener(int index,
                                      SurfaceUpdatedListener l)
                               throws IndexOutOfBoundsException
Description copied from interface: NativeSurface
Inserts the given SurfaceUpdatedListener at the specified position in the list.

Specified by:
addSurfaceUpdatedListener in interface NativeSurface
Parameters:
index - Position where the listener will be inserted. Should be within (0 <= index && index <= size()). An index value of -1 is interpreted as the end of the list, size().
l - The listener object to be inserted
Throws:
IndexOutOfBoundsException - If the index is not within (0 <= index && index <= size()), or -1

removeSurfaceUpdatedListener

public void removeSurfaceUpdatedListener(SurfaceUpdatedListener l)
Description copied from interface: NativeSurface
Remove the specified SurfaceUpdatedListener from the list.

Specified by:
removeSurfaceUpdatedListener in interface NativeSurface

surfaceUpdated

public void surfaceUpdated(Object updater,
                           NativeSurface ns,
                           long when)
Description copied from interface: SurfaceUpdatedListener
Notification of a surface update event, eg. after a swap buffer operation.

Specified by:
surfaceUpdated in interface SurfaceUpdatedListener
Parameters:
updater - is the caller object who updated the surface, e.g. a JOGL GLDrawable.
ns - the updated NativeSurface
when - the time in ms, when the surface was updated

lockSurface

public final int lockSurface()
                      throws NativeWindowException,
                             RuntimeException
Description copied from interface: NativeSurface
Lock the surface of this native window.

The surface handle shall be valid after a successfull call, ie return a value other than NativeSurface.LOCK_SURFACE_UNLOCKED and NativeSurface.LOCK_SURFACE_NOT_READY, which is

 
    boolean ok = LOCK_SURFACE_NOT_READY < lockSurface(); 
 

The caller may need to take care of the result NativeSurface.LOCK_SURFACE_CHANGED, where the surface handle is valid but has changed.

This call is blocking until the surface has been locked or a timeout is reached. The latter will throw a runtime exception.

This call allows recursion from the same thread.

The implementation may want to aquire the application level RecursiveLock first before proceeding with a native surface lock.

The implementation shall also invoke AbstractGraphicsDevice.lock() for the initial lock (recursive count zero).

Specified by:
lockSurface in interface NativeSurface
Returns:
NativeSurface.LOCK_SUCCESS, NativeSurface.LOCK_SURFACE_CHANGED or NativeSurface.LOCK_SURFACE_NOT_READY.
Throws:
NativeWindowException - if native locking failed, maybe platform related
RuntimeException - after timeout when waiting for the surface lock
See Also:
RecursiveLock

unlockSurface

public final void unlockSurface()
Description copied from interface: NativeSurface
Unlock the surface of this native window Shall not modify the surface handle, see NativeSurface.lockSurface()

The implementation shall also invoke AbstractGraphicsDevice.unlock() for the final unlock (recursive count zero).

The implementation shall be fail safe, i.e. tolerant in case the native resources are already released / unlocked. In this case the implementation shall simply ignore the call.

Specified by:
unlockSurface in interface NativeSurface
See Also:
NativeSurface.lockSurface(), RecursiveLock

isSurfaceLockedByOtherThread

public final boolean isSurfaceLockedByOtherThread()
Description copied from interface: NativeSurface
Query if surface is locked by another thread, i.e. not the current one.
Convenient shortcut for:
   final Thread o = getSurfaceLockOwner();
   if( null != o && Thread.currentThread() != o ) { .. }
 

Specified by:
isSurfaceLockedByOtherThread in interface NativeSurface

getSurfaceLockOwner

public final Thread getSurfaceLockOwner()
Description copied from interface: NativeSurface
Return the locking owner's Thread, or null if not locked.

Specified by:
getSurfaceLockOwner in interface NativeSurface

surfaceSwap

public boolean surfaceSwap()
Description copied from interface: NativeSurface
Provide a mechanism to utilize custom (pre-) swap surface code. This method is called before the render toolkit (e.g. JOGL) swaps the buffer/surface if double buffering is enabled.

The implementation may itself apply the swapping, in which case true shall be returned.

Specified by:
surfaceSwap in interface NativeSurface
Returns:
true if this method completed swapping the surface, otherwise false, in which case eg the GLDrawable implementation has to swap the code.

getSurfaceHandle

public long getSurfaceHandle()
Description copied from interface: NativeSurface
Returns the handle to the surface for this NativeSurface.

The surface handle should be set/update by NativeSurface.lockSurface(), where NativeSurface.unlockSurface() is not allowed to modify it. After NativeSurface.unlockSurface() it is no more guaranteed that the surface handle is still valid. The surface handle shall reflect the platform one for all drawable surface operations, e.g. opengl, swap-buffer.

On X11 this returns an entity of type Window, since there is no differentiation of surface and window there.
On Microsoft Windows this returns an entity of type HDC.

Specified by:
getSurfaceHandle in interface NativeSurface

getPrivateGraphicsConfiguration

public final AWTGraphicsConfiguration getPrivateGraphicsConfiguration()

getGraphicsConfiguration

public final AbstractGraphicsConfiguration getGraphicsConfiguration()
Description copied from interface: NativeSurface
Returns the graphics configuration corresponding to this window.

In case the implementation utilizes a delegation pattern to wrap abstract toolkits, this method shall return the native AbstractGraphicsConfiguration via AbstractGraphicsConfiguration.getNativeGraphicsConfiguration().

Specified by:
getGraphicsConfiguration in interface NativeSurface
See Also:
AbstractGraphicsConfiguration.getNativeGraphicsConfiguration(), javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)

getDisplayHandle

public final long getDisplayHandle()
Description copied from interface: NativeSurface
Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen . AbstractGraphicsDevice

Specified by:
getDisplayHandle in interface NativeSurface

getScreenIndex

public final int getScreenIndex()
Description copied from interface: NativeSurface
Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen

Specified by:
getScreenIndex in interface NativeSurface

getWidth

public final int getWidth()
Description copied from interface: NativeSurface
Returns the width of the client area excluding insets (window decorations).

Specified by:
getWidth in interface NativeSurface
Returns:
width of the client area

getHeight

public final int getHeight()
Description copied from interface: NativeSurface
Returns the height of the client area excluding insets (window decorations).

Specified by:
getHeight in interface NativeSurface
Returns:
height of the client area

destroy

public void destroy()
Description copied from interface: NativeWindow
Destroys this window incl. releasing all related resources.

Specified by:
destroy in interface NativeWindow

getParent

public final NativeWindow getParent()
Specified by:
getParent in interface NativeWindow
Returns:
The parent NativeWindow, or null if this NativeWindow is top level.

getWindowHandle

public long getWindowHandle()
Description copied from interface: NativeWindow
Returns the window handle for this NativeWindow.

The window handle shall reflect the platform one for all window related operations, e.g. open, close, resize.

On X11 this returns an entity of type Window.
On Microsoft Windows this returns an entity of type HWND.

Specified by:
getWindowHandle in interface NativeWindow

getX

public final int getX()
Specified by:
getX in interface NativeWindow
Returns:
the current x position of the top-left corner of the client area relative to it's parent. Since the position reflects the client area, it does not include the insets.
See Also:
NativeWindow.getInsets()

getY

public final int getY()
Specified by:
getY in interface NativeWindow
Returns:
the current y position of the top-left corner of the client area relative to it's parent. Since the position reflects the client area, it does not include the insets.
See Also:
NativeWindow.getInsets()

getLocationOnScreen

public Point getLocationOnScreen(Point storage)
Returns the current position of the top-left corner of the client area in screen coordinates.

Since the position reflects the client area, it does not include the insets.

This JAWT default implementation is currently still using a blocking implementation. It first attempts to retrieve the location via a native implementation. If this fails, it tries the blocking AWT implementation. If the latter fails due to an external AWT tree-lock, the non block implementation getLocationOnScreenNonBlocking(Point, Component) is being used. The latter simply traverse up to the AWT component tree and sums the rel. position. We have to determine whether the latter is good enough for all cases, currently only OS X utilizes the non blocking method per default.

Specified by:
getLocationOnScreen in interface NativeWindow
Parameters:
storage - if not null, Point.translate(javax.media.nativewindow.util.Point) the passed Point by this location on the screen and return it.
Returns:
either the passed non null translated point by the screen location of this NativeWindow, or a new instance with the screen location of this NativeWindow.

hasFocus

public boolean hasFocus()
Description copied from interface: NativeWindow
Returns true if this native window owns the focus, otherwise false.

Specified by:
hasFocus in interface NativeWindow

toString

public String toString()
Overrides:
toString in class Object


Copyright 2010 JogAmp Community.