BKE_armature.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2001-2002 NaN Holding BV. All rights reserved.
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
 
#pragma once
 
#include "BLI_bounds_types.hh"
#include "BLI_function_ref.hh"
#include "BLI_listbase.h"
#include "BLI_math_matrix_types.hh"
#include "BLI_math_vector_types.hh"
#include "BLI_set.hh"
 
#include "DNA_armature_types.h"
 
struct BMEditMesh;
struct Bone;
struct Depsgraph;
struct IDProperty;
struct ListBase;
struct Main;
struct Mesh;
struct Object;
struct PoseTree;
struct Scene;
struct bArmature;
struct bConstraint;
struct bGPDstroke;
struct bPose;
struct bPoseChannel;
struct MDeformVert;
 
struct EditBone {
  EditBone *next, *prev;
  IDProperty *prop;
  EditBone *parent;
  char name[64];
  float roll;
 
  float head[3];
  float tail[3];
  int flag;
  int layer;
  char inherit_scale_mode;
 
  /* Envelope distance & weight */
  float dist, weight;
  float xwidth, length, zwidth;
  float rad_head, rad_tail;
 
  /* Bendy-Bone parameters */
  short segments;
  float roll1, roll2;
  float curve_in_x, curve_in_z;
  float curve_out_x, curve_out_z;
  float ease1, ease2;
  float scale_in[3], scale_out[3];
 
  float oldlength;
 
  eBone_BBoneMappingMode bbone_mapping_mode;
  char bbone_prev_type;
  char bbone_next_type;
  int bbone_flag;
  short bbone_prev_flag;
  short bbone_next_flag;
  EditBone *bbone_prev;
  EditBone *bbone_next;
 
  /* Used for display */
  float disp_mat[4][4];
  float disp_tail_mat[4][4];
  float disp_bbone_mat[32][4][4];
 
  EditBone *bbone_child;
 
  ::BoneColor color; /* MUST be named the same as in bPoseChannel and Bone structs. */
  ListBase /*BoneCollectionReference*/ bone_collections;
 
  /* Used to store temporary data */
  union {
    EditBone *ebone;
    Bone *bone;
    void *p;
    int i;
  } temp;
};
 
struct PoseTarget {
  PoseTarget *next, *prev;
 
  bConstraint *con; /* the constraint of this target */
  int tip;          /* index of tip pchan in PoseTree */
};
 
struct PoseTree {
  PoseTree *next, *prev;
 
  int type;       /* type of IK that this serves (CONSTRAINT_TYPE_KINEMATIC or ..._SPLINEIK) */
  int totchannel; /* number of pose channels */
 
  ListBase targets;     /* list of targets of the tree */
  bPoseChannel **pchan; /* array of pose channels */
  int *parent;          /* and their parents */
 
  float (*basis_change)[3][3]; /* basis change result from solver */
  int iterations;              /* iterations from the constraint */
  int stretch;                 /* disable stretching */
};
 
/* Core armature functionality. */
 
bArmature *BKE_armature_add(Main *bmain, const char *name);
bArmature *BKE_armature_from_object(Object *ob);
int BKE_armature_bonelist_count(const ListBase *lb);
void BKE_armature_bonelist_free(ListBase *lb, bool do_id_user);
void BKE_armature_editbonelist_free(ListBase *lb, bool do_id_user);
 
void BKE_armature_copy_bone_transforms(bArmature *armature_dst, const bArmature *armature_src);
 
void BKE_armature_transform(bArmature *arm, const float mat[4][4], bool do_props);
 
std::optional<blender::Bounds<blender::float3>> BKE_armature_min_max(const Object *ob);
 
void BKE_pchan_minmax(const Object *ob,
                      const bPoseChannel *pchan,
                      const bool use_empty_drawtype,
                      float r_min[3],
                      float r_max[3]);
std::optional<blender::Bounds<blender::float3>> BKE_pose_minmax(const Object *ob, bool use_select);
 
bool bone_autoside_name(char name[64], int strip_number, short axis, float head, float tail);
 
Bone *BKE_armature_find_bone_name(bArmature *arm, const char *name);
 
void BKE_armature_bone_hash_make(bArmature *arm);
void BKE_armature_bone_hash_free(bArmature *arm);
 
bool BKE_armature_bone_flag_test_recursive(const Bone *bone, int flag);
 
float distfactor_to_bone(
    const float vec[3], const float b1[3], const float b2[3], float rad1, float rad2, float rdist);
 
void BKE_armature_where_is(bArmature *arm);
void BKE_armature_where_is_bone(Bone *bone, const Bone *bone_parent, bool use_recursion);
void BKE_pose_clear_pointers(bPose *pose);
void BKE_pose_remap_bone_pointers(bArmature *armature, bPose *pose);
void BKE_pchan_rebuild_bbone_handles(bPose *pose, bPoseChannel *pchan);
void BKE_pose_channels_clear_with_null_bone(bPose *pose, bool do_id_user);
void BKE_pose_rebuild(Main *bmain, Object *ob, bArmature *arm, bool do_id_user);
void BKE_pose_ensure(Main *bmain, Object *ob, bArmature *arm, bool do_id_user);
void BKE_pose_where_is(Depsgraph *depsgraph, Scene *scene, Object *ob);
void BKE_pose_where_is_bone(Depsgraph *depsgraph,
                            Scene *scene,
                            Object *ob,
                            bPoseChannel *pchan,
                            float ctime,
                            bool do_extra);
void BKE_pose_where_is_bone_tail(bPoseChannel *pchan);
 
void vec_roll_to_mat3(const float vec[3], float roll, float r_mat[3][3]);
 
void vec_roll_to_mat3_normalized(const float nor[3], float roll, float r_mat[3][3]);
void mat3_to_vec_roll(const float mat[3][3], float r_vec[3], float *r_roll);
void mat3_vec_to_roll(const float mat[3][3], const float vec[3], float *r_roll);
 
/* Common Conversions Between Co-ordinate Spaces */
 
void BKE_armature_mat_world_to_pose(Object *ob, const float inmat[4][4], float outmat[4][4]);
void BKE_armature_loc_world_to_pose(Object *ob, const float inloc[3], float outloc[3]);
void BKE_armature_mat_pose_to_bone(bPoseChannel *pchan,
                                   const float inmat[4][4],
                                   float outmat[4][4]);
void BKE_armature_loc_pose_to_bone(bPoseChannel *pchan, const float inloc[3], float outloc[3]);
void BKE_armature_mat_bone_to_pose(bPoseChannel *pchan,
                                   const float inmat[4][4],
                                   float outmat[4][4]);
void BKE_armature_mat_pose_to_delta(float delta_mat[4][4],
                                    float pose_mat[4][4],
                                    float arm_mat[4][4]);
 
void BKE_armature_mat_pose_to_bone_ex(Depsgraph *depsgraph,
                                      Object *ob,
                                      bPoseChannel *pchan,
                                      const float inmat[4][4],
                                      float outmat[4][4]);
 
void BKE_pchan_mat3_to_rot(bPoseChannel *pchan, const float mat[3][3], bool use_compat);
void BKE_pchan_rot_to_mat3(const bPoseChannel *pchan, float r_mat[3][3]);
void BKE_pchan_apply_mat4(bPoseChannel *pchan, const float mat[4][4], bool use_compat);
void BKE_pchan_to_mat4(const bPoseChannel *pchan, float r_chanmat[4][4]);
 
void BKE_pchan_calc_mat(bPoseChannel *pchan);
 
void BKE_bone_offset_matrix_get(const Bone *bone, float offs_bone[4][4]);
 
/* Transformation inherited from the parent bone. These matrices apply the effects of
 * HINGE/NO_SCALE/NO_LOCAL_LOCATION options over the pchan loc/rot/scale transformations. */
struct BoneParentTransform {
  float rotscale_mat[4][4]; /* parent effect on rotation & scale pose channels */
  float loc_mat[4][4];      /* parent effect on location pose channel */
  float post_scale[3];      /* additional scale to apply with post-multiply */
};
 
/* Matrix-like algebra operations on the transform */
void BKE_bone_parent_transform_clear(BoneParentTransform *bpt);
void BKE_bone_parent_transform_invert(BoneParentTransform *bpt);
void BKE_bone_parent_transform_combine(const BoneParentTransform *in1,
                                       const BoneParentTransform *in2,
                                       BoneParentTransform *result);
 
void BKE_bone_parent_transform_apply(const BoneParentTransform *bpt,
                                     const float inmat[4][4],
                                     float outmat[4][4]);
 
void BKE_bone_parent_transform_calc_from_pchan(const bPoseChannel *pchan,
                                               BoneParentTransform *r_bpt);
void BKE_bone_parent_transform_calc_from_matrices(int bone_flag,
                                                  int inherit_scale_mode,
                                                  const float offs_bone[4][4],
                                                  const float parent_arm_mat[4][4],
                                                  const float parent_pose_mat[4][4],
                                                  BoneParentTransform *r_bpt);
 
void BKE_rotMode_change_values(
    float quat[4], float eul[3], float axis[3], float *angle, short oldMode, short newMode);
 
/* B-Bone support */
#define MAX_BBONE_SUBDIV 32
 
struct Mat4 {
  float mat[4][4];
};
 
struct BBoneSplineParameters {
  int segments;
  float length;
 
  /* Non-uniform scale correction. */
  bool do_scale;
  float scale[3];
 
  /* Handle control bone data. */
  bool use_prev, prev_bbone;
  bool use_next, next_bbone;
 
  float prev_h[3], next_h[3];
  float prev_mat[4][4], next_mat[4][4];
 
  /* Control values. */
  float ease1, ease2;
  float roll1, roll2;
  float scale_in[3], scale_out[3];
  float curve_in_x, curve_in_z, curve_out_x, curve_out_z;
};
 
void BKE_pchan_bbone_handles_get(bPoseChannel *pchan,
                                 bPoseChannel **r_prev,
                                 bPoseChannel **r_next);
void BKE_pchan_bbone_spline_params_get(bPoseChannel *pchan,
                                       bool rest,
                                       BBoneSplineParameters *param);
 
void BKE_pchan_bbone_spline_setup(bPoseChannel *pchan,
                                  bool rest,
                                  bool for_deform,
                                  Mat4 *result_array);
 
void BKE_pchan_bbone_handles_compute(const BBoneSplineParameters *param,
                                     float h1[3],
                                     float *r_roll1,
                                     float h2[3],
                                     float *r_roll2,
                                     bool ease,
                                     bool offsets);
int BKE_pchan_bbone_spline_compute(BBoneSplineParameters *param,
                                   bool for_deform,
                                   Mat4 *result_array);
 
void BKE_pchan_bbone_segments_cache_compute(bPoseChannel *pchan);
void BKE_pchan_bbone_segments_cache_copy(bPoseChannel *pchan, bPoseChannel *pchan_from);
 
void BKE_pchan_bbone_deform_clamp_segment_index(const bPoseChannel *pchan,
                                                float head_tail,
                                                int *r_index,
                                                float *r_blend_next);
 
void BKE_pchan_bbone_deform_segment_index(const bPoseChannel *pchan,
                                          const float *co,
                                          int *r_index,
                                          float *r_blend_next);
 
/* like EBONE_VISIBLE,  be sure to #include "ANIM_bone_collections.hh". */
#define PBONE_VISIBLE(arm, bone) ANIM_bone_is_visible(arm, bone)
 
#define PBONE_SELECTABLE(arm, bone) \
  (PBONE_VISIBLE(arm, bone) && !((bone)->flag & BONE_UNSELECTABLE))
 
#define PBONE_SELECTED(arm, bone) (((bone)->flag & BONE_SELECTED) & PBONE_VISIBLE(arm, bone))
 
/* context.selected_pose_bones */
#define FOREACH_PCHAN_SELECTED_IN_OBJECT_BEGIN(_ob, _pchan) \
  for (bPoseChannel *_pchan = (bPoseChannel *)(_ob)->pose->chanbase.first; _pchan; \
       _pchan = _pchan->next) \
  { \
    if (PBONE_VISIBLE(((bArmature *)(_ob)->data), (_pchan)->bone) && \
        ((_pchan)->bone->flag & BONE_SELECTED)) \
    {
#define FOREACH_PCHAN_SELECTED_IN_OBJECT_END \
  } \
  } \
  ((void)0)
/* context.visible_pose_bones */
#define FOREACH_PCHAN_VISIBLE_IN_OBJECT_BEGIN(_ob, _pchan) \
  for (bPoseChannel *_pchan = (bPoseChannel *)(_ob)->pose->chanbase.first; _pchan; \
       _pchan = _pchan->next) \
  { \
    if (PBONE_VISIBLE(((bArmature *)(_ob)->data), (_pchan)->bone)) {
#define FOREACH_PCHAN_VISIBLE_IN_OBJECT_END \
  } \
  } \
  ((void)0)
 
/* Evaluation helpers */
struct bKinematicConstraint;
struct bPose;
struct bSplineIKConstraint;
 
bPoseChannel *BKE_armature_ik_solver_find_root(bPoseChannel *pchan, bKinematicConstraint *data);
bPoseChannel *BKE_armature_splineik_solver_find_root(bPoseChannel *pchan,
                                                     bSplineIKConstraint *data);
 
void BKE_pose_splineik_init_tree(Scene *scene, Object *ob, float ctime);
void BKE_splineik_execute_tree(
    Depsgraph *depsgraph, Scene *scene, Object *ob, bPoseChannel *pchan_root, float ctime);
 
void BKE_pose_pchan_index_rebuild(bPose *pose);
 
void BKE_pose_eval_init(Depsgraph *depsgraph, Scene *scene, Object *object);
 
void BKE_pose_eval_init_ik(Depsgraph *depsgraph, Scene *scene, Object *object);
 
void BKE_pose_eval_bone(Depsgraph *depsgraph, Scene *scene, Object *object, int pchan_index);
 
void BKE_pose_constraints_evaluate(Depsgraph *depsgraph,
                                   Scene *scene,
                                   Object *object,
                                   int pchan_index);
 
void BKE_pose_bone_done(Depsgraph *depsgraph, Object *object, int pchan_index);
 
void BKE_pose_eval_bbone_segments(Depsgraph *depsgraph, Object *object, int pchan_index);
 
void BKE_pose_iktree_evaluate(Depsgraph *depsgraph,
                              Scene *scene,
                              Object *object,
                              int rootchan_index);
 
void BKE_pose_splineik_evaluate(Depsgraph *depsgraph,
                                Scene *scene,
                                Object *object,
                                int rootchan_index);
 
void BKE_pose_eval_done(Depsgraph *depsgraph, Object *object);
 
void BKE_pose_eval_cleanup(Depsgraph *depsgraph, Scene *scene, Object *object);
 
/* -------------------------------------------------------------------- */
/* Note that we could have a 'BKE_armature_deform_coords' that doesn't take object data
 * currently there are no callers for this though. */
 
void BKE_armature_deform_coords_with_gpencil_stroke(const Object *ob_arm,
                                                    const Object *ob_target,
                                                    float (*vert_coords)[3],
                                                    float (*vert_deform_mats)[3][3],
                                                    int vert_coords_len,
                                                    int deformflag,
                                                    float (*vert_coords_prev)[3],
                                                    const char *defgrp_name,
                                                    bGPDstroke *gps_target);
 
void BKE_armature_deform_coords_with_curves(
    const Object &ob_arm,
    const Object &ob_target,
    const ListBase *defbase,
    blender::MutableSpan<blender::float3> vert_coords,
    std::optional<blender::MutableSpan<blender::float3>> vert_coords_prev,
    std::optional<blender::MutableSpan<blender::float3x3>> vert_deform_mats,
    blender::Span<MDeformVert> dverts,
    int deformflag,
    blender::StringRefNull defgrp_name);
 
void BKE_armature_deform_coords_with_mesh(const Object *ob_arm,
                                          const Object *ob_target,
                                          float (*vert_coords)[3],
                                          float (*vert_deform_mats)[3][3],
                                          int vert_coords_len,
                                          int deformflag,
                                          float (*vert_coords_prev)[3],
                                          const char *defgrp_name,
                                          const Mesh *me_target);
 
void BKE_armature_deform_coords_with_editmesh(const Object *ob_arm,
                                              const Object *ob_target,
                                              float (*vert_coords)[3],
                                              float (*vert_deform_mats)[3][3],
                                              int vert_coords_len,
                                              int deformflag,
                                              float (*vert_coords_prev)[3],
                                              const char *defgrp_name,
                                              const BMEditMesh *em_target);
 
namespace blender::bke {
 
struct SelectedBonesResult {
  bool all_bones_selected = true;
  bool no_bones_selected = true;
};
 
using SelectedBoneCallback = blender::FunctionRef<void(Bone *bone)>;
SelectedBonesResult BKE_armature_find_selected_bones(const bArmature *armature,
                                                     SelectedBoneCallback callback);
 
using BoneNameSet = blender::Set<std::string>;
BoneNameSet BKE_armature_find_selected_bone_names(const bArmature *armature);
 
};  // namespace blender::bke