diff --git a/engine/src/core/com/jme3/app/state/AppState.java b/engine/src/core/com/jme3/app/state/AppState.java
index 34af8906a..cd6e02e51 100644
--- a/engine/src/core/com/jme3/app/state/AppState.java
+++ b/engine/src/core/com/jme3/app/state/AppState.java
@@ -70,8 +70,14 @@ import com.jme3.renderer.RenderManager;
public interface AppState {
/**
- * Called to initialize the AppState
. This method is called
- * in the next render pass after the AppState
is attached.
+ * Called by {@link AppStateManager} when transitioning this {@code AppState}
+ * from initializing to running.
+ * This will happen on the next iteration through the update loop after
+ * {@link AppStateManager#attach()} was called.
+ *
+ * AppStateManager
will call this only from the update loop
+ * inside the rendering thread. This means is it safe to modify the scene
+ * graph from this method.
*
* @param stateManager The state manager
* @param app The application
@@ -88,6 +94,9 @@ public interface AppState {
* Enable or disable the functionality of the AppState
.
* The effect of this call depends on implementation. An
* AppState
starts as being enabled by default.
+ * A disabled AppState
s does not get calls to
+ * {@link #update(float)}, {@link #render(RenderManager)}, or
+ * {@link #postRender()} from its {@link AppStateManager}.
*
* @param active activate the AppState or not.
*/
@@ -101,19 +110,29 @@ public interface AppState {
public boolean isEnabled();
/**
- * Called when the state was attached. Most implementations should do little
- * or nothing in this method. In particular any scene graph changes need to
- * be made in initialize()
.
+ * Called by {@link AppStateManager#attach()} when transitioning this
+ * AppState
from detached to initializing.
+ *
+ * There is no assumption about the thread from which this function is
+ * called, therefore it is unsafe to modify the scene graph
+ * from this method. Please use
+ * {@link #initialize(com.jme3.app.state.AppStateManager, com.jme3.app.Application) }
+ * instead.
*
* @param stateManager State manager to which the state was attached to.
*/
public void stateAttached(AppStateManager stateManager);
/**
- * Called when the state was detached. Most implementations should do little
- * or nothing in this method. In particular any scene graph changes need to
- * be made in cleanup()
.
- *
+ * Called by {@link AppStateManager#detach()} when transitioning this
+ * AppState
from running to terminating.
+ *
+ * There is no assumption about the thread from which this function is
+ * called, therefore it is unsafe to modify the scene graph
+ * from this method. Please use
+ * {@link #cleanup() }
+ * instead.
+ *
* @param stateManager The state manager from which the state was detached from.
*/
public void stateDetached(AppStateManager stateManager);
@@ -122,29 +141,31 @@ public interface AppState {
* Called to update the AppState
. This method will be called
* every render pass if the AppState
is both attached and enabled.
*
- * @param tpf Time per frame.
+ * @param tpf Time since the last call to update(), in seconds.
*/
public void update(float tpf);
/**
- * Render the state.
+ * Render the state. This method will be called
+ * every render pass if the AppState
is both attached and enabled.
*
* @param rm RenderManager
*/
public void render(RenderManager rm);
/**
- * Called after all rendering commands are flushed.
+ * Called after all rendering commands are flushed. This method will be called
+ * every render pass if the AppState
is both attached and enabled.
*/
public void postRender();
/**
- * Called to clean up the AppState
after it has been removed. This
+ * Called by {@link AppStateManager} when transitioning this
+ * AppState
from terminating to detached. This
* method is called the following render pass after the AppState
has
* been detached and is always called once and only once for each time
* initialize()
is called. Either when the AppState
* is detached or when the application terminates (if it terminates normally).
- *
*/
public void cleanup();