Go to frame api

c/interactor_c_api.cxx

@@ -144,6 +144,66 @@ f3d_interactor_animation_direction_t f3d_interactor_get_animation_direction(
   return static_cast<f3d_interactor_animation_direction_t>(cpp_direction);
 }
 
+//----------------------------------------------------------------------------
+double f3d_interactor_get_delta_time(f3d_interactor_t* interactor)
+{
+  if (!interactor)
+  {
+    return 0.0;
+  }
+
+  f3d::interactor* cpp_interactor = reinterpret_cast<f3d::interactor*>(interactor);
+  return cpp_interactor->getDeltaTime();
+}
+
+//----------------------------------------------------------------------------
+void f3d_interactor_jump_to_frame(f3d_interactor_t* interactor, int index)
+{
+  if (!interactor)
+  {
+    return;
+  }
+
+  f3d::interactor* cpp_interactor = reinterpret_cast<f3d::interactor*>(interactor);
+  cpp_interactor->jumpToFrame(index);
+}
+
+//----------------------------------------------------------------------------
+void f3d_interactor_jump_to_frame_relative(f3d_interactor_t* interactor, int offset)
+{
+  if (!interactor)
+  {
+    return;
+  }
+
+  f3d::interactor* cpp_interactor = reinterpret_cast<f3d::interactor*>(interactor);
+  cpp_interactor->jumpToFrameRelative(offset);
+}
+
+//----------------------------------------------------------------------------
+void f3d_interactor_jump_to_keyframe(f3d_interactor_t* interactor, int index)
+{
+  if (!interactor)
+  {
+    return;
+  }
+
+  f3d::interactor* cpp_interactor = reinterpret_cast<f3d::interactor*>(interactor);
+  cpp_interactor->jumpToKeyframe(index);
+}
+
+//----------------------------------------------------------------------------
+void f3d_interactor_jump_to_keyframe_relative(f3d_interactor_t* interactor, int offset)
+{
+  if (!interactor)
+  {
+    return;
+  }
+
+  f3d::interactor* cpp_interactor = reinterpret_cast<f3d::interactor*>(interactor);
+  cpp_interactor->jumpToKeyframeRelative(offset);
+}
+
 //----------------------------------------------------------------------------
 void f3d_interactor_enable_camera_movement(f3d_interactor_t* interactor)
 {

c/interactor_c_api.h

@@ -335,6 +335,52 @@ extern "C"
    */
   F3D_EXPORT f3d_interactor_animation_direction_t f3d_interactor_get_animation_direction(
     f3d_interactor_t* interactor);
+
+  /**
+   * @brief Get the delta time used by the event loop.
+   *
+   * @param interactor Interactor handle.
+   * @return delta time in seconds.
+   */
+  F3D_EXPORT double f3d_interactor_get_delta_time(f3d_interactor_t* interactor);
+
+  /**
+   * @brief Jump to a specific frame by index.
+   *
+   * A negative index counts from the end of the animation (e.g. -1 is the last frame).
+   *
+   * @param interactor Interactor handle.
+   * @param index Frame index.
+   */
+  F3D_EXPORT void f3d_interactor_jump_to_frame(f3d_interactor_t* interactor, int index);
+
+  /**
+   * @brief Move the animation by a number of frames relative to the current frame.
+   *
+   * @param interactor Interactor handle.
+   * @param offset Frame offset. Positive moves forward, negative moves backward.
+   */
+  F3D_EXPORT void f3d_interactor_jump_to_frame_relative(f3d_interactor_t* interactor, int offset);
+
+  /**
+   * @brief Jump to a specific keyframe by index.
+   *
+   * The index is clamped to stay within the available keyframes range.
+   *
+   * @param interactor Interactor handle.
+   * @param index Keyframe index.
+   */
+  F3D_EXPORT void f3d_interactor_jump_to_keyframe(f3d_interactor_t* interactor, int index);
+
+  /**
+   * @brief Move the animation by a number of keyframes relative to the closest keyframe.
+   *
+   * @param interactor Interactor handle.
+   * @param offset Keyframe offset. Positive moves forward, negative moves backward.
+   *               An offset of 0 jumps to the closest keyframe.
+   */
+  F3D_EXPORT void f3d_interactor_jump_to_keyframe_relative(
+    f3d_interactor_t* interactor, int offset);
   ///@}
 
   ///@{ @name Movement

c/scene_c_api.cxx

@@ -256,6 +256,30 @@ void f3d_scene_load_animation_time(f3d_scene_t* scene, double time_value)
   cpp_scene->loadAnimationTime(time_value);
 }
 
+//----------------------------------------------------------------------------
+double f3d_scene_animation_time(f3d_scene_t* scene)
+{
+  if (!scene)
+  {
+    return 0.0;
+  }
+
+  f3d::scene* cpp_scene = reinterpret_cast<f3d::scene*>(scene);
+  return cpp_scene->animationTime();
+}
+
+//----------------------------------------------------------------------------
+size_t f3d_scene_animation_frame(f3d_scene_t* scene)
+{
+  if (!scene)
+  {
+    return 0;
+  }
+
+  f3d::scene* cpp_scene = reinterpret_cast<f3d::scene*>(scene);
+  return cpp_scene->animationFrame();
+}
+
 //----------------------------------------------------------------------------
 double* f3d_scene_get_animation_keyframes(f3d_scene_t* scene, unsigned int* count)
 {

c/scene_c_api.h

@@ -135,6 +135,22 @@ extern "C"
    */
   F3D_EXPORT void f3d_scene_load_animation_time(f3d_scene_t* scene, double time_value);
 
+  /**
+   * @brief Get current animation time of the loaded files.
+   *
+   * @param scene Scene handle.
+   * @return Current animation time.
+   */
+  F3D_EXPORT double f3d_scene_animation_time(f3d_scene_t* scene);
+
+  /**
+   * @brief Get current animation frame of the loaded files.
+   *
+   * @param scene Scene handle.
+   * @return Current animation frame.
+   */
+  F3D_EXPORT size_t f3d_scene_animation_frame(f3d_scene_t* scene);
+
   /**
    * @brief Get keyframes times of loaded files
    *

c/testing/test_interactor.c

@@ -42,6 +42,12 @@ int test_interactor()
     f3d_interactor_get_animation_direction(interactor);
   (void)direction;
   f3d_interactor_stop_animation(interactor);
+  f3d_interactor_jump_to_frame(interactor, 24);
+  f3d_interactor_jump_to_frame_relative(interactor, 1);
+  f3d_interactor_jump_to_frame(interactor, 0);
+  f3d_interactor_jump_to_keyframe(interactor, 4);
+  f3d_interactor_jump_to_keyframe_relative(interactor, 1);
+  f3d_interactor_jump_to_keyframe(interactor, 0);
 
   f3d_interactor_enable_camera_movement(interactor);
   f3d_interactor_disable_camera_movement(interactor);
@@ -59,6 +65,8 @@ int test_interactor()
   f3d_interactor_trigger_text_character(interactor, 65);
 
   f3d_interactor_trigger_event_loop(interactor, 0.016);
+  double delta = f3d_interactor_get_delta_time(interactor);
+  (void)delta;
 
   f3d_interactor_trigger_notification(interactor, "foo", "bar", 3.0);
 

c/testing/test_scene.c

@@ -78,6 +78,8 @@ int test_scene()
   // Test the rest of the API
 
   f3d_scene_load_animation_time(scene, 0.5);
+  f3d_scene_animation_time(scene);
+  f3d_scene_animation_frame(scene);
   double min_time, max_time;
   f3d_scene_animation_time_range(scene, &min_time, &max_time);
   unsigned int anim_count = f3d_scene_available_animations(scene);

doc/libf3d/02-CLASSES.md

@@ -41,7 +41,7 @@ Window lets you `render`, `renderToImage` and control other parameters of the wi
 
 When provided by the engine, the interactor class lets you choose how to interact with the data.
 
-It contains the animation API to start and stop animation as well as recover the number of available animations and their names.
+It contains the animation API to start and stop animation, go to frames or keyframes, as well as recover the number of available animations and their names.
 
 Interactor lets you add, remove and trigger your [commands](../user/07-COMMANDS.md).
 The commands let you interact with the libf3d in a very flexible manner.

java/F3DInteractorBindings.cxx

@@ -438,6 +438,32 @@ extern "C"
     return self;
   }
 
+  JNIEXPORT jobject JAVA_BIND(Interactor, jumpToFrame)(JNIEnv* env, jobject self, jint index)
+  {
+    GetInteractor(env, self).jumpToFrame(static_cast<int>(index));
+    return self;
+  }
+
+  JNIEXPORT jobject JAVA_BIND(Interactor, jumpToFrameRelative)(
+    JNIEnv* env, jobject self, jint offset)
+  {
+    GetInteractor(env, self).jumpToFrameRelative(static_cast<int>(offset));
+    return self;
+  }
+
+  JNIEXPORT jobject JAVA_BIND(Interactor, jumpToKeyframe)(JNIEnv* env, jobject self, jint index)
+  {
+    GetInteractor(env, self).jumpToKeyframe(static_cast<int>(index));
+    return self;
+  }
+
+  JNIEXPORT jobject JAVA_BIND(Interactor, jumpToKeyframeRelative)(
+    JNIEnv* env, jobject self, jint offset)
+  {
+    GetInteractor(env, self).jumpToKeyframeRelative(static_cast<int>(offset));
+    return self;
+  }
+
   JNIEXPORT jboolean JAVA_BIND(Interactor, isPlayingAnimation)(JNIEnv* env, jobject self)
   {
     return GetInteractor(env, self).isPlayingAnimation();
@@ -456,6 +482,11 @@ extern "C"
       enumClass, fromValueMethod, static_cast<int>(nativeDirection));
   }
 
+  JNIEXPORT jdouble JAVA_BIND(Interactor, getDeltaTime)(JNIEnv* env, jobject self)
+  {
+    return GetInteractor(env, self).getDeltaTime();
+  }
+
   JNIEXPORT jobject JAVA_BIND(Interactor, enableCameraMovement)(JNIEnv* env, jobject self)
   {
     GetInteractor(env, self).enableCameraMovement();

java/F3DSceneBindings.cxx

@@ -388,6 +388,16 @@ extern "C"
     return self;
   }
 
+  JNIEXPORT jdouble JAVA_BIND(Scene, animationTime)(JNIEnv* env, jobject self)
+  {
+    return GetEngine(env, self)->getScene().animationTime();
+  }
+
+  JNIEXPORT jlong JAVA_BIND(Scene, animationFrame)(JNIEnv* env, jobject self)
+  {
+    return static_cast<jlong>(GetEngine(env, self)->getScene().animationFrame());
+  }
+
   JNIEXPORT jdoubleArray JAVA_BIND(Scene, animationTimeRange)(JNIEnv* env, jobject self)
   {
     auto [minTime, maxTime] = GetEngine(env, self)->getScene().animationTimeRange();

java/Interactor.java

@@ -397,6 +397,47 @@ public Interactor startAnimation() {
      */
     public native AnimationDirection getAnimationDirection();
 
+    /**
+     * Get the delta time used by the event loop.
+     *
+     * @return delta time in seconds
+     */
+    public native double getDeltaTime();
+
+    /**
+     * Jump to a specific frame by index.
+     * A negative index counts from the end of the animation.
+     *
+     * @param index frame index
+     * @return this interactor for method chaining
+     */
+    public native Interactor jumpToFrame(int index);
+
+    /**
+     * Move the animation by a number of frames relative to the current frame.
+     *
+     * @param offset frame offset, positive moves forward, negative moves backward
+     * @return this interactor for method chaining
+     */
+    public native Interactor jumpToFrameRelative(int offset);
+
+    /**
+     * Jump to a specific keyframe by index.
+     *
+     * @param index keyframe index
+     * @return this interactor for method chaining
+     */
+    public native Interactor jumpToKeyframe(int index);
+
+    /**
+     * Move the animation by a number of keyframes relative to the closest keyframe.
+     *
+     * @param offset keyframe offset, positive moves forward, negative moves backward.
+     *               An offset of 0 jumps to the closest keyframe.
+     * @return this interactor for method chaining
+     */
+    public native Interactor jumpToKeyframeRelative(int offset);
+
     /**
      * Enable camera movement.
      *

java/Scene.java

@@ -161,6 +161,20 @@ public Scene add(byte[] buffer)
      */
     public native Scene loadAnimationTime(double timeValue);
 
+    /**
+     * Get current animation time of the loaded files.
+     *
+     * @return current animation time
+     */
+    public native double animationTime();
+
+    /**
+     * Get current animation frame of the loaded files.
+     *
+     * @return current animation frame
+     */
+    public native long animationFrame();
+
     /**
      * Get animation time range of currently added files.
      *

java/testing/TestInteractor.java

@@ -50,6 +50,13 @@ public static void main(String[] args) {
     interactor.stopAnimation();
     interactor.isPlayingAnimation();
     interactor.getAnimationDirection();
+    interactor.getDeltaTime();
+    interactor.jumpToFrame(24);
+    interactor.jumpToFrameRelative(1);
+    interactor.jumpToFrame(0);
+    interactor.jumpToKeyframe(4);
+    interactor.jumpToKeyframeRelative(1);
+    interactor.jumpToKeyframe(0);
 
     interactor.triggerNotification("foo", "bar", 3.0);
 

java/testing/TestScene.java

@@ -46,6 +46,8 @@ public static void main(String[] args) throws FileNotFoundException, IOException
     scene.add(mesh);
 
     scene.loadAnimationTime(0.5);
+    scene.animationTime();
+    scene.animationFrame();
     scene.animationTimeRange();
     scene.getAnimationKeyFrames();
     scene.availableAnimations();

library/private/animationManager.h

@@ -127,10 +127,19 @@ class animationManager
     return this->CurrentTime;
   }
 
+  /**
+   * Return the current animation frame number
+   */
+  size_t GetCurrentFrame() const;
+
   /**
    *Set the animation in delta time in seconds
    */
   void SetDeltaTime(double deltaTime);
+  double GetDeltaTime() const
+  {
+    return this->DeltaTime;
+  }
 
   /**
    * Advance animationTime of deltaTime and call loadAtTime accordingly

library/private/interactor_impl.h

@@ -73,6 +73,11 @@ class interactor_impl : public interactor
   interactor& stopAnimation() override;
   bool isPlayingAnimation() override;
   interactor::AnimationDirection getAnimationDirection() override;
+  double getDeltaTime() const override;
+  interactor& jumpToFrame(int index) override;
+  interactor& jumpToFrameRelative(int offset) override;
+  interactor& jumpToKeyframe(int index) override;
+  interactor& jumpToKeyframeRelative(int offset) override;
 
   interactor& enableCameraMovement() override;
   interactor& disableCameraMovement() override;