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.

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

Fields

Modifier and Type	Field and Description
static int	LOCK_SUCCESS Returned by lockSurface() if the surface is locked, and is unchanged, 3.
static int	LOCK_SURFACE_CHANGED Returned by lockSurface() if the surface is locked, but has changed, 2.
static int	LOCK_SURFACE_NOT_READY Returned by lockSurface() if the surface is not ready to be locked, 1.
static int	LOCK_SURFACE_UNLOCKED Unlocked state, 0.

Method Summary

Methods

Modifier and Type	Method and Description
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.
int[]	convertToPixelUnits(int[] windowUnitsAndResult) Converts the given window units into pixel units in place.
int[]	convertToWindowUnits(int[] pixelUnitsAndResult) Converts the given pixel units into window units in place.
long	getDisplayHandle() Convenience: Get display handle from AbstractGraphicsConfiguration .
AbstractGraphicsConfiguration	getGraphicsConfiguration() Returns the graphics configuration corresponding to this window.
int	getScreenIndex() Convenience: Get display handle from AbstractGraphicsConfiguration .
long	getSurfaceHandle() Returns the handle to the surface for this NativeSurface.
int	getSurfaceHeight() Returns the height of the client area excluding insets (window decorations) in pixel units.
Thread	getSurfaceLockOwner() Return the locking owner's Thread, or null if not locked.
int	getSurfaceWidth() Returns the width of the client area excluding insets (window decorations) in pixel units.
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, 0.

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, 1.

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, 2.

See Also:

Constant Field Values

LOCK_SUCCESS

static final int LOCK_SUCCESS

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

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.

getSurfaceWidth

int getSurfaceWidth()

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

Returns:

width of the client area in pixel units

See Also:

NativeWindow.getWidth(), convertToWindowUnits(int[])

getSurfaceHeight

int getSurfaceHeight()

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

Returns:

height of the client area in pixel units

See Also:

NativeWindow.getHeight(), convertToWindowUnits(int[])

convertToWindowUnits

int[] convertToWindowUnits(int[] pixelUnitsAndResult)

Converts the given pixel units into window units in place.

Parameters:

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

Returns:

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

convertToPixelUnits

int[] convertToPixelUnits(int[] windowUnitsAndResult)

Converts the given window units into pixel units in place.

Parameters:

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

Returns:

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

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