Remove bool flag for jump_to commands

Author: exbluesbreaker

doc/libf3d/06-MIGRATION.md

@@ -27,3 +27,11 @@ The callback takes an argument of type `f3d::interactor::interactor_state_t` all
 ## F3D_PLUGINS_PATH
 
 When running F3D, it was possible to specify the path for loading plugins using the environment variable `F3D_PLUGINS_PATH`. This variable has been removed in favor of the CLI option `--plugins-path` which is more secure.
+
+## Animation jump commands
+
+The `jump_to_frame` and `jump_to_keyframe` commands no longer take a second boolean argument to control whether the jump is relative or absolute. They now always perform an absolute jump and take a single index argument.
+
+To perform a relative jump, use the new dedicated `jump_to_frame_relative` and `jump_to_keyframe_relative` commands, which take a single offset argument.
+
+So `jump_to_frame 10 false` becomes `jump_to_frame 10`, and `jump_to_frame 1 true` becomes `jump_to_frame_relative 1`. Likewise `jump_to_keyframe 4 false` becomes `jump_to_keyframe 4`, and `jump_to_keyframe 1 true` becomes `jump_to_keyframe_relative 1`.

doc/user/07-COMMANDS.md

@@ -75,28 +75,37 @@ Supports `front`, `top`, `right`, `back`, `bottom`, `left`, `isometric` argument
 
 `toggle_animation_backward`: A specific command to start/stop the animation backward. No argument.
 
-`jump_to_frame`: A specific command to load an animation at a specific frame, takes a number and a boolean as arguments.
+`jump_to_frame`: A specific command to load an animation at a specific frame, takes a frame index as argument.
 eg:
 
-- `jump_to_frame 1 true` jump to next frame.
-- `jump_to_frame -1 true` jump to previous frame.
-- `jump_to_frame 0 false` jump to frame 0.
-- `jump_to_frame 1 false` jump to frame 1.
-- `jump_to_frame 10 false` jump to frame 10.
-- `jump_to_frame -1 false` jump to last frame.
-- `jump_to_frame -2 false` jump to second last frame.
+- `jump_to_frame 0` jump to frame 0.
+- `jump_to_frame 1` jump to frame 1.
+- `jump_to_frame 10` jump to frame 10.
+- `jump_to_frame -1` jump to last frame.
+- `jump_to_frame -2` jump to second last frame.
 
-`jump_to_keyframe`: A specific command to load an animation at a specific keyframe, takes a number and a boolean as arguments.
+`jump_to_frame_relative`: A specific command to move the animation by a number of frames relative to the current frame, takes a frame offset as argument.
+eg:
+
+- `jump_to_frame_relative 1` jump to next frame.
+- `jump_to_frame_relative -1` jump to previous frame.
+
+`jump_to_keyframe`: A specific command to load an animation at a specific keyframe, takes a keyframe index as argument.
+When jumping to a keyframe, the target keyframe index is adjusted to stay within the total number of available keyframes, avoiding invalid keyframe access.
+eg:
+
+- `jump_to_keyframe 0` jump to animation start frame.
+- `jump_to_keyframe 1` jump to keyframe 1.
+- `jump_to_keyframe 10` jump to keyframe 10.
+
+`jump_to_keyframe_relative`: A specific command to move the animation by a number of keyframes relative to the current keyframe, takes a keyframe offset as argument.
 When jumping between keyframes, the target keyframe index is adjusted to stay within the total number of available keyframes, avoiding invalid keyframe access.
 eg:
 
-- `jump_to_keyframe 1 true` jump to next keyframe.
-- `jump_to_keyframe -1 true` jump to previous keyframe.
-- `jump_to_keyframe 0 true` jump to closest keyframe.
-- `jump_to_keyframe 0 false` jump to animation start frame.
-- `jump_to_keyframe 1 false` jump to keyframe 1.
-- `jump_to_keyframe 10 false` jump to keyframe 10.
-- `jump_to_keyframe 10 true` jump 10 keyframes ahead.
+- `jump_to_keyframe_relative 0` jump to closest keyframe.
+- `jump_to_keyframe_relative 1` jump to next keyframe.
+- `jump_to_keyframe_relative -1` jump to previous keyframe.
+- `jump_to_keyframe_relative 10` jump 10 keyframes ahead.
 
 This command is currently supported only by the following readers :
 

library/src/interactor_impl.cxx

@@ -1112,15 +1112,28 @@ interactor& interactor_impl::initCommands()
     },
     command_documentation_t{ "roll_camera value", "roll the camera on its side" });
 
-  this->addCommand("jump_to_frame",
+  this->addCommand(
+    "jump_to_frame",
     [&](const std::vector<std::string>& args)
     {
-      check_args(args, 2, "jump_to_frame");
+      check_args(args, 1, "jump_to_frame");
       const int frame = options::parse<int>(args[0]);
-      const bool relative = options::parse<bool>(args[1]);
       this->Internals->AnimationManager->SetDeltaTime(this->Internals->CallbackDeltaTime);
-      this->Internals->AnimationManager->JumpToFrame(frame, relative);
-    });
+      this->Internals->AnimationManager->JumpToFrame(frame, false);
+    },
+    command_documentation_t{ "jump_to_frame index", "load animation at a specific frame" });
+
+  this->addCommand(
+    "jump_to_frame_relative",
+    [&](const std::vector<std::string>& args)
+    {
+      check_args(args, 1, "jump_to_frame_relative");
+      const int frame = options::parse<int>(args[0]);
+      this->Internals->AnimationManager->SetDeltaTime(this->Internals->CallbackDeltaTime);
+      this->Internals->AnimationManager->JumpToFrame(frame, true);
+    },
+    command_documentation_t{
+      "jump_to_frame_relative offset", "move animation a number of frames forward or backward" });
 
   this->addCommand(
     "elevation_camera",
@@ -1307,12 +1320,22 @@ interactor& interactor_impl::initCommands()
     "jump_to_keyframe",
     [&](const std::vector<std::string>& args)
     {
-      check_args(args, 2, "jump_to_keyframe");
-      int keyframe = options::parse<int>(args[0]);
-      bool relative = options::parse<bool>(args[1]);
-      this->Internals->AnimationManager->JumpToKeyFrame(keyframe, relative);
+      check_args(args, 1, "jump_to_keyframe");
+      const int keyframe = options::parse<int>(args[0]);
+      this->Internals->AnimationManager->JumpToKeyFrame(keyframe, false);
+    },
+    command_documentation_t{ "jump_to_keyframe index", "jump to a specific animation keyframe" });
+
+  this->addCommand(
+    "jump_to_keyframe_relative",
+    [&](const std::vector<std::string>& args)
+    {
+      check_args(args, 1, "jump_to_keyframe_relative");
+      const int keyframe = options::parse<int>(args[0]);
+      this->Internals->AnimationManager->JumpToKeyFrame(keyframe, true);
     },
-    command_documentation_t{ "jump_to_keyframe", "Jump to animation's key frame" });
+    command_documentation_t{
+      "jump_to_keyframe_relative offset", "move a number of keyframes forward or backward" });
 
   this->addCommand(
     "toggle_animation", [&](const std::vector<std::string>&) { this->toggleAnimation(); },

testing/scripts/TestCommandScriptAxesGridAnimation.txt

@@ -1,4 +1,4 @@
-jump_to_frame 25 true
-jump_to_frame 25 true
-jump_to_frame 25 true
-jump_to_frame 25 true
+jump_to_frame_relative 25
+jump_to_frame_relative 25
+jump_to_frame_relative 25
+jump_to_frame_relative 25

testing/scripts/TestCommandScriptJumpToAbsoluteKeyFrame.txt

@@ -1 +1 @@
-jump_to_keyframe 4 false
+jump_to_keyframe 4

testing/scripts/TestCommandScriptJumpToAbsoluteKeyFrameMultipleAnimations.txt

@@ -1 +1 @@
-jump_to_keyframe 14 false
+jump_to_keyframe 14

testing/scripts/TestCommandScriptJumpToClosestKeyFrame.txt

@@ -1 +1 @@
-jump_to_keyframe 0 true
+jump_to_keyframe_relative 0

testing/scripts/TestCommandScriptJumpToFirstFrame.txt

@@ -1 +1 @@
-jump_to_frame 0 false
+jump_to_frame 0

testing/scripts/TestCommandScriptJumpToFirstKeyFrame.txt

@@ -1 +1 @@
-jump_to_keyframe 1 false
+jump_to_keyframe 1

testing/scripts/TestCommandScriptJumpToKeyFrameNoAnimation.txt

@@ -1 +1 @@
-jump_to_keyframe 17 false
+jump_to_keyframe 17