Package com.jogamp.nativewindow

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.

    • Method Detail

      • getLock

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

      • 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:
        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​(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

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

      • 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

      • getDisplayHandle

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

      • getScreenIndex

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