[GL]Capabilities*: Enhance identity-check in root Capabilities.equals(..), comparing the VisualID first; Added VisualIDHolder.isVisualIDSupported(VIDType)

We cannot accept 2 capabilities with different VisualID but same attributes otherwise accepted as equal,
since the underlying windowing system uniquely identifies them via their VisualID.

Such comparison is used in certail GLAutoDrawable implementations like AWT GLCanvas
to determine a configuration change etc.

7 files changed, 208 insertions, 6 deletions

diff --git a/src/jogl/classes/jogamp/opengl/x11/glx/X11GLCapabilities.java b/src/jogl/classes/jogamp/opengl/x11/glx/X11GLCapabilities.java
index 740289fa6..8c74ba090 100644
--- a/src/jogl/classes/jogamp/opengl/x11/glx/X11GLCapabilities.java
+++ b/src/jogl/classes/jogamp/opengl/x11/glx/X11GLCapabilities.java
@@ -32,6 +32,7 @@ import jogamp.nativewindow.x11.XVisualInfo;
 
 import com.jogamp.nativewindow.NativeWindowException;
 import com.jogamp.nativewindow.VisualIDHolder;
+import com.jogamp.nativewindow.VisualIDHolder.VIDType;
 import com.jogamp.opengl.GLCapabilities;
 import com.jogamp.opengl.GLException;
 import com.jogamp.opengl.GLProfile;
@@ -92,6 +93,19 @@ public class X11GLCapabilities extends GLCapabilities {
   }
 
   @Override
+  final public boolean isVisualIDSupported(final VIDType type) {
+      switch(type) {
+          case INTRINSIC:
+          case NATIVE:
+          case X11_XVISUAL:
+          case X11_FBCONFIG:
+              return true;
+          default:
+              return false;
+      }
+  }
+
+  @Override
   public StringBuilder toString(StringBuilder sink) {
     if(null == sink) {
         sink = new StringBuilder();
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/Capabilities.java b/src/nativewindow/classes/com/jogamp/nativewindow/Capabilities.java
index fa172b201..ea9ca7fc4 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/Capabilities.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/Capabilities.java
@@ -1,6 +1,6 @@
 /*
+ * Copyright (c) 2010-2023 JogAmp Community. All rights reserved.
  * Copyright (c) 2003 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
@@ -121,6 +121,22 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
     return hash;
   }
 
+  private static boolean checkSameSuppSameValue(final VIDType type, final VisualIDHolder a, final VisualIDHolder b) {
+        final boolean has_a = a.isVisualIDSupported(type);
+        if( has_a != b.isVisualIDSupported(type) ) {
+            // both should either support or not support the extra X11_FBCONFIG
+            return false;
+        }
+        return !has_a || a.getVisualID(type) == b.getVisualID(type);
+  }
+  private static boolean checkSameValueIfBothSupp(final VIDType type, final VisualIDHolder a, final VisualIDHolder b) {
+        final boolean has_a = a.isVisualIDSupported(type);
+        if( has_a && has_a == b.isVisualIDSupported(type) ) {
+            return a.getVisualID(type) == b.getVisualID(type);
+        }
+        return true;
+  }
+
   @Override
   public boolean equals(final Object obj) {
     if(this == obj)  { return true; }
@@ -128,6 +144,20 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
         return false;
     }
     final CapabilitiesImmutable other = (CapabilitiesImmutable)obj;
+    {
+        // first check whether the VID is compatible
+        final int id_t = this.getVisualID(VIDType.NATIVE);
+        final int id_o = other.getVisualID(VIDType.NATIVE);
+        if( id_t != id_o ) {
+            return false;
+        }
+        if( !checkSameSuppSameValue(VIDType.X11_FBCONFIG, this, other) ) {
+            return false;
+        }
+        if( !checkSameValueIfBothSupp(VIDType.EGL_CONFIG, this, other) ) {
+            return false;
+        }
+    }
     boolean res = other.getRedBits()==redBits &&
                   other.getGreenBits()==greenBits &&
                   other.getBlueBits()==blueBits &&
@@ -182,6 +212,17 @@ public class Capabilities implements CapabilitiesImmutable, Cloneable {
   }
 
   @Override
+  public boolean isVisualIDSupported(final VIDType type) {
+      switch(type) {
+          case INTRINSIC:
+          case NATIVE:
+              return true;
+          default:
+              return false;
+      }
+  }
+
+  @Override
   public final int getRedBits() {
     return redBits;
   }
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/CapabilitiesImmutable.java b/src/nativewindow/classes/com/jogamp/nativewindow/CapabilitiesImmutable.java
index 780d537b8..526d184a1 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/CapabilitiesImmutable.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/CapabilitiesImmutable.java
@@ -1,5 +1,5 @@
 /**
- * Copyright 2010 JogAmp Community. All rights reserved.
+ * Copyright 2010-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:
@@ -122,11 +122,11 @@ public interface CapabilitiesImmutable extends VisualIDHolder, WriteCloneable, C
      */
     int getTransparentAlphaValue();
 
-    /** Equality over the immutable attributes of both objects */
+    /** Equality over the immutable attributes of both objects. */
     @Override
     boolean equals(Object obj);
 
-    /** hash code over the immutable attributes of both objects */
+    /** Hash code over the immutable attributes. */
     @Override
     int hashCode();
 
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/DefaultGraphicsConfiguration.java b/src/nativewindow/classes/com/jogamp/nativewindow/DefaultGraphicsConfiguration.java
index d20a6824d..220f0555b 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/DefaultGraphicsConfiguration.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/DefaultGraphicsConfiguration.java
@@ -32,6 +32,8 @@
 
 package com.jogamp.nativewindow;
 
+import com.jogamp.nativewindow.VisualIDHolder.VIDType;
+
 import jogamp.nativewindow.Debug;
 
 public class DefaultGraphicsConfiguration implements Cloneable, AbstractGraphicsConfiguration {
@@ -91,6 +93,11 @@ public class DefaultGraphicsConfiguration implements Cloneable, AbstractGraphics
         return capabilitiesChosen.getVisualID(type);
     }
 
+    @Override
+    final public boolean isVisualIDSupported(final VIDType type) {
+        return capabilitiesChosen.isVisualIDSupported(type);
+    }
+
     /**
      * Set the capabilities to a new value.
      *
diff --git a/src/nativewindow/classes/com/jogamp/nativewindow/VisualIDHolder.java b/src/nativewindow/classes/com/jogamp/nativewindow/VisualIDHolder.java
index 62b73d230..627fc4f3b 100644
--- a/src/nativewindow/classes/com/jogamp/nativewindow/VisualIDHolder.java
+++ b/src/nativewindow/classes/com/jogamp/nativewindow/VisualIDHolder.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:
@@ -90,6 +90,10 @@ public interface VisualIDHolder {
      *     </ul></li>
      * </ul>
      * </p>
+     * <p>
+     * One may use {@link #isVisualIDSupported(VIDType)} to test upfront whether a {@link VIDType} is supported,
+     * e.g. to avoid an exception or query or compare all available.
+     * </p>
      * Note: <code>INTRINSIC</code> and <code>NATIVE</code> are always handled,
      *       but may result in {@link #VID_UNDEFINED}. The latter is true if
      *       the native value are actually undefined or the corresponding object is not
@@ -98,10 +102,24 @@ public interface VisualIDHolder {
      * @throws NativeWindowException if <code>type</code> is neither
      *         <code>INTRINSIC</code> nor <code>NATIVE</code>
      *         and does not match the native implementation.
+     *
+     * @see #isVisualIDSupported(VIDType)
      */
     int getVisualID(VIDType type) throws NativeWindowException ;
 
     /**
+     * Returns true if the given {@link VIDType} is supported, otherwise false.
+     * <p>
+     * Note: <code>INTRINSIC</code> and <code>NATIVE</code> are always handled,
+     *       but may result in {@link #VID_UNDEFINED}. The latter is true if
+     *       the native value are actually undefined or the corresponding object is not
+     *       mapped to a native visual object.
+     * </p>
+     * @see #getVisualID(VIDType)
+     */
+    boolean isVisualIDSupported(VIDType type);
+
+    /**
      * {@link #getVisualID(VIDType)} result indicating an undefined value,
      * which could be cause by an unsupported query.
      * <p>
diff --git a/src/nativewindow/classes/jogamp/nativewindow/x11/X11Capabilities.java b/src/nativewindow/classes/jogamp/nativewindow/x11/X11Capabilities.java
index 99cfca97b..71bd033b0 100644
--- a/src/nativewindow/classes/jogamp/nativewindow/x11/X11Capabilities.java
+++ b/src/nativewindow/classes/jogamp/nativewindow/x11/X11Capabilities.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:
@@ -74,6 +74,19 @@ public class X11Capabilities extends Capabilities {
   }
 
   @Override
+  final public boolean isVisualIDSupported(final VIDType type) {
+      switch(type) {
+          case INTRINSIC:
+          case NATIVE:
+          case X11_XVISUAL:
+          case X11_FBCONFIG:
+              return true;
+          default:
+              return false;
+      }
+  }
+
+  @Override
   public StringBuilder toString(StringBuilder sink) {
     if(null == sink) {
         sink = new StringBuilder();
diff --git a/src/test/com/jogamp/opengl/test/junit/jogl/caps/TestIdentOfCapabilitiesNEWT.java b/src/test/com/jogamp/opengl/test/junit/jogl/caps/TestIdentOfCapabilitiesNEWT.java
new file mode 100644
index 000000000..4de270ce7
--- /dev/null
+++ b/src/test/com/jogamp/opengl/test/junit/jogl/caps/TestIdentOfCapabilitiesNEWT.java
@@ -0,0 +1,109 @@
+/**
+ * Copyright 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:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+
+package com.jogamp.opengl.test.junit.jogl.caps;
+
+import com.jogamp.opengl.GLCapabilitiesImmutable;
+import com.jogamp.opengl.GLDrawableFactory;
+import com.jogamp.opengl.GLException;
+import com.jogamp.opengl.JoglVersion;
+
+import org.junit.Test;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.junit.Assert;
+import org.junit.FixMethodOrder;
+import org.junit.runners.MethodSorters;
+
+import com.jogamp.junit.util.SingletonJunitCase;
+import com.jogamp.nativewindow.AbstractGraphicsDevice;
+
+@FixMethodOrder(MethodSorters.NAME_ASCENDING)
+public class TestIdentOfCapabilitiesNEWT extends SingletonJunitCase {
+
+  public static void main(final String[] args) {
+     final String tstname = TestIdentOfCapabilitiesNEWT.class.getName();
+     org.junit.runner.JUnitCore.main(tstname);
+  }
+
+  @Test
+  public void test01DesktopCapsEquals() throws InterruptedException {
+        final GLDrawableFactory factory = GLDrawableFactory.getFactory(false);
+        if( null == factory ) {
+            System.err.println("No desktop factory available, bailing out");
+            return;
+        }
+        testEquals(factory);
+  }
+  @Test
+  public void test02EGLCapsEquals() throws InterruptedException {
+        final GLDrawableFactory factory = GLDrawableFactory.getFactory(true);
+        if( null == factory ) {
+            System.err.println("No EGL factory available, bailing out");
+            return;
+        }
+        testEquals(factory);
+  }
+
+  private static List<GLCapabilitiesImmutable> getEquals(final GLCapabilitiesImmutable caps, final List<GLCapabilitiesImmutable> availCaps) {
+      final List<GLCapabilitiesImmutable> res = new ArrayList<GLCapabilitiesImmutable>();
+      for(final GLCapabilitiesImmutable c : availCaps) {
+          if( c.equals(caps) ) {
+              res.add(c);
+          }
+      }
+      return res;
+  }
+
+  private void testEquals(final GLDrawableFactory factory) {
+      final AbstractGraphicsDevice device = factory.getDefaultDevice();
+      Assert.assertNotNull(device);
+      // System.err.println(JoglVersion.getDefaultOpenGLInfo(device, null, true).toString());
+
+      try {
+          final List<GLCapabilitiesImmutable> availCaps = factory.getAvailableCapabilities(device);
+          if( null != availCaps ) {
+              for(int i=0; i < availCaps.size(); i++) {
+                  final GLCapabilitiesImmutable one = availCaps.get(i);
+                  final List<GLCapabilitiesImmutable> res = getEquals(one, availCaps);
+                  if( 1 != res.size() ) {
+                      // oops
+                      System.err.println("Error: "+one+" matches more than one in list, not unique:");
+                      res.forEach(System.err::println);
+                  }
+                  Assert.assertEquals(1,  res.size());
+                  System.err.printf("#%3d/%d: %s%n", (i+1), availCaps.size(), one);
+              }
+          }
+      } catch (final GLException gle) { /* n/a */ }
+  }
+
+
+}