ProxySurface (JOGL, NativeWindow and NEWT APIs)

java.lang.Object
- javax.media.nativewindow.ProxySurface

All Implemented Interfaces:

MutableSurface, NativeSurface, SurfaceUpdatedListener

Direct Known Subclasses:

WrappedSurface
```
public abstract class ProxySurface
extends Object
implements NativeSurface, MutableSurface
```

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`ProxySurface.UpstreamSurfaceHook` Interface allowing upstream caller to pass lifecycle actions and size info to a `ProxySurface` instance.

Field Summary

Fields
Modifier and Type	Field and Description
`static boolean`	`DEBUG`
`int`	`initialHeight`
`int`	`initialWidth`
`static int`	`INVISIBLE_WINDOW` Implementation specific bitvalue stating the upstream's `NativeSurface` is an invisible window, i.e.
`static int`	`OWN_DEVICE` Implementation specific bitvalue stating the upstream's `AbstractGraphicsDevice` is owned by this `ProxySurface`.

Fields inherited from interface javax.media.nativewindow.NativeSurface
LOCK_SUCCESS, LOCK_SURFACE_CHANGED, LOCK_SURFACE_NOT_READY, LOCK_SURFACE_UNLOCKED

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.
`void`	`createNotify()` If a valid `ProxySurface.UpstreamSurfaceHook` instance is passed in the `constructor`, `ProxySurface.UpstreamSurfaceHook.create(ProxySurface)` is being issued and the proxy surface/window handles shall be set.
`void`	`destroyNotify()` If a valid `ProxySurface.UpstreamSurfaceHook` instance is passed in the `constructor`, `ProxySurface.UpstreamSurfaceHook.destroy(ProxySurface)` is being issued and all fields are cleared.
`long`	`getDisplayHandle()` Convenience: Get display handle from AbstractGraphicsConfiguration .
`AbstractGraphicsConfiguration`	`getGraphicsConfiguration()` Returns the graphics configuration corresponding to this window.
`int`	`getHeight()` Returns the height of the client area excluding insets (window decorations).
`int`	`getImplBitfield()`
`int`	`getScreenIndex()` Convenience: Get display handle from AbstractGraphicsConfiguration .
`abstract long`	`getSurfaceHandle()` Returns the handle to the surface for this NativeSurface.
`Thread`	`getSurfaceLockOwner()` Return the locking owner's Thread, or null if not locked.
`ProxySurface.UpstreamSurfaceHook`	`getUpstreamSurfaceHook()`
`int`	`getWidth()` Returns the width of the client area excluding insets (window decorations).
`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.
`void`	`setImplBitfield(int v)`
`abstract void`	`setSurfaceHandle(long surfaceHandle)` Sets the surface handle which is created outside of this implementation.
`boolean`	`surfaceSwap()` Provide a mechanism to utilize custom (pre-) swap surface code.
`void`	`surfaceUpdated(Object updater, NativeSurface ns, long when)` Notification of a surface update event, eg.
`abstract String`	`toString()`
`void`	`unlockSurface()` Unlock the surface of this native window Shall not modify the surface handle, see `NativeSurface.lockSurface()`
`void`	`validateSurfaceLocked()`

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEBUG
```
public static final boolean DEBUG
```
  - OWN_DEVICE
```
public static final int OWN_DEVICE
```
    Implementation specific bitvalue stating the upstream's AbstractGraphicsDevice is owned by this ProxySurface.
    
    See Also:
    setImplBitfield(int), getImplBitfield(), Constant Field Values
  - INVISIBLE_WINDOW
```
public static final int INVISIBLE_WINDOW
```
    Implementation specific bitvalue stating the upstream's NativeSurface is an invisible window, i.e. maybe incomplete.
    
    See Also:
    setImplBitfield(int), getImplBitfield(), Constant Field Values
  - initialWidth
```
public final int initialWidth
```
  - initialHeight
```
public final int initialHeight
```
- Method Detail
  - getUpstreamSurfaceHook
```
public final ProxySurface.UpstreamSurfaceHook getUpstreamSurfaceHook()
```
  - createNotify
```
public void createNotify()
```
    If a valid ProxySurface.UpstreamSurfaceHook instance is passed in the constructor, ProxySurface.UpstreamSurfaceHook.create(ProxySurface) is being issued and the proxy surface/window handles shall be set.
  - destroyNotify
```
public void destroyNotify()
```
    If a valid ProxySurface.UpstreamSurfaceHook instance is passed in the constructor, ProxySurface.UpstreamSurfaceHook.destroy(ProxySurface) is being issued and all fields are cleared.
  - getDisplayHandle
```
public final long getDisplayHandle()
```
    Description copied from interface: NativeSurface
    
    Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen . AbstractGraphicsDevice
    
    Specified by:
    
    getDisplayHandle in interface NativeSurface
  - getGraphicsConfiguration
```
public final AbstractGraphicsConfiguration getGraphicsConfiguration()
```
    Description copied from interface: NativeSurface
    
    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().
    
    Specified by:
    
    getGraphicsConfiguration in interface NativeSurface
    
    See Also:
    AbstractGraphicsConfiguration.getNativeGraphicsConfiguration(), javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)
  - getScreenIndex
```
public final int getScreenIndex()
```
    Description copied from interface: NativeSurface
    
    Convenience: Get display handle from AbstractGraphicsConfiguration . AbstractGraphicsScreen
    
    Specified by:
    
    getScreenIndex in interface NativeSurface
  - getSurfaceHandle
```
public abstract long getSurfaceHandle()
```
    Description copied from interface: NativeSurface
    
    Returns the handle to the surface for this NativeSurface.
    The surface handle should be set/update by NativeSurface.lockSurface(), where NativeSurface.unlockSurface() is not allowed to modify it. After NativeSurface.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.
    
    Specified by:
    
    getSurfaceHandle in interface NativeSurface
  - setSurfaceHandle
```
public abstract void setSurfaceHandle(long surfaceHandle)
```
    Description copied from interface: MutableSurface
    
    Sets the surface handle which is created outside of this implementation.
    
    Specified by:
    
    setSurfaceHandle in interface MutableSurface
  - getWidth
```
public final int getWidth()
```
    Description copied from interface: NativeSurface
    
    Returns the width of the client area excluding insets (window decorations).
    
    Specified by:
    
    getWidth in interface NativeSurface
    
    Returns:
    width of the client area
  - getHeight
```
public final int getHeight()
```
    Description copied from interface: NativeSurface
    
    Returns the height of the client area excluding insets (window decorations).
    
    Specified by:
    
    getHeight in interface NativeSurface
    
    Returns:
    height of the client area
  - surfaceSwap
```
public boolean surfaceSwap()
```
    Description copied from interface: NativeSurface
    
    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. The implementation may itself apply the swapping, in which case true shall be returned.
    
    Specified by:
    
    surfaceSwap in interface NativeSurface
    
    Returns:
    true if this method completed swapping the surface, otherwise false, in which case eg the GLDrawable implementation has to swap the code.
  - addSurfaceUpdatedListener
```
public void addSurfaceUpdatedListener(SurfaceUpdatedListener l)
```
    Description copied from interface: NativeSurface
    
    Appends the given SurfaceUpdatedListener to the end of the list.
    
    Specified by:
    
    addSurfaceUpdatedListener in interface NativeSurface
  - addSurfaceUpdatedListener
```
public void addSurfaceUpdatedListener(int index,
                             SurfaceUpdatedListener l)
                               throws IndexOutOfBoundsException
```
    Description copied from interface: NativeSurface
    
    Inserts the given SurfaceUpdatedListener at the specified position in the list.
    
    Specified by:
    
    addSurfaceUpdatedListener in interface NativeSurface
    
    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
```
public void removeSurfaceUpdatedListener(SurfaceUpdatedListener l)
```
    Description copied from interface: NativeSurface
    
    Remove the specified SurfaceUpdatedListener from the list.
    
    Specified by:
    
    removeSurfaceUpdatedListener in interface NativeSurface
  - surfaceUpdated
```
public void surfaceUpdated(Object updater,
                  NativeSurface ns,
                  long when)
```
    Description copied from interface: SurfaceUpdatedListener
    
    Notification of a surface update event, eg. after a swap buffer operation.
    
    Specified by:
    
    surfaceUpdated in interface SurfaceUpdatedListener
    
    Parameters:
    updater - is the caller object who updated the surface, e.g. a JOGL GLDrawable.
    ns - the updated NativeSurface
    when - the time in ms, when the surface was updated
  - lockSurface
```
public int lockSurface()
                throws NativeWindowException,
                       RuntimeException
```
    Description copied from interface: NativeSurface
    Lock the surface of this native window.
    The surface handle shall be valid after a successfull call, ie return a value other than NativeSurface.LOCK_SURFACE_UNLOCKED and NativeSurface.LOCK_SURFACE_NOT_READY, which is
```
 
    boolean ok = lockSurface() > LOCK_SURFACE_NOT_READY; 
 
```
    The caller may need to take care of the result NativeSurface.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).
    Specified by:
    
    lockSurface in interface NativeSurface
    
    Returns:
    NativeSurface.LOCK_SUCCESS, NativeSurface.LOCK_SURFACE_CHANGED or NativeSurface.LOCK_SURFACE_NOT_READY.
    
    Throws:
    
    NativeWindowException - if native locking failed, maybe platform related
    
    RuntimeException - after timeout when waiting for the surface lock
    See Also:
    RecursiveLock
  - unlockSurface
```
public final void unlockSurface()
```
    Description copied from interface: NativeSurface
    
    Unlock the surface of this native window Shall not modify the surface handle, see NativeSurface.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.
    
    Specified by:
    
    unlockSurface in interface NativeSurface
    
    See Also:
    NativeSurface.lockSurface(), RecursiveLock
  - validateSurfaceLocked
```
public final void validateSurfaceLocked()
```
  - isSurfaceLockedByOtherThread
```
public final boolean isSurfaceLockedByOtherThread()
```
    Description copied from interface: NativeSurface
    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 ) { .. }
 
```
    Specified by:
    
    isSurfaceLockedByOtherThread in interface NativeSurface
  - getSurfaceLockOwner
```
public final Thread getSurfaceLockOwner()
```
    Description copied from interface: NativeSurface
    
    Return the locking owner's Thread, or null if not locked.
    
    Specified by:
    
    getSurfaceLockOwner in interface NativeSurface
  - toString
```
public abstract String toString()
```
    Overrides:
    
    toString in class Object
  - getImplBitfield
```
public int getImplBitfield()
```
  - setImplBitfield
```
public void setImplBitfield(int v)
```

Class ProxySurface

Nested Class Summary

Field Summary

Fields inherited from interface javax.media.nativewindow.NativeSurface

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEBUG

OWN_DEVICE

INVISIBLE_WINDOW

initialWidth

initialHeight

Method Detail

getUpstreamSurfaceHook

createNotify

destroyNotify

getDisplayHandle

getGraphicsConfiguration

getScreenIndex

getSurfaceHandle

setSurfaceHandle

getWidth

getHeight

surfaceSwap

addSurfaceUpdatedListener

addSurfaceUpdatedListener

removeSurfaceUpdatedListener

surfaceUpdated

lockSurface

unlockSurface

validateSurfaceLocked

isSurfaceLockedByOtherThread

getSurfaceLockOwner

toString

getImplBitfield

setImplBitfield