javax.media.nativewindow
Interface NativeSurface

All Superinterfaces:

SurfaceUpdatedListener

All Known Subinterfaces:

NativeWindow

All Known Implementing Classes:

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

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

Lock the surface of this native window

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

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

See Also:

RecursiveLock

unlockSurface

void unlockSurface()
                   throws NativeWindowException

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

Throws:

RuntimeException - if surface is not locked

NativeWindowException

See Also:

lockSurface(), RecursiveLock

isSurfaceLockedByOtherThread

boolean isSurfaceLockedByOtherThread()

Return if surface is locked by another thread, ie not the current one

isSurfaceLocked

boolean isSurfaceLocked()

Return if surface is locked

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

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.

See Also:

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