diff options
Diffstat (limited to 'src/nativewindow/classes/com/jogamp/nativewindow/NativeSurface.java')
| -rw-r--r-- | src/nativewindow/classes/com/jogamp/nativewindow/NativeSurface.java | 238 |
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(); + +} + |