JmeSurfaceView: Javadocs format improves (#1805)

* JmeSurfaceView: format fix and java-docs improves

* JmeSurfaceView: format fix and java-docs improves

* Code: removed import statements white spaces

jme3-android/src/main/java/com/jme3/app/jmeSurfaceView/JmeSurfaceView.java

@@ -66,8 +66,8 @@ import java.util.logging.Level;
 import java.util.logging.Logger;
 
 /**
- * <b>A RelativeLayout class holder that holds a {@link GLSurfaceView} as a renderer UI component and uses {@link OGLESContext} as a renderer context to render
- * a jme game on an android view for custom xmL designs.</b>
+ * <b>A RelativeLayout class holder that wraps a {@link GLSurfaceView} as a renderer UI component and uses {@link OGLESContext} as a renderer context to render
+ * a jme game on an android view for custom xml designs.</b>
  * The main idea of {@link JmeSurfaceView} class is to start a jMonkeyEngine application in a {@link SystemListener} context on a GL_ES thread,
  * then the game is rendered and updated through a {@link GLSurfaceView} component with a delay of user's choice using a {@link Handler}, during the delay,
  * the user has the ability to handle a couple of actions asynchronously as displaying a progress bar on a SplashScreen or an image or even play a preface game music of choice.
@@ -77,10 +77,10 @@ import java.util.logging.Logger;
 public class JmeSurfaceView extends RelativeLayout implements SystemListener, DialogInterface.OnClickListener, LifecycleEventObserver {
 
     private static final Logger jmeSurfaceViewLogger = Logger.getLogger(JmeSurfaceView.class.getName());
-    /*using {@link LegacyApplication} instead of {@link SimpleApplication} to include all classes extends LegacyApplication*/
-    private LegacyApplication legacyApplication;
     /*AppSettings attributes*/
     protected String audioRendererType = AppSettings.ANDROID_OPENAL_SOFT;
+    /*using {@link LegacyApplication} instead of {@link SimpleApplication} to include all classes extends LegacyApplication*/
+    private LegacyApplication legacyApplication;
     private AppSettings appSettings;
     private int eglBitsPerPixel = 24;
     private int eglAlphaBits = 0;
@@ -115,104 +115,6 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     private String crashLog = "";
     private String glEsVersion = "";
 
-    //******************Helper Classes************************
-
-    /**
-     * Used as a static memory to protect the game context from destruction by Activity#onDestroy().
-     * For usages :
-     *
-     * @see DestructionPolicy
-     * @see JmeSurfaceView#setDestructionPolicy(DestructionPolicy)
-     */
-    protected static final class GameState {
-
-        private static LegacyApplication legacyApplication;
-        private static boolean firstUpdatePassed = false;
-
-        /**
-         * Private constructor to inhibit instantiation of this class.
-         */
-        private GameState() {
-        }
-
-        /**
-         * Replaces the current application state.
-         * @param legacyApplication the new app instance holding the game state (including {@link AssetLoader}s, {@link AudioNode}s, {@link Spatial}s, etcetera).
-         */
-        protected static void setLegacyApplication(LegacyApplication legacyApplication) {
-            GameState.legacyApplication = legacyApplication;
-        }
-
-        /**
-         * Returns the current application state.
-         * @return game state instance, holding jME3 states (JmeContext, AssetManager, StateManager, Graphics, Sound, Input, Spatial/Nodes in place, etcetera).
-         */
-        protected static LegacyApplication getLegacyApplication() {
-            return legacyApplication;
-        }
-
-        /**
-         * Adjusts the first update flag.
-         * @param firstUpdatePassed set to true to determine whether the firstUpdate has passed, false otherwise.
-         */
-        protected static void setFirstUpdatePassed(boolean firstUpdatePassed) {
-            GameState.firstUpdatePassed = firstUpdatePassed;
-        }
-
-        /**
-         * Tests the first update flag.
-         * @return true if the firstUpdate has passed, false otherwise.
-         */
-        protected static boolean isFirstUpdatePassed() {
-            return firstUpdatePassed;
-        }
-    }
-
-    /**
-     * Determines whether the app context would be destructed
-     * with the holder activity context in case of {@link DestructionPolicy#DESTROY_WHEN_FINISH} or be
-     * spared for a second use in case of {@link DestructionPolicy#KEEP_WHEN_FINISH}.
-     * Default value is : {@link DestructionPolicy#DESTROY_WHEN_FINISH}.
-     *
-     * @see JmeSurfaceView#setDestructionPolicy(DestructionPolicy)
-     */
-    public enum DestructionPolicy {
-        /**
-         * Finishes the game context with the activity context (ignores the static memory {@link GameState#legacyApplication}).
-         */
-        DESTROY_WHEN_FINISH,
-        /**
-         * Spares the game context inside a static memory {@link GameState#legacyApplication}
-         * when the activity context is destroyed, but the app stills in the background.
-         */
-        KEEP_WHEN_FINISH
-    }
-
-    /**
-     * Delays the attachment surface view on the UI for the sake of initial frame pacing and splash screens,
-     * delaying the display of the game (GlSurfaceView) would lead to a substantial delay in the
-     * {@link android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10)} which would
-     * delay invoking both {@link LegacyApplication#initialize()} and {@link LegacyApplication#update()}.
-     * @see JmeSurfaceView#startRenderer(int)
-     * @see com.jme3.system.android.OGLESContext#onDrawFrame(javax.microedition.khronos.opengles.GL10)
-     */
-    private class RendererThread implements Runnable {
-        /**
-         * Delays the {@link GLSurfaceView} attachment on the UI thread.
-         *
-         * @see JmeSurfaceView#startRenderer(int)
-         */
-        @Override
-        public void run() {
-            addGlSurfaceView();
-            jmeSurfaceViewLogger.log(Level.INFO, "JmeSurfaceView's joined the UI thread.......");
-        }
-    }
-
-    //******************End of Helper Classes************************
-
-    //******************Constructors************************
-
     /**
      * Instantiates a default surface view holder without XML attributes.
      * On instantiating this surface view, the holder is bound directly to the
@@ -278,8 +180,6 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
         bindAppStateToActivityLifeCycle(bindAppState);
     }
 
-    //******************End of constructors************************
-
     /**
      * Starts the jmeRenderer on a GlSurfaceView attached to a RelativeLayout.
      *
@@ -316,7 +216,7 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
             /*start jme game context*/
             legacyApplication.start();
             /*fire the onStart() listener*/
-            if(onRendererStarted != null){
+            if (onRendererStarted != null) {
                 onRendererStarted.onRenderStart(legacyApplication, this);
             }
         }
@@ -339,15 +239,13 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     private void removeGlSurfaceView() {
-        ((Activity)getContext()).runOnUiThread(() -> {
+        ((Activity) getContext()).runOnUiThread(() -> {
             if (glSurfaceView != null) {
                 JmeSurfaceView.this.removeView(glSurfaceView);
             }
         });
     }
 
-    //******************Overridden methods by the implemented interfaces************************
-
     @Override
     public void handleError(String errorMsg, Throwable throwable) {
         throwable.printStackTrace();
@@ -359,15 +257,16 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
 
     /**
      * A state change observer to the holder Activity life cycle, used to keep this android view up-to-date with the holder activity life cycle.
+     *
      * @param source the life cycle source, aka the observable object.
-     * @param event the fired event by the observable object, which is dispatched and sent to the observers.
+     * @param event  the fired event by the observable object, which is dispatched and sent to the observers.
      */
     @Override
     public void onStateChanged(@NonNull LifecycleOwner source, @NonNull Lifecycle.Event event) {
         switch (event) {
             case ON_DESTROY:
                 /*destroy only if the policy flag is enabled*/
-                if(destructionPolicy == DestructionPolicy.DESTROY_WHEN_FINISH) {
+                if (destructionPolicy == DestructionPolicy.DESTROY_WHEN_FINISH) {
                     legacyApplication.stop(!isGLThreadPaused());
                 }
                 break;
@@ -403,7 +302,6 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
         jmeSurfaceViewLogger.log(Level.INFO, "Requested reshaping from the system listener");
     }
 
-
     @Override
     public void rescale(float x, float y) {
         if (legacyApplication == null) {
@@ -413,7 +311,6 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
         jmeSurfaceViewLogger.log(Level.INFO, "Requested rescaling from the system listener");
     }
 
-
     @Override
     public void update() {
         /*Invoking can be delayed by delaying the draw of GlSurfaceView component on the screen*/
@@ -421,9 +318,9 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
             return;
         }
         legacyApplication.update();
-        if(!GameState.isFirstUpdatePassed()){
-            ((Activity)getContext()).runOnUiThread(() -> {
-                jmeSurfaceViewLogger.log(Level.INFO,"User delay finishes with 0 errors");
+        if (!GameState.isFirstUpdatePassed()) {
+            ((Activity) getContext()).runOnUiThread(() -> {
+                jmeSurfaceViewLogger.log(Level.INFO, "User delay finishes with 0 errors");
                 if (onRendererCompleted != null) {
                     onRendererCompleted.onRenderCompletion(legacyApplication, legacyApplication.getContext().getSettings());
                 }
@@ -438,7 +335,7 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
         if (legacyApplication == null || (!isExitOnEscPressed())) {
             return;
         }
-        if(isShowEscExitPrompt()) {
+        if (isShowEscExitPrompt()) {
             final AlertDialog alertDialog = new AlertDialog.Builder(getContext()).create();
             alertDialog.setTitle("Exit Prompt");
             alertDialog.setMessage("Are you sure you want to quit ?");
@@ -446,7 +343,7 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
             alertDialog.setButton(DialogInterface.BUTTON_NEGATIVE, "No", (dialogInterface, i) -> alertDialog.dismiss());
             alertDialog.setButton(DialogInterface.BUTTON_POSITIVE, "Yes", (dialogInterface, i) -> legacyApplication.requestClose(esc));
             alertDialog.show();
-        }else{
+        } else {
             legacyApplication.requestClose(esc);
         }
     }
@@ -544,7 +441,7 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
         switch (which) {
             case DialogInterface.BUTTON_NEGATIVE:
                 dialog.dismiss();
-                ((Activity)getContext()).finish();
+                ((Activity) getContext()).finish();
                 break;
             case DialogInterface.BUTTON_POSITIVE:
                 dialog.dismiss();
@@ -559,22 +456,20 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
         }
     }
 
-    //******************End of the overridden methods by the implemented interfaces************************
-
     /**
      * Adds the glSurfaceView to the screen immediately, saving the current app instance.
      */
-    protected void addGlSurfaceView(){
+    protected void addGlSurfaceView() {
         /*jme Renderer joins the UIThread at that point*/
         JmeSurfaceView.this.addView(glSurfaceView);
         /*dispatch the layout drawn event*/
-        if(onLayoutDrawn != null){
+        if (onLayoutDrawn != null) {
             onLayoutDrawn.onLayoutDrawn(legacyApplication, this);
         }
         /*set the static memory to hold the game state, only if the destruction policy uses KEEP_WHEN_FINISHED policy*/
-        if (destructionPolicy == DestructionPolicy.KEEP_WHEN_FINISH){
+        if (destructionPolicy == DestructionPolicy.KEEP_WHEN_FINISH) {
             GameState.setLegacyApplication(legacyApplication);
-        }else{
+        } else {
             GameState.setLegacyApplication(null);
         }
     }
@@ -584,14 +479,15 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
      * 1st button is : EXIT to exit the activity and terminates the app.
      * 2nd button is : DISMISS to dismiss the dialog and ignore the exception.
      * 3rd button is : CopyCrashLog to copy the crash log to the clipboard.
+     *
      * @param throwable the throwable stack.
-     * @param title the message title.
+     * @param title     the message title.
      */
     protected void showErrorDialog(Throwable throwable, String title) {
-        if(!isShowErrorDialog()){
+        if (!isShowErrorDialog()) {
             return;
         }
-        ((Activity)getContext()).runOnUiThread(() -> {
+        ((Activity) getContext()).runOnUiThread(() -> {
             throwable.printStackTrace(new PrintWriter(crashLogWriter));
             crashLog = glEsVersion + "\n" + crashLogWriter.toString();
 
@@ -600,7 +496,7 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
             alertDialog.setMessage(crashLog);
             alertDialog.setCancelable(false);
             alertDialog.setButton(DialogInterface.BUTTON_NEGATIVE, "Exit", this);
-            alertDialog.setButton(DialogInterface.BUTTON_POSITIVE, "Dismiss",  this);
+            alertDialog.setButton(DialogInterface.BUTTON_POSITIVE, "Dismiss", this);
             alertDialog.setButton(DialogInterface.BUTTON_NEUTRAL, "Copy crash log", this);
             alertDialog.show();
         });
@@ -611,57 +507,71 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
      * Unbinding the game life cycle, would disable {@link JmeSurfaceView#gainFocus()}, {@link JmeSurfaceView#loseFocus()}
      * and {@link JmeSurfaceView#destroy()} from being invoked by the System Listener.
      * The Default value is : true, and the view component is pre-bounded to its activity lifeCycle when initialized.
+     *
      * @param condition true if you want to bind them, false otherwise.
      */
-    public void bindAppStateToActivityLifeCycle(final boolean condition){
+    public void bindAppStateToActivityLifeCycle(final boolean condition) {
         this.bindAppState = condition;
-        if(condition){
+        if (condition) {
             /*register this Ui Component as an observer to the context of jmeSurfaceView only if this context is a LifeCycleOwner*/
-            if(getContext() instanceof LifecycleOwner) {
+            if (getContext() instanceof LifecycleOwner) {
                 ((LifecycleOwner) getContext()).getLifecycle().addObserver(JmeSurfaceView.this);
             }
-        }else{
+        } else {
             /*un-register this Ui Component as an observer to the context of jmeSurfaceView only if this context is a LifeCycleOwner*/
-            if(getContext() instanceof LifecycleOwner) {
+            if (getContext() instanceof LifecycleOwner) {
                 ((LifecycleOwner) getContext()).getLifecycle().removeObserver(JmeSurfaceView.this);
             }
         }
     }
 
     /**
-     * Sets the current destruction policy, destruction policy {@link DestructionPolicy#KEEP_WHEN_FINISH} ensures that we protect the app state
-     * using {@link GameState#legacyApplication} static memory when the activity finishes, while
-     * {@link DestructionPolicy#DESTROY_WHEN_FINISH} destroys the game context with the activity onDestroy().
+     * Gets the current destruction policy.
      * Default value is : {@link DestructionPolicy#DESTROY_WHEN_FINISH}.
+     *
+     * @return the destruction policy, either {@link DestructionPolicy#DESTROY_WHEN_FINISH} or {@link DestructionPolicy#KEEP_WHEN_FINISH}.
      * @see DestructionPolicy
      * @see GameState
-     * @param destructionPolicy a destruction policy to set.
      */
-    public void setDestructionPolicy(DestructionPolicy destructionPolicy) {
-        this.destructionPolicy = destructionPolicy;
+    public DestructionPolicy getDestructionPolicy() {
+        return destructionPolicy;
     }
 
     /**
-     * Gets the current destruction policy.
+     * Sets the current destruction policy, destruction policy {@link DestructionPolicy#KEEP_WHEN_FINISH} ensures that we protect the app state
+     * using {@link GameState#legacyApplication} static memory when the activity finishes, while
+     * {@link DestructionPolicy#DESTROY_WHEN_FINISH} destroys the game context with the activity onDestroy().
      * Default value is : {@link DestructionPolicy#DESTROY_WHEN_FINISH}.
+     *
+     * @param destructionPolicy a destruction policy to set.
      * @see DestructionPolicy
      * @see GameState
-     * @return the destruction policy, either {@link DestructionPolicy#DESTROY_WHEN_FINISH} or {@link DestructionPolicy#KEEP_WHEN_FINISH}.
      */
-    public DestructionPolicy getDestructionPolicy() {
-        return destructionPolicy;
+    public void setDestructionPolicy(DestructionPolicy destructionPolicy) {
+        this.destructionPolicy = destructionPolicy;
     }
 
     /**
      * Checks whether the current game application life cycle is bound to the activity life cycle.
+     *
      * @return true it matches the condition, false otherwise.
      */
     public boolean isAppStateBoundToActivityLifeCycle() {
         return bindAppState;
     }
 
+    /**
+     * Checks whether the system would show an exit prompt dialog when the esc keyboard input is invoked.
+     *
+     * @return ture if the exit prompt dialog is activated on exit, false otherwise.
+     */
+    public boolean isShowEscExitPrompt() {
+        return showEscExitPrompt;
+    }
+
     /**
      * Determines whether to show an exit prompt dialog when the esc keyboard button is invoked.
+     *
      * @param showEscExitPrompt true to show the exit prompt dialog before exiting, false otherwise.
      */
     public void setShowEscExitPrompt(boolean showEscExitPrompt) {
@@ -669,15 +579,17 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Checks whether the system would show an exit prompt dialog when the esc keyboard input is invoked.
-     * @return ture if the exit prompt dialog is activated on exit, false otherwise.
+     * Checks whether the exit on esc press is activated.
+     *
+     * @return true if the exit on escape is activated, false otherwise.
      */
-    public boolean isShowEscExitPrompt() {
-        return showEscExitPrompt;
+    public boolean isExitOnEscPressed() {
+        return exitOnEscPressed;
     }
 
     /**
      * Determines whether the system would exit on pressing the keyboard esc button.
+     *
      * @param exitOnEscPressed true to activate exiting on Esc button press, false otherwise.
      */
     public void setExitOnEscPressed(boolean exitOnEscPressed) {
@@ -685,15 +597,17 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Checks whether the exit on esc press is activated.
-     * @return true if the exit on escape is activated, false otherwise.
+     * Gets the jme app instance.
+     *
+     * @return legacyApplication instance representing your game enclosure.
      */
-    public boolean isExitOnEscPressed() {
-        return exitOnEscPressed;
+    public LegacyApplication getLegacyApplication() {
+        return legacyApplication;
     }
 
     /**
      * Sets the jme game instance that will be engaged into the {@link SystemListener}.
+     *
      * @param legacyApplication your jme game instance.
      */
     public void setLegacyApplication(@NonNull LegacyApplication legacyApplication) {
@@ -701,15 +615,17 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Gets the jme app instance.
-     * @return legacyApplication instance representing your game enclosure.
+     * Gets the game window settings.
+     *
+     * @return app settings instance.
      */
-    public LegacyApplication getLegacyApplication() {
-        return legacyApplication;
+    public AppSettings getAppSettings() {
+        return appSettings;
     }
 
     /**
      * Sets the appSettings instance.
+     *
      * @param appSettings the custom appSettings instance
      */
     public void setAppSettings(@NonNull AppSettings appSettings) {
@@ -717,15 +633,17 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Gets the game window settings.
-     * @return app settings instance.
+     * Gets the bits/pixel for Embedded gL
+     *
+     * @return integer representing it.
      */
-    public AppSettings getAppSettings() {
-        return appSettings;
+    public int getEglBitsPerPixel() {
+        return eglBitsPerPixel;
     }
 
     /**
      * Sets the memory representing each pixel in bits.
+     *
      * @param eglBitsPerPixel the bits for each pixel.
      */
     public void setEglBitsPerPixel(int eglBitsPerPixel) {
@@ -733,15 +651,17 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Gets the bits/pixel for Embedded gL
+     * Gets the Embedded gL alpha(opacity) bits.
+     *
      * @return integer representing it.
      */
-    public int getEglBitsPerPixel() {
-        return eglBitsPerPixel;
+    public int getEglAlphaBits() {
+        return eglAlphaBits;
     }
 
     /**
      * Sets the memory representing the alpha of embedded gl in bits.
+     *
      * @param eglAlphaBits the alpha bits.
      */
     public void setEglAlphaBits(int eglAlphaBits) {
@@ -749,17 +669,19 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Gets the Embedded gL alpha(opacity) bits.
-     * @return integer representing it.
+     * Gets the memory representing the EGL depth in bits.
+     *
+     * @return the depth bits.
      */
-    public int getEglAlphaBits() {
-        return eglAlphaBits;
+    public int getEglDepthBits() {
+        return eglDepthBits;
     }
 
     /**
      * Sets the EGL depth in bits.
      * The depth buffer or Z-buffer is basically coupled with stencil buffer,
      * usually 8bits stencilBuffer + 24bits depthBuffer = 32bits shared memory.
+     *
      * @param eglDepthBits the depth bits.
      * @see JmeSurfaceView#setEglStencilBits(int)
      */
@@ -768,17 +690,19 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Gets the memory representing the EGL depth in bits.
-     * @return the depth bits.
+     * Gets the number of samples to use for multi-sampling.
+     *
+     * @return number of samples to use for multi-sampling.
      */
-    public int getEglDepthBits() {
-        return eglDepthBits;
+    public int getEglSamples() {
+        return eglSamples;
     }
 
     /**
      * Sets the number of samples to use for multi-sampling.
      * Leave 0 (default) to disable multi-sampling.
      * Set to 2 or 4 to enable multi-sampling.
+     *
      * @param eglSamples embedded gl samples bits to set.
      */
     public void setEglSamples(int eglSamples) {
@@ -786,11 +710,13 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Gets the number of samples to use for multi-sampling.
-     * @return number of samples to use for multi-sampling.
+     * Gets the number of stencil buffer bits.
+     * Default is : 0.
+     *
+     * @return the stencil buffer bits.
      */
-    public int getEglSamples() {
-        return eglSamples;
+    public int getEglStencilBits() {
+        return eglStencilBits;
     }
 
     /**
@@ -798,6 +724,7 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
      * Stencil buffer is used in depth-based shadow maps and shadow rendering as it limits rendering,
      * it's coupled with Z-buffer or depth buffer, usually 8bits stencilBuffer + 24bits depthBuffer = 32bits shared memory.
      * (default = 0)
+     *
      * @param eglStencilBits the desired number of stencil bits.
      * @see JmeSurfaceView#setEglDepthBits(int)
      */
@@ -806,17 +733,19 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Gets the number of stencil buffer bits.
-     * Default is : 0.
-     * @return the stencil buffer bits.
+     * Gets the limited FrameRate level for egl INFO.
+     * Default is : -1, for a device based limited value (determined by hardware).
+     *
+     * @return the limit frameRate in integers.
      */
-    public int getEglStencilBits() {
-        return eglStencilBits;
+    public int getFrameRate() {
+        return frameRate;
     }
 
     /**
      * Limits the frame rate (fps) in the second.
      * Default is : -1, for a device based limited value (determined by hardware).
+     *
      * @param frameRate the limitation in integers.
      */
     public void setFrameRate(int frameRate) {
@@ -824,17 +753,19 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Gets the limited FrameRate level for egl INFO.
-     * Default is : -1, for a device based limited value (determined by hardware).
-     * @return the limit frameRate in integers.
+     * Gets the audio renderer in String.
+     * Default is : {@link AppSettings#ANDROID_OPENAL_SOFT}.
+     *
+     * @return string representing audio renderer framework.
      */
-    public int getFrameRate() {
-        return frameRate;
+    public String getAudioRendererType() {
+        return audioRendererType;
     }
 
     /**
      * Sets the audioRenderer type.
      * Default is : {@link AppSettings#ANDROID_OPENAL_SOFT}.
+     *
      * @param audioRendererType string representing audioRenderer type.
      */
     public void setAudioRendererType(String audioRendererType) {
@@ -842,17 +773,19 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Gets the audio renderer in String.
-     * Default is : {@link AppSettings#ANDROID_OPENAL_SOFT}.
-     * @return string representing audio renderer framework.
+     * Checks if the keyboard interfacing is enabled.
+     * Default is : true.
+     *
+     * @return true if the keyboard interfacing is enabled.
      */
-    public String getAudioRendererType() {
-        return audioRendererType;
+    public boolean isEmulateKeyBoard() {
+        return emulateKeyBoard;
     }
 
     /**
      * Enables keyboard interfacing.
      * Default is : true.
+     *
      * @param emulateKeyBoard true to enable keyboard interfacing.
      */
     public void setEmulateKeyBoard(boolean emulateKeyBoard) {
@@ -860,17 +793,19 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Checks if the keyboard interfacing is enabled.
+     * Checks whether the mouse interfacing is enabled or not.
      * Default is : true.
-     * @return true if the keyboard interfacing is enabled.
+     *
+     * @return true if the mouse interfacing is enabled.
      */
-    public boolean isEmulateKeyBoard() {
-        return emulateKeyBoard;
+    public boolean isEmulateMouse() {
+        return emulateMouse;
     }
 
     /**
-     * enables mouse interfacing.
+     * Enables mouse interfacing.
      * Default is : true.
+     *
      * @param emulateMouse true to enable the mouse interfacing.
      */
     public void setEmulateMouse(boolean emulateMouse) {
@@ -878,16 +813,18 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Checks whether the mouse interfacing is enabled or not.
+     * Checks whether joystick interfacing is enabled or not.
      * Default is : true.
-     * @return true if the mouse interfacing is enabled.
+     *
+     * @return true if the joystick interfacing is enabled.
      */
-    public boolean isEmulateMouse() {
-        return emulateMouse;
+    public boolean isUseJoyStickEvents() {
+        return useJoyStickEvents;
     }
 
     /**
      * Enables joystick interfacing for a jme-game
+     *
      * @param useJoyStickEvents true to enable the joystick interfacing.
      */
     public void setUseJoyStickEvents(boolean useJoyStickEvents) {
@@ -895,33 +832,27 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Checks whether joystick interfacing is enabled or not.
-     * Default is : true.
-     * @return true if the joystick interfacing is enabled.
+     * Checks whether the GLThread is paused or not.
+     *
+     * @return true/false
      */
-    public boolean isUseJoyStickEvents() {
-        return useJoyStickEvents;
+    public boolean isGLThreadPaused() {
+        return isGLThreadPaused;
     }
 
     /**
      * Sets GL Thread paused.
+     *
      * @param GLThreadPaused true if you want to pause the GLThread.
      */
     protected void setGLThreadPaused(boolean GLThreadPaused) {
         isGLThreadPaused = GLThreadPaused;
     }
 
-    /**
-     * Checks whether the GLThread is paused or not.
-     * @return true/false
-     */
-    public boolean isGLThreadPaused() {
-        return isGLThreadPaused;
-    }
-
     /**
      * Sets the listener for the completion of rendering, ie : when the GL thread holding the {@link JmeSurfaceView}
      * joins the UI thread, after asynchronous rendering.
+     *
      * @param onRendererCompleted an instance of the interface {@link OnRendererCompleted}.
      */
     public void setOnRendererCompleted(OnRendererCompleted onRendererCompleted) {
@@ -930,6 +861,7 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
 
     /**
      * Sets the listener that will fire when an exception is thrown.
+     *
      * @param onExceptionThrown an instance of the interface {@link OnExceptionThrown}.
      */
     public void setOnExceptionThrown(OnExceptionThrown onExceptionThrown) {
@@ -938,6 +870,7 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
 
     /**
      * Sets the listener that will fire after initializing the game.
+     *
      * @param onRendererStarted an instance of the interface {@link OnRendererStarted}.
      */
     public void setOnRendererStarted(OnRendererStarted onRendererStarted) {
@@ -946,8 +879,9 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
 
     /**
      * Sets the listener that will dispatch an event when the layout is drawn by {@link JmeSurfaceView#addGlSurfaceView()}.
-     * @see JmeSurfaceView#addGlSurfaceView()
+     *
      * @param onLayoutDrawn the event to be dispatched.
+     * @see JmeSurfaceView#addGlSurfaceView()
      */
     public void setOnLayoutDrawn(OnLayoutDrawn onLayoutDrawn) {
         this.onLayoutDrawn = onLayoutDrawn;
@@ -955,15 +889,27 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
 
     /**
      * Gets the current device GL_ES version.
+     *
      * @return the current gl_es version in a string format.
      */
     public String getGlEsVersion() {
         return configurationInfo.getGlEsVersion();
     }
 
+    /**
+     * Checks whether the error dialog is enabled upon encountering exceptions/errors.
+     * Default is : true.
+     *
+     * @return true if the error dialog is activated, false otherwise.
+     */
+    public boolean isShowErrorDialog() {
+        return showErrorDialog;
+    }
+
     /**
      * Determines whether the error dialog would be shown on encountering exceptions.
      * Default is : true.
+     *
      * @param showErrorDialog true to activate the error dialog, false otherwise.
      */
     public void setShowErrorDialog(boolean showErrorDialog) {
@@ -971,11 +917,98 @@ public class JmeSurfaceView extends RelativeLayout implements SystemListener, Di
     }
 
     /**
-     * Checks whether the error dialog is enabled upon encountering exceptions/errors.
-     * Default is : true.
-     * @return true if the error dialog is activated, false otherwise.
+     * Determines whether the app context would be destructed
+     * with the holder activity context in case of {@link DestructionPolicy#DESTROY_WHEN_FINISH} or be
+     * spared for a second use in case of {@link DestructionPolicy#KEEP_WHEN_FINISH}.
+     * Default value is : {@link DestructionPolicy#DESTROY_WHEN_FINISH}.
+     *
+     * @see JmeSurfaceView#setDestructionPolicy(DestructionPolicy)
      */
-    public boolean isShowErrorDialog() {
-        return showErrorDialog;
+    public enum DestructionPolicy {
+        /**
+         * Finishes the game context with the activity context (ignores the static memory {@link GameState#legacyApplication}).
+         */
+        DESTROY_WHEN_FINISH,
+        /**
+         * Spares the game context inside a static memory {@link GameState#legacyApplication}
+         * when the activity context is destroyed, but the app stills in the background.
+         */
+        KEEP_WHEN_FINISH
+    }
+
+    /**
+     * Used as a static memory to protect the game context from destruction by Activity#onDestroy().
+     *
+     * @see DestructionPolicy
+     * @see JmeSurfaceView#setDestructionPolicy(DestructionPolicy)
+     */
+    protected static final class GameState {
+
+        private static LegacyApplication legacyApplication;
+        private static boolean firstUpdatePassed = false;
+
+        /**
+         * Private constructor to inhibit instantiation of this class.
+         */
+        private GameState() {
+        }
+
+        /**
+         * Returns the current application state.
+         *
+         * @return game state instance, holding jME3 states (JmeContext, AssetManager, StateManager, Graphics, Sound, Input, Spatial/Nodes in place, etcetera).
+         */
+        protected static LegacyApplication getLegacyApplication() {
+            return legacyApplication;
+        }
+
+        /**
+         * Replaces the current application state.
+         *
+         * @param legacyApplication the new app instance holding the game state (including {@link AssetLoader}s, {@link AudioNode}s, {@link Spatial}s, etcetera).
+         */
+        protected static void setLegacyApplication(LegacyApplication legacyApplication) {
+            GameState.legacyApplication = legacyApplication;
+        }
+
+        /**
+         * Tests the first update flag.
+         *
+         * @return true if the firstUpdate has passed, false otherwise.
+         */
+        protected static boolean isFirstUpdatePassed() {
+            return firstUpdatePassed;
+        }
+
+        /**
+         * Adjusts the first update flag.
+         *
+         * @param firstUpdatePassed set to true to determine whether the firstUpdate has passed, false otherwise.
+         */
+        protected static void setFirstUpdatePassed(boolean firstUpdatePassed) {
+            GameState.firstUpdatePassed = firstUpdatePassed;
+        }
+    }
+
+    /**
+     * Delays the attachment surface view on the UI for the sake of initial frame pacing and splash screens,
+     * delaying the display of the game (GlSurfaceView) would lead to a substantial delay in the
+     * {@link android.opengl.GLSurfaceView.Renderer#onDrawFrame(javax.microedition.khronos.opengles.GL10)} which would
+     * delay invoking both {@link LegacyApplication#initialize()} and {@link LegacyApplication#update()}.
+     *
+     * @see JmeSurfaceView#startRenderer(int)
+     * @see com.jme3.system.android.OGLESContext#onDrawFrame(javax.microedition.khronos.opengles.GL10)
+     */
+    private class RendererThread implements Runnable {
+        /**
+         * Delays the {@link GLSurfaceView} attachment on the UI thread.
+         *
+         * @see JmeSurfaceView#startRenderer(int)
+         */
+        @Override
+        public void run() {
+            addGlSurfaceView();
+            jmeSurfaceViewLogger.log(Level.INFO, "JmeSurfaceView's joined the UI thread");
+        }
     }
 }

jme3-android/src/main/java/com/jme3/app/jmeSurfaceView/OnExceptionThrown.java

@@ -33,13 +33,14 @@ package com.jme3.app.jmeSurfaceView;
 
 /**
  * An interface designed to listen for exceptions and fire an event when an exception is thrown.
- * @see JmeSurfaceView#setOnExceptionThrown(OnExceptionThrown)
  *
  * @author pavl_g.
+ * @see JmeSurfaceView#setOnExceptionThrown(OnExceptionThrown)
  */
 public interface OnExceptionThrown {
     /**
      * Listens for a thrown exception or a thrown error.
+     *
      * @param e the exception or the error that is throwable.
      */
     void onExceptionThrown(Throwable e);

jme3-android/src/main/java/com/jme3/app/jmeSurfaceView/OnLayoutDrawn.java

@@ -43,8 +43,9 @@ import com.jme3.app.LegacyApplication;
 public interface OnLayoutDrawn {
     /**
      * Dispatched when the layout is drawn on the screen.
+     *
      * @param legacyApplication the application instance.
-     * @param layout the current layout.
+     * @param layout            the current layout.
      */
     void onLayoutDrawn(LegacyApplication legacyApplication, View layout);
 }

jme3-android/src/main/java/com/jme3/app/jmeSurfaceView/OnRendererCompleted.java

@@ -36,17 +36,18 @@ import com.jme3.system.AppSettings;
 
 /**
  * An interface used for invoking an event when the user delay finishes, on the first update of the game.
- * @see JmeSurfaceView#setOnRendererCompleted(OnRendererCompleted)
  *
  * @author pavl_g.
+ * @see JmeSurfaceView#setOnRendererCompleted(OnRendererCompleted)
  */
 public interface OnRendererCompleted {
     /**
      * Invoked when the user delay finishes, on the first update of the game, the event is dispatched on the
      * enclosing Activity context thread.
-     * @see JmeSurfaceView#update()
+     *
      * @param application the current jme game instance.
      * @param appSettings the current window settings of the running jme game.
+     * @see JmeSurfaceView#update()
      */
     void onRenderCompletion(LegacyApplication application, AppSettings appSettings);
 }

jme3-android/src/main/java/com/jme3/app/jmeSurfaceView/OnRendererStarted.java

@@ -38,17 +38,18 @@ import com.jme3.app.LegacyApplication;
  * An interface used for invoking an event when the application is started explicitly from {@link JmeSurfaceView#startRenderer(int)}.
  * NB : This listener must be utilized before using {@link JmeSurfaceView#startRenderer(int)}, ie : it would be ignored if you try to use {@link JmeSurfaceView#setOnRendererStarted(OnRendererStarted)} after
  * {@link JmeSurfaceView#startRenderer(int)}.
- * @see JmeSurfaceView#setOnRendererStarted(OnRendererStarted)
  *
  * @author pavl_g.
+ * @see JmeSurfaceView#setOnRendererStarted(OnRendererStarted)
  */
 public interface OnRendererStarted {
     /**
      * Invoked when the game application is started by the {@link LegacyApplication#start()}, the event is dispatched on the
      * holder Activity context thread.
-     * @see JmeSurfaceView#startRenderer(int)
+     *
      * @param application the game instance.
-     * @param layout the enclosing layout.
+     * @param layout      the enclosing layout.
+     * @see JmeSurfaceView#startRenderer(int)
      */
     void onRenderStart(LegacyApplication application, View layout);
 }