Bug 682 - Relocating javax.media.opengl.* -> com.jogamp.opengl.* (Part 2)

Relocation javax.media.nativewindow.* -> com.jogamp.nativewindow.*
Relocation javax.media.opengl.* -> com.jogamp.opengl.*

1 files changed, 238 insertions, 0 deletions

diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/NativeSurface.java b/src/nativewindow/classes/com/jogamp/nativewindow/NativeSurface.java
new file mode 100644
index 000000000..ce0699c56
--- /dev/null
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/NativeSurface.java
@@ -0,0 +1,238 @@
+/**
+ * Copyright 2010 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+
+package com.jogamp.nativewindow;
+
+/**
+ * Provides low-level information required for
+ * hardware-accelerated rendering using a surface in a platform-independent manner.
+ * <p>
+ * All values of this interface are represented in pixel units, if not stated otherwise.
+ * See {@link NativeWindow}.
+ * </p>
+ * <p>
+ * 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.
+ * </p>
+ */
+public interface NativeSurface extends SurfaceUpdatedListener {
+  /** Unlocked state, {@value}. */
+  public static final int LOCK_SURFACE_UNLOCKED = 0;
+
+  /** Returned by {@link #lockSurface()} if the surface is not ready to be locked, {@value}. */
+  public static final int LOCK_SURFACE_NOT_READY = 1;
+
+  /** Returned by {@link #lockSurface()} if the surface is locked, but has changed, {@value}. */
+  public static final int LOCK_SURFACE_CHANGED = 2;
+
+  /** Returned by {@link #lockSurface()} if the surface is locked, and is unchanged, {@value}. */
+  public static final int LOCK_SUCCESS = 3;
+
+  /**
+   * Lock the surface of this native window.
+   * <p>
+   * The surface handle shall be valid after a successfull call,
+   * ie return a value other than {@link #LOCK_SURFACE_UNLOCKED} and {@link #LOCK_SURFACE_NOT_READY},
+   * which is
+   * <pre>
+   *    boolean ok = LOCK_SURFACE_NOT_READY < lockSurface();
+   * </pre>
+   * </p>
+   * <p>
+   * The caller may need to take care of the result {@link #LOCK_SURFACE_CHANGED},
+   * where the surface handle is valid but has changed.
+   * </p>
+   * <p>
+   * This call is blocking until the surface has been locked
+   * or a timeout is reached. The latter will throw a runtime exception.
+   * </p>
+   * <p>
+   * This call allows recursion from the same thread.
+   * </p>
+   * <p>
+   * The implementation may want to aquire the
+   * application level {@link com.jogamp.common.util.locks.RecursiveLock}
+   * first before proceeding with a native surface lock.
+   * </p>
+   * <p>
+   * The implementation shall also invoke {@link AbstractGraphicsDevice#lock()}
+   * for the initial lock (recursive count zero).
+   * </p>
+   *
+   * @return {@link #LOCK_SUCCESS}, {@link #LOCK_SURFACE_CHANGED} or {@link #LOCK_SURFACE_NOT_READY}.
+   *
+   * @throws RuntimeException after timeout when waiting for the surface lock
+   * @throws NativeWindowException if native locking failed, maybe platform related
+   *
+   * @see com.jogamp.common.util.locks.RecursiveLock
+   */
+  public int lockSurface() throws NativeWindowException, RuntimeException;
+
+  /**
+   * Unlock the surface of this native window
+   *
+   * Shall not modify the surface handle, see {@link #lockSurface()} <P>
+   *
+   * The implementation shall also invoke {@link AbstractGraphicsDevice#unlock()}
+   * for the final unlock (recursive count zero).<P>
+   *
+   * 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 #lockSurface
+   * @see com.jogamp.common.util.locks.RecursiveLock
+   */
+  public void unlockSurface();
+
+  /**
+   * Query if surface is locked by another thread, i.e. not the current one.
+   * <br>
+   * Convenient shortcut for:
+   * <pre>
+   *   final Thread o = getSurfaceLockOwner();
+   *   if( null != o && Thread.currentThread() != o ) { .. }
+   * </pre>
+   */
+  public boolean isSurfaceLockedByOtherThread();
+
+  /**
+   * Return the locking owner's Thread, or null if not locked.
+   */
+  public Thread getSurfaceLockOwner();
+
+  /**
+   * 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.
+   * <p>
+   * The implementation may itself apply the swapping,
+   * in which case true shall be returned.
+   * </p>
+   *
+   * @return true if this method completed swapping the surface,
+   *         otherwise false, in which case eg the GLDrawable
+   *         implementation has to swap the code.
+   */
+  public boolean surfaceSwap();
+
+  /** Appends the given {@link SurfaceUpdatedListener} to the end of the list. */
+  public void addSurfaceUpdatedListener(SurfaceUpdatedListener l);
+
+  /**
+   * Inserts the given {@link SurfaceUpdatedListener} at the
+   * specified position in the list.<br>
+   *
+   * @param 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().
+   * @param l The listener object to be inserted
+   * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
+   */
+  public void addSurfaceUpdatedListener(int index, SurfaceUpdatedListener l) throws IndexOutOfBoundsException;
+
+  /** Remove the specified {@link SurfaceUpdatedListener} from the list. */
+  public void removeSurfaceUpdatedListener(SurfaceUpdatedListener l);
+
+  /**
+   * Returns the handle to the surface for this NativeSurface. <P>
+   *
+   * The surface handle should be set/update by {@link #lockSurface()},
+   * where {@link #unlockSurface()} is not allowed to modify it.
+   * After {@link #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. <P>
+   *
+   * On X11 this returns an entity of type Window,
+   * since there is no differentiation of surface and window there. <BR>
+   * On Microsoft Windows this returns an entity of type HDC.
+   */
+  public long getSurfaceHandle();
+
+  /**
+   * Returns the width of the client area excluding insets (window decorations) in pixel units.
+   * @return width of the client area in pixel units
+   * @see NativeWindow#getWidth()
+   * @see #convertToWindowUnits(int[])
+   */
+  public int getSurfaceWidth();
+
+  /**
+   * Returns the height of the client area excluding insets (window decorations) in pixel units.
+   * @return height of the client area in pixel units
+   * @see NativeWindow#getHeight()
+   * @see #convertToWindowUnits(int[])
+   */
+  public int getSurfaceHeight();
+
+  /**
+   * Converts the given pixel units into window units <i>in place</i>.
+   * @param pixelUnitsAndResult int[2] storage holding the pixel units for the x- and y-coord to convert
+   *                             and the resulting values.
+   * @return result int[2] storage pixelUnitsAndResult for chaining holding the converted values
+   * @see ScalableSurface
+   */
+  public int[] convertToWindowUnits(final int[] pixelUnitsAndResult);
+
+  /**
+   * Converts the given window units into pixel units <i>in place</i>.
+   * @param windowUnitsAndResult int[2] storage holding the window units for the x- and y-coord to convert
+   *                             and the resulting values.
+   * @return result int[2] storage windowUnitsAndResult for chaining holding the converted values
+   * @see ScalableSurface
+   */
+  public int[] convertToPixelUnits(final int[] windowUnitsAndResult);
+
+  /**
+   * Returns the graphics configuration corresponding to this window.
+   * <p>
+   * In case the implementation utilizes a delegation pattern to wrap abstract toolkits,
+   * this method shall return the native {@link AbstractGraphicsConfiguration} via {@link AbstractGraphicsConfiguration#getNativeGraphicsConfiguration()}.
+   * </p>
+   * @see AbstractGraphicsConfiguration#getNativeGraphicsConfiguration()
+   * @see com.jogamp.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)
+   */
+  public AbstractGraphicsConfiguration getGraphicsConfiguration();
+
+  /**
+   * Convenience: Get display handle from
+   *   AbstractGraphicsConfiguration . AbstractGraphicsScreen . AbstractGraphicsDevice
+   */
+  public long getDisplayHandle();
+
+  /**
+   * Convenience: Get display handle from
+   *   AbstractGraphicsConfiguration . AbstractGraphicsScreen
+   */
+  public int  getScreenIndex();
+
+}
+