|
JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java (public API).
|
Provides low-level information required for hardware-accelerated rendering using a surface in a platform-independent manner. More...
Public Member Functions | |
| RecursiveLock | getLock () |
Returns the implementation's RecursiveLock synchronizing multithreaded access if used. More... | |
| int | lockSurface () throws NativeWindowException, RuntimeException |
| Lock the surface of this native window. More... | |
| void | unlockSurface () |
| Unlock the surface of this native window. More... | |
| boolean | isSurfaceLockedByOtherThread () |
| Query if surface is locked by another thread, i.e. More... | |
| Thread | getSurfaceLockOwner () |
| Return the locking owner's Thread, or null if not locked. More... | |
| boolean | surfaceSwap () |
| Provide a mechanism to utilize custom (pre-) swap surface code. More... | |
| void | addSurfaceUpdatedListener (SurfaceUpdatedListener l) |
Appends the given SurfaceUpdatedListener to the end of the list. More... | |
| void | addSurfaceUpdatedListener (int index, SurfaceUpdatedListener l) throws IndexOutOfBoundsException |
Inserts the given SurfaceUpdatedListener at the specified position in the list. More... | |
| void | removeSurfaceUpdatedListener (SurfaceUpdatedListener l) |
Remove the specified SurfaceUpdatedListener from the list. More... | |
| long | getSurfaceHandle () |
| Returns the handle to the surface for this NativeSurface. More... | |
| int | getSurfaceWidth () |
| Returns the width of the client area excluding insets (window decorations) in pixel units. More... | |
| int | getSurfaceHeight () |
| Returns the height of the client area excluding insets (window decorations) in pixel units. More... | |
| int[] | convertToWindowUnits (final int[] pixelUnitsAndResult) |
| Converts the given pixel units into window units in place. More... | |
| int[] | convertToPixelUnits (final int[] windowUnitsAndResult) |
| Converts the given window units into pixel units in place. More... | |
| AbstractGraphicsConfiguration | getGraphicsConfiguration () |
| Returns the graphics configuration corresponding to this window. More... | |
| long | getDisplayHandle () |
| Convenience: Get display handle from AbstractGraphicsConfiguration . More... | |
| int | getScreenIndex () |
| Convenience: Get display handle from AbstractGraphicsConfiguration . More... | |
Public Member Functions inherited from com.jogamp.nativewindow.SurfaceUpdatedListener | |
| void | surfaceUpdated (Object updater, NativeSurface ns, long when) |
| Notification of a surface update event, eg. More... | |
Static Public Attributes | |
| static final int | LOCK_SURFACE_UNLOCKED = 0 |
| Unlocked state, {@value}. More... | |
| static final int | LOCK_SURFACE_NOT_READY = 1 |
Returned by lockSurface() if the surface is not ready to be locked, {@value}. More... | |
| static final int | LOCK_SURFACE_CHANGED = 2 |
Returned by lockSurface() if the surface is locked, but has changed, {@value}. More... | |
| static final int | LOCK_SUCCESS = 3 |
Returned by lockSurface() if the surface is locked, and is unchanged, {@value}. More... | |
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.
Definition at line 47 of file NativeSurface.java.
| void com.jogamp.nativewindow.NativeSurface.addSurfaceUpdatedListener | ( | int | index, |
| SurfaceUpdatedListener | l | ||
| ) | throws IndexOutOfBoundsException |
Inserts the given SurfaceUpdatedListener at the specified position in the list.
| 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 |
| IndexOutOfBoundsException | If the index is not within (0 <= index && index <= size()), or -1 |
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| void com.jogamp.nativewindow.NativeSurface.addSurfaceUpdatedListener | ( | SurfaceUpdatedListener | l | ) |
Appends the given SurfaceUpdatedListener to the end of the list.
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| int[] com.jogamp.nativewindow.NativeSurface.convertToPixelUnits | ( | final int[] | windowUnitsAndResult | ) |
Converts the given window units into pixel units in place.
| windowUnitsAndResult | int[2] storage holding the window units for the x- and y-coord to convert and the resulting values. |
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| int[] com.jogamp.nativewindow.NativeSurface.convertToWindowUnits | ( | final int[] | pixelUnitsAndResult | ) |
Converts the given pixel units into window units in place.
| pixelUnitsAndResult | int[2] storage holding the pixel units for the x- and y-coord to convert and the resulting values. |
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| long com.jogamp.nativewindow.NativeSurface.getDisplayHandle | ( | ) |
Convenience: Get display handle from AbstractGraphicsConfiguration .
AbstractGraphicsScreen . AbstractGraphicsDevice
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| AbstractGraphicsConfiguration com.jogamp.nativewindow.NativeSurface.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().
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| RecursiveLock com.jogamp.nativewindow.NativeSurface.getLock | ( | ) |
Returns the implementation's RecursiveLock synchronizing multithreaded access if used.
Otherwise null is being returned.
NativeSurface's RecursiveLock 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 the RecursiveLock 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.
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| int com.jogamp.nativewindow.NativeSurface.getScreenIndex | ( | ) |
Convenience: Get display handle from AbstractGraphicsConfiguration .
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| long com.jogamp.nativewindow.NativeSurface.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.
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| int com.jogamp.nativewindow.NativeSurface.getSurfaceHeight | ( | ) |
Returns the height of the client area excluding insets (window decorations) in pixel units.
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| Thread com.jogamp.nativewindow.NativeSurface.getSurfaceLockOwner | ( | ) |
Return the locking owner's Thread, or null if not locked.
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| int com.jogamp.nativewindow.NativeSurface.getSurfaceWidth | ( | ) |
Returns the width of the client area excluding insets (window decorations) in pixel units.
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| boolean com.jogamp.nativewindow.NativeSurface.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 ) { .. }
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| int com.jogamp.nativewindow.NativeSurface.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).
LOCK_SUCCESS, LOCK_SURFACE_CHANGED or LOCK_SURFACE_NOT_READY.| RuntimeException | after timeout when waiting for the surface lock |
| NativeWindowException | if native locking failed, maybe platform related |
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| void com.jogamp.nativewindow.NativeSurface.removeSurfaceUpdatedListener | ( | SurfaceUpdatedListener | l | ) |
Remove the specified SurfaceUpdatedListener from the list.
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| boolean com.jogamp.nativewindow.NativeSurface.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.
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
| void com.jogamp.nativewindow.NativeSurface.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.
Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.
|
static |
Returned by lockSurface() if the surface is locked, and is unchanged, {@value}.
Definition at line 58 of file NativeSurface.java.
|
static |
Returned by lockSurface() if the surface is locked, but has changed, {@value}.
Definition at line 55 of file NativeSurface.java.
|
static |
Returned by lockSurface() if the surface is not ready to be locked, {@value}.
Definition at line 52 of file NativeSurface.java.
|
static |
Unlocked state, {@value}.
Definition at line 49 of file NativeSurface.java.