javax.media.nativewindow
Interface NativeSurface

All Superinterfaces:
SurfaceUpdatedListener
All Known Subinterfaces:
MutableSurface, NativeWindow, ProxySurface

public interface NativeSurface
extends SurfaceUpdatedListener

Provides low-level information required for hardware-accelerated rendering using a surface in a platform-independent manner.

A NativeSurface created for a particular on- or offscreen component is expected to have the same lifetime as that component. As long as the component is alive and realized/visible, NativeSurface must be able provide information such as the surface handle while it is locked.


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.
static int LOCK_SURFACE_UNLOCKED
          Unlocked state
 
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.
 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).
 int getScreenIndex()
          Convenience: Get display handle from AbstractGraphicsConfiguration .
 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).
 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.
 boolean surfaceSwap()
          Provide a mechanism to utilize custom (pre-) swap surface code.
 void unlockSurface()
          Unlock the surface of this native window Shall not modify the surface handle, see lockSurface()
 
Methods inherited from interface javax.media.nativewindow.SurfaceUpdatedListener
surfaceUpdated
 

Field Detail

LOCK_SURFACE_UNLOCKED

static final int LOCK_SURFACE_UNLOCKED
Unlocked state

See Also:
Constant Field Values

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,
                       RuntimeException
Lock the surface of this native window.

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

 
    boolean ok = LOCK_SURFACE_NOT_READY < lockSurface(); 
 

The caller may need to take care of the result 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).

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

unlockSurface

void unlockSurface()
Unlock the surface of this native window Shall not modify the surface handle, see 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.

See Also:
lockSurface(), RecursiveLock

isSurfaceLockedByOtherThread

boolean isSurfaceLockedByOtherThread()
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 ) { .. }
 


getSurfaceLockOwner

Thread getSurfaceLockOwner()
Return the locking owner's Thread, or null if not locked.


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 if double buffering is enabled.

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.

addSurfaceUpdatedListener

void addSurfaceUpdatedListener(SurfaceUpdatedListener l)
Appends the given SurfaceUpdatedListener to the end of the list.


addSurfaceUpdatedListener

void addSurfaceUpdatedListener(int index,
                               SurfaceUpdatedListener l)
                               throws IndexOutOfBoundsException
Inserts the given SurfaceUpdatedListener at the specified position in the list.

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

void removeSurfaceUpdatedListener(SurfaceUpdatedListener l)
Remove the specified SurfaceUpdatedListener from the list.


getSurfaceHandle

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

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 width of the client area excluding insets (window decorations).

Returns:
width of the client area

getHeight

int getHeight()
Returns the height of the client area excluding insets (window decorations).

Returns:
height of the client area

getGraphicsConfiguration

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

See Also:
AbstractGraphicsConfiguration.getNativeGraphicsConfiguration(), javax.media.nativewindow.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 2010 JogAmp Community.