- Fixing SPEC documentation for bindings JOGL and NativeWindow,

  lot's of javadoc changes/fixes.

- Fixing transparency values RGB[A] in GLX and EGL, adding those in GLCapabilities.

- Adding EGLPbuffer (untested yet)
  
  Added EGLOnscreenContext, EGLOnscreenDrawable and EGLPbufferContext, EGLPbufferDrawable,
  which completes the now abstract EGLContext and EGLDrawable.

- Decoupling EGLDrawableFactory and DynamicLookupHelper:
    Since OpenGL ES has 2 libraries and hence 2 DynamicLookupHelper, one for each,
    these are decoupled in EGLES1DynamicLookupHelper and EGLES2DynamicLookupHelper,
    where each uses the base class EGLDynamicLookupHelper.
    EGLDynamicLookupHelper act's also as the owner of these singleton instances.

    EGLDrawableFactory is now pure singleton, 
    and has no more relation to the ES[12] libraries.

    Still, GLDrawableFactory.getFactory(GLProfile) stays, due to the selection
    of the right factory, ie EGLDrawableFactory or a native one (X11GLX, WindowsWGL or MacOSXCGL).

    Added GLDrawableImpl.getDynamicLookupHelper().

    DynamicLookupHelper implementation is pushed down to the specialisation of GLDrawableImpl,
    hence removed GLDrawableImpl implements DynamicLookupHelper.

- Fixing Locking
    - Always throw an Exception if unlock is called without being locked.

    - Removed NativeWindow.LOCK_NOT_SUPPORTED, since it made the locking state ambiguos.

    - Using a generated Exception at locking to mark the object locked,
      and to let it throw in case of double locking.

    - Removed redundant lockToolkit() calls, where lockSurface() calls are made

- Fixing GLWindow wrapped toolkit (e.g. AWTWindow) usage
    - In case the passed NativeWindow only contains a wrapper window,
      we use the NativeWindowFactory.getNativeWindow() pipeline to produce a valid
      NativeWindow. This object is only referenced within the drawable, hence we have 
      to use it for actual NativeWindow related operations.

    - Add setVisible(): lockSurface()/unlockSurface() to allow getting the windowHandle

    - Overwriting all drawable related Window method's, using the drawable's NativeWindow if exists.
        - getNativeWindow()
        - lockSurface()/unlockSurface()/..
        - getWindowHandle()/getSurfaceHandle()

- Fix NativeWindowFactory.getNativeWindowType(),
  so the custom and pure values are set once (static init) - not overwritten (prev. bug).

- NEWT: Added WindowEvent.EVENT_WINDOW_DESTROY_NOTIFY support in AWTWindow.
  Now the proper dispose() calls are made to all GLEventListeners if the AWT window
  is being closed - before it is actually destroyed.

- Threading now uses the AWTThreadingPlugin, 
  a ThreadingPlugin interface AWT implementation, containing the refactored 
  Threading code.

- Reintroduced getChosen*Capabilities and getRequested*Capabilites,
  where get*Capabilities is renamed back to getRequested*Capabilities.
  The semantics are necessary to allow the drawables (and NativeWindow)
  to be regenerated in case of a device change in a multihead environment.
  Otherwise there is a risk that recursive choosing of the Capabilities
  will degenerate the result.

- Multihead logic ..

    Exception:   Xinerama, where all monitors share the same static configuration,
                 and the window handle 'survive'
                 X11, MacOSX and Win32 with a Xinerama behavior

      1) Recognition of a display/screen/surface change
        - It is prooven that the JAWT model (JAWT_LOCK_SURFACE_CHANGED) 
          while locking the surface is not reliably propagated, ie doesn't work here,
          if the display change happens.

        - AWT's Canvas.getGraphicsConfiguration() can reliably being used
          to detect this case, ie compare the old GraphicsConfiguration with the new one.

        - A solution for other native windowing toolkits must be found,
          ie query the current underlying pixel-configuration, if it changed - act.

      In which case the the following shall be done:
        2.0) - notify all GLEventListener via the dispose(GLAutoDrawable)
        2.1) - destroy the OpenGL context
        2.2) - call GLDrawable's setRealized(false)
        2.3) - call GLDrawable's setRealized(true)
        2.4) - create a new OpenGL context
        2.5) - notify all GLEventListener via the init(GLAutoDrawable)

      Steps 2.0 - 2.5 are executed with GLAutoDrawable's dispose(true) call.

      Step 2.3, setRealized(true) on GLDrawable shall:
        2.3.1) - Choose the GLCapabilities again, based on the requested ones,
                 and update the choosen ones in the AbstractGraphicsConfiguration.
        2.3.2) - Update AbstractScreen within the new AbstractGraphicsConfiguration to
                 reflect the possible screen change.

  DONE: Xinerama mode: X11 + Xinerama, MacOSX
  DONE: Introducing GLAutoDrawable.dispose(boolean regenerate)
  DONE: 2.3.1 on setRealized(true): Windows, MacOSX (implicit on createContext)
  TODO: Windows setRealized(true) on AWT Canvas getGraphicsConfiguration(),
        can't lock the JAWT surface sometimes - exception, code disabled, see GLCanvas.java
  TODO: 2.3.1 on setRealized(true): X11 and EGL
  TODO: Find a test case, without Xinerama behavior
  TODO: Code for Newt/NativeWindow to detect (1) and propagate GLAutoDrawable's dispose(true).

  TESTS: 
    - MacOSX (Xinerama) OK

    - X11
        -TwinView (NV) OK
        -Xinerama (NV) OK

    - Win32 (Xinerama) OK

    - GLAutoDrawable's dispose(true)

- 



git-svn-id: file:///usr/local/projects/SUN/JOGL/git-svn/svn-server-sync/jogl/branches/JOGL_2_SANDBOX@1929 232f8b59-042b-4e1e-8c03-345bb8c30851

20 files changed, 532 insertions, 157 deletions

diff --git a/src/nativewindow/classes/com/sun/nativewindow/impl/GraphicsConfigurationFactoryImpl.java b/src/nativewindow/classes/com/sun/nativewindow/impl/GraphicsConfigurationFactoryImpl.java
index 85d50e6bd..4e8e281a8 100644
--- a/src/nativewindow/classes/com/sun/nativewindow/impl/GraphicsConfigurationFactoryImpl.java
+++ b/src/nativewindow/classes/com/sun/nativewindow/impl/GraphicsConfigurationFactoryImpl.java
@@ -38,6 +38,6 @@ public class GraphicsConfigurationFactoryImpl extends GraphicsConfigurationFacto
     public AbstractGraphicsConfiguration chooseGraphicsConfiguration(Capabilities capabilities,
                                                                      CapabilitiesChooser chooser,
                                                                      AbstractGraphicsScreen screen) {
-        return new DefaultGraphicsConfiguration(screen, capabilities);
+        return new DefaultGraphicsConfiguration(screen, capabilities, capabilities);
     }
 }
diff --git a/src/nativewindow/classes/com/sun/nativewindow/impl/NativeWindowFactoryImpl.java b/src/nativewindow/classes/com/sun/nativewindow/impl/NativeWindowFactoryImpl.java
index 3d873209f..424b44c8c 100644
--- a/src/nativewindow/classes/com/sun/nativewindow/impl/NativeWindowFactoryImpl.java
+++ b/src/nativewindow/classes/com/sun/nativewindow/impl/NativeWindowFactoryImpl.java
@@ -69,24 +69,21 @@ public class NativeWindowFactoryImpl extends NativeWindowFactory {
     private NativeWindow getAWTNativeWindow(Object winObj, AbstractGraphicsConfiguration config) {
         if (nativeWindowConstructor == null) {
             try {
-                String osName = System.getProperty("os.name");
-                String osNameLowerCase = osName.toLowerCase();
+                String osType = getNativeWindowType(false);
                 String windowClassName = null;
 
                 // We break compile-time dependencies on the AWT here to
                 // make it easier to run this code on mobile devices
 
-                if (osNameLowerCase.startsWith("wind")) {
+                if (osType.equals(TYPE_WINDOWS)) {
                     windowClassName = "com.sun.nativewindow.impl.jawt.windows.WindowsJAWTWindow";
-                } else if (osNameLowerCase.startsWith("mac os x")) {
+                } else if (osType.equals(TYPE_MACOSX)) {
                     windowClassName = "com.sun.nativewindow.impl.jawt.macosx.MacOSXJAWTWindow";
-                } else {
+                } else if (osType.equals(TYPE_X11)) {
                     // Assume Linux, Solaris, etc. Should probably test for these explicitly.
                     windowClassName = "com.sun.nativewindow.impl.jawt.x11.X11JAWTWindow";
-                }
-
-                if (windowClassName == null) {
-                    throw new IllegalArgumentException("OS " + osName + " not yet supported");
+                } else {
+                    throw new IllegalArgumentException("OS " + getNativeOSName(false) + " not yet supported");
                 }
 
                 nativeWindowConstructor = NWReflection.getConstructor(windowClassName, new Class[] { Object.class, AbstractGraphicsConfiguration.class });
diff --git a/src/nativewindow/classes/com/sun/nativewindow/impl/NullWindow.java b/src/nativewindow/classes/com/sun/nativewindow/impl/NullWindow.java
index e448cd5d3..46128b227 100644
--- a/src/nativewindow/classes/com/sun/nativewindow/impl/NullWindow.java
+++ b/src/nativewindow/classes/com/sun/nativewindow/impl/NullWindow.java
@@ -39,7 +39,7 @@ package com.sun.nativewindow.impl;
 import javax.media.nativewindow.*;
 
 public class NullWindow implements NativeWindow {
-  protected boolean locked;
+  private Exception lockedStack = null;
   protected int width, height, scrnIndex;
   protected long surfaceHandle, displayHandle;
   protected AbstractGraphicsConfiguration config;
@@ -59,28 +59,34 @@ public class NullWindow implements NativeWindow {
   }
 
   public synchronized void invalidate() {
-    locked = false;
     displayHandle=0;
     scrnIndex=-1;
     surfaceHandle=0;
   }
 
   public synchronized int lockSurface() throws NativeWindowException {
-    if (locked) {
-      throw new NativeWindowException("Surface already locked");
+    if (null!=lockedStack) {
+      lockedStack.printStackTrace();
+      throw new NativeWindowException("Surface already locked - "+this);
     }
-    locked = true;
+    lockedStack = new Exception("NullWindow previously locked by "+Thread.currentThread().getName());
     return LOCK_SUCCESS;
   }
 
   public synchronized void unlockSurface() {
-    if (locked) {
-        locked = false;
+    if (null!=lockedStack) {
+        lockedStack = null;
+    } else {
+        throw new NativeWindowException("NullWindow not locked");
     }
   }
 
   public synchronized boolean isSurfaceLocked() {
-    return locked;
+    return null!=lockedStack;
+  }
+
+  public Exception getLockedStack() {
+    return lockedStack;
   }
 
   public long getDisplayHandle() {
diff --git a/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/JAWTWindow.java b/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/JAWTWindow.java
index 83e8e2266..5c13ab71c 100644
--- a/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/JAWTWindow.java
+++ b/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/JAWTWindow.java
@@ -55,7 +55,6 @@ public abstract class JAWTWindow implements NativeWindow {
 
   // lifetime: forever
   protected Component component;
-  protected boolean locked;
   protected AbstractGraphicsConfiguration config;
 
   // lifetime: valid after lock, forever until invalidate
@@ -78,12 +77,11 @@ public abstract class JAWTWindow implements NativeWindow {
   protected abstract void initNative() throws NativeWindowException;
 
   public synchronized void invalidate() {
-    locked = false;
     component = null;
     drawable= 0;
   }
 
-  private Exception lockedStack = null;
+  private volatile Exception lockedStack = null;
 
   public synchronized int lockSurface() throws NativeWindowException {
     if(DEBUG) {
@@ -94,19 +92,23 @@ public abstract class JAWTWindow implements NativeWindow {
           throw new NativeWindowException("JAWT already locked - "+this);
         }
     }
+
     if (null!=lockedStack) {
       lockedStack.printStackTrace();
       throw new NativeWindowException("Surface already locked - "+this);
     }
-    lockedStack = new Exception("JAWTWindow previous locked by:");
+
+    lockedStack = new Exception("JAWTWindow previously locked by "+Thread.currentThread().getName());
+
     return LOCK_SUCCESS;
   }
 
   public synchronized void unlockSurface() {
     if (null!=lockedStack) {
         lockedStack = null;
+        // notifyAll();
     } else {
-        throw new RuntimeException("JAWTWindow not locked");
+        throw new NativeWindowException("JAWTWindow not locked");
     }
   }
 
@@ -154,12 +156,16 @@ public abstract class JAWTWindow implements NativeWindow {
     StringBuffer sb = new StringBuffer();
 
     sb.append("JAWT-Window[config "+config+
-                ", windowHandle "+getWindowHandle()+
-                ", surfaceHandle "+getSurfaceHandle()+
-                ", pos "+component.getX()+"/"+component.getY()+", size "+getWidth()+"x"+getHeight()+
-                ", visible "+component.isVisible()+
-                ", locked "+locked+
-                ", wrappedWindow "+getWrappedWindow()+"]");
+                ", windowHandle 0x"+Long.toHexString(getWindowHandle())+
+                ", surfaceHandle 0x"+Long.toHexString(getSurfaceHandle()));
+    if(null!=component) {
+      sb.append(", pos "+component.getX()+"/"+component.getY()+", size "+getWidth()+"x"+getHeight()+
+                ", visible "+component.isVisible());
+    } else {
+      sb.append(", component NULL");
+    }
+    sb.append(", locked "+isSurfaceLocked()+
+              ", wrappedWindow "+getWrappedWindow()+"]");
 
     return sb.toString();
   }
diff --git a/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/macosx/MacOSXJAWTWindow.java b/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/macosx/MacOSXJAWTWindow.java
index ef1984474..2d85f1d4d 100644
--- a/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/macosx/MacOSXJAWTWindow.java
+++ b/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/macosx/MacOSXJAWTWindow.java
@@ -70,6 +70,7 @@ public class MacOSXJAWTWindow extends JAWTWindow {
     }
     int res = ds.Lock();
     if ((res & JAWTFactory.JAWT_LOCK_ERROR) != 0) {
+      super.unlockSurface();
       throw new NativeWindowException("Unable to lock surface");
     }
     // See whether the surface changed and if so destroy the old
@@ -127,7 +128,9 @@ public class MacOSXJAWTWindow extends JAWTWindow {
   }
     
   public void unlockSurface() throws NativeWindowException {
-    if(!isSurfaceLocked()) return;
+    if(!isSurfaceLocked()) {
+        throw new RuntimeException("JAWTWindow not locked");
+    }
     ds.FreeDrawingSurfaceInfo(dsi);
     ds.Unlock();
     JAWT.getJAWT().FreeDrawingSurface(ds);
diff --git a/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/windows/WindowsJAWTWindow.java b/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/windows/WindowsJAWTWindow.java
index e624641cd..591213038 100644
--- a/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/windows/WindowsJAWTWindow.java
+++ b/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/windows/WindowsJAWTWindow.java
@@ -74,6 +74,7 @@ public class WindowsJAWTWindow extends JAWTWindow {
     }
     int res = ds.Lock();
     if ((res & JAWTFactory.JAWT_LOCK_ERROR) != 0) {
+      super.unlockSurface();
       throw new NativeWindowException("Unable to lock surface");
     }
     // See whether the surface changed and if so destroy the old
@@ -130,7 +131,9 @@ public class WindowsJAWTWindow extends JAWTWindow {
   }
 
   public void unlockSurface() {
-    if(!isSurfaceLocked()) return;
+    if(!isSurfaceLocked()) {
+        throw new RuntimeException("JAWTWindow not locked");
+    }
     long startTime = 0;
     if (PROFILING) {
       startTime = System.currentTimeMillis();
@@ -141,7 +144,6 @@ public class WindowsJAWTWindow extends JAWTWindow {
     ds = null;
     dsi = null;
     win32dsi = null;
-    drawable = 0;
     super.unlockSurface();
     if (PROFILING) {
       long endTime = System.currentTimeMillis();
diff --git a/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/x11/X11JAWTWindow.java b/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/x11/X11JAWTWindow.java
index f53a048bf..75133488f 100644
--- a/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/x11/X11JAWTWindow.java
+++ b/src/nativewindow/classes/com/sun/nativewindow/impl/jawt/x11/X11JAWTWindow.java
@@ -68,6 +68,7 @@ public class X11JAWTWindow extends JAWTWindow {
     }
     int res = ds.Lock();
     if ((res & JAWTFactory.JAWT_LOCK_ERROR) != 0) {
+      super.unlockSurface();
       throw new NativeWindowException("Unable to lock surface");
     }
     // See whether the surface changed and if so destroy the old
diff --git a/src/nativewindow/classes/com/sun/nativewindow/impl/x11/X11GraphicsConfigurationFactory.java b/src/nativewindow/classes/com/sun/nativewindow/impl/x11/X11GraphicsConfigurationFactory.java
index 1844b1c37..890f017ab 100644
--- a/src/nativewindow/classes/com/sun/nativewindow/impl/x11/X11GraphicsConfigurationFactory.java
+++ b/src/nativewindow/classes/com/sun/nativewindow/impl/x11/X11GraphicsConfigurationFactory.java
@@ -47,7 +47,7 @@ public class X11GraphicsConfigurationFactory extends GraphicsConfigurationFactor
         if(null==screen || !(screen instanceof X11GraphicsScreen)) {
             throw new NativeWindowException("Only valid X11GraphicsScreen are allowed");
         }
-        return new X11GraphicsConfiguration((X11GraphicsScreen)screen, capabilities, getXVisualInfo(screen, capabilities));
+        return new X11GraphicsConfiguration((X11GraphicsScreen)screen, capabilities, capabilities, getXVisualInfo(screen, capabilities));
     }
 
     public static XVisualInfo getXVisualInfo(AbstractGraphicsScreen screen, long visualID)
diff --git a/src/nativewindow/classes/com/sun/nativewindow/impl/x11/X11NativeWindowFactory.java b/src/nativewindow/classes/com/sun/nativewindow/impl/x11/X11NativeWindowFactory.java
index 1643c30d8..1c67d6184 100644
--- a/src/nativewindow/classes/com/sun/nativewindow/impl/x11/X11NativeWindowFactory.java
+++ b/src/nativewindow/classes/com/sun/nativewindow/impl/x11/X11NativeWindowFactory.java
@@ -67,6 +67,7 @@ public class X11NativeWindowFactory extends NativeWindowFactoryImpl {
                     return;
                 }
                 owner = null;
+                notifyAll();
             }
         };
 
diff --git a/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsConfiguration.java b/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsConfiguration.java
index 8cf8d1b0d..e53f75251 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsConfiguration.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/AbstractGraphicsConfiguration.java
@@ -51,8 +51,20 @@ public interface AbstractGraphicsConfiguration extends Cloneable {
     /**
      * Return the capabilities reflecting this graphics configuration,
      * which may differ from the capabilites used to choose this configuration.
+     *
+     * @return A copy of the Capabilities to avoid mutation by the user.
      */
-    public Capabilities getCapabilities();
+    public Capabilities getChosenCapabilities();
+
+    /**
+     * Return the capabilities used to choose this graphics configuration.
+     *
+     * These may be used to reconfigure the NativeWindow in case
+     * the device changes in a multi screen environment.
+     *
+     * @return A copy of the Capabilities to avoid mutation by the user.
+     */
+    public Capabilities getRequestedCapabilities();
 
     /**
      * In case this instance already reflects a native configuration,
diff --git a/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java b/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
index 201d2538f..6c4c93003 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/Capabilities.java
@@ -50,6 +50,13 @@ public class Capabilities implements Cloneable {
   private int     blueBits       = 8;
   private int     alphaBits      = 0;
 
+  // Support for transparent windows containing OpenGL content
+  private boolean backgroundOpaque = true;
+  private int     transparentValueRed = -1;
+  private int     transparentValueGreen = -1;
+  private int     transparentValueBlue = -1;
+  private int     transparentValueAlpha = -1;
+
   /** Creates a Capabilities object. All attributes are in a default
       state.
     */
@@ -63,6 +70,26 @@ public class Capabilities implements Cloneable {
     }
   }
 
+  public boolean equals(Object obj) {
+    if(!(obj instanceof Capabilities)) {
+        return false;
+    }
+    Capabilities other = (Capabilities)obj;
+    boolean res = other.getRedBits()==redBits &&
+                  other.getGreenBits()==greenBits &&
+                  other.getBlueBits()==blueBits &&
+                  other.getAlphaBits()==alphaBits &&
+                  other.isBackgroundOpaque()==backgroundOpaque;
+    if(!backgroundOpaque) {
+     res = res && other.getTransparentRedValue()==transparentValueRed &&
+                  other.getTransparentGreenValue()==transparentValueGreen &&
+                  other.getTransparentBlueValue()==transparentValueBlue &&
+                  other.getTransparentAlphaValue()==transparentValueAlpha;
+    }
+
+    return res;
+  }
+
   /** Returns the number of bits requested for the color buffer's red
       component. On some systems only the color depth, which is the
       sum of the red, green, and blue bits, is considered. */
@@ -119,14 +146,114 @@ public class Capabilities implements Cloneable {
     this.alphaBits = alphaBits;
   }
 
+  /** For on-screen OpenGL contexts on some platforms, sets whether
+      the background of the context should be considered opaque. On
+      supported platforms, setting this to false, in conjunction with
+      the transparency values, may allow
+      hardware-accelerated OpenGL content inside of windows of
+      arbitrary shape. To achieve this effect it is necessary to use
+      an OpenGL clear color with an alpha less than 1.0. The default
+      value for this flag is <code>true</code>; setting it to false
+      may incur a certain performance penalty, so it is not
+      recommended to arbitrarily set it to false.<br>
+      If not set already, the transparency values for red, green, blue and alpha
+      are set to their default value, which is half of the value range
+      of the framebuffer's corresponding component,
+      ie <code> redValue = ( 1 << ( redBits - 1 ) ) -1 </code>.
+    */
+  public void setBackgroundOpaque(boolean opaque) {
+    backgroundOpaque = opaque;
+    if(!opaque) {
+        if(transparentValueRed<0)
+            transparentValueRed = ( 1 << ( getRedBits() - 1 ) )  - 1 ;
+        if(transparentValueGreen<0)
+            transparentValueGreen = ( 1 << ( getGreenBits() - 1 ) )  - 1 ;
+        if(transparentValueBlue<0)
+            transparentValueBlue = ( 1 << ( getBlueBits() - 1 ) )  - 1 ;
+        if(transparentValueAlpha<0)
+            transparentValueAlpha = ( 1 << ( getAlphaBits() - 1 ) )  - 1 ;
+    }
+  }
+
+  /** Indicates whether the background of this OpenGL context should
+      be considered opaque. Defaults to true.
+
+      @see #setBackgroundOpaque
+  */
+  public boolean isBackgroundOpaque() {
+    return backgroundOpaque;
+  }
+
+  /** Gets the transparent red value for the frame buffer configuration.
+    * This value is undefined if {@link #isBackgroundOpaque()} equals true.
+    * @see #setTransparentRedValue
+    */
+  public int getTransparentRedValue() { return transparentValueRed; }
+
+  /** Gets the transparent green value for the frame buffer configuration.
+    * This value is undefined if {@link #isBackgroundOpaque()} equals true.
+    * @see #setTransparentGreenValue
+    */
+  public int getTransparentGreenValue() { return transparentValueGreen; }
+
+  /** Gets the transparent blue value for the frame buffer configuration.
+    * This value is undefined if {@link #isBackgroundOpaque()} equals true.
+    * @see #setTransparentBlueValue
+    */
+  public int getTransparentBlueValue() { return transparentValueBlue; }
+
+  /** Gets the transparent alpha value for the frame buffer configuration.
+    * This value is undefined if {@link #isBackgroundOpaque()} equals true.
+    * @see #setTransparentAlphaValue
+    */
+  public int getTransparentAlphaValue() { return transparentValueAlpha; }
+
+  /** Sets the transparent red value for the frame buffer configuration,
+      ranging from 0 to the maximum frame buffer value for red.
+      This value is ignored if {@link #isBackgroundOpaque()} equals true.<br>
+      It defaults to half of the frambuffer value for red. <br>
+      A value of -1 is interpreted as any value. */
+  public void setTransparentRedValue(int transValueRed) { transparentValueRed=transValueRed; }
+
+  /** Sets the transparent green value for the frame buffer configuration,
+      ranging from 0 to the maximum frame buffer value for green.
+      This value is ignored if {@link #isBackgroundOpaque()} equals true.<br>
+      It defaults to half of the frambuffer value for green.<br>
+      A value of -1 is interpreted as any value. */
+  public void setTransparentGreenValue(int transValueGreen) { transparentValueGreen=transValueGreen; }
+
+  /** Sets the transparent blue value for the frame buffer configuration,
+      ranging from 0 to the maximum frame buffer value for blue.
+      This value is ignored if {@link #isBackgroundOpaque()} equals true.<br>
+      It defaults to half of the frambuffer value for blue.<br>
+      A value of -1 is interpreted as any value. */
+  public void setTransparentBlueValue(int transValueBlue) { transparentValueBlue=transValueBlue; }
+
+  /** Sets the transparent alpha value for the frame buffer configuration,
+      ranging from 0 to the maximum frame buffer value for alpha.
+      This value is ignored if {@link #isBackgroundOpaque()} equals true.<br>
+      It defaults to half of the frambuffer value for alpha.<br>
+      A value of -1 is interpreted as any value. */
+  public void setTransparentAlphaValue(int transValueAlpha) { transparentValueAlpha=transValueAlpha; }
+
+
   /** Returns a textual representation of this Capabilities
       object. */ 
   public String toString() {
-    return getClass().toString()+"[" +
-	    "Red: " + redBits +
+    StringBuffer msg = new StringBuffer();
+    msg.append("Capabilities[");
+	msg.append("Red: " + redBits +
 	    ", Green: " + greenBits +
 	    ", Blue: " + blueBits +
 	    ", Alpha: " + alphaBits +
-	    " ]";
+        ", Opaque: " + backgroundOpaque);
+    if(!backgroundOpaque) {
+        msg.append(", Transparent RGBA: [0x"+ Integer.toHexString(transparentValueRed)+
+                   " 0x"+ Integer.toHexString(transparentValueGreen)+
+                   " 0x"+ Integer.toHexString(transparentValueBlue)+
+                   " 0x"+ Integer.toHexString(transparentValueAlpha)+"] ");
+    }
+	msg.append("]");
+    return msg.toString();
   }
 }
diff --git a/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesChooser.java b/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesChooser.java
index 4d99216f0..246aeb03e 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesChooser.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/CapabilitiesChooser.java
@@ -42,7 +42,7 @@ package javax.media.nativewindow;
 /** Provides a mechanism by which applications can customize the
     window type selection for a given {@link Capabilities}.
     Developers can implement this interface and pass an instance into
-    the appropriate method of {@link NativeWindowFactory}; the chooser
+    the method {@link GraphicsConfigurationFactory#chooseGraphicsConfiguration}; the chooser
     will be called at window creation time, on some platforms. */
 
 public interface CapabilitiesChooser {
@@ -56,10 +56,9 @@ public interface CapabilitiesChooser {
       not necessarily required, that the chooser select that entry.
 
       <P> <em>Note:</em> this method is called automatically by the
-      {@link NativeWindowFactory} when an instance of this class is
-      passed in to its {@link
-      NativeWindowFactory#chooseGraphicsConfiguration
-      chooseGraphicsConfiguration} method. It should generally not be
+      {@link GraphicsConfigurationFactory#chooseGraphicsConfiguration} method 
+      when an instance of this class is passed in to it.
+      It should generally not be
       invoked by users directly, unless it is desired to delegate the
       choice to some other CapabilitiesChooser object.
   */
diff --git a/src/nativewindow/classes/javax/media/nativewindow/DefaultGraphicsConfiguration.java b/src/nativewindow/classes/javax/media/nativewindow/DefaultGraphicsConfiguration.java
index 7aba7e171..f5448dfa7 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/DefaultGraphicsConfiguration.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/DefaultGraphicsConfiguration.java
@@ -34,11 +34,14 @@ package javax.media.nativewindow;
 
 public class DefaultGraphicsConfiguration implements Cloneable, AbstractGraphicsConfiguration {
     private AbstractGraphicsScreen screen;
-    private Capabilities capabilities;
+    private Capabilities capabilitiesChosen;
+    private Capabilities capabilitiesRequested;
 
-    public DefaultGraphicsConfiguration(AbstractGraphicsScreen screen, Capabilities caps) {
+    public DefaultGraphicsConfiguration(AbstractGraphicsScreen screen, 
+                                        Capabilities capsChosen, Capabilities capsRequested) {
         this.screen = screen;
-        this.capabilities = caps;
+        this.capabilitiesChosen = capsChosen;
+        this.capabilitiesRequested = capsRequested;
     }
 
     public Object clone() {
@@ -53,8 +56,12 @@ public class DefaultGraphicsConfiguration implements Cloneable, AbstractGraphics
         return screen;
     }
 
-    public Capabilities getCapabilities() {
-        return (Capabilities)capabilities.clone();
+    public Capabilities getChosenCapabilities() {
+        return (Capabilities)capabilitiesChosen.clone();
+    }
+
+    public Capabilities getRequestedCapabilities() {
+        return (Capabilities)capabilitiesRequested.clone();
     }
 
     public AbstractGraphicsConfiguration getNativeGraphicsConfiguration() {
@@ -63,17 +70,31 @@ public class DefaultGraphicsConfiguration implements Cloneable, AbstractGraphics
 
     /**
      * Set the capabilities to a new value.
-     * Despite the architecture's goal to gather this data upfront,
-     * on some platforms we can gather the info only after the window creation..
-     * However, if you can, please use {@link GraphicsConfigurationFactory GraphicsConfigurationFactory}.
+     *
+     * The use case for setting the Capabilities at a later time is
+     * a change of the graphics device in a multi-screen environment.<br>
+     *
+     * A copy of the passed object is being used.
      *
      * @see javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)
      */
-    protected void setCapabilities(Capabilities caps) {
-        capabilities = (Capabilities) caps.clone();
+    protected void setChosenCapabilities(Capabilities capsChosen) {
+        capabilitiesChosen = (Capabilities) capsChosen.clone();
+    }
+
+    /**
+     * Set a new screen.
+     *
+     * the use case for setting a new screen at a later time is
+     * a change of the graphics device in a multi-screen environment.<br>
+     *
+     * A copy of the passed object is being used.
+     */
+    protected void setScreen(DefaultGraphicsScreen screen) {
+        this.screen = (AbstractGraphicsScreen) screen.clone();
     }
 
     public String toString() {
-        return getClass().toString()+"[" + screen +", "+ capabilities +"]";
+        return getClass().toString()+"[" + screen +", "+ capabilitiesChosen +"]";
     }
 }
diff --git a/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java b/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java
index ab0255c86..686360726 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/GraphicsConfigurationFactory.java
@@ -40,7 +40,7 @@ import com.sun.nativewindow.impl.*;
 /**
  * Provides the mechanism by which the graphics configuration for a
  * given window can be chosen before the window is created. On some
- * window systems (X11 in particular) the graphics configuration
+ * window systems (EGL/OpenKODE and X11 in particular) the graphics configuration
  * decides parameters related to hardware accelerated rendering such
  * as the OpenGL pixel format. On these platforms it is necessary to
  * choose the graphics configuration early. Note that the selection of
@@ -172,7 +172,7 @@ public abstract class GraphicsConfigurationFactory {
      * Here the validation of the capabilities is performed later.
      * In this case, the AbstractGraphicsConfiguration implementation 
      * must allow an overwrite of the Capabilites, for example
-     * {@link DefaultGraphicsConfiguration#setCapabilities DefaultGraphicsConfiguration.setCapabilities()}.
+     * {@link DefaultGraphicsConfiguration#setChosenCapabilities DefaultGraphicsConfiguration.setChosenCapabilities(..)}.
      * </P>
      *
      * <P>
@@ -183,8 +183,8 @@ public abstract class GraphicsConfigurationFactory {
      * returned graphics configuration must be specified in the
      * documentation binding this particular API to the underlying
      * window toolkit. The Reference Implementation accepts {@link
-     * AWTGraphicsDevice AWTGraphicsDevice} objects and returns {@link
-     * AWTGraphicsConfiguration AWTGraphicsConfiguration} objects. On
+     * javax.media.nativewindow.awt.AWTGraphicsDevice AWTGraphicsDevice} objects and returns {@link
+     * javax.media.nativewindow.awt.AWTGraphicsConfiguration AWTGraphicsConfiguration} objects. On
      * X11 platforms where the AWT is not in use, it also accepts
      * {@link javax.media.nativewindow.x11.X11GraphicsDevice
      * X11GraphicsDevice} objects and returns {@link
@@ -198,7 +198,7 @@ public abstract class GraphicsConfigurationFactory {
      *         the selection of the graphics configuration to fail.
      *
      * @see javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration(Capabilities, CapabilitiesChooser, AbstractGraphicsScreen)
-     * @see javax.media.nativewindow.DefaultGraphicsConfiguration#setCapabilities(Capabilities caps)
+     * @see javax.media.nativewindow.DefaultGraphicsConfiguration#setChosenCapabilities(Capabilities caps)
      */
     public abstract AbstractGraphicsConfiguration
         chooseGraphicsConfiguration(Capabilities capabilities,
diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java b/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
index f55815aaa..ea053e317 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeWindow.java
@@ -52,24 +52,53 @@ package javax.media.nativewindow;
     it, and any time it is visible and locked, provide information
     such as the window handle.
 */
-
 public interface NativeWindow {
-  public static final int LOCK_NOT_SUPPORTED = 0;
+  /** Returned by {@link #lockSurface()} if the surface is not ready to be locked. */
   public static final int LOCK_SURFACE_NOT_READY = 1;
+
+  /** Returned by {@link #lockSurface()} if the surface is locked, but has changed. */
   public static final int LOCK_SURFACE_CHANGED = 2;
+
+  /** Returned by {@link #lockSurface()} if the surface is locked, and is unchanged. */
   public static final int LOCK_SUCCESS = 3;
 
   /**
-   * Lock this surface
+   * Lock the surface of this native window<P>
+   *
+   * The window handle, see {@link #getWindowHandle()},
+   * and the surface handle, see {@link #lockSurface()}, <br>
+   * shall be set and be valid after a successfull call,
+   * ie a return value other than {@link #LOCK_SURFACE_NOT_READY}.<P>
+   *
+   * @return {@link #LOCK_SUCCESS}, {@link #LOCK_SURFACE_CHANGED} or {@link #LOCK_SURFACE_NOT_READY}.
+   *
+   * @throws NativeWindowException if surface is already locked
    */
   public int lockSurface() throws NativeWindowException ;
 
   /**
-   * Unlock this surface
+   * Unlock the surface of this native window
+   *
+   * Shall not modify the window handle, see {@link #getWindowHandle()},
+   * or the surface handle, see {@link #lockSurface()} <P>
+   *
+   * @throws NativeWindowException if surface is not locked
+   */
+  public void unlockSurface() throws NativeWindowException ;
+
+  /**
+   * Return if surface is locked
    */
-  public void unlockSurface();
   public boolean isSurfaceLocked();
 
+  /**
+   * Return the lock-exception, or null if not locked.
+   *
+   * The lock-exception is created at {@link #lockSurface()}
+   * and hence holds the locker's call stack.
+   */
+  public Exception getLockedStack();
+
   /** 
    * render all native window information invalid,
    * as if the native window was destroyed
@@ -79,6 +108,11 @@ public interface NativeWindow {
   /**
    * Returns the window handle for this NativeWindow. <P>
    *
+   * The window handle should be set/update by {@link #lockSurface()},
+   * where {@link #unlockSurface()} is not allowed to modify it.<br>
+   * After {@link #unlockSurface()} it is no more guaranteed 
+   * that the window handle is still valid.<p>
+   *
    * The window handle shall reflect the platform one 
    * for all window related operations, e.g. open, close, resize. <P>
    *
@@ -90,6 +124,11 @@ public interface NativeWindow {
   /**
    * Returns the handle to the surface for this NativeWindow. <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>
    *
diff --git a/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java b/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java
index d14800e30..5de4622f2 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/NativeWindowFactory.java
@@ -64,88 +64,92 @@ public abstract class NativeWindowFactory {
     public static final String TYPE_DEFAULT = "default";
 
     private static NativeWindowFactory defaultFactory;
-    private static Map/*<Class, NativeWindowFactory>*/ registeredFactories =
-        Collections.synchronizedMap(new HashMap());
+    private static Map/*<Class, NativeWindowFactory>*/ registeredFactories;
     private static Class nativeWindowClass;
-    private static String nativeWindowingType=null;
+    private static String nativeWindowingTypePure;
+    private static String nativeOSNamePure;
+    private static String nativeWindowingTypeCustom;
+    private static String nativeOSNameCustom;
 
     /** Creates a new NativeWindowFactory instance. End users do not
         need to call this method. */
     protected NativeWindowFactory() {
     }
 
-    private static boolean initialized = false;
-    private static void initialize() {
-        synchronized (NativeWindowFactory.class) {
-            if (initialized) {
-                return;
+    private static String _getNativeWindowingType(String osNameLowerCase) {
+        if (osNameLowerCase.startsWith("kd")) {
+              return TYPE_EGL;
+        } else if (osNameLowerCase.startsWith("wind")) {
+              return TYPE_WINDOWS;
+        } else if (osNameLowerCase.startsWith("mac os x") ||
+                     osNameLowerCase.startsWith("darwin")) {
+              return TYPE_MACOSX;
+        } else if (osNameLowerCase.equals("awt")) {
+              return TYPE_AWT;
+        } else {
+              return TYPE_X11;
+        }
+    }
+
+    static {
+        // Gather the windowing OS first
+        nativeOSNamePure = System.getProperty("os.name");
+        nativeOSNameCustom = System.getProperty("nativewindow.ws.name");
+        if(null==nativeOSNameCustom||nativeOSNameCustom.length()==0) {
+              nativeOSNameCustom = nativeOSNamePure;
+        }
+        nativeWindowingTypePure = _getNativeWindowingType(nativeOSNamePure.toLowerCase());
+        nativeWindowingTypeCustom = _getNativeWindowingType(nativeOSNameCustom.toLowerCase());
+
+        registeredFactories = Collections.synchronizedMap(new HashMap());
+
+        String factoryClassName = null;
+
+        // We break compile-time dependencies on the AWT here to
+        // make it easier to run this code on mobile devices
+
+        NativeWindowFactory factory = new NativeWindowFactoryImpl();
+        nativeWindowClass = javax.media.nativewindow.NativeWindow.class;
+        registerFactory(nativeWindowClass, factory);
+        defaultFactory = factory;
+    
+        Class componentClass = null;
+        try {
+            componentClass = Class.forName("java.awt.Component");
+        } catch (Exception e) { }
+
+        if(TYPE_X11.equals(nativeWindowingTypeCustom)) {
+            // Assume X11 platform -- should probably test for these explicitly
+            NativeWindowFactory _factory = null;
+            if (componentClass != null) {
+                try {
+                    Constructor factoryConstructor =
+                        NWReflection.getConstructor("com.sun.nativewindow.impl.x11.awt.X11AWTNativeWindowFactory", new Class[] {});
+                    _factory = (NativeWindowFactory) factoryConstructor.newInstance(null);
+                } catch (Exception e) { }
+            }
+            if (null ==_factory) {
+                // Try the non-AWT X11 native window factory
+                try {
+                    Constructor factoryConstructor =
+                        NWReflection.getConstructor("com.sun.nativewindow.impl.x11.X11NativeWindowFactory", new Class[] {});
+                    _factory = (NativeWindowFactory) factoryConstructor.newInstance(null);
+                } catch (Exception e) { }
             }
-            initialized = true;
-
-            String factoryClassName = null;
-
-            // We break compile-time dependencies on the AWT here to
-            // make it easier to run this code on mobile devices
-
-            NativeWindowFactory factory = new NativeWindowFactoryImpl();
-            nativeWindowClass = javax.media.nativewindow.NativeWindow.class;
-            registerFactory(nativeWindowClass, factory);
-            defaultFactory = factory;
-        
-            Class componentClass = null;
-            try {
-                componentClass = Class.forName("java.awt.Component");
-            } catch (Exception e) { }
-
-            if(TYPE_X11.equals(getNativeWindowType(true))) {
-                // Assume X11 platform -- should probably test for these explicitly
-                NativeWindowFactory _factory = null;
-                if (componentClass != null) {
-                    try {
-                        Constructor factoryConstructor =
-                            NWReflection.getConstructor("com.sun.nativewindow.impl.x11.awt.X11AWTNativeWindowFactory", new Class[] {});
-                        _factory = (NativeWindowFactory) factoryConstructor.newInstance(null);
-                    } catch (Exception e) { }
-                }
-                if (null ==_factory) {
-                    // Try the non-AWT X11 native window factory
-                    try {
-                        Constructor factoryConstructor =
-                            NWReflection.getConstructor("com.sun.nativewindow.impl.x11.X11NativeWindowFactory", new Class[] {});
-                        _factory = (NativeWindowFactory) factoryConstructor.newInstance(null);
-                    } catch (Exception e) { }
-                }
-                if (null !=_factory) {
-                    factory = _factory;
-                }
+            if (null !=_factory) {
+                factory = _factory;
             }
-            registerFactory(componentClass, factory);
-            defaultFactory = factory;
         }
+        registerFactory(componentClass, factory);
+        defaultFactory = factory;
+    }
+
+    public static String getNativeOSName(boolean useCustom) {
+        return useCustom?nativeOSNameCustom:nativeOSNamePure;
     }
 
     public static String getNativeWindowType(boolean useCustom) {
-      if(null==nativeWindowingType) {
-          String osName = useCustom?System.getProperty("nativewindow.ws.name"):null;
-          if(null==osName||osName.length()==0) {
-              osName = System.getProperty("os.name");
-          }
-          String osNameLowerCase = osName.toLowerCase();
-          String windowType;
-          if (osNameLowerCase.startsWith("kd")) {
-              nativeWindowingType = NativeWindowFactory.TYPE_EGL;
-          } else if (osNameLowerCase.startsWith("wind")) {
-              nativeWindowingType = NativeWindowFactory.TYPE_WINDOWS;
-          } else if (osNameLowerCase.startsWith("mac os x") ||
-                     osNameLowerCase.startsWith("darwin")) {
-              nativeWindowingType = NativeWindowFactory.TYPE_MACOSX;
-          } else if (useCustom && osNameLowerCase.equals("awt")) {
-              nativeWindowingType = NativeWindowFactory.TYPE_AWT;
-          } else {
-              nativeWindowingType = NativeWindowFactory.TYPE_X11;
-          }
-      }
-      return nativeWindowingType;
+        return useCustom?nativeWindowingTypeCustom:nativeWindowingTypePure;
     }
 
     /** Sets the default NativeWindowFactory. Certain operations on
@@ -160,7 +164,6 @@ public abstract class NativeWindowFactory {
         within the Java binding to OpenGL. By default, if the AWT is
         available, the default toolkit will support the AWT. */
     public static void setDefaultFactory(NativeWindowFactory factory) {
-        initialize();
         defaultFactory = factory;
     }
 
@@ -176,7 +179,6 @@ public abstract class NativeWindowFactory {
         within the Java binding to OpenGL. By default, if the AWT is
         available, the default toolkit will support the AWT. */
     public static NativeWindowFactory getDefaultFactory() {
-        initialize();
         return defaultFactory;
     }
 
@@ -187,7 +189,6 @@ public abstract class NativeWindowFactory {
         NativeWindow implementation, or it might be that of a toolkit
         class like {@link java.awt.Component Component}. */
     public static NativeWindowFactory getFactory(Class windowClass) throws IllegalArgumentException {
-        initialize();
         if (nativeWindowClass.isAssignableFrom(windowClass)) {
             return (NativeWindowFactory) registeredFactories.get(nativeWindowClass);
         }
@@ -206,22 +207,21 @@ public abstract class NativeWindowFactory {
         given class. This does not need to be called by end users,
         only implementors of new NativeWindowFactory subclasses. */
     protected static void registerFactory(Class windowClass, NativeWindowFactory factory) {
-        initialize();
         registeredFactories.put(windowClass, factory);
     }
 
-    /** Converts the given window object and it's optional
+    /** Converts the given window object and it's
         {@link AbstractGraphicsConfiguration AbstractGraphicsConfiguration} into a 
-        {@link NativeWindow NativeWindow} which can be operated upon by the 
-        {@link GLDrawableFactory GLDrawableFactory}. The object may be a
-        component for a particular window toolkit, such as an AWT
-        Canvas. In this case {@link AbstractGraphicsConfiguration AbstractGraphicsConfiguration}
-        must be valid. It may also be a NativeWindow object, in which no
-        conversion is necessary and {@link AbstractGraphicsConfiguration AbstractGraphicsConfiguration}
-        will be ignored. The particular implementation of the
+        {@link NativeWindow NativeWindow} which can be operated upon by a custom
+        toolkit, e.g. {@link javax.media.opengl.GLDrawableFactory javax.media.opengl.GLDrawableFactory}.<br>
+        The object may be a component for a particular window toolkit, such as an AWT
+        Canvas.  It may also be a NativeWindow object itself.<br>
+        You shall utilize {@link javax.media.nativewindow.GraphicsConfigurationFactory GraphicsConfigurationFactory}
+        to construct a proper {@link AbstractGraphicsConfiguration AbstractGraphicsConfiguration}.<br>
+        The particular implementation of the
         NativeWindowFactory is responsible for handling objects from a
         particular window toolkit. The built-in NativeWindowFactory
-        handles NativeWindow instances as well as AWT Components.
+        handles NativeWindow instances as well as AWT Components.<br>
     
         @throws IllegalArgumentException if the given window object
         could not be handled by any of the registered
diff --git a/src/nativewindow/classes/javax/media/nativewindow/awt/AWTGraphicsConfiguration.java b/src/nativewindow/classes/javax/media/nativewindow/awt/AWTGraphicsConfiguration.java
index 89af0c6f6..56d5c5ce9 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/awt/AWTGraphicsConfiguration.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/awt/AWTGraphicsConfiguration.java
@@ -41,7 +41,10 @@ package javax.media.nativewindow.awt;
 
 import javax.media.nativewindow.*;
 import java.awt.GraphicsConfiguration;
+import java.awt.Transparency;
+import java.awt.image.ColorModel;
 import javax.media.nativewindow.AbstractGraphicsConfiguration;
+import com.sun.nativewindow.impl.Debug;
 
 /** A wrapper for an AWT GraphicsConfiguration allowing it to be
     handled in a toolkit-independent manner. */
@@ -50,14 +53,16 @@ public class AWTGraphicsConfiguration extends DefaultGraphicsConfiguration imple
   private GraphicsConfiguration config;
   AbstractGraphicsConfiguration encapsuled;
 
-  public AWTGraphicsConfiguration(AWTGraphicsScreen screen, Capabilities caps, GraphicsConfiguration config, AbstractGraphicsConfiguration encapsuled) {
-    super(screen, caps);
+  public AWTGraphicsConfiguration(AWTGraphicsScreen screen, 
+                                  Capabilities capsChosen, Capabilities capsRequested,
+                                  GraphicsConfiguration config, AbstractGraphicsConfiguration encapsuled) {
+    super(screen, capsChosen, capsRequested);
     this.config = config;
     this.encapsuled=encapsuled;
   }
 
-  public AWTGraphicsConfiguration(AWTGraphicsScreen screen, Capabilities caps, GraphicsConfiguration config) {
-    super(screen, caps);
+  public AWTGraphicsConfiguration(AWTGraphicsScreen screen, Capabilities capsChosen, Capabilities capsRequested, GraphicsConfiguration config) {
+    super(screen, capsChosen, capsRequested);
     this.config = config;
     this.encapsuled=null;
   }
@@ -74,7 +79,46 @@ public class AWTGraphicsConfiguration extends DefaultGraphicsConfiguration imple
     return (null!=encapsuled)?encapsuled:this;
   }
 
+  /**
+   * Setup the Capabilities RGBA size in regard to the given GraphicsConfiguration ColorModel
+   */
+  public static Capabilities SetupCapabilitiesPixelformat(Capabilities capabilities, GraphicsConfiguration gc) {
+    int cmTransparency = capabilities.isBackgroundOpaque()?Transparency.OPAQUE:Transparency.TRANSLUCENT;
+    ColorModel cm = gc.getColorModel(cmTransparency);
+    if(null==cm && !capabilities.isBackgroundOpaque()) {
+        capabilities.setBackgroundOpaque(true);
+        cmTransparency = Transparency.OPAQUE;
+        cm = gc.getColorModel(cmTransparency);
+    }
+    if(null==cm) {
+        throw new NativeWindowException("Could not determine AWT ColorModel");
+    }
+    int cmBitsPerPixel = cm.getPixelSize();
+    int bitsPerPixel = 0;
+    int[] bitesPerComponent = cm.getComponentSize();
+    if(bitesPerComponent.length>=3) {
+        capabilities.setRedBits(bitesPerComponent[0]);
+        bitsPerPixel += bitesPerComponent[0];
+        capabilities.setGreenBits(bitesPerComponent[1]);
+        bitsPerPixel += bitesPerComponent[1];
+        capabilities.setBlueBits(bitesPerComponent[2]);
+        bitsPerPixel += bitesPerComponent[2];
+    }
+    if(bitesPerComponent.length>=4) {
+        capabilities.setAlphaBits(bitesPerComponent[3]);
+        bitsPerPixel += bitesPerComponent[3];
+    } else {
+        capabilities.setAlphaBits(0);
+    }
+    if(Debug.debugAll()) {
+        if(cmBitsPerPixel!=bitsPerPixel) {
+            System.err.println("AWT Colormodel bits per components/pixel mismatch: "+bitsPerPixel+" != "+cmBitsPerPixel);
+        }
+    }
+    return capabilities;
+  }
+
   public String toString() {
-    return getClass().toString()+"[" + getScreen() + ", " + getCapabilities() + ", " + config +", encapsuled "+encapsuled+"]";
+    return getClass().toString()+"[" + getScreen() + ", " + getChosenCapabilities() + ", " + config +", encapsuled "+encapsuled+"]";
   }
 }
diff --git a/src/nativewindow/classes/javax/media/nativewindow/package.html b/src/nativewindow/classes/javax/media/nativewindow/package.html
new file mode 100644
index 000000000..ce9dbbb7a
--- /dev/null
+++ b/src/nativewindow/classes/javax/media/nativewindow/package.html
@@ -0,0 +1,111 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+  <title>NativeWindow Protocol Draft Public Review Specification</title>
+</head>
+  <body>
+   
+<h2><i>NativeWindow Protocol</i> Specification Overview</h2>
+   
+<h3>Preface</h3>
+  This specification, an optional set of packages, describing a <i>protocol</i> for a 
+  <i>native windowing interface</i> binding to Java(TM).<br>
+  Currently specified <i>native windowing systems</i> are:<br><br>
+  <ul>
+    <li> EGL/OpenKODE Windowing System</li>
+    <li> X11 Windowing System</li>
+    <li> Microsoft Windows</li>
+    <li> Apple MacOSX</li>
+    <li> Java's AWT</li>
+  </ul>
+  <br>
+  However, any other native windowing system may be added to the implementation,
+  using a generic string identifier and an optional specialisation of:<br><br>
+  <ul>
+    <li>{@link javax.media.nativewindow.AbstractGraphicsDevice AbstractGraphicsDevice},<br>
+       <br>
+       Shall return the new string identifier with {@link javax.media.nativewindow.AbstractGraphicsDevice#getType() getType()}</li><br>
+    <li>{@link javax.media.nativewindow.AbstractGraphicsScreen AbstractGraphicsScreen}</li>
+    <li>{@link javax.media.nativewindow.AbstractGraphicsConfiguration AbstractGraphicsConfiguration}</li><br>
+  </ul>
+  <br>
+  The implementor has to provide the following:<br><br>
+  <ul>
+    <li> The specialisation of the abstract class {@link javax.media.nativewindow.NativeWindowFactory NativeWindowFactory}<br>
+         <br>
+         shall be registered with {@link javax.media.nativewindow.NativeWindowFactory#registerFactory NativeWindowFactory.registerFactory(..)}.</li><br>
+
+    <li> The specialisation of the abstract class {@link javax.media.nativewindow.GraphicsConfigurationFactory GraphicsConfigurationFactory}<br>
+         <br>
+         shall be registered with {@link javax.media.nativewindow.GraphicsConfigurationFactory#registerFactory GraphicsConfigurationFactory.registerFactory(..)}.</li><br>
+  </ul><br>
+  This protocol <i>does not</i> describe how to <i>create</i> native windows, but how to <i>bind</i> a native window to an implementation of
+  {@link javax.media.nativewindow.NativeWindow NativeWindow}.<br>
+  However, an implementation of this protocol (e.g. {@link com.sun.javafx.newt}) may support the creation.<br>
+   
+<h3>Dependencies</h3>
+  This binding has dependencies to the following:<br><br>
+  <ul>
+    <li> Either of the following Java implementations:<br>
+    <ul>
+        <li> <a href="http://java.sun.com/j2se/1.4.2/docs/api/">Java SE 1.4 or later</a> </li><br>
+        <li> <a href="http://java.sun.com/javame/technology/cdc/">Java ME CDC 1.1.2 (JSR 218)</a> and 
+             <a href="http://java.sun.com/products/foundation/">Foundation Profile 1.1.2 (JSR 219)</a><br>
+             and either of the following <i>java.nio</i> implementations:<br>
+             <ul>
+                <li> <a href="http://java.sun.com/javame/reference/apis/jsr239/java/nio/package-summary.html"> JSR239 <i>java.nio</i> subset</a> </li>
+                <li> <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/package-summary.html"> Java 1.4 <i>java.nio</i> implementation</a> </li>
+             </ul><br>
+    </ul>    
+  </ul>
+  <br>
+
+<h3>Package Structure</h3>
+  The packages defined by this specification include:<br><br>
+<ul>
+    <li>The <b>javax.media.nativewindow</b> package<br>
+      <br>
+  This package contains Java bindings for a native windowing system.<br>
+  Subsequent packages contain marker type classes, containing native characteristics of the windowing system.</li><br><br>
+  <ul>
+    <li>The <b>javax.media.nativewindow.awt</b> package<br>
+      <br>
+  This sub package contains classes to cover the native characteristics of the AWT windowing system.</li><br>
+
+    <li>The <b>javax.media.nativewindow.x11</b> package<br>
+      <br>
+  This sub package contains classes to cover the native characteristics of the X11 windowing system.</li><br>
+
+    <li>The <b>javax.media.nativewindow.windows</b> package<br>
+      <br>
+  This sub package contains classes to cover the native characteristics of the Windows windowing system.</li><br>
+
+    <li>The <b>javax.media.nativewindow.macosx</b> package<br>
+      <br>
+  This sub package contains classes to cover the native characteristics of the MacOSX windowing system.</li><br>
+
+    <li>The <b>javax.media.nativewindow.egl</b> package<br>
+      <br>
+  This sub package contains classes to cover the native characteristics of the EGL/OpenKODE windowing system.</li><br>
+  </ul>
+</ul>
+
+<h3>Factory Model</h3>
+Running on a platform with a supported windowing system, the factory model shall be used
+to instantiate a native window, see {@link javax.media.nativewindow.NativeWindowFactory NativeWindowFactory}.<br>
+The implementor has to specialize 
+All supported 
+Regardless of the knowledge of the underly
+<br>
+
+<h3>Revision History<br>
+  </h3>
+   
+<ul>
+<li> Early Draft Review, June 2009
+</ul>
+  <br>
+  <br>
+ <br>
+</body>
+</html>
diff --git a/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsConfiguration.java b/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsConfiguration.java
index 8784033bc..9c2351cc4 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsConfiguration.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsConfiguration.java
@@ -37,15 +37,17 @@ import com.sun.nativewindow.impl.x11.XVisualInfo;
 
 /** Encapsulates a graphics configuration, or OpenGL pixel format, on
     X11 platforms. Objects of this type are returned from {@link
-    NativeWindowFactory#chooseGraphicsConfiguration
-    NativeWindowFactory.chooseGraphicsConfiguration()} on X11
+    javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration
+    GraphicsConfigurationFactory.chooseGraphicsConfiguration()} on X11
     platforms when toolkits other than the AWT are being used.  */
 
 public class X11GraphicsConfiguration extends DefaultGraphicsConfiguration implements Cloneable {
     private XVisualInfo info;
 
-    public X11GraphicsConfiguration(X11GraphicsScreen screen, Capabilities caps, XVisualInfo info) {
-        super(screen, caps);
+    public X11GraphicsConfiguration(X11GraphicsScreen screen, 
+                                    Capabilities capsChosen, Capabilities capsRequested,
+                                    XVisualInfo info) {
+        super(screen, capsChosen, capsRequested);
         this.info = info;
     }
 
@@ -57,11 +59,15 @@ public class X11GraphicsConfiguration extends DefaultGraphicsConfiguration imple
         return info;
     }
 
+    protected void setXVisualInfo(XVisualInfo info) {
+        this.info = info;
+    }
+
     public long getVisualID() {
         return (null!=info)?info.visualid():0;
     }
     
     public String toString() {
-        return getClass().toString()+"["+getScreen()+", visualID 0x" + Long.toHexString(getVisualID()) + ", " + getCapabilities() +"]";
+        return getClass().toString()+"["+getScreen()+", visualID 0x" + Long.toHexString(getVisualID()) + ", " + getChosenCapabilities() +"]";
     }
 }
diff --git a/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsScreen.java b/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsScreen.java
index 1dcc7f026..afee33688 100644
--- a/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsScreen.java
+++ b/src/nativewindow/classes/javax/media/nativewindow/x11/X11GraphicsScreen.java
@@ -38,8 +38,8 @@ import com.sun.nativewindow.impl.x11.*;
 
 /** Encapsulates a screen index on X11
     platforms. Objects of this type are passed to {@link
-    NativeWindowFactory#chooseGraphicsConfiguration
-    NativeWindowFactory.chooseGraphicsConfiguration()} on X11
+    javax.media.nativewindow.GraphicsConfigurationFactory#chooseGraphicsConfiguration
+    GraphicsConfigurationFactory.chooseGraphicsConfiguration()} on X11
     platforms when toolkits other than the AWT are being used.  */
 
 public class X11GraphicsScreen extends DefaultGraphicsScreen implements Cloneable {