Blender  V3.3
Typedefs | Enumerations | Functions
BKE_lib_remap.h File Reference
#include "BLI_compiler_attrs.h"

Go to the source code of this file.

Typedefs

typedef enum eIDRemapType eIDRemapType
 
typedef void(* BKE_library_free_notifier_reference_cb) (const void *)
 
typedef void(* BKE_library_remap_editor_id_reference_cb) (const struct IDRemapper *mappings)
 
typedef enum IDRemapperApplyResult IDRemapperApplyResult
 
typedef enum IDRemapperApplyOptions IDRemapperApplyOptions
 
typedef void(* IDRemapperIterFunction) (struct ID *old_id, struct ID *new_id, void *user_data)
 

Enumerations

enum  {
  ID_REMAP_SKIP_INDIRECT_USAGE = 1 << 0 , ID_REMAP_SKIP_NEVER_NULL_USAGE = 1 << 1 , ID_REMAP_FLAG_NEVER_NULL_USAGE = 1 << 2 , ID_REMAP_FORCE_NEVER_NULL_USAGE = 1 << 3 ,
  ID_REMAP_SKIP_OVERRIDE_LIBRARY = 1 << 5 , ID_REMAP_SKIP_USER_CLEAR = 1 << 6 , ID_REMAP_FORCE_INTERNAL_RUNTIME_POINTERS = 1 << 7 , ID_REMAP_FORCE_USER_REFCOUNT = 1 << 8 ,
  ID_REMAP_FORCE_OBDATA_IN_EDITMODE = 1 << 9
}
 
enum  eIDRemapType { ID_REMAP_TYPE_REMAP = 0 , ID_REMAP_TYPE_CLEANUP = 1 }
 
enum  IDRemapperApplyResult { ID_REMAP_RESULT_SOURCE_UNAVAILABLE , ID_REMAP_RESULT_SOURCE_NOT_MAPPABLE , ID_REMAP_RESULT_SOURCE_REMAPPED , ID_REMAP_RESULT_SOURCE_UNASSIGNED }
 
enum  IDRemapperApplyOptions { ID_REMAP_APPLY_UPDATE_REFCOUNT = (1 << 0) , ID_REMAP_APPLY_ENSURE_REAL = (1 << 1) , ID_REMAP_APPLY_UNMAP_WHEN_REMAPPING_TO_SELF = (1 << 2) , ID_REMAP_APPLY_DEFAULT = 0 }
 

Functions

void BKE_libblock_remap_multiple_locked (struct Main *bmain, struct IDRemapper *mappings, short remap_flags)
 
void BKE_libblock_remap_multiple (struct Main *bmain, struct IDRemapper *mappings, short remap_flags)
 
void BKE_libblock_remap_locked (struct Main *bmain, void *old_idv, void *new_idv, short remap_flags) ATTR_NONNULL(1
 
void void BKE_libblock_remap (struct Main *bmain, void *old_idv, void *new_idv, short remap_flags) ATTR_NONNULL(1
 
void void void BKE_libblock_unlink (struct Main *bmain, void *idv, bool do_flag_never_null, bool do_skip_indirect) ATTR_NONNULL()
 
void BKE_libblock_relink_ex (struct Main *bmain, void *idv, void *old_idv, void *new_idv, short remap_flags) ATTR_NONNULL(1
 
void void BKE_libblock_relink_multiple (struct Main *bmain, struct LinkNode *ids, eIDRemapType remap_type, struct IDRemapper *id_remapper, short remap_flags)
 
void BKE_libblock_relink_to_newid (struct Main *bmain, struct ID *id, int remap_flag) ATTR_NONNULL()
 
void BKE_library_callback_free_notifier_reference_set (BKE_library_free_notifier_reference_cb func)
 
void BKE_library_callback_remap_editor_id_reference_set (BKE_library_remap_editor_id_reference_cb func)
 
struct IDRemapper * BKE_id_remapper_create (void)
 
void BKE_id_remapper_clear (struct IDRemapper *id_remapper)
 
bool BKE_id_remapper_is_empty (const struct IDRemapper *id_remapper)
 
void BKE_id_remapper_free (struct IDRemapper *id_remapper)
 
void BKE_id_remapper_add (struct IDRemapper *id_remapper, struct ID *old_id, struct ID *new_id)
 
IDRemapperApplyResult BKE_id_remapper_apply (const struct IDRemapper *id_remapper, struct ID **r_id_ptr, IDRemapperApplyOptions options)
 
IDRemapperApplyResult BKE_id_remapper_apply_ex (const struct IDRemapper *id_remapper, struct ID **r_id_ptr, IDRemapperApplyOptions options, struct ID *id_self)
 
bool BKE_id_remapper_has_mapping_for (const struct IDRemapper *id_remapper, uint64_t type_filter)
 
IDRemapperApplyResult BKE_id_remapper_get_mapping_result (const struct IDRemapper *id_remapper, struct ID *id, IDRemapperApplyOptions options, const struct ID *id_self)
 
void BKE_id_remapper_iter (const struct IDRemapper *id_remapper, IDRemapperIterFunction func, void *user_data)
 
const char * BKE_id_remapper_result_string (const IDRemapperApplyResult result)
 
void BKE_id_remapper_print (const struct IDRemapper *id_remapper)
 

Detailed Description

API to perform remapping from one data-block pointer to another.

Note
BKE_lib_ files are for operations over data-blocks themselves, although they might alter Main as well (when creating/renaming/deleting an ID e.g.).

Names

Warning
Descriptions below is ideal goal, current status of naming does not yet fully follow it (this is WIP).

Definition in file BKE_lib_remap.h.

Typedef Documentation

◆ BKE_library_free_notifier_reference_cb

typedef void(* BKE_library_free_notifier_reference_cb) (const void *)

Definition at line 161 of file BKE_lib_remap.h.

◆ BKE_library_remap_editor_id_reference_cb

typedef void(* BKE_library_remap_editor_id_reference_cb) (const struct IDRemapper *mappings)

Definition at line 162 of file BKE_lib_remap.h.

◆ eIDRemapType

typedef enum eIDRemapType eIDRemapType

◆ IDRemapperApplyOptions

◆ IDRemapperApplyResult

◆ IDRemapperIterFunction

typedef void(* IDRemapperIterFunction) (struct ID *old_id, struct ID *new_id, void *user_data)

Definition at line 212 of file BKE_lib_remap.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
ID_REMAP_SKIP_INDIRECT_USAGE 

Do not remap indirect usages of IDs (that is, when user is some linked data).

ID_REMAP_SKIP_NEVER_NULL_USAGE 

This flag should always be set, except for 'unlink' scenarios (only relevant when new_id == NULL). Basically, when unset, NEVER_NULL ID usages will keep pointing to old_id, but (if needed) old_id user count will still be decremented. This is mandatory for 'delete ID' case, but in all other situation this would lead to invalid user counts!

ID_REMAP_FLAG_NEVER_NULL_USAGE 

This tells the callback func to flag with #LIB_DOIT all IDs using target one with a 'never NULL' pointer (like e.g. Object.data).

ID_REMAP_FORCE_NEVER_NULL_USAGE 

This tells the callback func to force setting IDs using target one with a 'never NULL' pointer to NULL.

Warning
Use with extreme care, this will leave database in broken state and can cause crashes very easily!
ID_REMAP_SKIP_OVERRIDE_LIBRARY 

Do not remap library override pointers.

ID_REMAP_SKIP_USER_CLEAR 

Don't touch the special user counts (use when the 'old' remapped ID remains in use):

  • Do not transfer 'fake user' status from old to new ID.
  • Do not clear 'extra user' from old ID.
ID_REMAP_FORCE_INTERNAL_RUNTIME_POINTERS 

Force internal ID runtime pointers (like ID.newid, ID.orig_id etc.) to also be processed. This should only be needed in some very specific cases, typically only BKE ID management code should need it (e.g. required from id_delete to ensure no runtime pointer remains using freed ones).

ID_REMAP_FORCE_USER_REFCOUNT 

Force handling user count even for IDs that are outside of Main (used in some cases when dealing with IDs temporarily out of Main, but which will be put in it ultimately).

ID_REMAP_FORCE_OBDATA_IN_EDITMODE 

Force obdata pointers to also be processed, even when object (id_owner) is in Edit mode. This is required by some tools creating/deleting IDs while operating in Edit mode, like e.g. the 'separate' mesh operator.

Definition at line 34 of file BKE_lib_remap.h.

◆ eIDRemapType

Enumerator
ID_REMAP_TYPE_REMAP 

Remap an ID reference to a new reference. The new reference can also be null.

ID_REMAP_TYPE_CLEANUP 

Cleanup all IDs used by a specific one.

Definition at line 83 of file BKE_lib_remap.h.

◆ IDRemapperApplyOptions

Enumerator
ID_REMAP_APPLY_UPDATE_REFCOUNT 

Update the user count of the old and new ID datablock.

For remapping the old ID users will be decremented and the new ID users will be incremented. When un-assigning the old ID users will be decremented.

NOTE: Currently unused by main remapping code, since usercount is handled by foreach_libblock_remap_callback_apply there, depending on whether the remapped pointer does use it or not. Need for rare cases in UI handling though (see e.g. image_id_remap in space_image.c).

ID_REMAP_APPLY_ENSURE_REAL 

Make sure that the new ID datablock will have a 'real' user.

NOTE: See Note for ID_REMAP_APPLY_UPDATE_REFCOUNT above.

ID_REMAP_APPLY_UNMAP_WHEN_REMAPPING_TO_SELF 

Unassign in stead of remap when the new ID datablock would become id_self.

To use this option 'BKE_id_remapper_apply_ex' must be used with a not-null id_self parameter.

ID_REMAP_APPLY_DEFAULT 

Definition at line 181 of file BKE_lib_remap.h.

◆ IDRemapperApplyResult

Enumerator
ID_REMAP_RESULT_SOURCE_UNAVAILABLE 

No remapping rules available for the source.

ID_REMAP_RESULT_SOURCE_NOT_MAPPABLE 

Source isn't mappable (e.g. NULL).

ID_REMAP_RESULT_SOURCE_REMAPPED 

Source has been remapped to a new pointer.

ID_REMAP_RESULT_SOURCE_UNASSIGNED 

Source has been set to NULL.

Definition at line 170 of file BKE_lib_remap.h.

Function Documentation

◆ BKE_id_remapper_add()

void BKE_id_remapper_add ( struct IDRemapper *  id_remapper,
struct ID old_id,
struct ID new_id 
)

◆ BKE_id_remapper_apply()

IDRemapperApplyResult BKE_id_remapper_apply ( const struct IDRemapper *  id_remapper,
struct ID **  r_id_ptr,
IDRemapperApplyOptions  options 
)

◆ BKE_id_remapper_apply_ex()

IDRemapperApplyResult BKE_id_remapper_apply_ex ( const struct IDRemapper *  id_remapper,
struct ID **  r_id_ptr,
IDRemapperApplyOptions  options,
struct ID id_self 
)

Apply a remapping.

Use this function when ID_REMAP_APPLY_UNMAP_WHEN_REMAPPING_TO_SELF. In this case the #id_self parameter is required. Otherwise the BKE_id_remapper_apply can be used.

Parameters
id_selfrequired for ID_REMAP_APPLY_UNMAP_WHEN_REMAPPING_TO_SELF. When remapping to id_self it will then be remapped to NULL.

Referenced by foreach_libblock_remap_callback_apply(), and blender::bke::id::remapper::tests::TEST().

◆ BKE_id_remapper_clear()

void BKE_id_remapper_clear ( struct IDRemapper *  id_remapper)

◆ BKE_id_remapper_create()

struct IDRemapper* BKE_id_remapper_create ( void  )

◆ BKE_id_remapper_free()

void BKE_id_remapper_free ( struct IDRemapper *  id_remapper)

◆ BKE_id_remapper_get_mapping_result()

IDRemapperApplyResult BKE_id_remapper_get_mapping_result ( const struct IDRemapper *  id_remapper,
struct ID id,
IDRemapperApplyOptions  options,
const struct ID id_self 
)

Determine the mapping result, without applying the mapping.

Definition at line 168 of file lib_id_remapper.cc.

References blender::bke::id::remapper::IDRemapper::get_mapping_result(), options, and unwrap().

Referenced by foreach_libblock_remap_callback(), and libblock_remap_data_preprocess_ob().

◆ BKE_id_remapper_has_mapping_for()

bool BKE_id_remapper_has_mapping_for ( const struct IDRemapper *  id_remapper,
uint64_t  type_filter 
)

◆ BKE_id_remapper_is_empty()

bool BKE_id_remapper_is_empty ( const struct IDRemapper *  id_remapper)

◆ BKE_id_remapper_iter()

void BKE_id_remapper_iter ( const struct IDRemapper *  id_remapper,
IDRemapperIterFunction  func,
void user_data 
)

◆ BKE_id_remapper_print()

void BKE_id_remapper_print ( const struct IDRemapper *  id_remapper)

Prints out the rules inside the given id_remapper. Can be used for debugging purposes.

Definition at line 234 of file lib_id_remapper.cc.

References BKE_id_remapper_iter(), and id_remapper_print_item_cb().

◆ BKE_id_remapper_result_string()

const char* BKE_id_remapper_result_string ( const IDRemapperApplyResult  result)

Returns a readable string for the given result. Can be used for debugging purposes.

Definition at line 207 of file lib_id_remapper.cc.

References BLI_assert_unreachable, ID_REMAP_RESULT_SOURCE_NOT_MAPPABLE, ID_REMAP_RESULT_SOURCE_REMAPPED, ID_REMAP_RESULT_SOURCE_UNASSIGNED, ID_REMAP_RESULT_SOURCE_UNAVAILABLE, and result.

Referenced by foreach_libblock_remap_callback().

◆ BKE_libblock_relink_ex()

void BKE_libblock_relink_ex ( struct Main bmain,
void idv,
void old_idv,
void new_idv,
short  remap_flags 
)

Similar to libblock_remap, but only affects IDs used by given idv ID.

Parameters
old_idvUnlike BKE_libblock_remap, can be NULL, in which case all ID usages by given idv will be cleared.

Referenced by BKE_id_free_ex(), BKE_lib_override_library_create_from_id(), id_delete(), id_swap(), and scene_copy_data().

◆ BKE_libblock_relink_multiple()

void void BKE_libblock_relink_multiple ( struct Main bmain,
struct LinkNode ids,
eIDRemapType  remap_type,
struct IDRemapper *  id_remapper,
short  remap_flags 
)

◆ BKE_libblock_relink_to_newid()

void BKE_libblock_relink_to_newid ( struct Main bmain,
struct ID id,
int  remap_flag 
)

Remaps ID usages of given ID to their id->newid pointer if not None, and proceeds recursively in the dependency tree of IDs for all data-blocks tagged with LIB_TAG_NEW.

Note
LIB_TAG_NEW is cleared.

Very specific usage, not sure we'll keep it on the long run, currently only used in Object/Collection duplication code.

Definition at line 894 of file lib_remap.c.

References BKE_id_remapper_create(), BKE_id_remapper_free(), BKE_libblock_relink_multiple(), BLI_assert, BLI_linklist_free(), ID_IS_LINKED, ID_REMAP_SKIP_INDIRECT_USAGE, ID_REMAP_SKIP_OVERRIDE_LIBRARY, ID_REMAP_TYPE_REMAP, RelinkToNewIDData::id_remapper, RelinkToNewIDData::ids, libblock_relink_to_newid_prepare_data(), NULL, and Main::relations.

Referenced by BKE_blendfile_append(), BKE_collection_duplicate(), BKE_object_duplicate(), BKE_scene_duplicate(), copy_object_set_idnew(), ED_object_add_duplicate(), libblock_relink_collection(), make_object_duplilist_real(), and single_object_users().

◆ BKE_libblock_remap()

void void BKE_libblock_remap ( struct Main bmain,
void old_idv,
void new_idv,
short  remap_flags 
)

◆ BKE_libblock_remap_locked()

void BKE_libblock_remap_locked ( struct Main bmain,
void old_idv,
void new_idv,
short  remap_flags 
)

Replace all references in given Main to old_id by new_id (if new_id is NULL, it unlinks old_id).

Note
Requiring new_id to be non-null, this may not be the case ultimately, but makes things simpler for now.

Referenced by blendfile_library_relocate_remap(), and id_delete().

◆ BKE_libblock_remap_multiple()

void BKE_libblock_remap_multiple ( struct Main bmain,
struct IDRemapper *  mappings,
short  remap_flags 
)

◆ BKE_libblock_remap_multiple_locked()

void BKE_libblock_remap_multiple_locked ( struct Main bmain,
struct IDRemapper *  mappings,
short  remap_flags 
)

Replace all references in given Main using the given mappings

Note
Is preferred over BKE_libblock_remap_locked due to performance.

Definition at line 614 of file lib_remap.c.

References BKE_id_remapper_is_empty(), BKE_id_remapper_iter(), DEG_relations_tag_update(), ID_REMAP_TYPE_REMAP, libblock_remap_data(), libblock_remap_foreach_idpair_cb(), NULL, remap_editor_id_reference_cb, and user_data.

Referenced by BKE_libblock_remap_locked(), BKE_libblock_remap_multiple(), and id_delete().

◆ BKE_libblock_unlink()

void void void BKE_libblock_unlink ( struct Main bmain,
void idv,
bool  do_flag_never_null,
bool  do_skip_indirect 
)

Unlink given id from given bmain (does not touch to indirect, i.e. library, usages of the ID).

Parameters
do_flag_never_nullIf true, all IDs using idv in a 'non-NULL' way are flagged by LIB_TAG_DOIT flag (quite obviously, 'non-NULL' usages can never be unlinked by this function).

Definition at line 670 of file lib_remap.c.

References BKE_libblock_remap_locked(), BKE_main_lock(), BKE_main_unlock(), ID_REMAP_FLAG_NEVER_NULL_USAGE, ID_REMAP_SKIP_INDIRECT_USAGE, and NULL.

Referenced by BKE_id_free_us().

◆ BKE_library_callback_free_notifier_reference_set()

void BKE_library_callback_free_notifier_reference_set ( BKE_library_free_notifier_reference_cb  func)

Definition at line 41 of file lib_remap.c.

References free_notifier_reference_cb.

Referenced by WM_init().

◆ BKE_library_callback_remap_editor_id_reference_set()

void BKE_library_callback_remap_editor_id_reference_set ( BKE_library_remap_editor_id_reference_cb  func)

Definition at line 48 of file lib_remap.c.

References remap_editor_id_reference_cb.

Referenced by WM_init().