diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:19:15 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:38:48 +0300 |
commit | ffc4c126f5416b04a01653e7a03451797b98aba4 (patch) | |
tree | ac63d70d33aae5ab1666c9c2f62058c9c1eebd5c /source/blender/blenkernel/intern/armature.c | |
parent | f159d49f56cedccd509ee93f5a5fb51f4f39eeb8 (diff) |
Cleanup: move public doc-strings into headers for 'blenkernel'
- Added space below non doc-string comments to make it clear
these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.
Ref T92709
Diffstat (limited to 'source/blender/blenkernel/intern/armature.c')
-rw-r--r-- | source/blender/blenkernel/intern/armature.c | 190 |
1 files changed, 0 insertions, 190 deletions
diff --git a/source/blender/blenkernel/intern/armature.c b/source/blender/blenkernel/intern/armature.c index 96524ce78d7..0a91d662c1b 100644 --- a/source/blender/blenkernel/intern/armature.c +++ b/source/blender/blenkernel/intern/armature.c @@ -609,10 +609,6 @@ static Bone *get_named_bone_bonechildren(ListBase *lb, const char *name) return NULL; } -/** - * Walk the list until the bone is found (slow!), - * use #BKE_armature_bone_from_name_map for multiple lookups. - */ Bone *BKE_armature_find_bone_name(bArmature *arm, const char *name) { if (!arm) { @@ -717,10 +713,6 @@ void BKE_armature_refresh_layer_used(struct Depsgraph *depsgraph, struct bArmatu /** \name Armature Layer Refresh Used * \{ */ -/* Finds the best possible extension to the name on a particular axis. (For renaming, check for - * unique names afterwards) strip_number: removes number extensions (TODO: not used) - * axis: the axis to name on - * head/tail: the head/tail co-ordinate of the bone on the specified axis */ bool bone_autoside_name( char name[MAXBONENAME], int UNUSED(strip_number), short axis, float head, float tail) { @@ -932,7 +924,6 @@ static void evaluate_cubic_bezier(const float control[4][3], madd_v3_v3v3fl(r_pos, layer2[0], r_tangent, t); } -/* Get "next" and "prev" bones - these are used for handle calculations. */ void BKE_pchan_bbone_handles_get(bPoseChannel *pchan, bPoseChannel **r_prev, bPoseChannel **r_next) { if (pchan->bone->bbone_prev_type == BBONE_HANDLE_AUTO) { @@ -959,7 +950,6 @@ void BKE_pchan_bbone_handles_get(bPoseChannel *pchan, bPoseChannel **r_prev, bPo } } -/* Compute B-Bone spline parameters for the given channel. */ void BKE_pchan_bbone_spline_params_get(struct bPoseChannel *pchan, const bool rest, struct BBoneSplineParameters *param) @@ -1205,8 +1195,6 @@ void BKE_pchan_bbone_spline_params_get(struct bPoseChannel *pchan, } } -/* Fills the array with the desired amount of bone->segments elements. - * This calculation is done within unit bone space. */ void BKE_pchan_bbone_spline_setup(bPoseChannel *pchan, const bool rest, const bool for_deform, @@ -1219,7 +1207,6 @@ void BKE_pchan_bbone_spline_setup(bPoseChannel *pchan, pchan->bone->segments = BKE_pchan_bbone_spline_compute(¶m, for_deform, result_array); } -/* Computes the bezier handle vectors and rolls coming from custom handles. */ void BKE_pchan_bbone_handles_compute(const BBoneSplineParameters *param, float h1[3], float *r_roll1, @@ -1377,8 +1364,6 @@ static void ease_handle_axis(const float deriv1[3], const float deriv2[3], float } } -/* Fills the array with the desired amount of bone->segments elements. - * This calculation is done within unit bone space. */ int BKE_pchan_bbone_spline_compute(BBoneSplineParameters *param, const bool for_deform, Mat4 *result_array) @@ -1513,7 +1498,6 @@ static void allocate_bbone_cache(bPoseChannel *pchan, int segments) } } -/** Compute and cache the B-Bone shape in the channel runtime struct. */ void BKE_pchan_bbone_segments_cache_compute(bPoseChannel *pchan) { bPoseChannel_Runtime *runtime = &pchan->runtime; @@ -1565,7 +1549,6 @@ void BKE_pchan_bbone_segments_cache_compute(bPoseChannel *pchan) } } -/** Copy cached B-Bone segments from one channel to another */ void BKE_pchan_bbone_segments_cache_copy(bPoseChannel *pchan, bPoseChannel *pchan_from) { bPoseChannel_Runtime *runtime = &pchan->runtime; @@ -1589,10 +1572,6 @@ void BKE_pchan_bbone_segments_cache_copy(bPoseChannel *pchan, bPoseChannel *pcha } } -/** - * Calculate index and blend factor for the two B-Bone segment nodes - * affecting the point at 0 <= pos <= 1. - */ void BKE_pchan_bbone_deform_segment_index(const bPoseChannel *pchan, float pos, int *r_index, @@ -1624,7 +1603,6 @@ void BKE_pchan_bbone_deform_segment_index(const bPoseChannel *pchan, /** \name Bone Space to Space Conversion API * \{ */ -/* Convert World-Space Matrix to Pose-Space Matrix */ void BKE_armature_mat_world_to_pose(Object *ob, const float inmat[4][4], float outmat[4][4]) { float obmat[4][4]; @@ -1641,9 +1619,6 @@ void BKE_armature_mat_world_to_pose(Object *ob, const float inmat[4][4], float o mul_m4_m4m4(outmat, inmat, obmat); } -/* Convert World-Space Location to Pose-Space Location - * NOTE: this cannot be used to convert to pose-space location of the supplied - * pose-channel into its local space (i.e. 'visual'-keyframing) */ void BKE_armature_loc_world_to_pose(Object *ob, const float inloc[3], float outloc[3]) { float xLocMat[4][4]; @@ -1664,8 +1639,6 @@ void BKE_armature_loc_world_to_pose(Object *ob, const float inloc[3], float outl /** \name Bone Matrix Calculation API * \{ */ -/* Simple helper, computes the offset bone matrix. - * offs_bone = yoffs(b-1) + root(b) + bonemat(b). */ void BKE_bone_offset_matrix_get(const Bone *bone, float offs_bone[4][4]) { BLI_assert(bone->parent != NULL); @@ -1680,24 +1653,6 @@ void BKE_bone_offset_matrix_get(const Bone *bone, float offs_bone[4][4]) offs_bone[3][1] += bone->parent->length; } -/* Construct the matrices (rot/scale and loc) - * to apply the PoseChannels into the armature (object) space. - * I.e. (roughly) the "pose_mat(b-1) * yoffs(b-1) * d_root(b) * bone_mat(b)" in the - * pose_mat(b)= pose_mat(b-1) * yoffs(b-1) * d_root(b) * bone_mat(b) * chan_mat(b) - * ...function. - * - * This allows to get the transformations of a bone in its object space, - * *before* constraints (and IK) get applied (used by pose evaluation code). - * And reverse: to find pchan transformations needed to place a bone at a given loc/rot/scale - * in object space (used by interactive transform, and snapping code). - * - * Note that, with the HINGE/NO_SCALE/NO_LOCAL_LOCATION options, the location matrix - * will differ from the rotation/scale matrix... - * - * NOTE: This cannot be used to convert to pose-space transforms of the supplied - * pose-channel into its local space (i.e. 'visual'-keyframing). - * (note: I don't understand that, so I keep it :p --mont29). - */ void BKE_bone_parent_transform_calc_from_pchan(const bPoseChannel *pchan, BoneParentTransform *r_bpt) { @@ -1727,12 +1682,6 @@ void BKE_bone_parent_transform_calc_from_pchan(const bPoseChannel *pchan, } } -/* Compute the parent transform using data decoupled from specific data structures. - * - * bone_flag: Bone->flag containing settings - * offs_bone: delta from parent to current arm_mat (or just arm_mat if no parent) - * parent_arm_mat, parent_pose_mat: arm_mat and pose_mat of parent, or NULL - * r_bpt: OUTPUT parent transform */ void BKE_bone_parent_transform_calc_from_matrices(int bone_flag, int inherit_scale_mode, const float offs_bone[4][4], @@ -1914,9 +1863,6 @@ void BKE_bone_parent_transform_apply(const struct BoneParentTransform *bpt, rescale_m4(outmat, bpt->post_scale); } -/* Convert Pose-Space Matrix to Bone-Space Matrix. - * NOTE: this cannot be used to convert to pose-space transforms of the supplied - * pose-channel into its local space (i.e. 'visual'-keyframing) */ void BKE_armature_mat_pose_to_bone(bPoseChannel *pchan, const float inmat[4][4], float outmat[4][4]) @@ -1928,7 +1874,6 @@ void BKE_armature_mat_pose_to_bone(bPoseChannel *pchan, BKE_bone_parent_transform_apply(&bpt, inmat, outmat); } -/* Convert Bone-Space Matrix to Pose-Space Matrix. */ void BKE_armature_mat_bone_to_pose(bPoseChannel *pchan, const float inmat[4][4], float outmat[4][4]) @@ -1939,9 +1884,6 @@ void BKE_armature_mat_bone_to_pose(bPoseChannel *pchan, BKE_bone_parent_transform_apply(&bpt, inmat, outmat); } -/* Convert Pose-Space Location to Bone-Space Location - * NOTE: this cannot be used to convert to pose-space location of the supplied - * pose-channel into its local space (i.e. 'visual'-keyframing) */ void BKE_armature_loc_pose_to_bone(bPoseChannel *pchan, const float inloc[3], float outloc[3]) { float xLocMat[4][4]; @@ -1984,9 +1926,6 @@ void BKE_armature_mat_pose_to_bone_ex(struct Depsgraph *depsgraph, BKE_armature_mat_pose_to_bone(&work_pchan, inmat, outmat); } -/** - * Same as #BKE_object_mat3_to_rot(). - */ void BKE_pchan_mat3_to_rot(bPoseChannel *pchan, const float mat[3][3], bool use_compat) { BLI_ASSERT_UNIT_M3(mat); @@ -2009,9 +1948,6 @@ void BKE_pchan_mat3_to_rot(bPoseChannel *pchan, const float mat[3][3], bool use_ } } -/** - * Same as #BKE_object_rot_to_mat3(). - */ void BKE_pchan_rot_to_mat3(const bPoseChannel *pchan, float r_mat[3][3]) { /* rotations may either be quats, eulers (with various rotation orders), or axis-angle */ @@ -2036,10 +1972,6 @@ void BKE_pchan_rot_to_mat3(const bPoseChannel *pchan, float r_mat[3][3]) } } -/** - * Apply a 4x4 matrix to the pose bone, - * similar to #BKE_object_apply_mat4(). - */ void BKE_pchan_apply_mat4(bPoseChannel *pchan, const float mat[4][4], bool use_compat) { float rot[3][3]; @@ -2047,11 +1979,6 @@ void BKE_pchan_apply_mat4(bPoseChannel *pchan, const float mat[4][4], bool use_c BKE_pchan_mat3_to_rot(pchan, rot, use_compat); } -/** - * Remove rest-position effects from pose-transform for obtaining - * 'visual' transformation of pose-channel. - * (used by the Visual-Keyframing stuff). - */ void BKE_armature_mat_pose_to_delta(float delta_mat[4][4], float pose_mat[4][4], float arm_mat[4][4]) @@ -2070,11 +1997,6 @@ void BKE_armature_mat_pose_to_delta(float delta_mat[4][4], * Used for Objects and Pose Channels, since both can have multiple rotation representations. * \{ */ -/** - * Called from RNA when rotation mode changes - * - the result should be that the rotations given in the provided pointers have had conversions - * applied (as appropriate), such that the rotation of the element hasn't 'visually' changed. - */ void BKE_rotMode_change_values( float quat[4], float eul[3], float axis[3], float *angle, short oldMode, short newMode) { @@ -2148,8 +2070,6 @@ void BKE_rotMode_change_values( * * \{ */ -/* Computes vector and roll based on a rotation. - * "mat" must contain only a rotation, and no scaling. */ void mat3_to_vec_roll(const float mat[3][3], float r_vec[3], float *r_roll) { if (r_vec) { @@ -2161,8 +2081,6 @@ void mat3_to_vec_roll(const float mat[3][3], float r_vec[3], float *r_roll) } } -/* Computes roll around the vector that best approximates the matrix. - * If vec is the Y vector from purely rotational mat, result should be exact. */ void mat3_vec_to_roll(const float mat[3][3], const float vec[3], float *r_roll) { float vecmat[3][3], vecmatinv[3][3], rollmat[3][3], q[4]; @@ -2178,79 +2096,6 @@ void mat3_vec_to_roll(const float mat[3][3], const float vec[3], float *r_roll) *r_roll = quat_split_swing_and_twist(q, 1, NULL, NULL); } -/* Calculates the rest matrix of a bone based on its vector and a roll around that vector. */ -/** - * Given `v = (v.x, v.y, v.z)` our (normalized) bone vector, we want the rotation matrix M - * from the Y axis (so that `M * (0, 1, 0) = v`). - * - The rotation axis a lays on XZ plane, and it is orthonormal to v, - * hence to the projection of v onto XZ plane. - * - `a = (v.z, 0, -v.x)` - * - * We know a is eigenvector of M (so M * a = a). - * Finally, we have w, such that M * w = (0, 1, 0) - * (i.e. the vector that will be aligned with Y axis once transformed). - * We know w is symmetric to v by the Y axis. - * - `w = (-v.x, v.y, -v.z)` - * - * Solving this, we get (x, y and z being the components of v): - * <pre> - * ┌ (x^2 * y + z^2) / (x^2 + z^2), x, x * z * (y - 1) / (x^2 + z^2) ┐ - * M = │ x * (y^2 - 1) / (x^2 + z^2), y, z * (y^2 - 1) / (x^2 + z^2) │ - * └ x * z * (y - 1) / (x^2 + z^2), z, (x^2 + z^2 * y) / (x^2 + z^2) ┘ - * </pre> - * - * This is stable as long as v (the bone) is not too much aligned with +/-Y - * (i.e. x and z components are not too close to 0). - * - * Since v is normalized, we have `x^2 + y^2 + z^2 = 1`, - * hence `x^2 + z^2 = 1 - y^2 = (1 - y)(1 + y)`. - * - * This allows to simplifies M like this: - * <pre> - * ┌ 1 - x^2 / (1 + y), x, -x * z / (1 + y) ┐ - * M = │ -x, y, -z │ - * └ -x * z / (1 + y), z, 1 - z^2 / (1 + y) ┘ - * </pre> - * - * Written this way, we see the case v = +Y is no more a singularity. - * The only one - * remaining is the bone being aligned with -Y. - * - * Let's handle - * the asymptotic behavior when bone vector is reaching the limit of y = -1. - * Each of the four corner elements can vary from -1 to 1, - * depending on the axis a chosen for doing the rotation. - * And the "rotation" here is in fact established by mirroring XZ plane by that given axis, - * then inversing the Y-axis. - * For sufficiently small x and z, and with y approaching -1, - * all elements but the four corner ones of M will degenerate. - * So let's now focus on these corner elements. - * - * We rewrite M so that it only contains its four corner elements, - * and combine the `1 / (1 + y)` factor: - * <pre> - * ┌ 1 + y - x^2, -x * z ┐ - * M* = 1 / (1 + y) * │ │ - * └ -x * z, 1 + y - z^2 ┘ - * </pre> - * - * When y is close to -1, computing 1 / (1 + y) will cause severe numerical instability, - * so we use a different approach based on x and z as inputs. - * We know `y^2 = 1 - (x^2 + z^2)`, and `y < 0`, hence `y = -sqrt(1 - (x^2 + z^2))`. - * - * Since x and z are both close to 0, we apply the binomial expansion to the second order: - * `y = -sqrt(1 - (x^2 + z^2)) = -1 + (x^2 + z^2) / 2 + (x^2 + z^2)^2 / 8`, which allows - * eliminating the problematic `1` constant. - * - * A first order expansion allows simplifying to this, but second order is more precise: - * <pre> - * ┌ z^2 - x^2, -2 * x * z ┐ - * M* = 1 / (x^2 + z^2) * │ │ - * └ -2 * x * z, x^2 - z^2 ┘ - * </pre> - * - * P.S. In the end, this basically is a heavily optimized version of Damped Track +Y. - */ void vec_roll_to_mat3_normalized(const float nor[3], const float roll, float r_mat[3][3]) { const float SAFE_THRESHOLD = 6.1e-3f; /* Theta above this value has good enough precision. */ @@ -2321,10 +2166,6 @@ void vec_roll_to_mat3(const float vec[3], const float roll, float r_mat[3][3]) /** \name Armature Bone Matrix Calculation (Recursive) * \{ */ -/** - * Recursive part, calculates rest-position of entire tree of children. - * \note Used when exiting edit-mode too. - */ void BKE_armature_where_is_bone(Bone *bone, const Bone *bone_parent, const bool use_recursion) { float vec[3]; @@ -2363,8 +2204,6 @@ void BKE_armature_where_is_bone(Bone *bone, const Bone *bone_parent, const bool } } -/* updates vectors and matrices on rest-position level, only needed - * after editing armature itself, now only on reading file */ void BKE_armature_where_is(bArmature *arm) { Bone *bone; @@ -2581,10 +2420,6 @@ static int rebuild_pose_bone( return counter; } -/** - * Clear pointers of object's pose - * (needed in remap case, since we cannot always wait for a complete pose rebuild). - */ void BKE_pose_clear_pointers(bPose *pose) { LISTBASE_FOREACH (bPoseChannel *, pchan, &pose->chanbase) { @@ -2606,7 +2441,6 @@ static bPoseChannel *pose_channel_find_bone(bPose *pose, Bone *bone) return (bone != NULL) ? BKE_pose_channel_find_name(pose, bone->name) : NULL; } -/** Update the links for the B-Bone handles from Bone data. */ void BKE_pchan_rebuild_bbone_handles(bPose *pose, bPoseChannel *pchan) { pchan->bbone_prev = pose_channel_find_bone(pose, pchan->bone->bbone_prev); @@ -2624,13 +2458,6 @@ void BKE_pose_channels_clear_with_null_bone(bPose *pose, const bool do_id_user) } } -/** - * Only after leave editmode, duplicating, validating older files, library syncing. - * - * \note pose->flag is set for it. - * - * \param bmain: May be NULL, only used to tag depsgraph as being dirty... - */ void BKE_pose_rebuild(Main *bmain, Object *ob, bArmature *arm, const bool do_id_user) { Bone *bone; @@ -2698,11 +2525,6 @@ void BKE_pose_rebuild(Main *bmain, Object *ob, bArmature *arm, const bool do_id_ } } -/** - * Ensures object's pose is rebuilt if needed. - * - * \param bmain: May be NULL, only used to tag depsgraph as being dirty... - */ void BKE_pose_ensure(Main *bmain, Object *ob, bArmature *arm, const bool do_id_user) { BLI_assert(!ELEM(NULL, arm, ob)); @@ -2718,9 +2540,6 @@ void BKE_pose_ensure(Main *bmain, Object *ob, bArmature *arm, const bool do_id_u /** \name Pose Solver * \{ */ -/** - * Convert the loc/rot/size to \a r_chanmat (typically #bPoseChannel.chan_mat). - */ void BKE_pchan_to_mat4(const bPoseChannel *pchan, float r_chanmat[4][4]) { float smat[3][3]; @@ -2744,8 +2563,6 @@ void BKE_pchan_to_mat4(const bPoseChannel *pchan, float r_chanmat[4][4]) } } -/* loc/rot/size to mat4 */ -/* used in constraint.c too */ void BKE_pchan_calc_mat(bPoseChannel *pchan) { /* this is just a wrapper around the copy of this function which calculates the matrix @@ -2754,7 +2571,6 @@ void BKE_pchan_calc_mat(bPoseChannel *pchan) BKE_pchan_to_mat4(pchan, pchan->chan_mat); } -/* calculate tail of posechannel */ void BKE_pose_where_is_bone_tail(bPoseChannel *pchan) { float vec[3]; @@ -2764,10 +2580,6 @@ void BKE_pose_where_is_bone_tail(bPoseChannel *pchan) add_v3_v3v3(pchan->pose_tail, pchan->pose_head, vec); } -/* The main armature solver, does all constraints excluding IK */ -/* pchan is validated, as having bone and parent pointer - * 'do_extra': when zero skips loc/size/rot, constraints and strip modifiers. - */ void BKE_pose_where_is_bone(struct Depsgraph *depsgraph, Scene *scene, Object *ob, @@ -2832,8 +2644,6 @@ void BKE_pose_where_is_bone(struct Depsgraph *depsgraph, BKE_pose_where_is_bone_tail(pchan); } -/* This only reads anim data from channels, and writes to channels */ -/* This is the only function adding poses */ void BKE_pose_where_is(struct Depsgraph *depsgraph, Scene *scene, Object *ob) { bArmature *arm; |