JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
com.jogamp.nativewindow.NativeSurface Interface Reference

Provides low-level information required for hardware-accelerated rendering using a surface in a platform-independent manner. More...

Inheritance diagram for com.jogamp.nativewindow.NativeSurface:
Collaboration diagram for com.jogamp.nativewindow.NativeSurface:

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

Detailed Description

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.

Member Function Documentation

◆ addSurfaceUpdatedListener() [1/2]

void com.jogamp.nativewindow.NativeSurface.addSurfaceUpdatedListener ( int  index,
SurfaceUpdatedListener  l 
) throws IndexOutOfBoundsException

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


Parameters
indexPosition 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().
lThe listener object to be inserted
Exceptions
IndexOutOfBoundsExceptionIf the index is not within (0 <= index && index <= size()), or -1

Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.

◆ addSurfaceUpdatedListener() [2/2]

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.

◆ convertToPixelUnits()

int[] com.jogamp.nativewindow.NativeSurface.convertToPixelUnits ( final int[]  windowUnitsAndResult)

Converts the given window units into pixel units in place.

Parameters
windowUnitsAndResultint[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

Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.

Here is the caller graph for this function:

◆ convertToWindowUnits()

int[] com.jogamp.nativewindow.NativeSurface.convertToWindowUnits ( final int[]  pixelUnitsAndResult)

Converts the given pixel units into window units in place.

Parameters
pixelUnitsAndResultint[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

Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.

◆ getDisplayHandle()

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.

Here is the caller graph for this function:

◆ getGraphicsConfiguration()

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

See also
AbstractGraphicsConfiguration::getNativeGraphicsConfiguration()
com.jogamp.nativewindow.GraphicsConfigurationFactory::chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)

Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.

Here is the caller graph for this function:

◆ getLock()

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.

◆ getScreenIndex()

int com.jogamp.nativewindow.NativeSurface.getScreenIndex ( )

Convenience: Get display handle from AbstractGraphicsConfiguration .

AbstractGraphicsScreen

Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.

Here is the caller graph for this function:

◆ getSurfaceHandle()

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.

Here is the caller graph for this function:

◆ getSurfaceHeight()

int com.jogamp.nativewindow.NativeSurface.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[])

Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.

Here is the caller graph for this function:

◆ getSurfaceLockOwner()

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.

◆ getSurfaceWidth()

int com.jogamp.nativewindow.NativeSurface.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[])

Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.

Here is the caller graph for this function:

◆ isSurfaceLockedByOtherThread()

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.

◆ lockSurface()

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

Returns
LOCK_SUCCESS, LOCK_SURFACE_CHANGED or LOCK_SURFACE_NOT_READY.
Exceptions
RuntimeExceptionafter timeout when waiting for the surface lock
NativeWindowExceptionif native locking failed, maybe platform related
See also
com.jogamp.common.util.locks.RecursiveLock

Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.

Here is the caller graph for this function:

◆ removeSurfaceUpdatedListener()

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.

◆ surfaceSwap()

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.

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

Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.

◆ unlockSurface()

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.

See also
lockSurface
com.jogamp.common.util.locks.RecursiveLock

Implemented in com.jogamp.nativewindow.awt.JAWTWindow, and com.jogamp.newt.opengl.GLWindow.

Here is the caller graph for this function:

Member Data Documentation

◆ LOCK_SUCCESS

final int com.jogamp.nativewindow.NativeSurface.LOCK_SUCCESS = 3
static

Returned by lockSurface() if the surface is locked, and is unchanged, {@value}.

Definition at line 58 of file NativeSurface.java.

◆ LOCK_SURFACE_CHANGED

final int com.jogamp.nativewindow.NativeSurface.LOCK_SURFACE_CHANGED = 2
static

Returned by lockSurface() if the surface is locked, but has changed, {@value}.

Definition at line 55 of file NativeSurface.java.

◆ LOCK_SURFACE_NOT_READY

final int com.jogamp.nativewindow.NativeSurface.LOCK_SURFACE_NOT_READY = 1
static

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

Definition at line 52 of file NativeSurface.java.

◆ LOCK_SURFACE_UNLOCKED

final int com.jogamp.nativewindow.NativeSurface.LOCK_SURFACE_UNLOCKED = 0
static

Unlocked state, {@value}.

Definition at line 49 of file NativeSurface.java.


The documentation for this interface was generated from the following file: