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 Details

  • Method Details

    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • 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:
    • getDisplayHandle

      long getDisplayHandle()
      Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen . AbstractGraphicsDevice
    • getScreenIndex

      int getScreenIndex()
      Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen