Interface NativeSurface
-
- All Superinterfaces:
SurfaceUpdatedListener
- All Known Subinterfaces:
MutableSurface
,NativeWindow
,ProxySurface
- All Known Implementing Classes:
JAWTWindow
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 Description static int
LOCK_SUCCESS
Returned bylockSurface()
if the surface is locked, and is unchanged, 3.static int
LOCK_SURFACE_CHANGED
Returned bylockSurface()
if the surface is locked, but has changed, 2.static int
LOCK_SURFACE_NOT_READY
Returned bylockSurface()
if the surface is not ready to be locked, 1.static int
LOCK_SURFACE_UNLOCKED
Unlocked state, 0.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addSurfaceUpdatedListener(int index, SurfaceUpdatedListener l)
Inserts the givenSurfaceUpdatedListener
at the specified position in the list.void
addSurfaceUpdatedListener(SurfaceUpdatedListener l)
Appends the givenSurfaceUpdatedListener
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.RecursiveLock
getLock()
Returns the implementation'sRecursiveLock
synchronizing multithreaded access if used.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 specifiedSurfaceUpdatedListener
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, seelockSurface()
-
Methods inherited from interface com.jogamp.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 bylockSurface()
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 bylockSurface()
if the surface is locked, but has changed, 2.- See Also:
- Constant Field Values
-
LOCK_SUCCESS
static final int LOCK_SUCCESS
Returned bylockSurface()
if the surface is locked, and is unchanged, 3.- See Also:
- Constant Field Values
-
-
Method Detail
-
getLock
RecursiveLock getLock()
Returns the implementation'sRecursiveLock
synchronizing multithreaded access if used. Otherwisenull
is being returned.NativeSurface
'sRecursiveLock
is only exposed to resolve special situations within the implementation and its usage is not advised if not absolutely necessary.Note that certain
NativeSurface
implementations only use theRecursiveLock
as an upfront re-entrance lock vehicle, but actually acquire and release the underlying windowing toolkit's lock facility on the first or last re-entrance lock, respectively.
-
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
andLOCK_SURFACE_NOT_READY
, which isboolean 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
orLOCK_SURFACE_NOT_READY
.- Throws:
RuntimeException
- after timeout when waiting for the surface lockNativeWindowException
- 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, seelockSurface()
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 givenSurfaceUpdatedListener
to the end of the list.
-
addSurfaceUpdatedListener
void addSurfaceUpdatedListener(int index, SurfaceUpdatedListener l) throws IndexOutOfBoundsException
Inserts the givenSurfaceUpdatedListener
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 specifiedSurfaceUpdatedListener
from the list.
-
getSurfaceHandle
long getSurfaceHandle()
Returns the handle to the surface for this NativeSurface.The surface handle should be set/update by
lockSurface()
, whereunlockSurface()
is not allowed to modify it. AfterunlockSurface()
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
- See Also:
ScalableSurface
-
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
- See Also:
ScalableSurface
-
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
viaAbstractGraphicsConfiguration.getNativeGraphicsConfiguration()
.- See Also:
AbstractGraphicsConfiguration.getNativeGraphicsConfiguration()
,com.jogamp.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
-
-