Animation: add function to apply a pose from an Action

Add `BKE_pose_apply_action(object, action, anim_eval_context)` function
and expose in RNA as `Pose.apply_action(action, evaluation_time)`.

This makes it possible to do the following:

- Have a rig in pose mode.
- Select a subset of the bones.
- Have some Action loaded that contains the pose you want to apply.
- Run `C.object.pose.apply_pose_from_action(D.actions['PoseName'])`
- The selected bones are now posed as determined by the Action.

Just like Blender's current pose library, having no bones selected acts
the same as having all bones selected.

Manifest Task: T86159

Reviewed By: Severin

Differential Revision: https://developer.blender.org/D10578

4 files changed, 189 insertions, 5 deletions

diff --git a/source/blender/blenkernel/BKE_armature.h b/source/blender/blenkernel/BKE_armature.h
index db44a771095..f5face2120e 100644
--- a/source/blender/blenkernel/BKE_armature.h
+++ b/source/blender/blenkernel/BKE_armature.h
@@ -27,6 +27,8 @@
 extern "C" {
 #endif
 
+struct AnimationEvalContext;
+struct bAction;
 struct BMEditMesh;
 struct Bone;
 struct Depsgraph;
@@ -193,6 +195,12 @@ void BKE_pose_where_is_bone(struct Depsgraph *depsgraph,
                             bool do_extra);
 void BKE_pose_where_is_bone_tail(struct bPoseChannel *pchan);
 
+/* Evaluate the action and apply it to the pose. If any pose bones are selected, only FCurves that
+ * relate to those bones are evaluated. */
+void BKE_pose_apply_action(struct Object *ob,
+                           struct bAction *action,
+                           struct AnimationEvalContext *anim_eval_context);
+
 /* get_objectspace_bone_matrix has to be removed still */
 void get_objectspace_bone_matrix(struct Bone *bone,
                                  float M_accumulatedMatrix[4][4],
diff --git a/source/blender/blenkernel/CMakeLists.txt b/source/blender/blenkernel/CMakeLists.txt
index 1e7986eedd9..c954d0670f0 100644
--- a/source/blender/blenkernel/CMakeLists.txt
+++ b/source/blender/blenkernel/CMakeLists.txt
@@ -77,6 +77,7 @@ set(SRC
   intern/appdir.c
   intern/armature.c
   intern/armature_deform.c
+  intern/armature_pose.cc
   intern/armature_update.c
   intern/asset.cc
   intern/attribute.c
diff --git a/source/blender/blenkernel/intern/armature_pose.cc b/source/blender/blenkernel/intern/armature_pose.cc
new file mode 100644
index 00000000000..a9613da2335
--- /dev/null
+++ b/source/blender/blenkernel/intern/armature_pose.cc
@@ -0,0 +1,133 @@
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * The Original Code is Copyright (C) 2015 Blender Foundation.
+ * All rights reserved.
+ *
+ * Defines and code for core node types
+ */
+
+/** \file
+ * \ingroup bke
+ */
+
+#include "BKE_animsys.h"
+#include "BKE_armature.h"
+
+#include "BLI_set.hh"
+
+#include "DNA_action_types.h"
+#include "DNA_anim_types.h"
+#include "DNA_armature_types.h"
+#include "DNA_object_types.h"
+
+#include "RNA_access.h"
+
+namespace {
+using BoneNameSet = blender::Set<std::string>;
+
+// Forward declarations.
+BoneNameSet pose_apply_find_selected_bones(const bPose *pose);
+void pose_apply_disable_fcurves_for_unselected_bones(bAction *action,
+                                                     const BoneNameSet &selected_bone_names);
+void pose_apply_restore_fcurves(bAction *action);
+}  // namespace
+
+void BKE_pose_apply_action(struct Object *ob,
+                           struct bAction *action,
+                           struct AnimationEvalContext *anim_eval_context)
+{
+  bPose *pose = ob->pose;
+  if (pose == NULL) {
+    return;
+  }
+
+  const BoneNameSet selected_bone_names = pose_apply_find_selected_bones(pose);
+  const bool limit_to_selected_bones = !selected_bone_names.is_empty();
+
+  if (limit_to_selected_bones) {
+    /* Mute all FCurves that are not associated with selected bones. This separates the concept of
+     * bone selection from the FCurve evaluation code. */
+    pose_apply_disable_fcurves_for_unselected_bones(action, selected_bone_names);
+  }
+
+  /* Apply the Action. */
+  PointerRNA pose_owner_ptr;
+  RNA_id_pointer_create(&ob->id, &pose_owner_ptr);
+  animsys_evaluate_action(&pose_owner_ptr, action, anim_eval_context, false);
+
+  if (limit_to_selected_bones) {
+    pose_apply_restore_fcurves(action);
+  }
+}
+
+namespace {
+BoneNameSet pose_apply_find_selected_bones(const bPose *pose)
+{
+  BoneNameSet selected_bone_names;
+  bool all_bones_selected = true;
+  bool no_bones_selected = true;
+
+  LISTBASE_FOREACH (bPoseChannel *, pchan, &pose->chanbase) {
+    const bool is_selected = (pchan->bone->flag & BONE_SELECTED) != 0 &&
+                             (pchan->bone->flag & BONE_HIDDEN_P) == 0;
+    all_bones_selected &= is_selected;
+    no_bones_selected &= !is_selected;
+
+    if (is_selected) {
+      /* Bone names are unique, so no need to check for duplicates. */
+      selected_bone_names.add_new(pchan->name);
+    }
+  }
+
+  /* If no bones are selected, act as if all are. */
+  if (all_bones_selected || no_bones_selected) {
+    return BoneNameSet(); /* An empty set means "ignore bone selection". */
+  }
+  return selected_bone_names;
+}
+
+void pose_apply_restore_fcurves(bAction *action)
+{
+  /* TODO(Sybren): Restore the FCurve flags, instead of just erasing the 'disabled' flag. */
+  LISTBASE_FOREACH (FCurve *, fcu, &action->curves) {
+    fcu->flag &= ~FCURVE_DISABLED;
+  }
+}
+
+void pose_apply_disable_fcurves_for_unselected_bones(bAction *action,
+                                                     const BoneNameSet &selected_bone_names)
+{
+  LISTBASE_FOREACH (FCurve *, fcu, &action->curves) {
+    if (!fcu->rna_path || !strstr(fcu->rna_path, "pose.bones[")) {
+      continue;
+    }
+
+    /* Get bone name, and check if this bone is selected. */
+    char *bone_name = BLI_str_quoted_substrN(fcu->rna_path, "pose.bones[");
+    if (!bone_name) {
+      continue;
+    }
+    const bool is_selected = selected_bone_names.contains(bone_name);
+    MEM_freeN(bone_name);
+    if (is_selected) {
+      continue;
+    }
+
+    fcu->flag |= FCURVE_DISABLED;
+  }
+}
+
+}  // namespace
diff --git a/source/blender/makesrna/intern/rna_pose_api.c b/source/blender/makesrna/intern/rna_pose_api.c
index 59704b00391..d93972aa0ad 100644
--- a/source/blender/makesrna/intern/rna_pose_api.c
+++ b/source/blender/makesrna/intern/rna_pose_api.c
@@ -38,9 +38,14 @@
 
 #ifdef RNA_RUNTIME
 
-/* #include "DNA_anim_types.h" */
+#  include "BKE_animsys.h"
 #  include "BKE_armature.h"
-#  include "DNA_action_types.h" /* bPose */
+#  include "BKE_context.h"
+
+#  include "DNA_action_types.h"
+#  include "DNA_anim_types.h"
+
+#  include "BLI_ghash.h"
 
 static float rna_PoseBone_do_envelope(bPoseChannel *chan, float *vec)
 {
@@ -102,12 +107,49 @@ static void rna_PoseBone_compute_bbone_handles(bPoseChannel *pchan,
   BKE_pchan_bbone_handles_compute(
       &params, ret_h1, ret_roll1, ret_h2, ret_roll2, ease || offsets, offsets);
 }
+
+static void rna_Pose_apply_pose_from_action(ID *pose_owner,
+                                            bContext *C,
+                                            bAction *action,
+                                            const float evaluation_time)
+{
+  BLI_assert(GS(pose_owner->name) == ID_OB);
+  Object *pose_owner_ob = (Object *)pose_owner;
+
+  AnimationEvalContext anim_eval_context = {CTX_data_depsgraph_pointer(C), evaluation_time};
+  BKE_pose_apply_action(pose_owner_ob, action, &anim_eval_context);
+
+  /* Do NOT tag with ID_RECALC_ANIMATION, as that would overwrite the just-applied pose. */
+  DEG_id_tag_update(pose_owner, ID_RECALC_GEOMETRY);
+  WM_event_add_notifier(C, NC_OBJECT | ND_POSE, pose_owner);
+}
+
 #else
 
-void RNA_api_pose(StructRNA *UNUSED(srna))
+void RNA_api_pose(StructRNA *srna)
 {
-  /* FunctionRNA *func; */
-  /* PropertyRNA *parm; */
+  FunctionRNA *func;
+  PropertyRNA *parm;
+
+  func = RNA_def_function(srna, "apply_pose_from_action", "rna_Pose_apply_pose_from_action");
+  RNA_def_function_flag(func, FUNC_USE_SELF_ID | FUNC_NO_SELF | FUNC_USE_CONTEXT);
+  RNA_def_function_ui_description(
+      func,
+      "Apply the given action to this pose by evaluating it at a specific time. Only updates the "
+      "pose of selected bones, or all bones if none are selected");
+
+  parm = RNA_def_pointer(func, "action", "Action", "Action", "The Action containing the pose");
+  RNA_def_parameter_flags(parm, 0, PARM_REQUIRED);
+
+  parm = RNA_def_float(func,
+                       "evaluation_time",
+                       0.0f,
+                       -FLT_MAX,
+                       FLT_MAX,
+                       "Evaluation Time",
+                       "Time at which the given action is evaluated to obtain the pose",
+                       -FLT_MAX,
+                       FLT_MAX);
 }
 
 void RNA_api_pose_channel(StructRNA *srna)