Blender  V3.3
Classes | Macros | Typedefs | Enumerations | Functions
BKE_lib_query.h File Reference
#include "BLI_sys_types.h"

Go to the source code of this file.

Classes

struct  LibraryIDLinkCallbackData
 

Macros

#define BKE_LIB_FOREACHID_PROCESS_ID(_data, _id, _cb_flag)
 
#define BKE_LIB_FOREACHID_PROCESS_IDSUPER(_data, _id_super, _cb_flag)
 
#define BKE_LIB_FOREACHID_PROCESS_FUNCTION_CALL(_data, _func_call)
 

Typedefs

typedef struct LibraryIDLinkCallbackData LibraryIDLinkCallbackData
 
typedef int(* LibraryIDLinkCallback) (LibraryIDLinkCallbackData *cb_data)
 
typedef struct LibraryForeachIDData LibraryForeachIDData
 

Enumerations

enum  {
  IDWALK_CB_NOP = 0 , IDWALK_CB_NEVER_NULL = (1 << 0) , IDWALK_CB_NEVER_SELF = (1 << 1) , IDWALK_CB_INDIRECT_USAGE = (1 << 2) ,
  IDWALK_CB_EMBEDDED = (1 << 3) , IDWALK_CB_LOOPBACK = (1 << 4) , IDWALK_CB_OVERRIDE_LIBRARY_REFERENCE = (1 << 5) , IDWALK_CB_OVERRIDE_LIBRARY_NOT_OVERRIDABLE = (1 << 6) ,
  IDWALK_CB_INTERNAL = (1 << 7) , IDWALK_CB_USER = (1 << 8) , IDWALK_CB_USER_ONE = (1 << 9)
}
 
enum  { IDWALK_RET_NOP = 0 , IDWALK_RET_STOP_ITER = 1 << 0 , IDWALK_RET_STOP_RECURSION = 1 << 1 }
 
enum  {
  IDWALK_NOP = 0 , IDWALK_READONLY = (1 << 0) , IDWALK_RECURSE = (1 << 1) , IDWALK_INCLUDE_UI = (1 << 2) ,
  IDWALK_IGNORE_EMBEDDED_ID = (1 << 3) , IDWALK_DO_INTERNAL_RUNTIME_POINTERS = (1 << 9)
}
 

Functions

bool BKE_lib_query_foreachid_iter_stop (struct LibraryForeachIDData *data)
 
void BKE_lib_query_foreachid_process (struct LibraryForeachIDData *data, struct ID **id_pp, int cb_flag)
 
int BKE_lib_query_foreachid_process_flags_get (struct LibraryForeachIDData *data)
 
int BKE_lib_query_foreachid_process_callback_flag_override (struct LibraryForeachIDData *data, int cb_flag, bool do_replace)
 
void BKE_library_foreach_ID_embedded (struct LibraryForeachIDData *data, struct ID **id_pp)
 
void BKE_lib_query_idpropertiesForeachIDLink_callback (struct IDProperty *id_prop, void *user_data)
 
void BKE_library_foreach_ID_link (struct Main *bmain, struct ID *id, LibraryIDLinkCallback callback, void *user_data, int flag)
 
void BKE_library_update_ID_link_user (struct ID *id_dst, struct ID *id_src, int cb_flag)
 
int BKE_library_ID_use_ID (struct ID *id_user, struct ID *id_used)
 
bool BKE_library_id_can_use_idtype (struct ID *id_owner, short id_type_used)
 
uint64_t BKE_library_id_can_use_filter_id (const struct ID *id_owner)
 
bool BKE_library_ID_is_locally_used (struct Main *bmain, void *idv)
 
bool BKE_library_ID_is_indirectly_used (struct Main *bmain, void *idv)
 
void BKE_library_ID_test_usages (struct Main *bmain, void *idv, bool *is_used_local, bool *is_used_linked)
 
void BKE_lib_query_unused_ids_tag (struct Main *bmain, int tag, bool do_local_ids, bool do_linked_ids, bool do_tag_recursive, int *r_num_tagged)
 
void BKE_library_unused_linked_data_set_tag (struct Main *bmain, bool do_init_tag)
 
void BKE_library_indirectly_used_data_tag_clear (struct Main *bmain)
 

Detailed Description

API to perform operations over all ID pointers used by a given data-block.

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_query.h.

Macro Definition Documentation

◆ BKE_LIB_FOREACHID_PROCESS_FUNCTION_CALL

#define BKE_LIB_FOREACHID_PROCESS_FUNCTION_CALL (   _data,
  _func_call 
)
Value:
{ \
_func_call; \
return; \
} \
} \
((void)0)
bool BKE_lib_query_foreachid_iter_stop(struct LibraryForeachIDData *data)
Definition: lib_query.c:63
SyclQueue void void size_t num_bytes void

Definition at line 174 of file BKE_lib_query.h.

◆ BKE_LIB_FOREACHID_PROCESS_ID

#define BKE_LIB_FOREACHID_PROCESS_ID (   _data,
  _id,
  _cb_flag 
)
Value:
{ \
CHECK_TYPE_ANY((_id), ID *, void *); \
BKE_lib_query_foreachid_process((_data), (ID **)&(_id), (_cb_flag)); \
return; \
} \
} \
((void)0)
Definition: DNA_ID.h:368

Definition at line 154 of file BKE_lib_query.h.

◆ BKE_LIB_FOREACHID_PROCESS_IDSUPER

#define BKE_LIB_FOREACHID_PROCESS_IDSUPER (   _data,
  _id_super,
  _cb_flag 
)
Value:
{ \
CHECK_TYPE(&((_id_super)->id), ID *); \
BKE_lib_query_foreachid_process((_data), (ID **)&(_id_super), (_cb_flag)); \
return; \
} \
} \
((void)0)

Definition at line 164 of file BKE_lib_query.h.

Typedef Documentation

◆ LibraryForeachIDData

Definition at line 113 of file BKE_lib_query.h.

◆ LibraryIDLinkCallback

typedef int(* LibraryIDLinkCallback) (LibraryIDLinkCallbackData *cb_data)

Call a callback for each ID link which the given ID uses.

Returns
a set of flags to control further iteration (0 to keep going).

Definition at line 113 of file BKE_lib_query.h.

◆ LibraryIDLinkCallbackData

Enumeration Type Documentation

◆ anonymous enum

anonymous enum
Enumerator
IDWALK_CB_NOP 
IDWALK_CB_NEVER_NULL 
IDWALK_CB_NEVER_SELF 
IDWALK_CB_INDIRECT_USAGE 

Indicates whether this is direct (i.e. by local data) or indirect (i.e. by linked data) usage.

Note
Object proxies are half-local, half-linked...
IDWALK_CB_EMBEDDED 

That ID is used as mere sub-data by its owner (only case currently: those root nodetrees in materials etc., and the Scene's master collections). This means callback shall not do anything, only use this as informative data if it needs it.

IDWALK_CB_LOOPBACK 

That ID is not really used by its owner, it's just an internal hint/helper. This marks the 'from' pointers issue, like Key->from. How to handle that kind of cases totally depends on what caller code is doing...

IDWALK_CB_OVERRIDE_LIBRARY_REFERENCE 

That ID is used as library override's reference by its owner.

IDWALK_CB_OVERRIDE_LIBRARY_NOT_OVERRIDABLE 

That ID pointer is not overridable.

IDWALK_CB_INTERNAL 

Indicates that this is an internal runtime ID pointer, like e.g. ID.newid or ID.original.

Note
Those should be ignored in most cases, and won't be processed/generated anyway unless IDWALK_DO_INTERNAL_RUNTIME_POINTERS option is enabled.
IDWALK_CB_USER 

This ID usage is fully refcounted. Callback is responsible to deal accordingly with ID.us if needed.

IDWALK_CB_USER_ONE 

This ID usage is not refcounted, but at least one user should be generated by it (to avoid e.g. losing the used ID on save/reload). Callback is responsible to deal accordingly with ID.us if needed.

Definition at line 32 of file BKE_lib_query.h.

◆ anonymous enum

anonymous enum
Enumerator
IDWALK_RET_NOP 
IDWALK_RET_STOP_ITER 

Completely stop iteration.

IDWALK_RET_STOP_RECURSION 

Stop recursion, that is, do not loop over ID used by current one.

Definition at line 82 of file BKE_lib_query.h.

◆ anonymous enum

anonymous enum
Enumerator
IDWALK_NOP 
IDWALK_READONLY 

The callback will never modify the ID pointers it processes.

IDWALK_RECURSE 

Recurse into 'descendant' IDs. Each ID is only processed once. Order of ID processing is not guaranteed.

Also implies IDWALK_READONLY, and excludes IDWALK_DO_INTERNAL_RUNTIME_POINTERS.

NOTE: When enabled, embedded IDs are processed separately from their owner, as if they were regular IDs. Owner ID is not available then in the LibraryForeachIDData callback data.

IDWALK_INCLUDE_UI 

Include UI pointers (from WM and screens editors).

IDWALK_IGNORE_EMBEDDED_ID 

Do not process ID pointers inside embedded IDs. Needed by depsgraph processing e.g.

IDWALK_DO_INTERNAL_RUNTIME_POINTERS 

Also process internal ID pointers like ID.newid or ID.orig_id. WARNING: Dangerous, use with caution.

Definition at line 116 of file BKE_lib_query.h.

Function Documentation

◆ BKE_lib_query_foreachid_iter_stop()

bool BKE_lib_query_foreachid_iter_stop ( struct LibraryForeachIDData data)

Check whether current iteration over ID usages should be stopped or not.

Returns
true if the iteration should be stopped, false otherwise.

Definition at line 63 of file lib_query.c.

References data, and IDWALK_STOP.

Referenced by BKE_lib_query_foreachid_process(), BKE_library_foreach_ID_embedded(), library_foreach_ID_link(), and window_manager_foreach_id().

◆ BKE_lib_query_foreachid_process()

void BKE_lib_query_foreachid_process ( struct LibraryForeachIDData data,
struct ID **  id_pp,
int  cb_flag 
)

◆ BKE_lib_query_foreachid_process_callback_flag_override()

int BKE_lib_query_foreachid_process_callback_flag_override ( struct LibraryForeachIDData data,
int  cb_flag,
bool  do_replace 
)

Definition at line 114 of file lib_query.c.

References data.

◆ BKE_lib_query_foreachid_process_flags_get()

int BKE_lib_query_foreachid_process_flags_get ( struct LibraryForeachIDData data)

Definition at line 109 of file lib_query.c.

References data.

Referenced by screen_foreach_id(), and window_manager_foreach_id().

◆ BKE_lib_query_idpropertiesForeachIDLink_callback()

void BKE_lib_query_idpropertiesForeachIDLink_callback ( struct IDProperty id_prop,
void user_data 
)

◆ BKE_lib_query_unused_ids_tag()

void BKE_lib_query_unused_ids_tag ( struct Main bmain,
int  tag,
bool  do_local_ids,
bool  do_linked_ids,
bool  do_tag_recursive,
int *  r_num_tagged 
)

Tag all unused IDs (a.k.a 'orphaned').

By default only tag IDs with 0 user count. If do_tag_recursive is set, it will check dependencies to detect all IDs that are not actually used in current file, including 'archipelagos‘ (i.e. set of IDs referencing each other in loops, but without any 'external’ valid usages.

Valid usages here are defined as ref-counting usages, which are not towards embedded or loop-back data.

Parameters
r_num_taggedIf non-NULL, must be a zero-initialized array of INDEX_ID_MAX integers. Number of tagged-as-unused IDs is then set for each type, and as total in INDEX_ID_NULL item.

Definition at line 778 of file lib_query.c.

References BKE_idtype_idcode_to_index(), BKE_main_relations_create(), BKE_main_relations_free(), BLI_assert, BLI_ghash_lookup(), FOREACH_MAIN_ID_BEGIN, FOREACH_MAIN_ID_END, GS, id, ID_IS_LINKED, INDEX_ID_NULL, lib_query_unused_ids_tag_recurse(), MAINIDRELATIONS_ENTRY_TAGS_INPROGRESS, MAINIDRELATIONS_ENTRY_TAGS_PROCESSED, ID::name, NULL, Main::relations, MainIDRelations::relations_from_pointers, ID::tag, MainIDRelationsEntry::tags, and ID::us.

Referenced by bpy_orphans_purge(), outliner_orphans_purge_exec(), and outliner_orphans_purge_invoke().

◆ BKE_library_foreach_ID_embedded()

void BKE_library_foreach_ID_embedded ( struct LibraryForeachIDData data,
struct ID **  id_pp 
)

Process embedded ID pointers (root node-trees, master collections, ...).

Those require specific care, since they are technically sub-data of their owner, yet in some cases they still behave as regular IDs.

Definition at line 147 of file lib_query.c.

References BKE_lib_query_foreachid_iter_stop(), BKE_lib_query_foreachid_process(), BLI_assert, BLI_gset_add(), BLI_LINKSTACK_PUSH, data, IDWALK_CB_EMBEDDED, IDWALK_IGNORE_EMBEDDED_ID, IDWALK_RECURSE, IDWALK_STOP, library_foreach_ID_link(), and NULL.

Referenced by light_foreach_id(), linestyle_foreach_id(), material_foreach_id(), scene_foreach_id(), simulation_foreach_id(), texture_foreach_id(), and world_foreach_id().

◆ BKE_library_foreach_ID_link()

void BKE_library_foreach_ID_link ( struct Main bmain,
struct ID id,
LibraryIDLinkCallback  callback,
void user_data,
int  flag 
)

◆ BKE_library_id_can_use_filter_id()

uint64_t BKE_library_id_can_use_filter_id ( const struct ID id_owner)

Given the id_owner return the type of id_types it can use as a filter_id.

Referenced by libblock_remap_data().

◆ BKE_library_id_can_use_idtype()

bool BKE_library_id_can_use_idtype ( struct ID id_owner,
short  id_type_used 
)

Say whether given id_owner may use (in any way) a data-block of id_type_used.

This is a 'simplified' abstract version of BKE_library_foreach_ID_link() above, quite useful to reduce useless iterations in some cases.

Definition at line 484 of file lib_query.c.

References BKE_idtype_idcode_to_idfilter(), BKE_library_id_can_use_filter_id(), ELEM, GS, ID_CU_LEGACY, ID_KE, ID_LI, ID_LT, ID_ME, ID_SCR, ID_WS, ID::name, and ID::properties.

Referenced by BKE_library_ID_test_usages(), and library_ID_is_used().

◆ BKE_library_ID_is_indirectly_used()

bool BKE_library_ID_is_indirectly_used ( struct Main bmain,
void idv 
)

◆ BKE_library_ID_is_locally_used()

bool BKE_library_ID_is_locally_used ( struct Main bmain,
void idv 
)

Check whether given ID is used locally (i.e. by another non-linked ID).

Definition at line 610 of file lib_query.c.

References library_ID_is_used().

◆ BKE_library_ID_test_usages()

void BKE_library_ID_test_usages ( struct Main bmain,
void idv,
bool is_used_local,
bool is_used_linked 
)

◆ BKE_library_ID_use_ID()

int BKE_library_ID_use_ID ( struct ID id_user,
struct ID id_used 
)

Return the number of times given id_user uses/references id_used.

Note
This only checks for pointer references of an ID, shallow usages (like e.g. by RNA paths, as done for FCurves) are not detected at all.
Parameters
id_userthe ID which is supposed to use (reference) id_used.
id_usedthe ID which is supposed to be used (referenced) by id_user.
Returns
the number of direct usages/references of id_used by id_user.

Definition at line 562 of file lib_query.c.

References BKE_library_foreach_ID_link(), IDUsersIter::count_direct, IDUsersIter::count_indirect, IDUsersIter::curr_id, foreach_libblock_id_users_callback(), IDUsersIter::id, IDWALK_READONLY, and NULL.

◆ BKE_library_indirectly_used_data_tag_clear()

void BKE_library_indirectly_used_data_tag_clear ( struct Main bmain)

Untag linked data blocks used by other untagged linked data-blocks. Used to detect data-blocks that we can forcefully make local (instead of copying them to later get rid of original): All data-blocks we want to make local are tagged by caller, after this function has ran caller knows data-blocks still tagged can directly be made local, since they are only used by other data-blocks that will also be made fully local.

Definition at line 903 of file lib_query.c.

References BKE_library_foreach_ID_link(), foreach_libblock_used_linked_data_tag_clear_cb(), id, ID_IS_LINKED, IDWALK_READONLY, INDEX_ID_MAX, LIB_TAG_DOIT, LISTBASE_FOREACH, set_listbasepointers(), and ID::tag.

◆ BKE_library_unused_linked_data_set_tag()

void BKE_library_unused_linked_data_set_tag ( struct Main bmain,
bool  do_init_tag 
)

Detect orphaned linked data blocks (i.e. linked data not used (directly or indirectly) in any way by any local data), including complex cases like 'linked archipelagoes', i.e. linked data-blocks that use each other in loops, which prevents their deletion by 'basic' usage checks.

Parameters
do_init_tagif true, all linked data are checked, if false, only linked data-blocks already tagged with LIB_TAG_DOIT are checked.

Definition at line 874 of file lib_query.c.

References BKE_library_foreach_ID_link(), foreach_libblock_used_linked_data_tag_clear_cb(), FOREACH_MAIN_ID_BEGIN, FOREACH_MAIN_ID_END, id, IDWALK_READONLY, ID::lib, LIB_TAG_DOIT, LIB_TAG_INDIRECT, and ID::tag.

◆ BKE_library_update_ID_link_user()

void BKE_library_update_ID_link_user ( struct ID id_dst,
struct ID id_src,
int  cb_flag 
)

Re-usable function, use when replacing ID's.

Definition at line 356 of file lib_query.c.

References id_us_ensure_real(), id_us_min(), id_us_plus(), IDWALK_CB_USER, and IDWALK_CB_USER_ONE.