BKE_lib_remap.hh File Reference

#include "BLI_compiler_attrs.h"
#include "BLI_function_ref.hh"
#include "BLI_map.hh"
#include "BLI_set.hh"
#include "BLI_span.hh"
#include "BLI_utildefines.h"

Go to the source code of this file.

Classes
class	blender::bke::id::IDRemapper

Namespaces
namespace	blender
namespace	blender::bke
namespace	blender::bke::id

Typedefs
using	BKE_library_free_notifier_reference_cb = void (*)(const void *)
using	BKE_library_remap_editor_id_reference_cb
using	IDRemapperIterFunction = void (*)(ID *old_id, ID *new_id, void *user_data)
using	IDTypeFilter = uint64_t

Enumerations
enum	{   ID_REMAP_SKIP_INDIRECT_USAGE = 1 << 0 , ID_REMAP_SKIP_NEVER_NULL_USAGE = 1 << 1 , ID_REMAP_STORE_NEVER_NULL_USAGE = 1 << 2 , ID_REMAP_FORCE_NEVER_NULL_USAGE = 1 << 3 ,   ID_REMAP_SKIP_OVERRIDE_LIBRARY = 1 << 4 , ID_REMAP_FORCE_INTERNAL_RUNTIME_POINTERS = 1 << 5 , ID_REMAP_FORCE_UI_POINTERS = 1 << 6 , ID_REMAP_FORCE_OBDATA_IN_EDITMODE = 1 << 7 ,   ID_REMAP_DO_LIBRARY_POINTERS = 1 << 8 , ID_REMAP_ALLOW_IDTYPE_MISMATCH = 1 << 9 , ID_REMAP_SKIP_USER_CLEAR = 1 << 16 , ID_REMAP_FORCE_USER_REFCOUNT = 1 << 17 ,   ID_REMAP_SKIP_USER_REFCOUNT = 1 << 18 , ID_REMAP_SKIP_UPDATE_TAGGING = 1 << 19 , ID_REMAP_NO_ORIG_POINTERS_ACCESS = 1 << 20 }
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 (Main *bmain, blender::bke::id::IDRemapper &mappings, const int remap_flags)
void	BKE_libblock_remap_multiple (Main *bmain, blender::bke::id::IDRemapper &mappings, const int remap_flags)
void	BKE_libblock_remap_multiple_raw (Main *bmain, blender::bke::id::IDRemapper &mappings, const int remap_flags)
void	BKE_libblock_remap_locked (Main *bmain, void *old_idv, void *new_idv, int remap_flags) ATTR_NONNULL(1
void void	BKE_libblock_remap (Main *bmain, void *old_idv, void *new_idv, int remap_flags) ATTR_NONNULL(1
void void void	BKE_libblock_unlink (Main *bmain, void *idv, bool do_skip_indirect) ATTR_NONNULL()
void	BKE_libblock_relink_ex (Main *bmain, void *idv, void *old_idv, void *new_idv, int remap_flags) ATTR_NONNULL(2)
void	BKE_libblock_relink_multiple (Main *bmain, const blender::Span< ID * > ids, eIDRemapType remap_type, blender::bke::id::IDRemapper &id_remapper, int remap_flags)
void	BKE_libblock_relink_to_newid (Main *bmain, 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)

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).

• BKE_lib_remap_libblock_ should be used for functions performing remapping.
• BKE_lib_remap_callback_ should be used for functions managing remapping callbacks.

Definition in file BKE_lib_remap.hh.

Typedef Documentation

BKE_library_free_notifier_reference_cb

using BKE_library_free_notifier_reference_cb = void (*)(const void *)

Definition at line 213 of file BKE_lib_remap.hh.

BKE_library_remap_editor_id_reference_cb

using BKE_library_remap_editor_id_reference_cb

Initial value:

 
void (*)(const blender::bke::id::IDRemapper &mappings)

Definition at line 214 of file BKE_lib_remap.hh.

IDRemapperIterFunction

using IDRemapperIterFunction = void (*)(ID *old_id, ID *new_id, void *user_data)

Definition at line 265 of file BKE_lib_remap.hh.

IDTypeFilter

using IDTypeFilter = uint64_t

Definition at line 266 of file BKE_lib_remap.hh.

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_STORE_NEVER_NULL_USAGE	Store in the #IDRemapper all IDs using target one with a 'never NULL' pointer (like e.g. Object.data), when such ID usage has (or should have) been remapped to nullptr. See also ID_REMAP_FORCE_NEVER_NULL_USAGE and ID_REMAP_SKIP_NEVER_NULL_USAGE.
ID_REMAP_FORCE_NEVER_NULL_USAGE	This tells the callback function 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_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_UI_POINTERS	Force remapping of 'UI-like' ID usages (ID pointers stored in editors data etc.).
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.
ID_REMAP_DO_LIBRARY_POINTERS	Do remapping of lib Library pointers of IDs (by default these are completely ignored). WARNING: Use with caution. This is currently a 'raw' remapping, with no further processing. In particular, DO NOT use this to make IDs local (i.e. remap a library pointer to NULL), unless the calling code takes care of the rest of the required changes (ID tags & flags updates, etc.).
ID_REMAP_ALLOW_IDTYPE_MISMATCH	Allow remapping of an ID pointer of a certain to another one of a different type. WARNING: Use with caution. Should only be needed in a very small amount of cases, e.g. when converting an ID type to another.
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_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_SKIP_USER_REFCOUNT	Do NOT handle user count for IDs (used in some cases when dealing with IDs from different BMains, if user-count will be recomputed anyway afterwards, like e.g. in memfile reading during undo step decoding).
ID_REMAP_SKIP_UPDATE_TAGGING	Do NOT tag IDs which had some of their ID pointers updated for update in the depsgraph, or ID type specific updates, like e.g. with node trees.
ID_REMAP_NO_ORIG_POINTERS_ACCESS	Do not attempt to access original ID pointers (triggers usages of IDWALK_NO_ORIG_POINTERS_ACCESS too). Use when original ID pointers values are (probably) not valid, e.g. during read-file process.

Definition at line 40 of file BKE_lib_remap.hh.

eIDRemapType

enum 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 130 of file BKE_lib_remap.hh.

IDRemapperApplyOptions

enum IDRemapperApplyOptions

Enumerator
ID_REMAP_APPLY_UPDATE_REFCOUNT	Update the user count of the old and new ID data-block. 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 user-count is handled by foreach_libblock_remap_callback_apply there, depending on whether the remapped pointer does use it or not. Needed for rare cases in UI handling though (see e.g. image_id_remap in space_image.cc).
ID_REMAP_APPLY_ENSURE_REAL	Make sure that the new ID data-block will have a 'real' user. NOTE: See Note for ID_REMAP_APPLY_UPDATE_REFCOUNT above.
ID_REMAP_APPLY_UNMAP_WHEN_REMAPPING_TO_SELF	Unassign instead of remap when the new ID pointer would point to itself. To use this option #IDRemapper::apply must be used with a non-null id_self parameter.
ID_REMAP_APPLY_DEFAULT

Definition at line 233 of file BKE_lib_remap.hh.

IDRemapperApplyResult

enum 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 222 of file BKE_lib_remap.hh.

Function Documentation

BKE_libblock_relink_ex()

void BKE_libblock_relink_ex	(	Main *	bmain,
		void *	idv,
		void *	old_idv,
		void *	new_idv,
		int	remap_flags )

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

Parameters

old_idv	Unlike BKE_libblock_remap, can be NULL, in which case all ID usages by given idv will be cleared.
bmain	May be NULL, in which case there won't be depsgraph updates nor post-processing on some ID types (like collections or objects) to ensure their runtime data is valid.

Definition at line 854 of file lib_remap.cc.

References blender::bke::id::IDRemapper::add(), BKE_libblock_relink_multiple(), BLI_assert, GS, ID_REMAP_TYPE_CLEANUP, ID_REMAP_TYPE_REMAP, ID::name, and UNUSED_VARS_NDEBUG.

Referenced by BKE_lib_override_library_create_from_id(), and id_free().

BKE_libblock_relink_multiple()

void BKE_libblock_relink_multiple	(	Main *	bmain,
		const blender::Span< ID * >	ids,
		eIDRemapType	remap_type,
		blender::bke::id::IDRemapper &	id_remapper,
		int	remap_flags )

Same as BKE_libblock_relink_ex, but applies all rules defined in id_remapper to ids (or does cleanup if ID_REMAP_TYPE_CLEANUP is specified as remap_type).

Definition at line 792 of file lib_remap.cc.

References BLI_assert, BLI_assert_unreachable, DEG_relations_tag_update(), GS, ID_GR, ID_REMAP_TYPE_CLEANUP, ID_REMAP_TYPE_REMAP, ID_SCE, blender::bke::id::IDRemapper::is_empty(), blender::bke::id::IDRemapper::iter(), libblock_relink_foreach_idpair(), libblock_remap_data(), libblock_remap_data_postprocess_collection_update(), and libblock_remap_data_postprocess_object_update().

Referenced by BKE_lib_override_library_create_from_tag(), BKE_libblock_relink_ex(), BKE_libblock_relink_to_newid(), BKE_main_merge(), id_delete(), id_swap(), lib_override_library_remap(), lib_override_library_resync(), and pack_linked_ids().

BKE_libblock_relink_to_newid()

void BKE_libblock_relink_to_newid	(	Main *	bmain,
		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 ID_TAG_NEW.

Note

ID_TAG_NEW is cleared.

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

Definition at line 931 of file lib_remap.cc.

References BKE_libblock_relink_multiple(), BLI_assert, 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(), and Main::relations.

Referenced by blender::ed::object::add_duplicate(), BKE_blendfile_append(), BKE_brush_duplicate(), BKE_collection_duplicate(), BKE_object_duplicate(), BKE_scene_duplicate(), blender::ed::object::copy_object_set_idnew(), blender::ed::object::libblock_relink_collection(), blender::ed::object::make_object_duplilist_real(), blender::seq::seq_duplicate_postprocess(), and blender::ed::object::single_object_users().

BKE_libblock_remap()

void void BKE_libblock_remap	(	Main *	bmain,
		void *	old_idv,
		void *	new_idv,
		int	remap_flags )

Referenced by BKE_lib_id_make_local_generic(), BKE_lib_override_library_delete(), BKE_library_make_local(), brush_make_local(), blender::ed::object::clear_override_library_exec(), blender::ed::outliner::id_override_library_clear_single_process(), blender::ed::outliner::outliner_id_remap_exec(), override_idtemplate_clear_exec(), paste_material_exec(), blender::bke::tests::TEST_F(), blender::bke::tests::TEST_F(), blender::bke::tests::TEST_F(), blender::bke::tests::TEST_F(), blender::bke::tests::TEST_F(), blender::bke::tests::TEST_F(), blender::bke::tests::TEST_F(), blender::bke::tests::TEST_F(), and blender::bke::tests::TEST_F().

BKE_libblock_remap_locked()

void BKE_libblock_remap_locked	(	Main *	bmain,
		void *	old_idv,
		void *	new_idv,
		int	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.

BKE_libblock_remap_multiple()

void BKE_libblock_remap_multiple	(	Main *	bmain,
		blender::bke::id::IDRemapper &	mappings,
		const int	remap_flags )

Definition at line 711 of file lib_remap.cc.

References BKE_libblock_remap_multiple_locked(), BKE_main_lock(), and BKE_main_unlock().

Referenced by blender::bke::greasepencil::convert::legacy_main(), lib_override_library_remap(), and make_selected_objects_local().

BKE_libblock_remap_multiple_locked()

void BKE_libblock_remap_multiple_locked	(	Main *	bmain,
		blender::bke::id::IDRemapper &	mappings,
		const int	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 655 of file lib_remap.cc.

References DEG_relations_tag_update(), ID_REMAP_TYPE_REMAP, blender::bke::id::IDRemapper::is_empty(), blender::bke::id::IDRemapper::iter(), libblock_remap_data(), libblock_remap_foreach_idpair(), and remap_editor_id_reference_cb.

Referenced by BKE_libblock_remap_locked(), BKE_libblock_remap_multiple(), blendfile_library_relocate_id_remap(), id_delete(), blender::bke::tests::TEST_F(), and blender::bke::tests::TEST_F().

BKE_libblock_remap_multiple_raw()

void BKE_libblock_remap_multiple_raw	(	Main *	bmain,
		blender::bke::id::IDRemapper &	mappings,
		const int	remap_flags )

Bare raw remapping of IDs, with no other processing than actually updating the ID pointers. No user-count, direct vs indirect linked status update, depsgraph tagging, etc.

This is way more efficient than regular remapping from BKE_libblock_remap_multiple & co, but it implies that calling code handles all the other aspects described above. This is typically the case e.g. in read-file process.

WARNING: This call will likely leave the given BMain in invalid state in many aspects.

Definition at line 679 of file lib_remap.cc.

References ID_REMAP_SKIP_UPDATE_TAGGING, ID_REMAP_SKIP_USER_REFCOUNT, ID_REMAP_TYPE_REMAP, blender::bke::id::IDRemapper::is_empty(), and libblock_remap_data().

Referenced by setup_app_data().

BKE_libblock_unlink()

void void void BKE_libblock_unlink	(	Main *	bmain,
		void *	idv,
		bool	do_skip_indirect )

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

Definition at line 720 of file lib_remap.cc.

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

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 46 of file lib_remap.cc.

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 53 of file lib_remap.cc.

References remap_editor_id_reference_cb.

Referenced by WM_init().