fix LWJGL3 Canvas Frame Rate

Co-authored-by: gpt-5.6-sol <103840984+codex128@users.noreply.github.com>
Co-authored-by: gpt-5.6-luna <103840984+codex128@users.noreply.github.com>

Author: riccardobl

jme3-lwjgl3/src/main/java/com/jme3/system/lwjgl/AwtEventQueueFairness.java

@@ -0,0 +1,99 @@
+/*
+ * Copyright (c) 2009-2026 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * 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.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "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 THE COPYRIGHT OWNER 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.
+ */
+package com.jme3.system.lwjgl;
+
+import java.awt.EventQueue;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.concurrent.locks.LockSupport;
+import java.util.function.Consumer;
+import java.util.function.LongConsumer;
+import java.util.function.LongSupplier;
+
+/**
+ * Prevents an unbounded AWT canvas render loop from starving Swing's event
+ * dispatch thread without imposing a fixed frame-rate limit.
+ */
+final class AwtEventQueueFairness {
+
+    static final long PROBE_INTERVAL_NANOS = TimeUnit.MILLISECONDS.toNanos(4);
+    static final long EDT_STALL_NANOS = TimeUnit.MILLISECONDS.toNanos(2);
+    static final long BACKOFF_NANOS = TimeUnit.MICROSECONDS.toNanos(100);
+
+    private final LongSupplier nanoTime;
+    private final Consumer<Runnable> edtExecutor;
+    private final LongConsumer parker;
+    private final AtomicBoolean probePending = new AtomicBoolean();
+
+    private long lastProbeNanos = Long.MIN_VALUE;
+    private volatile long pendingSinceNanos;
+
+    AwtEventQueueFairness() {
+        this(System::nanoTime, EventQueue::invokeLater, LockSupport::parkNanos);
+    }
+
+    AwtEventQueueFairness(LongSupplier nanoTime, Consumer<Runnable> edtExecutor,
+            LongConsumer parker) {
+        this.nanoTime = nanoTime;
+        this.edtExecutor = edtExecutor;
+        this.parker = parker;
+    }
+
+    static boolean isRequired(boolean vsyncPacedFrame, int frameRateLimit) {
+        return !vsyncPacedFrame && frameRateLimit <= 0;
+    }
+
+    void afterFrame() {
+        long now = nanoTime.getAsLong();
+        if (probePending.get()) {
+            if (now - pendingSinceNanos >= EDT_STALL_NANOS) {
+                parker.accept(BACKOFF_NANOS);
+            }
+            return;
+        }
+
+        if (lastProbeNanos != Long.MIN_VALUE
+                && now - lastProbeNanos < PROBE_INTERVAL_NANOS) {
+            return;
+        }
+
+        if (probePending.compareAndSet(false, true)) {
+            lastProbeNanos = now;
+            pendingSinceNanos = now;
+            try {
+                edtExecutor.accept(() -> probePending.set(false));
+            } catch (RuntimeException exception) {
+                probePending.set(false);
+            }
+        }
+    }
+}

jme3-lwjgl3/src/main/java/com/jme3/system/lwjgl/LwjglCanvas.java

@@ -62,6 +62,7 @@
 import java.util.HashMap;
 import java.util.Map;
 import java.util.concurrent.atomic.AtomicBoolean;
+import java.util.function.BooleanSupplier;
 import java.util.function.Consumer;
 import java.util.logging.Level;
 import java.util.logging.Logger;
@@ -113,6 +114,18 @@ public class LwjglCanvas extends LwjglWindow implements JmeCanvasContext, Runnab
     /** Logger class. */
     private static final Logger LOGGER = Logger.getLogger(LwjglCanvas.class.getName());
 
+    static boolean swapBuffersAndCheckNativeVsync(boolean nativeVsyncEnabled,
+            BooleanSupplier swapBuffers) {
+        boolean swapped = swapBuffers.getAsBoolean();
+        return nativeVsyncEnabled && swapped;
+    }
+
+    /** Gives Swing time to process events when rendering without any limiter. */
+    private final AwtEventQueueFairness edtFairness = new AwtEventQueueFairness();
+
+    /** Whether the platform successfully enabled native vertical sync. */
+    private volatile boolean nativeVsyncEnabled;
+
     /** GL versions map. */
     private static final Map<String, Consumer<GLData>> RENDER_CONFIGS = new HashMap<>();
 
@@ -272,12 +285,14 @@ public GLData getGLDataEffective() {
          * To start drawing on the AWT surface, the AWT threads must be locked to
          * avoid conflicts when drawing on the canvas.
          */
-        public void lock() {
+        public boolean lock() {
             synchronized (lock) {
                 try {
                     platformCanvas.lock();// <- MUST lock on Linux
+                    return true;
                 } catch (AWTException e) {
                     listener.handleError("Failed to lock Canvas", e);
+                    return false;
                 }
             }
         }
@@ -305,8 +320,8 @@ public void doDisposeCanvas() {
         /**
          * This is where you actually draw on the canvas (framebuffer).
          */
-        public void swapBuffers() {
-            platformCanvas.swapBuffers();
+        public boolean swapBuffers() {
+            return platformCanvas.swapBuffers();
         }
 
         /**
@@ -575,18 +590,22 @@ public void run() {
                 //       with demanding scenes.
                 runLoop();
 
+                boolean nativeVsyncPacedFrame = false;
+
                 // All this does is call swapBuffers().
                 // If the canvas is not active, there's no need to waste time
                 // doing that.
                 if (renderable.get() && canvas.hasContext() && canvas.isValid()) {
                     try {
                         if (allowSwapBuffers && autoFlush) {
                             // calls swap buffers | lock, etc.
-                            try {
-                                canvas.lock();
-                                canvas.swapBuffers();
-                            } finally {
-                                canvas.unlock();
+                            if (canvas.lock()) {
+                                try {
+                                    nativeVsyncPacedFrame = swapBuffersAndCheckNativeVsync(
+                                            nativeVsyncEnabled, canvas::swapBuffers);
+                                } finally {
+                                    canvas.unlock();
+                                }
                             }
 
                             // Sync the display on some systems.
@@ -596,6 +615,12 @@ public void run() {
                         listener.handleError("Error while swapping buffers", ex);
                     }
                 }
+
+                // With neither VSync nor a software FPS limit, keep rendering
+                // unbounded but yield briefly if Swing's EDT stops progressing.
+                if (AwtEventQueueFairness.isRequired(nativeVsyncPacedFrame, frameRateLimit)) {
+                    edtFairness.afterFrame();
+                }
             } else {
                 // HACK: If the GL context is not rendering, the thread will
                 //       enter a waiting state, thus avoiding CPU overload.
@@ -705,6 +730,8 @@ protected void destroyContext() {
      */
     @Override
     protected void createContext(AppSettings settings) {
+        nativeVsyncEnabled = false;
+
         boolean linux = Platform.get() == Platform.LINUX
                 || Platform.get() == Platform.FREEBSD;
         if (!settings.isX11PlatformPreferred() && linux && JmeSystem.isWaylandSession()) {
@@ -763,6 +790,13 @@ protected void createContext(AppSettings settings) {
         canvas.createContext();
         canvas.makeCurrent();
 
+        nativeVsyncEnabled = settings.isVSync()
+                && Integer.valueOf(1).equals(canvas.getGLDataEffective().swapInterval);
+        if (settings.isVSync() && !nativeVsyncEnabled) {
+            LOGGER.warning("Native VSync is unavailable for the AWT canvas; "
+                    + "EDT fairness will be used when no FPS limit is set.");
+        }
+
         SwingUtilities.invokeLater(() -> {
             canvas.validate();
         });

jme3-lwjgl3/src/main/java/com/jme3/system/lwjglx/MacOSXGLPlatform.java

@@ -31,8 +31,16 @@
  */
 package com.jme3.system.lwjglx;
 
+import static org.lwjgl.opengl.CGL.CGLSetParameter;
+import static org.lwjgl.opengl.CGL.kCGLCPSwapInterval;
+import static org.lwjgl.opengl.CGL.kCGLNoError;
+import static org.lwjgl.system.jawt.JAWTFunctions.JAWT_FreeDrawingSurface;
+
+import java.awt.AWTException;
+import java.awt.Canvas;
+
+import org.lwjgl.opengl.awt.GLData;
 import org.lwjgl.opengl.awt.PlatformMacOSXGLCanvas;
-import static org.lwjgl.system.jawt.JAWTFunctions.*;
 
 /**
  * <code>MacOSXGLPlatform</code> class that implements the {@link com.jme3.system.lwjglx.LwjglxGLPlatform} 
@@ -42,6 +50,25 @@
  */
 final class MacOSXGLPlatform extends PlatformMacOSXGLCanvas implements LwjglxGLPlatform {
 
+    @Override
+    public long create(Canvas canvas, GLData data, GLData effective) throws AWTException {
+        effective.swapInterval = null;
+        if (data.swapInterval != null && data.swapInterval < 0) {
+            throw new AWTException("Negative swap intervals are not supported by CGL");
+        }
+
+        long context = super.create(canvas, data, effective);
+        if (data.swapInterval == null) {
+            return context;
+        }
+
+        int result = CGLSetParameter(context, kCGLCPSwapInterval, data.swapInterval);
+        if (result == kCGLNoError) {
+            effective.swapInterval = data.swapInterval;
+        }
+        return context;
+    }
+
     /**
      * (non-Javadoc)
      * @see com.jme3.system.lwjglx.LwjglxGLPlatform#destroy() 

jme3-lwjgl3/src/main/java/com/jme3/system/lwjglx/Win32GLPlatform.java

@@ -31,7 +31,18 @@
  */
 package com.jme3.system.lwjglx;
 
-import static org.lwjgl.system.jawt.JAWTFunctions.*;
+import static org.lwjgl.opengl.WGL.wglGetCurrentContext;
+import static org.lwjgl.opengl.WGL.wglGetCurrentDC;
+import static org.lwjgl.opengl.WGL.wglGetProcAddress;
+import static org.lwjgl.opengl.WGL.wglMakeCurrent;
+import static org.lwjgl.system.JNI.callI;
+import static org.lwjgl.system.MemoryUtil.NULL;
+import static org.lwjgl.system.jawt.JAWTFunctions.JAWT_FreeDrawingSurface;
+
+import java.awt.AWTException;
+import java.awt.Canvas;
+
+import org.lwjgl.opengl.awt.GLData;
 import org.lwjgl.opengl.awt.PlatformWin32GLCanvas;
 
 /**
@@ -42,6 +53,47 @@
  */
 final class Win32GLPlatform extends PlatformWin32GLCanvas implements LwjglxGLPlatform {
 
+    @Override
+    public long create(Canvas canvas, GLData data, GLData effective) throws AWTException {
+        effective.swapInterval = null;
+        Integer requestedSwapInterval = data.swapInterval;
+        long context;
+        try {
+            // The dependency treats an unavailable WGL swap-control extension
+            // as a fatal context-creation error. Create first, then apply VSync
+            // here so jME can fall back to EDT fairness instead.
+            data.swapInterval = null;
+            context = super.create(canvas, data, effective);
+        } finally {
+            data.swapInterval = requestedSwapInterval;
+        }
+
+        if (requestedSwapInterval == null) {
+            return context;
+        }
+
+        long previousContext = wglGetCurrentContext(null);
+        long previousDc = wglGetCurrentDC();
+        try {
+            if (!makeCurrent(context)) {
+                return context;
+            }
+
+            long setAddress = wglGetProcAddress(null, "wglSwapIntervalEXT");
+            if (setAddress == NULL || callI(requestedSwapInterval, setAddress) == 0) {
+                return context;
+            }
+
+            long getAddress = wglGetProcAddress(null, "wglGetSwapIntervalEXT");
+            if (getAddress != NULL && callI(getAddress) == requestedSwapInterval) {
+                effective.swapInterval = requestedSwapInterval;
+            }
+        } finally {
+            wglMakeCurrent(null, previousDc, previousContext);
+        }
+        return context;
+    }
+
     /* (non-Javadoc)
      * @see com.jme3.system.lwjglx.LwjglxGLPlatform#dispose()
      */