EGLGraphicsDevice: Cleanup and enhance API doc for clarity ...

5 files changed, 140 insertions, 37 deletions

diff --git a/src/jogl/classes/jogamp/opengl/egl/EGLDisplayUtil.java b/src/jogl/classes/jogamp/opengl/egl/EGLDisplayUtil.java
index 65ada6e09..e1c094b75 100644
--- a/src/jogl/classes/jogamp/opengl/egl/EGLDisplayUtil.java
+++ b/src/jogl/classes/jogamp/opengl/egl/EGLDisplayUtil.java
@@ -1,5 +1,5 @@
 /**
- * Copyright 2012 JogAmp Community. All rights reserved.
+ * Copyright 2012-2023 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:
@@ -418,13 +418,13 @@ public class EGLDisplayUtil {
      * <p>
      * Using the default {@link ToolkitLock}, via {@link NativeWindowFactory#getDefaultToolkitLock(String)}.
      * </p>
-     * @param nativeDisplayID
-     * @param connection
-     * @param unitID
+     * @param nativeDisplayID the existing native display ID
+     * @param connection the existing underlying native connection name
+     * @param unitID the unit ID
      * @return an uninitialized {@link EGLGraphicsDevice}
      */
     public static EGLGraphicsDevice eglCreateEGLGraphicsDevice(final long nativeDisplayID, final String connection, final int unitID)  {
-        return new EGLGraphicsDevice(nativeDisplayID, EGL.EGL_NO_DISPLAY, connection, unitID, eglLifecycleCallback);
+        return new EGLGraphicsDevice(nativeDisplayID, connection, unitID, eglLifecycleCallback);
     }
 
     /**
@@ -436,11 +436,11 @@ public class EGLDisplayUtil {
      * <p>
      * Using the default {@link ToolkitLock}, via {@link NativeWindowFactory#getDefaultToolkitLock(String)}.
      * </p>
-     * @param adevice
+     * @param aDevice valid {@link AbstractGraphicsDevice}'s native display ID, connection and unitID
      * @return an uninitialized {@link EGLGraphicsDevice}
      */
     public static EGLGraphicsDevice eglCreateEGLGraphicsDevice(final AbstractGraphicsDevice aDevice)  {
-        return new EGLGraphicsDevice(aDevice, EGL.EGL_NO_DISPLAY, eglLifecycleCallback);
+        return new EGLGraphicsDevice(aDevice, eglLifecycleCallback);
     }
 
     /**
@@ -463,6 +463,6 @@ public class EGLDisplayUtil {
             nativeDisplayID = surface.getDisplayHandle(); // 0 == EGL.EGL_DEFAULT_DISPLAY
         }
         final AbstractGraphicsDevice adevice = surface.getGraphicsConfiguration().getScreen().getDevice();
-        return new EGLGraphicsDevice(nativeDisplayID, EGL.EGL_NO_DISPLAY, adevice.getConnection(), adevice.getUnitID(), eglLifecycleCallback);
+        return new EGLGraphicsDevice(nativeDisplayID, adevice.getConnection(), adevice.getUnitID(), eglLifecycleCallback);
     }
 }
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/AbstractGraphicsDevice.java b/src/nativewindow/classes/com/jogamp/nativewindow/AbstractGraphicsDevice.java
index 7b630b1ea..3afb81d67 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/AbstractGraphicsDevice.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/AbstractGraphicsDevice.java
@@ -1,6 +1,6 @@
 /*
+ * Copyright (c) 2010-2023 JogAmp Community. All rights reserved.
  * Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved.
- * Copyright (c) 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
@@ -68,13 +68,15 @@ public interface AbstractGraphicsDevice extends Cloneable {
     /**
      * Returns the semantic GraphicsDevice connection.<br>
      * On platforms supporting remote devices, eg via tcp/ip network,
-     * the implementation shall return a unique name for each remote address.<br>
-     * On X11 for example, the connection string should be as the following example.<br>
+     * the implementation shall return a unique name for each remote address.
+     * <p>
+     * For {@link com.jogamp.nativewindow.x11.X11GraphicsDevice X11GraphicsDevice},
+     * the connection string should be as the follows
      * <ul>
      *   <li><code>:0.0</code> for a local connection</li>
      *   <li><code>remote.host.net:0.0</code> for a remote connection</li>
      * </ul>
-     *
+     * </p>
      * To support multiple local device, see {@link #getUnitID()}.
      */
     public String getConnection();
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/NativeWindowFactory.java b/src/nativewindow/classes/com/jogamp/nativewindow/NativeWindowFactory.java
index 29829be18..a7a022cda 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/NativeWindowFactory.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/NativeWindowFactory.java
@@ -1,6 +1,6 @@
 /*
+ * Copyright (c) 2010-2023 JogAmp Community. All rights reserved.
  * Copyright (c) 2008-2009 Sun Microsystems, Inc. All Rights Reserved.
- * Copyright (c) 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
@@ -43,6 +43,7 @@ import java.util.List;
 import java.util.Map;
 
 import com.jogamp.nativewindow.util.Point;
+
 import jogamp.common.os.PlatformPropsImpl;
 import jogamp.nativewindow.BcmVCArtifacts;
 import jogamp.nativewindow.Debug;
@@ -742,7 +743,7 @@ public abstract class NativeWindowFactory {
                     throw new NativeWindowException("EGLDisplayUtil.eglCreateEGLGraphicsDevice failed");
                 }
             } else {
-                device = new com.jogamp.nativewindow.egl.EGLGraphicsDevice(0, 0 /* EGL.EGL_NO_DISPLAY */, displayConnection, AbstractGraphicsDevice.DEFAULT_UNIT, null);
+                device = new com.jogamp.nativewindow.egl.EGLGraphicsDevice(0 /* EGL.EGL_DEFAULT_DISPLAY */, displayConnection, AbstractGraphicsDevice.DEFAULT_UNIT);
             }
             return device;
         } else if( NativeWindowFactory.TYPE_AWT == nwt ) {
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java b/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java
index 320c0ec75..fc58f4140 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/egl/EGLGraphicsDevice.java
@@ -1,4 +1,5 @@
 /*
+ * Copyright (c) 2010-2023 JogAmp Community. All rights reserved.
  * Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -38,9 +39,15 @@ import com.jogamp.nativewindow.DefaultGraphicsDevice;
 import com.jogamp.nativewindow.NativeWindowException;
 import com.jogamp.nativewindow.NativeWindowFactory;
 
-/** Encapsulates a graphics device on EGL platforms.
+/**
+ * Encapsulates a graphics device on EGL platforms.
  */
 public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneable {
+    /** EGL default native display ID */
+    public static final int EGL_DEFAULT_DISPLAY = 0;
+    /** EGL no display handle */
+    public static final int EGL_NO_DISPLAY = 0;
+
     private final long[] nativeDisplayID = new long[1];
     private /* final */ EGLDisplayLifecycleCallback eglLifecycleCallback;
     private VersionNumber eglVersion = VersionNumber.zeroVersion;
@@ -71,38 +78,134 @@ public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
     }
 
     /**
-     * Note that this is not an open connection, ie no native display handle exist.
-     * This constructor exist to setup a default device connection/unit.<br>
+     * Returns the native display ID of the given abstract device,
+     * i.e. either {@link EGLGraphicsDevice#getNativeDisplayID()} or {@link AbstractGraphicsDevice#getHandle()}.
      */
-    public EGLGraphicsDevice() {
-        super(NativeWindowFactory.TYPE_EGL, DefaultGraphicsDevice.getDefaultDisplayConnection(), AbstractGraphicsDevice.DEFAULT_UNIT);
-        this.nativeDisplayID[0] = 0 ; // EGL.EGL_DEFAULT_DISPLAY
-        this.eglLifecycleCallback = null;
-    }
-
-    public EGLGraphicsDevice(final AbstractGraphicsDevice aDevice, final long eglDisplay, final EGLDisplayLifecycleCallback eglLifecycleCallback) {
-        super(NativeWindowFactory.TYPE_EGL, aDevice.getConnection(), aDevice.getUnitID(), eglDisplay);
-        final long nativeDisplayID;
+    public static long getNativeDisplayID(final AbstractGraphicsDevice aDevice) {
         if( aDevice instanceof EGLGraphicsDevice ) {
-            nativeDisplayID = ((EGLGraphicsDevice)aDevice).getNativeDisplayID();
+            return ((EGLGraphicsDevice)aDevice).getNativeDisplayID();
         } else {
-            nativeDisplayID = aDevice.getHandle();
+            return aDevice.getHandle();
         }
-        this.nativeDisplayID[0] = nativeDisplayID;
-        this.eglLifecycleCallback = eglLifecycleCallback;
     }
 
-    public EGLGraphicsDevice(final long nativeDisplayID, final long eglDisplay, final String connection, final int unitID, final EGLDisplayLifecycleCallback eglLifecycleCallback) {
-        super(NativeWindowFactory.TYPE_EGL, connection, unitID, eglDisplay);
+    /**
+     * Generic EGLGraphicsDevice constructor.
+     * @param nativeDisplayID the existing native display ID
+     * @param connection the existing underlying native connection name
+     * @param unitID the unit ID
+     * @param handle the handle, maybe 0
+     * @param eglLifecycleCallback
+     */
+    private EGLGraphicsDevice(final long nativeDisplayID, final String connection, final int unitID, final long handle,
+                              final EGLDisplayLifecycleCallback eglLifecycleCallback)
+    {
+        super(NativeWindowFactory.TYPE_EGL, connection, unitID, handle);
         this.nativeDisplayID[0] = nativeDisplayID;
         this.eglLifecycleCallback = eglLifecycleCallback;
     }
 
+    /**
+     * Constructs a dummy {@link EGLGraphicsDevice} with default connection settings.
+     * <p>
+     * The constructed instance will never create a valid EGL display handle.
+     * </p>
+     */
+    public EGLGraphicsDevice() {
+        this(EGL_DEFAULT_DISPLAY, DefaultGraphicsDevice.getDefaultDisplayConnection(), AbstractGraphicsDevice.DEFAULT_UNIT, EGL_NO_DISPLAY, null);
+    }
+
+    /**
+     * Constructs a new dummy {@link EGLGraphicsDevice} reusing the given native display connection
+     * with a {@link EGL#EGL_NO_DISPLAY} EGL display handle.
+     * <p>
+     * The constructed instance will never create a valid EGL display handle.
+     * </p>
+     * @param nativeDisplayID the existing native display ID
+     * @param eglDisplay the existing EGL handle to this nativeDisplayID
+     * @param connection the existing underlying native connection name
+     * @param unitID the unit ID
+     */
+    public EGLGraphicsDevice(final long nativeDisplayID, final String connection, final int unitID) {
+        this(nativeDisplayID, connection, unitID, EGL_NO_DISPLAY, null);
+    }
+
+    /**
+     * Constructs a new {@link EGLGraphicsDevice} reusing the given native display connection and handle
+     * <p>
+     * The constructed instance will not take ownership of given EGL display handle.
+     * </p>
+     * @param nativeDisplayID the existing native display ID
+     * @param eglDisplay the existing EGL handle to this nativeDisplayID
+     * @param connection the existing underlying native connection name
+     * @param unitID the unit ID
+     */
+    public EGLGraphicsDevice(final long nativeDisplayID, final long eglDisplay, final String connection, final int unitID) {
+        this(nativeDisplayID, connection, unitID, eglDisplay, null);
+        if (EGL_NO_DISPLAY == this.nativeDisplayID[0]) {
+            throw new NativeWindowException("Invalid EGL_NO_DISPLAY display handle");
+        }
+    }
+
+    /**
+     * Constructs a new {@link EGLGraphicsDevice} using {@link AbstractGraphicsDevice}'s native display ID and connection,
+     * using the {@link EGLDisplayLifecycleCallback} to handle this instance's native EGL lifecycle.
+     * <p>
+     * The constructed instance will take ownership of the created EGL display handle.
+     * </p>
+     * @param aDevice valid {@link AbstractGraphicsDevice}'s native display ID, connection and unitID
+     * @param eglLifecycleCallback valid {@link EGLDisplayLifecycleCallback} to handle this instance's native EGL lifecycle.
+     */
+    public EGLGraphicsDevice(final AbstractGraphicsDevice aDevice, final EGLDisplayLifecycleCallback eglLifecycleCallback) {
+        this(getNativeDisplayID(aDevice), aDevice.getConnection(), aDevice.getUnitID(), EGL_NO_DISPLAY, eglLifecycleCallback);
+        if (null == eglLifecycleCallback) {
+            throw new NativeWindowException("Null EGLDisplayLifecycleCallback");
+        }
+    }
+
+    /**
+     * Constructs a new {@link EGLGraphicsDevice} using {@link AbstractGraphicsDevice}'s native display ID and connection,
+     * using the {@link EGLDisplayLifecycleCallback} to handle this instance's native EGL lifecycle.
+     * <p>
+     * The constructed instance will take ownership of the created EGL display handle.
+     * </p>
+     * @param nativeDisplayID the existing native display ID
+     * @param connection the existing underlying native connection name
+     * @param unitID the unit ID
+     * @param eglLifecycleCallback valid {@link EGLDisplayLifecycleCallback} to handle this instance's native EGL lifecycle.
+     */
+    public EGLGraphicsDevice(final long nativeDisplayID, final String connection, final int unitID, final EGLDisplayLifecycleCallback eglLifecycleCallback) {
+        this(nativeDisplayID, connection, unitID, EGL_NO_DISPLAY, eglLifecycleCallback);
+        if (null == eglLifecycleCallback) {
+            throw new NativeWindowException("Null EGLDisplayLifecycleCallback");
+        }
+    }
+
     /** EGL server version as returned by {@code eglInitialize(..)}. Only valid after {@link #open()}. */
     public VersionNumber getEGLVersion() { return eglVersion; }
 
+    /**
+     * Return the native display ID of this instance.
+     * <p>
+     * Since EGL 1.4, sharing resources requires e.g. a GLContext to use the same native display ID
+     * for the so called shared context list and the to be created context.
+     * </p>
+     * @see #getNativeDisplayID(AbstractGraphicsDevice)
+     */
     public long getNativeDisplayID() { return nativeDisplayID[0]; }
 
+    /**
+     * Returns true if given {@link AbstractGraphicsDevice} uses the same {@link #getNativeDisplayID()} of this instance.
+     * <p>
+     * In case given {@link AbstractGraphicsDevice} is not a {@link EGLGraphicsDevice}, its {@link AbstractGraphicsDevice#getHandle()}
+     * is being used as the native display id for a matching {@link EGLGraphicsDevice} instance.
+     * </p>
+     * @see #getNativeDisplayID(AbstractGraphicsDevice)
+     */
+    public boolean sameNativeDisplayID(final AbstractGraphicsDevice aDevice) {
+        return getNativeDisplayID(aDevice) == getNativeDisplayID();
+    }
+
     @Override
     public Object clone() {
       return super.clone();
@@ -172,7 +275,7 @@ public class EGLGraphicsDevice extends DefaultGraphicsDevice implements Cloneabl
 
     @Override
     public String toString() {
-        return getClass().getSimpleName()+"[type "+getType()+", v"+eglVersion+", connection "+getConnection()+", unitID "+getUnitID()+", handle 0x"+Long.toHexString(getHandle())+", owner "+isHandleOwner()+", "+toolkitLock+"]";
+        return getClass().getSimpleName()+"[type "+getType()+", v"+eglVersion+", nativeDisplayID 0x"+Long.toHexString(nativeDisplayID[0])+", connection "+getConnection()+", unitID "+getUnitID()+", handle 0x"+Long.toHexString(getHandle())+", owner "+isHandleOwner()+", "+toolkitLock+"]";
     }
 }
 
diff --git a/src/newt/classes/jogamp/newt/driver/bcm/egl/DisplayDriver.java b/src/newt/classes/jogamp/newt/driver/bcm/egl/DisplayDriver.java
index a65bd1e4c..99d9cc079 100644
--- a/src/newt/classes/jogamp/newt/driver/bcm/egl/DisplayDriver.java
+++ b/src/newt/classes/jogamp/newt/driver/bcm/egl/DisplayDriver.java
@@ -63,10 +63,7 @@ public class DisplayDriver extends jogamp.newt.DisplayImpl {
     @Override
     protected void createNativeImpl() {
         final long handle = CreateDisplay(ScreenDriver.fixedWidth, ScreenDriver.fixedHeight);
-        if (handle == EGL.EGL_NO_DISPLAY) {
-            throw new NativeWindowException("BC EGL CreateDisplay failed");
-        }
-        aDevice = new EGLGraphicsDevice(EGL.EGL_DEFAULT_DISPLAY, handle, AbstractGraphicsDevice.DEFAULT_CONNECTION, AbstractGraphicsDevice.DEFAULT_UNIT, null);
+        aDevice = new EGLGraphicsDevice(EGL.EGL_DEFAULT_DISPLAY, handle, AbstractGraphicsDevice.DEFAULT_CONNECTION, AbstractGraphicsDevice.DEFAULT_UNIT);
     }
 
     @Override