add cinematic abstraction

Author: riccardobl

jme3-core/src/main/java/com/jme3/cinematic/Cinematic.java

@@ -94,7 +94,7 @@
  *
  * @author Nehon
  */
-public class Cinematic extends AbstractCinematicEvent implements AppState {
+public class Cinematic extends AbstractCinematicEvent implements AppState, CinematicHandler {
 
     private static final Logger logger = Logger.getLogger(Cinematic.class.getName());
     private static final String CINEMATIC_REF = "Cinematic:Refs";
@@ -544,6 +544,7 @@ public void setTime(float time) {
      * @param cinematicEvent the cinematic event
      * @return the keyFrame for that event.
      */
+    @Override
     public KeyFrame addCinematicEvent(float timeStamp, CinematicEvent cinematicEvent) {
         KeyFrame keyFrame = timeLine.getKeyFrameAtTime(timeStamp);
         if (keyFrame == null) {
@@ -565,6 +566,7 @@ public KeyFrame addCinematicEvent(float timeStamp, CinematicEvent cinematicEvent
      * @param cinematicEvent the cinematic event to enqueue
      * @return the timestamp the event was scheduled.
      */
+    @Override
     public float enqueueCinematicEvent(CinematicEvent cinematicEvent) {
         float scheduleTime = nextEnqueue;
         addCinematicEvent(scheduleTime, cinematicEvent);
@@ -578,6 +580,7 @@ public float enqueueCinematicEvent(CinematicEvent cinematicEvent) {
      * @param cinematicEvent the cinematicEvent to remove
      * @return true if the element has been removed
      */
+    @Override
     public boolean removeCinematicEvent(CinematicEvent cinematicEvent) {
         cinematicEvent.dispose();
         cinematicEvents.remove(cinematicEvent);
@@ -597,6 +600,7 @@ public boolean removeCinematicEvent(CinematicEvent cinematicEvent) {
      * @param cinematicEvent the cinematicEvent to remove
      * @return true if the element has been removed
      */
+    @Override
     public boolean removeCinematicEvent(float timeStamp, CinematicEvent cinematicEvent) {
         KeyFrame keyFrame = timeLine.getKeyFrameAtTime(timeStamp);
         return removeCinematicEvent(keyFrame, cinematicEvent);
@@ -610,6 +614,7 @@ public boolean removeCinematicEvent(float timeStamp, CinematicEvent cinematicEve
      * @param cinematicEvent the cinematicEvent to remove
      * @return true if the element has been removed
      */
+    @Override
     public boolean removeCinematicEvent(KeyFrame keyFrame, CinematicEvent cinematicEvent) {
         cinematicEvent.dispose();
         boolean ret = keyFrame.cinematicEvents.remove(cinematicEvent);
@@ -677,6 +682,7 @@ public void fitDuration() {
      * @param cam the scene camera.
      * @return the created CameraNode.
      */
+    @Override
     public CameraNode bindCamera(String cameraName, Camera cam) {
         if (cameras.containsKey(cameraName)) {
             throw new IllegalArgumentException("Camera " + cameraName + " is already bound to this cinematic");
@@ -696,6 +702,7 @@ public CameraNode bindCamera(String cameraName, Camera cam) {
      * Cinematic#bindCamera())
      * @return the cameraNode for this name
      */
+    @Override
     public CameraNode getCamera(String cameraName) {
         return cameras.get(cameraName);
     }
@@ -718,6 +725,7 @@ private void setEnableCurrentCam(boolean enabled) {
      * @param cameraName the camera name (as registered in
      * Cinematic#bindCamera())
      */
+    @Override
     public void setActiveCamera(String cameraName) {
         setEnableCurrentCam(false);
         currentCam = cameras.get(cameraName);
@@ -734,6 +742,7 @@ public void setActiveCamera(String cameraName) {
      * @param cameraName the camera name (as registered in
      * Cinematic#bindCamera())
      */
+    @Override
     public void activateCamera(final float timeStamp, final String cameraName) {
         addCinematicEvent(timeStamp, new CameraEvent(this, cameraName));
     }
@@ -757,6 +766,7 @@ private Map<String, Map<Object, Object>> getEventsData() {
      * @param key the key
      * @param object the data
      */
+    @Override
     public void putEventData(String type, Object key, Object object) {
         Map<String, Map<Object, Object>> data = getEventsData();
         Map<Object, Object> row = data.get(type);
@@ -774,6 +784,7 @@ public void putEventData(String type, Object key, Object object) {
      * @param key the key
      * @return the pre-existing object, or null
      */
+    @Override
     public Object getEventData(String type, Object key) {
         if (eventsData != null) {
             Map<Object, Object> row = eventsData.get(type);
@@ -790,6 +801,7 @@ public Object getEventData(String type, Object key) {
      * @param type the type of data
      * @param key the key of the data
      */
+    @Override
     public void removeEventData(String type, Object key) {
         if (eventsData != null) {
             Map<Object, Object> row = eventsData.get(type);
@@ -849,6 +861,7 @@ public void clear() {
      * This method removes all previously bound CameraNodes and clears the
      * internal camera map, effectively detaching all cameras from the scene.
      */
+    @Override
     public void clearCameras() {
         for (CameraNode cameraNode : cameras.values()) {
             scene.detachChild(cameraNode);

jme3-core/src/main/java/com/jme3/cinematic/CinematicHandler.java

@@ -0,0 +1,130 @@
+package com.jme3.cinematic;
+
+import com.jme3.cinematic.events.CinematicEvent;
+import com.jme3.renderer.Camera;
+import com.jme3.scene.CameraNode;
+
+public interface CinematicHandler {
+
+    /**
+     * Adds a cinematic event to this cinematic at the given timestamp. This
+     * operation returns a keyFrame
+     *
+     * @param timeStamp the time when the event will start after the beginning
+     * of the cinematic
+     * @param cinematicEvent the cinematic event
+     * @return the keyFrame for that event.
+     */
+    KeyFrame addCinematicEvent(float timeStamp, CinematicEvent cinematicEvent);
+
+    /**
+     * Enqueue a cinematic event to a Cinematic. This is handy when you
+     * want to chain events without knowing their durations.
+     *
+     * @param cinematicEvent the cinematic event to enqueue
+     * @return the timestamp the event was scheduled.
+     */
+    float enqueueCinematicEvent(CinematicEvent cinematicEvent);
+
+    /**
+     * removes the first occurrence found of the given cinematicEvent.
+     *
+     * @param cinematicEvent the cinematicEvent to remove
+     * @return true if the element has been removed
+     */
+    boolean removeCinematicEvent(CinematicEvent cinematicEvent);
+
+    /**
+     * removes the first occurrence found of the given cinematicEvent for the
+     * given time stamp.
+     *
+     * @param timeStamp the timestamp when the cinematicEvent has been added
+     * @param cinematicEvent the cinematicEvent to remove
+     * @return true if the element has been removed
+     */
+    boolean removeCinematicEvent(float timeStamp, CinematicEvent cinematicEvent);
+
+    /**
+     * removes the first occurrence found of the given cinematicEvent for the
+     * given keyFrame
+     *
+     * @param keyFrame the keyFrame returned by the addCinematicEvent method.
+     * @param cinematicEvent the cinematicEvent to remove
+     * @return true if the element has been removed
+     */
+    boolean removeCinematicEvent(KeyFrame keyFrame, CinematicEvent cinematicEvent);
+
+    /**
+     * Binds a camera to this Cinematic, tagged by a unique name. This method
+     * creates and returns a CameraNode for the cam and attaches it to the scene.
+     * The control direction is set to SpatialToCamera. This camera Node can
+     * then be used in other events to handle the camera movements during
+     * playback.
+     *
+     * @param cameraName the unique tag the camera should have
+     * @param cam the scene camera.
+     * @return the created CameraNode.
+     */
+    CameraNode bindCamera(String cameraName, Camera cam);
+
+    /**
+     * returns a cameraNode given its name
+     *
+     * @param cameraName the camera name (as registered in
+     * Cinematic#bindCamera())
+     * @return the cameraNode for this name
+     */
+    CameraNode getCamera(String cameraName);
+
+    /**
+     * Sets the active camera instantly (use activateCamera if you want to
+     * schedule that event)
+     *
+     * @param cameraName the camera name (as registered in
+     * Cinematic#bindCamera())
+     */
+    void setActiveCamera(String cameraName);
+
+    /**
+     * schedule an event that will activate the camera at the given time
+     *
+     * @param timeStamp the time to activate the cam
+     * @param cameraName the camera name (as registered in
+     * Cinematic#bindCamera())
+     */
+    void activateCamera(float timeStamp, String cameraName);
+
+    /**
+     * used internally put an eventdata in the cinematic
+     *
+     * @param type the type of data
+     * @param key the key
+     * @param object the data
+     */
+    void putEventData(String type, Object key, Object object);
+
+    /**
+     * used internally return and event data
+     *
+     * @param type the type of data
+     * @param key the key
+     * @return the pre-existing object, or null
+     */
+    Object getEventData(String type, Object key);
+
+    /**
+     * Used internally remove an eventData
+     *
+     * @param type the type of data
+     * @param key the key of the data
+     */
+    void removeEventData(String type, Object key);
+
+    /**
+     * Clears all camera nodes bound to the cinematic from the scene node.
+     * This method removes all previously bound CameraNodes and clears the
+     * internal camera map, effectively detaching all cameras from the scene.
+     */
+    void clearCameras();
+
+}

jme3-core/src/main/java/com/jme3/cinematic/events/AbstractCinematicEvent.java

@@ -34,7 +34,7 @@
 import com.jme3.animation.AnimationUtils;
 import com.jme3.animation.LoopMode;
 import com.jme3.app.Application;
-import com.jme3.cinematic.Cinematic;
+import com.jme3.cinematic.CinematicHandler;
 import com.jme3.cinematic.PlayState;
 import com.jme3.export.InputCapsule;
 import com.jme3.export.JmeExporter;
@@ -317,7 +317,7 @@ public void read(JmeImporter im) throws IOException {
      * @param cinematic ignored
      */
     @Override
-    public void initEvent(Application app, Cinematic cinematic) {
+    public void initEvent(Application app, CinematicHandler cinematic) {
     }
 
     /**

jme3-core/src/main/java/com/jme3/cinematic/events/AnimEvent.java

@@ -36,6 +36,7 @@
 import com.jme3.animation.LoopMode;
 import com.jme3.app.Application;
 import com.jme3.cinematic.Cinematic;
+import com.jme3.cinematic.CinematicHandler;
 import com.jme3.cinematic.PlayState;
 import com.jme3.export.InputCapsule;
 import com.jme3.export.JmeExporter;
@@ -127,10 +128,14 @@ protected AnimEvent() {
      * @param cinematic the Cinematic that contains this event
      */
     @Override
-    public void initEvent(Application app, Cinematic cinematic) {
+    public void initEvent(Application app, CinematicHandler cinematic) {
         super.initEvent(app, cinematic);
     }
 
+    @Deprecated
+    public void initEvent(Application app, Cinematic cinematic) {
+        initEvent(app, (CinematicHandler) cinematic);
+    }
 
     /**
      * Callback when the event is paused.

jme3-core/src/main/java/com/jme3/cinematic/events/AnimationEvent.java

@@ -34,6 +34,7 @@
 import com.jme3.animation.*;
 import com.jme3.app.Application;
 import com.jme3.cinematic.Cinematic;
+import com.jme3.cinematic.CinematicHandler;
 import com.jme3.cinematic.PlayState;
 import com.jme3.export.*;
 import com.jme3.scene.Node;
@@ -287,9 +288,9 @@ public AnimationEvent(Spatial model, String animationName, float initialDuration
 
     @Override
     @SuppressWarnings("unchecked")
-    public void initEvent(Application app, Cinematic cinematic) {
-        super.initEvent(app, cinematic);
-        this.cinematic = cinematic;
+    public void initEvent(Application app, CinematicHandler handler) {
+        super.initEvent(app, handler);
+        this.cinematic = (Cinematic) handler;
         if (channel == null) {
             Object s = cinematic.getEventData(MODEL_CHANNELS, model);
             if (s == null) {

jme3-core/src/main/java/com/jme3/cinematic/events/CameraEvent.java

@@ -32,7 +32,7 @@
 package com.jme3.cinematic.events;
 
 import com.jme3.app.Application;
-import com.jme3.cinematic.Cinematic;
+import com.jme3.cinematic.CinematicHandler;
 import com.jme3.export.InputCapsule;
 import com.jme3.export.JmeExporter;
 import com.jme3.export.JmeImporter;
@@ -55,7 +55,7 @@ public class CameraEvent extends AbstractCinematicEvent {
      * The `Cinematic` instance to which this event belongs and on which the
      * camera will be set.
      */
-    private Cinematic cinematic;
+    private CinematicHandler cinematic;
 
     /**
      * For serialization only. Do not use.
@@ -69,13 +69,13 @@ public CameraEvent() {
      * @param cinematic  The `Cinematic` instance this event belongs to (cannot be null).
      * @param cameraName The name of the camera to be activated by this event (cannot be null or empty).
      */
-    public CameraEvent(Cinematic cinematic, String cameraName) {
+    public CameraEvent(CinematicHandler cinematic, String cameraName) {
         this.cinematic = cinematic;
         this.cameraName = cameraName;
     }
 
     @Override
-    public void initEvent(Application app, Cinematic cinematic) {
+    public void initEvent(Application app, CinematicHandler cinematic) {
         super.initEvent(app, cinematic);
         this.cinematic = cinematic;
     }
@@ -116,15 +116,15 @@ public void setTime(float time) {
      * Returns the `Cinematic` instance associated with this event.
      * @return The `Cinematic` instance.
      */
-    public Cinematic getCinematic() {
+    public CinematicHandler getCinematic() {
         return cinematic;
     }
 
     /**
      * Sets the `Cinematic` instance for this event.
      * @param cinematic The `Cinematic` instance to set (cannot be null).
      */
-    public void setCinematic(Cinematic cinematic) {
+    public void setCinematic(CinematicHandler cinematic) {
         this.cinematic = cinematic;
     }
 

jme3-core/src/main/java/com/jme3/cinematic/events/CinematicEvent.java

@@ -33,7 +33,7 @@
 
 import com.jme3.animation.LoopMode;
 import com.jme3.app.Application;
-import com.jme3.cinematic.Cinematic;
+import com.jme3.cinematic.CinematicHandler;
 import com.jme3.cinematic.PlayState;
 import com.jme3.export.Savable;
 
@@ -135,7 +135,7 @@ public interface CinematicEvent extends Savable {
      * @param app the application
      * @param cinematic the cinematic
      */
-    public void initEvent(Application app, Cinematic cinematic);
+    public void initEvent(Application app, CinematicHandler cinematic);
 
     /**
      * Fast-forwards to the given time, where time=0 is the start of the event.

jme3-core/src/main/java/com/jme3/cinematic/events/MotionEvent.java

@@ -34,7 +34,7 @@
 import com.jme3.animation.AnimationUtils;
 import com.jme3.animation.LoopMode;
 import com.jme3.app.Application;
-import com.jme3.cinematic.Cinematic;
+import com.jme3.cinematic.CinematicHandler;
 import com.jme3.cinematic.MotionPath;
 import com.jme3.cinematic.PlayState;
 import com.jme3.export.InputCapsule;
@@ -197,7 +197,7 @@ public void internalUpdate(float tpf) {
     }
 
     @Override
-    public void initEvent(Application app, Cinematic cinematic) {
+    public void initEvent(Application app, CinematicHandler cinematic) {
         super.initEvent(app, cinematic);
         isControl = false;
     }