javax.media.nativewindow

## Interface NativeSurface

- All Superinterfaces:
    SurfaceUpdatedListener
  All Known Subinterfaces:
    MutableSurface, NativeWindow, ProxySurface

      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 and Description
    --- | ---
    `static int` | `LOCK_SUCCESS` Returned by `lockSurface()` if the surface is locked, and is unchanged, 3.
    `static int` | `LOCK_SURFACE_CHANGED` Returned by `lockSurface()` if the surface is locked, but has changed, 2.
    `static int` | `LOCK_SURFACE_NOT_READY` Returned by `lockSurface()` if the surface is not ready to be locked, 1.
    `static int` | `LOCK_SURFACE_UNLOCKED` Unlocked state, 0.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addSurfaceUpdatedListener(int index, SurfaceUpdatedListener l)` Inserts the given `SurfaceUpdatedListener` at the specified position in the list.
    `void` | `addSurfaceUpdatedListener(SurfaceUpdatedListener l)` Appends the given `SurfaceUpdatedListener` 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.
    `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 specified `SurfaceUpdatedListener` 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, see `lockSurface()`

    - ### Methods inherited from interface javax.media.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 by `lockSurface()` 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 by `lockSurface()` if the surface is locked, but has changed, 2.
      See Also:
        Constant Field Values

    - #### LOCK_SUCCESS

          static final int LOCK_SUCCESS

      Returned by `lockSurface()` if the surface is locked, and is unchanged, 3.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### 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:
        `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 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:
        `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

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

    - #### 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:
        `AbstractGraphicsConfiguration.getNativeGraphicsConfiguration()`, `javax.media.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

Copyright 2010 JogAmp Community.