javax.media.nativewindow
Interface NativeWindow

All Known Implementing Classes:
GLWindow, Window

public interface NativeWindow

Provides the low-level information required for hardware-accelerated rendering in a platform-independent manner. A window toolkit such as the AWT may either implement this interface directly with one of its components, or provide and register an implementation of NativeWindowFactory which can create NativeWindow objects for its components.

A NativeWindow created for a particular on-screen component is expected to have the same lifetime as that component. As long as the component is alive, the NativeWindow must be able to control it, and any time it is visible and locked, provide information such as the window handle.


Field Summary
static int LOCK_SUCCESS
          Returned by lockSurface() if the surface is locked, and is unchanged.
static int LOCK_SURFACE_CHANGED
          Returned by lockSurface() if the surface is locked, but has changed.
static int LOCK_SURFACE_NOT_READY
          Returned by lockSurface() if the surface is not ready to be locked.
 
Method Summary
 void destroy()
          destroys the window and releases windowing related resources.
 long getDisplayHandle()
          Convenience: Get display handle from AbstractGraphicsConfiguration .
 AbstractGraphicsConfiguration getGraphicsConfiguration()
          Returns the graphics configuration corresponding to this window.
 int getHeight()
          Returns the current height of this window.
 Exception getLockedStack()
          Return the lock-exception, or null if not locked.
 int getScreenIndex()
          Convenience: Get display handle from AbstractGraphicsConfiguration .
 long getSurfaceHandle()
          Returns the handle to the surface for this NativeWindow.
 int getWidth()
          Returns the current width of this window.
 long getWindowHandle()
          Returns the window handle for this NativeWindow.
 void invalidate()
          render all native window information invalid, as if the native window was destroyed
 boolean isSurfaceLocked()
          Return if surface is locked
 int lockSurface()
          Lock the surface of this native window
 boolean surfaceSwap()
          Provide a mechanism to utilize custom (pre-) swap surface code.
 void surfaceUpdated()
          Method invoked after the render toolkit (e.g.
 void unlockSurface()
          Unlock the surface of this native window Shall not modify the window handle, see getWindowHandle(), or the surface handle, see lockSurface()
 

Field Detail

LOCK_SURFACE_NOT_READY

static final int LOCK_SURFACE_NOT_READY
Returned by lockSurface() if the surface is not ready to be locked.

See Also:
Constant Field Values

LOCK_SURFACE_CHANGED

static final int LOCK_SURFACE_CHANGED
Returned by lockSurface() if the surface is locked, but has changed.

See Also:
Constant Field Values

LOCK_SUCCESS

static final int LOCK_SUCCESS
Returned by lockSurface() if the surface is locked, and is unchanged.

See Also:
Constant Field Values
Method Detail

lockSurface

int lockSurface()
                throws NativeWindowException
Lock the surface of this native window

The window handle, see getWindowHandle(), and the surface handle, see lockSurface(),
shall be set and be valid after a successfull call, ie a return value other than LOCK_SURFACE_NOT_READY.

The semantics of the underlying native locked resource may be related to the ToolkitLock one. Hence it is important that implementation of both harmonize well.
The implementation may want to aquire the ToolkitLock first to become it's owner before proceeding with it's actual surface lock.

Returns:
LOCK_SUCCESS, LOCK_SURFACE_CHANGED or LOCK_SURFACE_NOT_READY.
Throws:
NativeWindowException - if surface is already locked
See Also:
ToolkitLock

unlockSurface

void unlockSurface()
                   throws NativeWindowException
Unlock the surface of this native window Shall not modify the window handle, see getWindowHandle(), or the surface handle, see lockSurface()

Throws:
NativeWindowException - if surface is not locked
See Also:
lockSurface(), ToolkitLock

isSurfaceLocked

boolean isSurfaceLocked()
Return if surface is locked


getLockedStack

Exception getLockedStack()
Return the lock-exception, or null if not locked. The lock-exception is created at lockSurface() and hence holds the locker's call stack.


surfaceSwap

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

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

surfaceUpdated

void surfaceUpdated()
Method invoked after the render toolkit (e.g. JOGL) swapped/changed the buffer/surface.


invalidate

void invalidate()
render all native window information invalid, as if the native window was destroyed

See Also:
destroy()

destroy

void destroy()
destroys the window and releases windowing related resources.


getWindowHandle

long getWindowHandle()
Returns the window handle for this NativeWindow.

The window handle should be set/update by lockSurface(), where unlockSurface() is not allowed to modify it.
After unlockSurface() it is no more guaranteed that the window handle is still valid.

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.


getSurfaceHandle

long getSurfaceHandle()
Returns the handle to the surface for this NativeWindow.

The surface handle should be set/update by lockSurface(), where unlockSurface() is not allowed to modify it. After 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.


getWidth

int getWidth()
Returns the current width of this window.


getHeight

int getHeight()
Returns the current height of this window.


getGraphicsConfiguration

AbstractGraphicsConfiguration getGraphicsConfiguration()
Returns the graphics configuration corresponding to this window.

See Also:
GraphicsConfigurationFactory.chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)

getDisplayHandle

long getDisplayHandle()
Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen . AbstractGraphicsDevice


getScreenIndex

int getScreenIndex()
Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen



Copyright 2005 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.