Blender V4.3
ANIM_bone_collections.hh File Reference

C++ functions to deal with Armature collections (i.e. the successor of bone layers). More...

#include <stdbool.h>
#include "BLI_map.hh"
#include "BLI_math_bits.h"
#include "BKE_armature.hh"
#include "DNA_action_types.h"
#include "DNA_armature_types.h"

Go to the source code of this file.

Namespaces

namespace  blender
 
namespace  blender::animrig
 

Enumerations

enum class  MoveLocation { Before , After }
 

Functions

BoneCollectionANIM_bonecoll_new (const char *name) ATTR_WARN_UNUSED_RESULT
 
void ANIM_bonecoll_free (BoneCollection *bcoll, bool do_id_user_count=true)
 
void ANIM_armature_runtime_refresh (bArmature *armature)
 
void ANIM_armature_runtime_free (bArmature *armature)
 
BoneCollectionANIM_armature_bonecoll_new (bArmature *armature, const char *name, int parent_index=-1)
 
BoneCollectionANIM_armature_bonecoll_insert_copy_after (bArmature *armature_dst, const bArmature *armature_src, const BoneCollection *anchor_in_dst, const BoneCollection *bcoll_to_copy)
 
void ANIM_armature_bonecoll_remove_from_index (bArmature *armature, const int index)
 
void ANIM_armature_bonecoll_remove (bArmature *armature, BoneCollection *bcoll)
 
void ANIM_armature_bonecoll_active_set (bArmature *armature, BoneCollection *bcoll)
 
void ANIM_armature_bonecoll_active_index_set (bArmature *armature, int bone_collection_index)
 
void ANIM_armature_bonecoll_active_name_set (bArmature *armature, const char *name)
 
void ANIM_armature_bonecoll_active_runtime_refresh (bArmature *armature)
 
bool ANIM_armature_bonecoll_is_editable (const bArmature *armature, const BoneCollection *bcoll)
 
bool ANIM_armature_bonecoll_move_to_index (bArmature *armature, int from_index, int to_index)
 
int ANIM_armature_bonecoll_move_before_after_index (bArmature *armature, int from_index, int to_index, MoveLocation before_after)
 
bool ANIM_armature_bonecoll_move (bArmature *armature, BoneCollection *bcoll, int step)
 
BoneCollectionANIM_armature_bonecoll_get_by_name (bArmature *armature, const char *name) ATTR_WARN_UNUSED_RESULT
 
int ANIM_armature_bonecoll_get_index_by_name (bArmature *armature, const char *name) ATTR_WARN_UNUSED_RESULT
 
void ANIM_armature_bonecoll_name_set (bArmature *armature, BoneCollection *bcoll, const char *name)
 
void ANIM_bonecoll_show (bArmature *armature, BoneCollection *bcoll)
 
void ANIM_bonecoll_hide (bArmature *armature, BoneCollection *bcoll)
 
void ANIM_armature_bonecoll_is_visible_set (bArmature *armature, BoneCollection *bcoll, bool is_visible)
 
void ANIM_armature_bonecoll_solo_set (bArmature *armature, BoneCollection *bcoll, bool is_solo)
 
void ANIM_armature_refresh_solo_active (bArmature *armature)
 
bool ANIM_armature_bonecoll_is_visible_effectively (const bArmature *armature, const BoneCollection *bcoll)
 
void ANIM_armature_bonecoll_is_expanded_set (BoneCollection *bcoll, bool is_expanded)
 
bool ANIM_armature_bonecoll_assign (BoneCollection *bcoll, Bone *bone)
 
bool ANIM_armature_bonecoll_assign_editbone (BoneCollection *bcoll, EditBone *ebone)
 
bool ANIM_armature_bonecoll_assign_and_move (BoneCollection *bcoll, Bone *bone)
 
bool ANIM_armature_bonecoll_assign_and_move_editbone (BoneCollection *bcoll, EditBone *ebone)
 
bool ANIM_armature_bonecoll_unassign (BoneCollection *bcoll, Bone *bone)
 
bool ANIM_armature_bonecoll_unassign_editbone (BoneCollection *bcoll, EditBone *ebone)
 
void ANIM_armature_bonecoll_unassign_all (Bone *bone)
 
void ANIM_armature_bonecoll_unassign_all_editbone (EditBone *ebone)
 
void ANIM_armature_bonecoll_assign_active (const bArmature *armature, EditBone *ebone)
 
bool ANIM_armature_bonecoll_contains_active_bone (const bArmature *armature, const BoneCollection *bcoll)
 
void ANIM_armature_bonecoll_reconstruct (bArmature *armature)
 
bool ANIM_bone_in_visible_collection (const bArmature *armature, const Bone *bone)
 
bool ANIM_bone_is_visible (const bArmature *armature, const Bone *bone)
 
bool ANIM_bonecoll_is_visible_editbone (const bArmature *armature, const EditBone *ebone)
 
bool ANIM_bone_is_visible_editbone (const bArmature *armature, const EditBone *ebone)
 
bool ANIM_bonecoll_is_visible_pchan (const bArmature *armature, const bPoseChannel *pchan)
 
bool ANIM_bonecoll_is_visible_actbone (const bArmature *armature)
 
void ANIM_armature_bonecoll_show_all (bArmature *armature)
 
void ANIM_armature_bonecoll_hide_all (bArmature *armature)
 
void ANIM_armature_bonecoll_show_from_bone (bArmature *armature, const Bone *bone)
 
void ANIM_armature_bonecoll_show_from_ebone (bArmature *armature, const EditBone *ebone)
 
void ANIM_armature_bonecoll_show_from_pchan (bArmature *armature, const bPoseChannel *pchan)
 
int blender::animrig::armature_bonecoll_find_index (const bArmature *armature, const ::BoneCollection *bcoll)
 
int blender::animrig::armature_bonecoll_find_parent_index (const bArmature *armature, int bcoll_index)
 
int blender::animrig::armature_bonecoll_child_number_find (const bArmature *armature, const ::BoneCollection *bcoll)
 
int blender::animrig::armature_bonecoll_child_number_set (bArmature *armature, ::BoneCollection *bcoll, int new_child_number)
 
bool blender::animrig::armature_bonecoll_is_root (const bArmature *armature, int bcoll_index)
 
bool blender::animrig::armature_bonecoll_is_child_of (const bArmature *armature, int potential_parent_index, int potential_child_index)
 
bool blender::animrig::armature_bonecoll_is_descendant_of (const bArmature *armature, int potential_parent_index, int potential_descendant_index)
 
bool blender::animrig::bonecoll_has_children (const BoneCollection *bcoll)
 
void blender::animrig::bonecolls_copy_expanded_flag (Span< BoneCollection * > bcolls_dest, Span< const BoneCollection * > bcolls_source)
 
int blender::animrig::armature_bonecoll_move_to_parent (bArmature *armature, int from_bcoll_index, int to_child_num, int from_parent_index, int to_parent_index)
 
blender::Map< BoneCollection *, BoneCollection * > blender::animrig::ANIM_bonecoll_array_copy_no_membership (BoneCollection ***bcoll_array_dst, int *bcoll_array_dst_num, BoneCollection **bcoll_array_src, int bcoll_array_src_num, bool do_id_user)
 
void blender::animrig::ANIM_bonecoll_array_free (BoneCollection ***bcoll_array, int *bcoll_array_num, bool do_id_user)
 

Detailed Description

C++ functions to deal with Armature collections (i.e. the successor of bone layers).

Definition in file ANIM_bone_collections.hh.

Enumeration Type Documentation

◆ MoveLocation

enum class MoveLocation
strong
Enumerator
Before 
After 

Definition at line 179 of file ANIM_bone_collections.hh.

Function Documentation

◆ ANIM_armature_bonecoll_active_index_set()

◆ ANIM_armature_bonecoll_active_name_set()

void ANIM_armature_bonecoll_active_name_set ( bArmature * armature,
const char * name )

Set the bone collection with the given name as the active one.

Pass an empty name to clear the active bone collection. A non-existent name will also cause the active bone collection to be cleared.

Definition at line 433 of file animrig/intern/bone_collections.cc.

References ANIM_armature_bonecoll_active_set(), and ANIM_armature_bonecoll_get_by_name().

Referenced by bc_add_armature_collections(), blender::animrig::tests::TEST_F(), and blender::animrig::tests::TEST_F().

◆ ANIM_armature_bonecoll_active_runtime_refresh()

void ANIM_armature_bonecoll_active_runtime_refresh ( bArmature * armature)

Refresh the Armature runtime info about the active bone collection.

The ground truth for the active bone collection is the collection's name, whereas the runtime info also contains the active collection's index and pointer. This function updates the runtime info to point to the named collection. If that named collection cannot be found, the name will be cleared.

Definition at line 439 of file animrig/intern/bone_collections.cc.

References bArmature_Runtime::active_collection, bArmature_Runtime::active_collection_index, bArmature::active_collection_name, armature_bonecoll_active_clear(), and bArmature::runtime.

Referenced by ANIM_armature_bonecoll_insert_copy_after(), ANIM_armature_runtime_refresh(), and bone_collection_move_exec().

◆ ANIM_armature_bonecoll_active_set()

◆ ANIM_armature_bonecoll_assign()

bool ANIM_armature_bonecoll_assign ( BoneCollection * bcoll,
Bone * bone )

Assign the bone to the bone collection.

No-op if the bone is already a member of the collection.

Returns
true if the bone was actually assigned, false if not (f.e. when it already was assigned previously).

Definition at line 882 of file animrig/intern/bone_collections.cc.

References add_membership(), add_reference(), BoneCollection::bones, and LISTBASE_FOREACH.

Referenced by ANIM_armature_bonecoll_assign_and_move(), assign_to_collection_exec(), bone_collection_assign_exec(), bone_collection_create_and_assign_exec(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), and version_bonegroups_to_bonecollections().

◆ ANIM_armature_bonecoll_assign_active()

void ANIM_armature_bonecoll_assign_active ( const bArmature * armature,
EditBone * ebone )

◆ ANIM_armature_bonecoll_assign_and_move()

bool ANIM_armature_bonecoll_assign_and_move ( BoneCollection * bcoll,
Bone * bone )

◆ ANIM_armature_bonecoll_assign_and_move_editbone()

bool ANIM_armature_bonecoll_assign_and_move_editbone ( BoneCollection * bcoll,
EditBone * ebone )

◆ ANIM_armature_bonecoll_assign_editbone()

◆ ANIM_armature_bonecoll_contains_active_bone()

bool ANIM_armature_bonecoll_contains_active_bone ( const bArmature * armature,
const BoneCollection * bcoll )

◆ ANIM_armature_bonecoll_get_by_name()

BoneCollection * ANIM_armature_bonecoll_get_by_name ( bArmature * armature,
const char * name )

◆ ANIM_armature_bonecoll_get_index_by_name()

int ANIM_armature_bonecoll_get_index_by_name ( bArmature * armature,
const char * name )

Scan the bone collections to find the one with the given name.

Returns
the index of the bone collection, or -1 if not found.

Definition at line 732 of file animrig/intern/bone_collections.cc.

References bArmature::collection_array, bArmature::collection_array_num, BoneCollection::name, and STREQ.

Referenced by blender::animrig::tests::TEST_F().

◆ ANIM_armature_bonecoll_hide_all()

void ANIM_armature_bonecoll_hide_all ( bArmature * armature)

Definition at line 1033 of file animrig/intern/bone_collections.cc.

References ANIM_bonecoll_hide().

◆ ANIM_armature_bonecoll_insert_copy_after()

BoneCollection * ANIM_armature_bonecoll_insert_copy_after ( bArmature * armature_dst,
const bArmature * armature_src,
const BoneCollection * anchor_in_dst,
const BoneCollection * bcoll_to_copy )

Add a bone collection to the Armature.

If anchor is null or isn't found, this inserts the copy at the start of the collection array.

NOTE: this should not typically be used. It is only used by the library overrides system to apply override operations.

Definition at line 356 of file animrig/intern/bone_collections.cc.

References ANIM_armature_bonecoll_active_runtime_refresh(), blender::animrig::armature_bonecoll_find_index(), blender::animrig::armature_bonecoll_is_root(), BLI_assert_msg, bonecoll_ensure_name_unique(), bonecoll_insert_as_root(), copy_and_update_ownership(), bArmature::id, liboverride_recursively_add_children(), BoneCollection::name, ID::name, and printf.

Referenced by blender::animrig::tests::TEST_F().

◆ ANIM_armature_bonecoll_is_editable()

◆ ANIM_armature_bonecoll_is_expanded_set()

void ANIM_armature_bonecoll_is_expanded_set ( BoneCollection * bcoll,
bool is_expanded )

◆ ANIM_armature_bonecoll_is_visible_effectively()

bool ANIM_armature_bonecoll_is_visible_effectively ( const bArmature * armature,
const BoneCollection * bcoll )

Determine whether this bone collection is visible, taking into account the visibility of its ancestors and the "solo" flags that are in use.

Definition at line 844 of file animrig/intern/bone_collections.cc.

References ARM_BCOLL_SOLO_ACTIVE, and bArmature::flag.

Referenced by any_bone_collection_visible().

◆ ANIM_armature_bonecoll_is_visible_set()

void ANIM_armature_bonecoll_is_visible_set ( bArmature * armature,
BoneCollection * bcoll,
bool is_visible )

Show or hide this bone collection.

Calling this with a hard-coded is_visible parameter is equivalent to calling the dedicated show/hide functions. Prefer the dedicated functions for clarity.

See also
ANIM_bonecoll_show
ANIM_bonecoll_hide

Definition at line 797 of file animrig/intern/bone_collections.cc.

References ANIM_bonecoll_hide(), and ANIM_bonecoll_show().

◆ ANIM_armature_bonecoll_move()

bool ANIM_armature_bonecoll_move ( bArmature * armature,
BoneCollection * bcoll,
int step )

Move the bone collection by step places up/down.

Returns
whether the move actually happened.
Note
This function is limited to moving between siblings of the bone collection at from_index.
See also
blender::animrig::armature_bonecoll_move_to_parent() to move bone collections between different parents.

Definition at line 572 of file animrig/intern/bone_collections.cc.

References ANIM_armature_bonecoll_move_to_index(), blender::animrig::armature_bonecoll_find_index(), and bArmature::collection_array_num.

Referenced by bone_collection_move_exec().

◆ ANIM_armature_bonecoll_move_before_after_index()

◆ ANIM_armature_bonecoll_move_to_index()

bool ANIM_armature_bonecoll_move_to_index ( bArmature * armature,
int from_index,
int to_index )

Move the bone collection at from_index to its sibling at to_index.

The element at to_index is shifted to make space; it is not overwritten. This shift happens towards from_index.

This operation does not change the total number of elements in the array.

Returns
true if the collection was successfully moved, false otherwise. The latter happens if either index is out of bounds, or if the indices are equal.
Note
This function is limited to moving between siblings of the bone collection at from_index.
This function ensures that the element at index from_index (before the call) will end up at to_index (after the call). The element at to_index before the call will shift towards from_index; in other words, depending on the direction of movement, the moved element will end up either before or after that one.

TODO: add ASCII-art illustration of left & right movement.

See also
blender::animrig::armature_bonecoll_move_to_parent() to move bone collections between different parents.

Definition at line 480 of file animrig/intern/bone_collections.cc.

References blender::animrig::armature_bonecoll_find_parent_index(), blender::animrig::armature_bonecoll_is_child_of(), blender::animrig::internal::bonecolls_move_to_index(), BoneCollection::child_index, bArmature::collection_array, and bArmature::collection_array_num.

Referenced by ANIM_armature_bonecoll_move(), ANIM_armature_bonecoll_move_before_after_index(), blender::animrig::tests::TEST_F(), and blender::animrig::tests::TEST_F().

◆ ANIM_armature_bonecoll_name_set()

void ANIM_armature_bonecoll_name_set ( bArmature * armature,
BoneCollection * bcoll,
const char * name )

◆ ANIM_armature_bonecoll_new()

BoneCollection * ANIM_armature_bonecoll_new ( bArmature * armature,
const char * name,
int parent_index = -1 )

Add a new bone collection to the given armature.

Parameters
parent_indexIndex into the Armature's collections_array. -1 adds it as a root (i.e. parentless) collection.

The Armature owns the returned pointer.

Definition at line 219 of file animrig/intern/bone_collections.cc.

References bArmature_Runtime::active_collection, ANIM_armature_bonecoll_active_set(), ANIM_bonecoll_new(), BONE_COLLECTION_OVERRIDE_LIBRARY_LOCAL, bonecoll_ensure_name_unique(), bonecoll_insert_as_child(), bonecoll_insert_as_root(), BoneCollection::flags, bArmature::id, ID_IS_LINKED, ID_IS_OVERRIDE_LIBRARY, and bArmature::runtime.

Referenced by add_or_move_to_collection_bcoll(), bc_add_armature_collections(), bone_collection_add_exec(), bone_collection_create_and_assign_exec(), join_armature_remap_collection(), blender::ed::object::object_armature_add_exec(), blender::animrig::tests::ArmatureBoneCollectionsLiboverrides::SetUp(), blender::animrig::tests::ArmatureBoneCollectionsTestList::SetUp(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), blender::animrig::tests::TEST_F(), version_bonegroups_to_bonecollections(), and version_bonelayers_to_bonecollections().

◆ ANIM_armature_bonecoll_reconstruct()

void ANIM_armature_bonecoll_reconstruct ( bArmature * armature)

Reconstruct the bone collection memberships, based on the bone runtime data.

This is needed to transition out of armature edit mode. That removes all bones, and recreates them from the edit-bones.

Definition at line 985 of file animrig/intern/bone_collections.cc.

References blender::animrig::ANIM_armature_foreach_bone(), BLI_freelistN(), and bArmature::bonebase.

Referenced by ED_armature_from_edit().

◆ ANIM_armature_bonecoll_remove()

◆ ANIM_armature_bonecoll_remove_from_index()

◆ ANIM_armature_bonecoll_show_all()

void ANIM_armature_bonecoll_show_all ( bArmature * armature)

◆ ANIM_armature_bonecoll_show_from_bone()

◆ ANIM_armature_bonecoll_show_from_ebone()

◆ ANIM_armature_bonecoll_show_from_pchan()

void ANIM_armature_bonecoll_show_from_pchan ( bArmature * armature,
const bPoseChannel * pchan )

◆ ANIM_armature_bonecoll_solo_set()

void ANIM_armature_bonecoll_solo_set ( bArmature * armature,
BoneCollection * bcoll,
bool is_solo )

◆ ANIM_armature_bonecoll_unassign()

◆ ANIM_armature_bonecoll_unassign_all()

void ANIM_armature_bonecoll_unassign_all ( Bone * bone)

◆ ANIM_armature_bonecoll_unassign_all_editbone()

void ANIM_armature_bonecoll_unassign_all_editbone ( EditBone * ebone)

◆ ANIM_armature_bonecoll_unassign_editbone()

◆ ANIM_armature_refresh_solo_active()

void ANIM_armature_refresh_solo_active ( bArmature * armature)

Refresh the ARM_BCOLL_SOLO_ACTIVE flag.

Definition at line 826 of file animrig/intern/bone_collections.cc.

References ARM_BCOLL_SOLO_ACTIVE, BONE_COLLECTION_SOLO, and bArmature::flag.

Referenced by ANIM_armature_bonecoll_remove_from_index(), and ANIM_armature_bonecoll_solo_set().

◆ ANIM_armature_runtime_free()

void ANIM_armature_runtime_free ( bArmature * armature)

Free armature & bone runtime data. TODO: move to BKE?

Definition at line 113 of file animrig/intern/bone_collections.cc.

References blender::animrig::ANIM_armature_foreach_bone(), and bArmature::bonebase.

Referenced by ANIM_armature_runtime_refresh(), and armature_free_data().

◆ ANIM_armature_runtime_refresh()

void ANIM_armature_runtime_refresh ( bArmature * armature)

◆ ANIM_bone_in_visible_collection()

◆ ANIM_bone_is_visible()

◆ ANIM_bone_is_visible_editbone()

bool ANIM_bone_is_visible_editbone ( const bArmature * armature,
const EditBone * ebone )
inline

◆ ANIM_bonecoll_free()

void ANIM_bonecoll_free ( BoneCollection * bcoll,
bool do_id_user_count = true )

Free the bone collection.

You don't typically need this function, unless you created a bone collection outside the scope of a bArmature. Normally bone collections are owned (and thus managed) by the armature.

See also
ANIM_armature_bonecoll_remove
Parameters
do_id_user_countWhether to update user counts for IDs referenced from IDProperties of the bone collection. Needs to be false when freeing an evaluated copy, true otherwise.

Definition at line 72 of file animrig/intern/bone_collections.cc.

References BLI_assert_msg, BLI_listbase_is_empty(), BoneCollection::bones, IDP_FreeProperty_ex(), and BoneCollection::prop.

Referenced by armature_free_data(), blender::animrig::internal::bonecoll_unassign_and_free(), blender::animrig::tests::TEST(), blender::animrig::tests::TEST(), and blender::animrig::tests::TEST_F().

◆ ANIM_bonecoll_hide()

void ANIM_bonecoll_hide ( bArmature * armature,
BoneCollection * bcoll )

Hide this bone collection.

This marks the bone collection as 'hidden'. This also effectively hides its descendants, regardless of their visibility state.

Definition at line 791 of file animrig/intern/bone_collections.cc.

References ancestors_visible_descendants_update(), and BoneCollection::flags.

Referenced by ANIM_armature_bonecoll_hide_all(), ANIM_armature_bonecoll_is_visible_set(), bc_add_armature_collections(), blender::animrig::tests::TEST_F(), version_bonegroups_to_bonecollections(), and version_bonelayers_to_bonecollections().

◆ ANIM_bonecoll_is_visible_actbone()

bool ANIM_bonecoll_is_visible_actbone ( const bArmature * armature)
inline

Definition at line 330 of file ANIM_bone_collections.hh.

References bArmature::act_bone, and ANIM_bone_in_visible_collection().

Referenced by draw_selected_name().

◆ ANIM_bonecoll_is_visible_editbone()

◆ ANIM_bonecoll_is_visible_pchan()

bool ANIM_bonecoll_is_visible_pchan ( const bArmature * armature,
const bPoseChannel * pchan )
inline

◆ ANIM_bonecoll_new()

BoneCollection * ANIM_bonecoll_new ( const char * name)

Construct a new BoneCollection with the given name.

The caller owns the returned pointer.

You don't typically use this function directly, but rather create a bone collection on a bArmature.

See also
#armature_bonecoll_new

Definition at line 53 of file animrig/intern/bone_collections.cc.

References DATA_, BoneCollection::flags, BoneCollection::name, BoneCollection::prop, and STRNCPY_UTF8.

Referenced by ANIM_armature_bonecoll_new(), blender::animrig::tests::TEST(), blender::animrig::tests::TEST(), and blender::animrig::tests::TEST_F().

◆ ANIM_bonecoll_show()

void ANIM_bonecoll_show ( bArmature * armature,
BoneCollection * bcoll )

Show this bone collection.

This marks the bone collection as 'visible'. Whether it is effectively visible also depends on the visibility state of its ancestors.

Definition at line 785 of file animrig/intern/bone_collections.cc.

References ancestors_visible_descendants_update(), BONE_COLLECTION_VISIBLE, and BoneCollection::flags.

Referenced by ANIM_armature_bonecoll_is_visible_set(), ANIM_armature_bonecoll_show_all(), and bc_add_armature_collections().