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 the window and releases windowing related resources.
 void detachSurfaceLayer(long layerHandle)
          Detaches a previously attached offscreen layer from this offscreen layer surface.
 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.
 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 isSurfaceLocked()
          Return if surface is locked
 boolean isSurfaceLockedByOtherThread()
          Return if surface is locked by another thread, ie not the current one
 int lockSurface()
          Lock the surface of this native window.
 void removeSurfaceUpdatedListener(SurfaceUpdatedListener l)
          Remove the specified SurfaceUpdatedListener from the list.
 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

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)

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().


attachSurfaceLayer

public final void attachSurfaceLayer(long layerHandle)
                              throws NativeWindowException
Attach the offscreen layer to this offscreen layer surface.

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

detachSurfaceLayer

public final void detachSurfaceLayer(long layerHandle)
                              throws NativeWindowException
Detaches a previously attached offscreen layer from this offscreen layer surface.

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

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
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 = lockSurface() > LOCK_SURFACE_NOT_READY; 
 

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

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

isSurfaceLockedByOtherThread

public final boolean isSurfaceLockedByOtherThread()
Description copied from interface: NativeSurface
Return if surface is locked by another thread, ie not the current one

Specified by:
isSurfaceLockedByOtherThread in interface NativeSurface

isSurfaceLocked

public final boolean isSurfaceLocked()
Description copied from interface: NativeSurface
Return if surface is locked

Specified by:
isSurfaceLocked 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. 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 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 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 the window and releases windowing 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.