Add ThrottleOnLostFocus - a slightly less crappy version of PauseOnLostFocus

jme3-core/src/main/java/com/jme3/app/Application.java

@@ -83,7 +83,7 @@ public class Application implements SystemListener {
     protected Listener listener;
 
     protected boolean inputEnabled = true;
-    protected boolean pauseOnFocus = true;
+    protected LostFocusBehavior lostFocusBehavior = LostFocusBehavior.ThrottleOnLostFocus;
     protected float speed = 1f;
     protected boolean paused = false;
     protected MouseInput mouseInput;
@@ -104,15 +104,40 @@ public class Application implements SystemListener {
         initStateManager();
     }
 
+    /**
+     * Determine the application's behavior when unfocused.
+     * 
+     * @return The lost focus behavior of the application.
+     */
+    public LostFocusBehavior getLostFocusBehavior() {
+        return lostFocusBehavior;
+    }
+    
+    /**
+     * Change the application's behavior when unfocused.
+     * 
+     * By default, the application will 
+     * {@link LostFocusBehavior#ThrottleOnLostFocus throttle the update loop} 
+     * so as to not take 100% CPU usage when it is not in focus, e.g.
+     * alt-tabbed, minimized, or obstructed by another window.
+     * 
+     * @param lostFocusBehavior The new lost focus behavior to use.
+     * 
+     * @see LostFocusBehavior
+     */
+    public void setLostFocusBehavior(LostFocusBehavior lostFocusBehavior) {
+        this.lostFocusBehavior = lostFocusBehavior;
+    }
+    
     /**
      * Returns true if pause on lost focus is enabled, false otherwise.
      *
      * @return true if pause on lost focus is enabled
      *
-     * @see #setPauseOnLostFocus(boolean)
+     * @see #getLostFocusBehavior() 
      */
     public boolean isPauseOnLostFocus() {
-        return pauseOnFocus;
+        return getLostFocusBehavior() == LostFocusBehavior.PauseOnLostFocus;
     }
 
     /**
@@ -128,9 +153,15 @@ public class Application implements SystemListener {
      *
      * @param pauseOnLostFocus True to enable pause on lost focus, false
      * otherwise.
+     * 
+     * @see #setLostFocusBehavior(com.jme3.app.LostFocusBehavior)
      */
     public void setPauseOnLostFocus(boolean pauseOnLostFocus) {
-        this.pauseOnFocus = pauseOnLostFocus;
+        if (pauseOnLostFocus) {
+            setLostFocusBehavior(LostFocusBehavior.PauseOnLostFocus);
+        } else {
+            setLostFocusBehavior(LostFocusBehavior.Disabled);
+        }
     }
 
     @Deprecated
@@ -563,8 +594,10 @@ public class Application implements SystemListener {
      * Internal use only.
      */
     public void gainFocus(){
-        if (pauseOnFocus) {
-            paused = false;
+        if (lostFocusBehavior != LostFocusBehavior.Disabled) {
+            if (lostFocusBehavior == LostFocusBehavior.PauseOnLostFocus) {
+                paused = false;
+            }
             context.setAutoFlushFrames(true);
             if (inputManager != null) {
                 inputManager.reset();
@@ -576,8 +609,10 @@ public class Application implements SystemListener {
      * Internal use only.
      */
     public void loseFocus(){
-        if (pauseOnFocus){
-            paused = true;
+        if (lostFocusBehavior != LostFocusBehavior.Disabled){
+            if (lostFocusBehavior == LostFocusBehavior.PauseOnLostFocus) {
+                paused = true;
+            }
             context.setAutoFlushFrames(false);
         }
     }

jme3-core/src/main/java/com/jme3/app/LostFocusBehavior.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2009-2015 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.app;
+
+/**
+ * Defines the behavior of an application when it is not in focus or minimized.
+ *
+ * @author Kirill Vainer
+ */
+public enum LostFocusBehavior {
+
+    /**
+     * No lost focus behavior.
+     *
+     * The application will update and render as usual.
+     */
+    Disabled,
+    /**
+     * The application will not update when unfocused.
+     *
+     * For online or real-time applications, this might not be preferable. For
+     * other applications, it is best to keep it on so that CPU usage is not
+     * used when not necessary.
+     */
+    PauseOnLostFocus,
+    /**
+     * The application will update at a reduced rate when unfocused.
+     *
+     * This is a compromise between {@link #Disabled} and
+     * {@link #PauseOnLostFocus}, allowing the application to update at a
+     * reduced rate (20 updates per second), but without rendering.
+     */
+    ThrottleOnLostFocus;
+}