Top Description Fields Methods
com.jogamp.nativewindow

public Interface NativeSurface

extends SurfaceUpdatedListener
Known Direct Subinterfaces
com.jogamp.nativewindow.NativeWindow, com.jogamp.nativewindow.MutableSurface
Provides low-level information required for hardware-accelerated rendering using a surface in a platform-independent manner.

All values of this interface are represented in pixel units, if not stated otherwise. See NativeWindow.

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

Modifier and TypeField and Description
public static final int
LOCK_SUCCESS

Returned by lockSurface() if the surface is locked, and is unchanged, .

public static final int
LOCK_SURFACE_CHANGED

Returned by lockSurface() if the surface is locked, but has changed, .

public static final int
LOCK_SURFACE_NOT_READY

Returned by lockSurface() if the surface is not ready to be locked, .

public static final int
LOCK_SURFACE_UNLOCKED

Unlocked state, .

Method Summary

Modifier and TypeMethod and Description
public void
addSurfaceUpdatedListener(SurfaceUpdatedListener l)

Appends the given SurfaceUpdatedListener to the end of the list.

public void
addSurfaceUpdatedListener(int
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().
index, SurfaceUpdatedListener
The listener object to be inserted
l)

Inserts the given SurfaceUpdatedListener at the specified position in the list.

public int[]

Returns:

result int[2] storage windowUnitsAndResult for chaining holding the converted values
convertToPixelUnits(final int[]
int[2] storage holding the window units for the x- and y-coord to convert and the resulting values.
windowUnitsAndResult)

Converts the given window units into pixel units in place.

public int[]

Returns:

result int[2] storage pixelUnitsAndResult for chaining holding the converted values
convertToWindowUnits(final int[]
int[2] storage holding the pixel units for the x- and y-coord to convert and the resulting values.
pixelUnitsAndResult)

Converts the given pixel units into window units in place.

public long
getDisplayHandle()

Convenience: Get display handle from AbstractGraphicsConfiguration .

public AbstractGraphicsConfiguration
getGraphicsConfiguration()

Returns the graphics configuration corresponding to this window.

public int
getScreenIndex()

Convenience: Get display handle from AbstractGraphicsConfiguration .

public long
getSurfaceHandle()

Returns the handle to the surface for this NativeSurface.

public int

Returns:

height of the client area in pixel units
getSurfaceHeight()

Returns the height of the client area excluding insets (window decorations) in pixel units.

public Thread
getSurfaceLockOwner()

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

public int

Returns:

width of the client area in pixel units
getSurfaceWidth()

Returns the width of the client area excluding insets (window decorations) in pixel units.

public boolean
isSurfaceLockedByOtherThread()

Query if surface is locked by another thread, i.e. not the current one.

public int

Returns:

LOCK_SUCCESS, LOCK_SURFACE_CHANGED or LOCK_SURFACE_NOT_READY.
lockSurface()

Lock the surface of this native window.

public void
removeSurfaceUpdatedListener(SurfaceUpdatedListener l)

Remove the specified SurfaceUpdatedListener from the list.

public boolean

Returns:

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

Provide a mechanism to utilize custom (pre-) swap surface code.

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

Inherited from com.jogamp.nativewindow.SurfaceUpdatedListener:
surfaceUpdated

Field Detail

LOCK_SUCCESSback to summary
public static final int LOCK_SUCCESS

Returned by lockSurface() if the surface is locked, and is unchanged, .

LOCK_SURFACE_CHANGEDback to summary
public static final int LOCK_SURFACE_CHANGED

Returned by lockSurface() if the surface is locked, but has changed, .

LOCK_SURFACE_NOT_READYback to summary
public static final int LOCK_SURFACE_NOT_READY

Returned by lockSurface() if the surface is not ready to be locked, .

LOCK_SURFACE_UNLOCKEDback to summary
public static final int LOCK_SURFACE_UNLOCKED

Unlocked state, .

Method Detail

addSurfaceUpdatedListenerback to summary
public void addSurfaceUpdatedListener(SurfaceUpdatedListener l)

Appends the given SurfaceUpdatedListener to the end of the list.

addSurfaceUpdatedListenerback to summary
public void addSurfaceUpdatedListener(int index, SurfaceUpdatedListener l) throws IndexOutOfBoundsException

Inserts the given SurfaceUpdatedListener at the specified position in the list.

Parameters
index:int

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:SurfaceUpdatedListener

The listener object to be inserted

Exceptions
IndexOutOfBoundsException:
If the index is not within (0 <= index && index <= size()), or -1
convertToPixelUnitsback to summary
public int[] convertToPixelUnits(final int[] windowUnitsAndResult)

Converts the given window units into pixel units in place.

Parameters
windowUnitsAndResult:int[]

int[2] storage holding the window units for the x- and y-coord to convert and the resulting values.

Returns:int[]

result int[2] storage windowUnitsAndResult for chaining holding the converted values

See Also
ScalableSurface
convertToWindowUnitsback to summary
public int[] convertToWindowUnits(final int[] pixelUnitsAndResult)

Converts the given pixel units into window units in place.

Parameters
pixelUnitsAndResult:int[]

int[2] storage holding the pixel units for the x- and y-coord to convert and the resulting values.

Returns:int[]

result int[2] storage pixelUnitsAndResult for chaining holding the converted values

See Also
ScalableSurface
getDisplayHandleback to summary
public long getDisplayHandle()

Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen . AbstractGraphicsDevice

getGraphicsConfigurationback to summary
public 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(), com.jogamp.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)
getScreenIndexback to summary
public int getScreenIndex()

Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen

getSurfaceHandleback to summary
public 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.

getSurfaceHeightback to summary
public int getSurfaceHeight()

Returns the height of the client area excluding insets (window decorations) in pixel units.

Returns:int

height of the client area in pixel units

See Also
NativeWindow#getHeight(), convertToWindowUnits(int[])
getSurfaceLockOwnerback to summary
public Thread getSurfaceLockOwner()

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

getSurfaceWidthback to summary
public int getSurfaceWidth()

Returns the width of the client area excluding insets (window decorations) in pixel units.

Returns:int

width of the client area in pixel units

See Also
NativeWindow#getWidth(), convertToWindowUnits(int[])
isSurfaceLockedByOtherThreadback to summary
public 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 ) { .. }
lockSurfaceback to summary
public 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 com.jogamp.common.util.locks.RecursiveLock first before proceeding with a native surface lock.

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

Returns:int

LOCK_SUCCESS, LOCK_SURFACE_CHANGED or LOCK_SURFACE_NOT_READY.

Exceptions
NativeWindowException:
if native locking failed, maybe platform related
RuntimeException:
after timeout when waiting for the surface lock
See Also
com.jogamp.common.util.locks.RecursiveLock
removeSurfaceUpdatedListenerback to summary
public void removeSurfaceUpdatedListener(SurfaceUpdatedListener l)

Remove the specified SurfaceUpdatedListener from the list.

surfaceSwapback to summary
public 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:boolean

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

unlockSurfaceback to summary
public 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, com.jogamp.common.util.locks.RecursiveLock