2023-08-15 16:20:26 +02:00
|
|
|
/* SPDX-FileCopyrightText: 2014 Blender Authors
|
2023-05-31 16:19:06 +02:00
|
|
|
*
|
|
|
|
* SPDX-License-Identifier: GPL-2.0-or-later */
|
2020-02-10 16:54:24 +01:00
|
|
|
#pragma once
|
2014-03-26 11:55:20 +01:00
|
|
|
|
2019-02-17 22:08:12 +01:00
|
|
|
/** \file
|
|
|
|
* \ingroup bke
|
2020-02-10 15:05:54 +01:00
|
|
|
*
|
|
|
|
* 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.).
|
|
|
|
*
|
|
|
|
* \section Function Names
|
|
|
|
*
|
|
|
|
* \warning Descriptions below is ideal goal, current status of naming does not yet fully follow it
|
|
|
|
* (this is WIP).
|
|
|
|
*
|
|
|
|
* - `BKE_lib_query_` should be used for functions in that file.
|
2014-03-26 11:55:20 +01:00
|
|
|
*/
|
|
|
|
|
2024-02-09 15:08:31 +01:00
|
|
|
#include "DNA_ID.h"
|
|
|
|
|
2024-02-21 13:13:02 +01:00
|
|
|
#include "BLI_function_ref.hh"
|
2022-02-11 08:23:52 +01:00
|
|
|
#include "BLI_sys_types.h"
|
|
|
|
|
2024-02-09 15:08:31 +01:00
|
|
|
#include <array>
|
|
|
|
|
2024-02-15 18:34:17 +01:00
|
|
|
struct IDTypeInfo;
|
2024-01-30 20:53:41 +01:00
|
|
|
struct LibraryForeachIDData;
|
ID-Remap - Step one: core work (cleanup and rework of generic ID datablock handling).
This commit changes a lot of how IDs are handled internally, especially the unlinking/freeing
processes. So far, this was very fuzy, to summarize cleanly deleting or replacing a datablock
was pretty much impossible, except for a few special cases.
Also, unlinking was handled by each datatype, in a rather messy and prone-to-errors way (quite
a few ID usages were missed or wrongly handled that way).
One of the main goal of id-remap branch was to cleanup this, and fatorize ID links handling
by using library_query utils to allow generic handling of those, which is now the case
(now, generic ID links handling is only "knwon" from readfile.c and library_query.c).
This commit also adds backends to allow live replacement and deletion of datablocks in Blender
(so-called 'remapping' process, where we replace all usages of a given ID pointer by a new one,
or NULL one in case of unlinking).
This will allow nice new features, like ability to easily reload or relocate libraries, real immediate
deletion of datablocks in blender, replacement of one datablock by another, etc.
Some of those are for next commits.
A word of warning: this commit is highly risky, because it affects potentially a lot in Blender core.
Though it was tested rather deeply, being totally impossible to check all possible ID usage cases,
it's likely there are some remaining issues and bugs in new code... Please report them! ;)
Review task: D2027 (https://developer.blender.org/D2027).
Reviewed by campbellbarton, thanks a bunch.
2016-06-22 17:29:38 +02:00
|
|
|
struct Main;
|
2014-03-26 11:55:20 +01:00
|
|
|
|
|
|
|
/* Tips for the callback for cases it's gonna to modify the pointer. */
|
|
|
|
enum {
|
2017-01-31 09:47:59 +01:00
|
|
|
IDWALK_CB_NOP = 0,
|
|
|
|
IDWALK_CB_NEVER_NULL = (1 << 0),
|
|
|
|
IDWALK_CB_NEVER_SELF = (1 << 1),
|
2019-04-17 06:17:24 +02:00
|
|
|
|
2016-07-08 19:33:22 +02:00
|
|
|
/**
|
|
|
|
* Indicates whether this is direct (i.e. by local data) or indirect (i.e. by linked data) usage.
|
|
|
|
*/
|
2017-01-31 09:47:59 +01:00
|
|
|
IDWALK_CB_INDIRECT_USAGE = (1 << 2),
|
2022-11-30 11:13:37 +01:00
|
|
|
/**
|
|
|
|
* Indicates that this is a direct weak link usage, i.e. if the user is a local ID, and is using
|
|
|
|
* (pointing to) a linked ID, that usage does not make the linked ID directly linked.
|
|
|
|
*
|
|
|
|
* E.g. usages of linked collections or objects by ViewLayerCollections or Bases in scenes.
|
|
|
|
*
|
|
|
|
* See also #LIB_INDIRECT_WEAK_LINK in DNA_ID.h
|
|
|
|
*/
|
|
|
|
IDWALK_CB_DIRECT_WEAK_LINK = (1 << 3),
|
2019-04-17 06:17:24 +02:00
|
|
|
|
2019-04-27 04:07:07 +02:00
|
|
|
/**
|
2023-07-07 07:11:19 +02:00
|
|
|
* That ID is used as mere sub-data by its owner (only case currently: those root node-trees in
|
2020-03-11 12:47:25 +01:00
|
|
|
* 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.
|
2019-04-27 04:07:07 +02:00
|
|
|
*/
|
2022-11-30 11:13:37 +01:00
|
|
|
IDWALK_CB_EMBEDDED = (1 << 4),
|
2023-04-14 13:25:06 +02:00
|
|
|
/**
|
|
|
|
* That ID pointer points to an embedded ID, but does not own it.
|
|
|
|
*
|
|
|
|
* E.g the `collection` pointer of the first ViewLayerCollection of a ViewLayer should always
|
|
|
|
* point to the scene's master collection, which is an embedded ID 'owned' by
|
|
|
|
* `Scene.master_collection`.
|
|
|
|
*/
|
|
|
|
IDWALK_CB_EMBEDDED_NOT_OWNING = (1 << 5),
|
2019-04-17 06:17:24 +02:00
|
|
|
|
2020-03-11 12:47:25 +01:00
|
|
|
/**
|
|
|
|
* That ID is not really used by its owner, it's just an internal hint/helper.
|
2022-02-03 17:57:40 +01:00
|
|
|
* This marks the 'from' pointers issue, like Key->from.
|
2017-05-05 16:13:01 +02:00
|
|
|
* How to handle that kind of cases totally depends on what caller code is doing... */
|
2023-04-14 13:25:06 +02:00
|
|
|
IDWALK_CB_LOOPBACK = (1 << 6),
|
2019-04-17 06:17:24 +02:00
|
|
|
|
2021-03-12 09:39:23 +01:00
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*/
|
2023-04-14 13:25:06 +02:00
|
|
|
IDWALK_CB_INTERNAL = (1 << 9),
|
2021-03-12 09:39:23 +01:00
|
|
|
|
2023-08-22 19:01:04 +02:00
|
|
|
/**
|
2023-08-23 05:30:55 +02:00
|
|
|
* This ID usage should not be processed during readfile (neither during lib-linking nor
|
2023-08-22 19:01:04 +02:00
|
|
|
* expanding).
|
|
|
|
*
|
|
|
|
* Note that all embedded IDs pointers (#IDWALK_CB_EMBEDDED and #IDWALK_CB_EMBEDDED_NOT_OWNING)
|
|
|
|
* cases are also ignored during readfile.
|
|
|
|
*
|
|
|
|
* Mainly used for some 'loopback' pointers like the 'owner_id' of the embedded IDs.
|
|
|
|
*/
|
|
|
|
IDWALK_CB_READFILE_IGNORE = (1 << 10),
|
|
|
|
|
2015-10-08 11:09:30 +02:00
|
|
|
/**
|
2020-04-22 15:58:55 +02:00
|
|
|
* This ID usage is fully refcounted.
|
|
|
|
* Callback is responsible to deal accordingly with #ID.us if needed.
|
2015-10-08 11:09:30 +02:00
|
|
|
*/
|
2023-08-22 19:01:04 +02:00
|
|
|
IDWALK_CB_USER = (1 << 11),
|
2020-04-22 15:58:55 +02:00
|
|
|
/**
|
|
|
|
* This ID usage is not refcounted, but at least one user should be generated by it (to avoid
|
2021-02-06 04:07:03 +01:00
|
|
|
* e.g. losing the used ID on save/reload).
|
2020-04-22 15:58:55 +02:00
|
|
|
* Callback is responsible to deal accordingly with #ID.us if needed.
|
|
|
|
*/
|
2023-08-22 19:01:04 +02:00
|
|
|
IDWALK_CB_USER_ONE = (1 << 12),
|
LibOverride: Modify automatic handling of which IDs to override in a hierarchy.
The previous behavior, fairly rough, was simply considering all
Collections and IDs found as part of the root's hierarchy as to be
overridden.
The new behavior is based on a specific tag added to some ID usages.
Currently, these are only the links from a Collection to its Objects
and children Collections, and the link from an Object to its parent.
The goal of this huge reduction of the 'automatically overridden' set of
data in a hierarchy is to avoid creating liboverrides for 'utils' data,
e.g. a collection used as source of data by a GeometryNode generating
some parametric geometry (Blender Studio use-case: some form of LOD
handling).
In general, it means that only Collections and objects part of the
collection hierarchy of the root collection are now overridden.
This should not change in the typical recommended use-case so far (where
there is a clear root collection to the whole overridden hierarchy, and
it contains all related collections and objects).
But this should allow much less overhead (and viewport pollution, due to
the current principle that local (and therefore liboverridden) objects
have to be instanciated in a Scene) for more complex setups.
Note that the initial idea/change is fairly simple and easy to
implement, but it creates some additional complexity in the partial
resync code, since now some linked data may not be detected as needing
a liboverride anymore when processing a sub-hierarchy, while it would
require it when processing the whole hierarchy.
This required adding some more processing to the util functions which
define which ID should be overridden. It essentially creates a
'reference set' of all reference IDs that should be overridden when
the whole hierarchy is considered, and use this as additional input to
decide which ID to override when processing a sub-hierarchy for the
partial resync.
Pull Request: https://projects.blender.org/blender/blender/pulls/115853
2023-12-06 16:49:51 +01:00
|
|
|
|
|
|
|
/** This ID is used as library override's reference by its owner. */
|
|
|
|
IDWALK_CB_OVERRIDE_LIBRARY_REFERENCE = (1 << 16),
|
|
|
|
|
|
|
|
/** This ID pointer is not overridable. */
|
|
|
|
IDWALK_CB_OVERRIDE_LIBRARY_NOT_OVERRIDABLE = (1 << 17),
|
|
|
|
|
|
|
|
/** This ID pointer is expected to be overridden by default, in liboverride hierarchy context. */
|
|
|
|
IDWALK_CB_OVERRIDE_LIBRARY_HIERARCHY_DEFAULT = (1 << 18),
|
|
|
|
|
2014-03-26 11:55:20 +01:00
|
|
|
};
|
|
|
|
|
2016-03-24 12:28:41 +01:00
|
|
|
enum {
|
|
|
|
IDWALK_RET_NOP = 0,
|
2019-07-02 14:17:22 +02:00
|
|
|
/** Completely stop iteration. */
|
|
|
|
IDWALK_RET_STOP_ITER = 1 << 0,
|
|
|
|
/** Stop recursion, that is, do not loop over ID used by current one. */
|
|
|
|
IDWALK_RET_STOP_RECURSION = 1 << 1,
|
2016-03-24 12:28:41 +01:00
|
|
|
};
|
|
|
|
|
2024-01-18 12:20:42 +01:00
|
|
|
struct LibraryIDLinkCallbackData {
|
2020-02-13 12:56:10 +01:00
|
|
|
void *user_data;
|
2020-05-25 15:26:58 +02:00
|
|
|
/** Main database used to call `BKE_library_foreach_ID_link()`. */
|
2024-01-18 12:20:42 +01:00
|
|
|
Main *bmain;
|
2020-03-11 12:37:25 +01:00
|
|
|
/**
|
|
|
|
* 'Real' ID, the one that might be in bmain, only differs from self_id when the later is an
|
2020-03-11 17:29:20 +01:00
|
|
|
* embedded one.
|
2020-03-11 12:37:25 +01:00
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
ID *owner_id;
|
2020-03-11 12:37:25 +01:00
|
|
|
/**
|
2020-03-11 17:29:20 +01:00
|
|
|
* ID from which the current ID pointer is being processed. It may be an embedded ID like master
|
2020-03-11 12:37:25 +01:00
|
|
|
* collection or root node tree.
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
ID *self_id;
|
|
|
|
ID **id_pointer;
|
2020-02-13 12:56:10 +01:00
|
|
|
int cb_flag;
|
2024-01-18 12:20:42 +01:00
|
|
|
};
|
2020-02-13 12:56:10 +01:00
|
|
|
|
2016-03-24 12:28:41 +01:00
|
|
|
/**
|
|
|
|
* Call a callback for each ID link which the given ID uses.
|
2014-03-26 11:55:20 +01:00
|
|
|
*
|
2016-04-01 01:02:59 +02:00
|
|
|
* \return a set of flags to control further iteration (0 to keep going).
|
2014-03-26 11:55:20 +01:00
|
|
|
*/
|
2024-02-13 21:34:32 +01:00
|
|
|
using LibraryIDLinkCallback = int (*)(LibraryIDLinkCallbackData *cb_data);
|
2014-03-26 11:55:20 +01:00
|
|
|
|
|
|
|
/* Flags for the foreach function itself. */
|
|
|
|
enum {
|
2017-01-31 09:47:59 +01:00
|
|
|
IDWALK_NOP = 0,
|
2023-05-27 07:10:58 +02:00
|
|
|
/**
|
|
|
|
* The callback will never modify the ID pointers it processes.
|
2023-04-14 13:25:06 +02:00
|
|
|
* WARNING: It is very important to pass this flag when valid, as it can lead to important
|
2023-05-27 07:10:58 +02:00
|
|
|
* optimizations and debug/assert code.
|
|
|
|
*/
|
2014-03-26 11:55:20 +01:00
|
|
|
IDWALK_READONLY = (1 << 0),
|
2023-05-27 07:10:58 +02:00
|
|
|
/**
|
|
|
|
* Recurse into 'descendant' IDs.
|
2022-03-16 13:14:32 +01:00
|
|
|
* 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_RECURSE = (1 << 1),
|
|
|
|
/** Include UI pointers (from WM and screens editors). */
|
|
|
|
IDWALK_INCLUDE_UI = (1 << 2),
|
2020-03-11 17:25:31 +01:00
|
|
|
/** Do not process ID pointers inside embedded IDs. Needed by depsgraph processing e.g. */
|
|
|
|
IDWALK_IGNORE_EMBEDDED_ID = (1 << 3),
|
2023-08-22 15:42:19 +02:00
|
|
|
|
2023-04-24 15:30:04 +02:00
|
|
|
/**
|
|
|
|
* Do not access original processed pointer's data, only process its address value.
|
|
|
|
*
|
|
|
|
* This is required in cases where to current address may not be valid anymore (e.g. during
|
|
|
|
* readfile process). A few ID pointers (like e.g. the `LayerCollection.collection` one) are by
|
|
|
|
* default accessed to check things (e.g. whether they are pointing to an embedded ID or a
|
|
|
|
* regular one).
|
|
|
|
*
|
|
|
|
* \note Access to owning embedded ID pointers (e.g. `Scene.master_collection`) is not affected
|
|
|
|
* here, these are presumed always valid.
|
|
|
|
*
|
2023-08-23 11:39:47 +02:00
|
|
|
* \note This flag is mutually exclusive with `IDWALK_RECURSE`, since by definition accessing the
|
|
|
|
* current ID pointer is required for recursion.
|
2023-04-24 15:30:04 +02:00
|
|
|
*
|
|
|
|
* \note After remapping, code may access the newly set ID pointer, which is always presumed
|
|
|
|
* valid.
|
|
|
|
*
|
|
|
|
* \warning Use only with great caution, this flag will modify the handling of some ID pointers
|
|
|
|
* (especially when it comes to detecting `IDWALK_CB_EMBEDDED_NOT_OWNING` usages).
|
|
|
|
*/
|
|
|
|
IDWALK_NO_ORIG_POINTERS_ACCESS = (1 << 5),
|
2017-06-26 18:55:30 +02:00
|
|
|
|
2023-03-09 00:39:49 +01:00
|
|
|
/**
|
|
|
|
* Also process internal ID pointers like `ID.newid` or `ID.orig_id`.
|
|
|
|
* WARNING: Dangerous, use with caution.
|
|
|
|
*/
|
2021-03-12 09:39:23 +01:00
|
|
|
IDWALK_DO_INTERNAL_RUNTIME_POINTERS = (1 << 9),
|
2023-03-09 00:39:49 +01:00
|
|
|
/**
|
|
|
|
* Also process the ID.lib pointer. It is an option because this pointer can usually be fully
|
|
|
|
* ignored.
|
|
|
|
*/
|
2023-02-06 17:31:01 +01:00
|
|
|
IDWALK_DO_LIBRARY_POINTER = (1 << 10),
|
2023-08-22 15:42:19 +02:00
|
|
|
/** Also process the DNA-deprecated pointers. Should only be used in readfile related code (for
|
|
|
|
* proper lib_linking and expanding of older files). */
|
|
|
|
IDWALK_DO_DEPRECATED_POINTERS = (1 << 11),
|
2014-03-26 11:55:20 +01:00
|
|
|
};
|
|
|
|
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* Check whether current iteration over ID usages should be stopped or not.
|
|
|
|
* \return true if the iteration should be stopped, false otherwise.
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
bool BKE_lib_query_foreachid_iter_stop(const LibraryForeachIDData *data);
|
|
|
|
void BKE_lib_query_foreachid_process(LibraryForeachIDData *data, ID **id_pp, int cb_flag);
|
|
|
|
int BKE_lib_query_foreachid_process_flags_get(const LibraryForeachIDData *data);
|
|
|
|
int BKE_lib_query_foreachid_process_callback_flag_override(LibraryForeachIDData *data,
|
2022-01-07 01:38:08 +01:00
|
|
|
int cb_flag,
|
|
|
|
bool do_replace);
|
2020-05-07 12:36:35 +02:00
|
|
|
|
2023-08-22 15:42:19 +02:00
|
|
|
/** Should typically only be used when processing deprecated ID types (like IPO ones). */
|
|
|
|
#define BKE_LIB_FOREACHID_PROCESS_ID_NOCHECK(data_, id_, cb_flag_) \
|
2020-05-07 12:36:35 +02:00
|
|
|
{ \
|
2023-06-21 15:03:57 +02:00
|
|
|
BKE_lib_query_foreachid_process((data_), (ID **)&(id_), (cb_flag_)); \
|
|
|
|
if (BKE_lib_query_foreachid_iter_stop((data_))) { \
|
2020-05-07 12:36:35 +02:00
|
|
|
return; \
|
|
|
|
} \
|
|
|
|
} \
|
|
|
|
((void)0)
|
|
|
|
|
2023-08-22 15:42:19 +02:00
|
|
|
#define BKE_LIB_FOREACHID_PROCESS_ID(data_, id_, cb_flag_) \
|
|
|
|
{ \
|
|
|
|
CHECK_TYPE_ANY((id_), ID *, void *); \
|
|
|
|
BKE_LIB_FOREACHID_PROCESS_ID_NOCHECK(data_, id_, cb_flag_); \
|
|
|
|
} \
|
|
|
|
((void)0)
|
|
|
|
|
2023-06-21 15:03:57 +02:00
|
|
|
#define BKE_LIB_FOREACHID_PROCESS_IDSUPER_P(data_, id_super_p_, cb_flag_) \
|
2020-05-07 12:36:35 +02:00
|
|
|
{ \
|
2023-06-21 15:03:57 +02:00
|
|
|
CHECK_TYPE(&((*(id_super_p_))->id), ID *); \
|
|
|
|
BKE_lib_query_foreachid_process((data_), (ID **)(id_super_p_), (cb_flag_)); \
|
|
|
|
if (BKE_lib_query_foreachid_iter_stop((data_))) { \
|
2020-05-07 12:36:35 +02:00
|
|
|
return; \
|
|
|
|
} \
|
|
|
|
} \
|
|
|
|
((void)0)
|
|
|
|
|
2023-06-21 15:03:57 +02:00
|
|
|
#define BKE_LIB_FOREACHID_PROCESS_IDSUPER(data_, id_super_, cb_flag_) \
|
2021-10-27 11:30:43 +02:00
|
|
|
{ \
|
2023-06-21 15:03:57 +02:00
|
|
|
BKE_LIB_FOREACHID_PROCESS_IDSUPER_P(data_, &(id_super_), cb_flag_); \
|
|
|
|
} \
|
|
|
|
((void)0)
|
|
|
|
|
|
|
|
#define BKE_LIB_FOREACHID_PROCESS_FUNCTION_CALL(data_, func_call_) \
|
|
|
|
{ \
|
|
|
|
func_call_; \
|
|
|
|
if (BKE_lib_query_foreachid_iter_stop((data_))) { \
|
2021-10-27 11:30:43 +02:00
|
|
|
return; \
|
|
|
|
} \
|
|
|
|
} \
|
|
|
|
((void)0)
|
|
|
|
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
void BKE_library_foreach_ID_embedded(LibraryForeachIDData *data, ID **id_pp);
|
|
|
|
void BKE_lib_query_idpropertiesForeachIDLink_callback(IDProperty *id_prop, void *user_data);
|
2020-05-07 12:36:35 +02:00
|
|
|
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* Loop over all of the ID's this data-block links to.
|
|
|
|
*/
|
2017-01-30 21:41:44 +01:00
|
|
|
void BKE_library_foreach_ID_link(
|
2024-01-18 12:20:42 +01:00
|
|
|
Main *bmain, ID *id, LibraryIDLinkCallback callback, void *user_data, int flag);
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* Re-usable function, use when replacing ID's.
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
void BKE_library_update_ID_link_user(ID *id_dst, ID *id_src, int cb_flag);
|
2014-03-26 11:55:20 +01:00
|
|
|
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* Return the number of times given \a id_user uses/references \a 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.
|
|
|
|
*
|
|
|
|
* \param id_user: the ID which is supposed to use (reference) \a id_used.
|
|
|
|
* \param id_used: the ID which is supposed to be used (referenced) by \a id_user.
|
|
|
|
* \return the number of direct usages/references of \a id_used by \a id_user.
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
int BKE_library_ID_use_ID(ID *id_user, ID *id_used);
|
2016-01-06 19:34:42 +01:00
|
|
|
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
2023-05-16 18:14:43 +02:00
|
|
|
* Say whether given \a owner_id may use (in any way) a data-block of \a id_type_used.
|
2021-12-07 07:19:15 +01:00
|
|
|
*
|
|
|
|
* This is a 'simplified' abstract version of #BKE_library_foreach_ID_link() above,
|
|
|
|
* quite useful to reduce useless iterations in some cases.
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
bool BKE_library_id_can_use_idtype(ID *owner_id, short id_type_used);
|
2016-07-07 20:51:21 +02:00
|
|
|
|
2022-02-11 08:23:52 +01:00
|
|
|
/**
|
2023-05-16 18:14:43 +02:00
|
|
|
* Given the owner_id return the type of id_types it can use as a filter_id.
|
2022-02-11 08:23:52 +01:00
|
|
|
*/
|
2024-02-15 18:34:17 +01:00
|
|
|
uint64_t BKE_library_id_can_use_filter_id(const ID *owner_id,
|
|
|
|
const bool include_ui,
|
|
|
|
const IDTypeInfo *owner_id_type = nullptr);
|
2022-02-11 08:23:52 +01:00
|
|
|
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* Check whether given ID is used locally (i.e. by another non-linked ID).
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
bool BKE_library_ID_is_locally_used(Main *bmain, void *idv);
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* Check whether given ID is used indirectly (i.e. by another linked ID).
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
bool BKE_library_ID_is_indirectly_used(Main *bmain, void *idv);
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* Combine #BKE_library_ID_is_locally_used() and #BKE_library_ID_is_indirectly_used()
|
|
|
|
* in a single call.
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
void BKE_library_ID_test_usages(Main *bmain,
|
2016-07-07 19:39:14 +02:00
|
|
|
void *idv,
|
2023-11-30 00:42:18 +01:00
|
|
|
bool *r_is_used_local,
|
|
|
|
bool *r_is_used_linked);
|
"Fix" crash when deleting linked object which has indirect usages.
This is in fact very hairy situation here... Objects are only refcounted by scenes,
any other usage is 'free', which means once all object instanciations are gone Blender
considers it can delete it.
There is a trap here though: indirect usages. Typically, we should never modify linked data
(because it is essencially useless, changes would be ignored and ost on next reload or
even undo/redo). This means indirect usages are not affected by default 'safe' remapping/unlinking.
For unlinking preceeding deletion however, this is not acceptable - we are likely to end with
a zero-user ID (aka deletable one) which is still actually used by other linked data.
Solution choosen here is double:
I) From 'user-space' (i.e. outliner, operators...), we check for cases where deleting datablocks
should not be allowed (indirect data or indirectly used data), and abort (with report) if needed.
II) From 'lower' level (BKE_library_remap and RNA), we also unlink from linked data,
which makes actual deletion possible and safe.
Note that with previous behavior (2.77 one), linked object would be deleted, including from linked data -
but then, once file is saved and reloaded, indirect usage would link back the deleted object,
without any instanciation in scene, which made it somehow virtual and unreachable...
With new behavior, this is no more possible, but on the other hand it means that in situations of dependency cycles
(two linked objects using each other), linked objects become impossible to delete (from user space).
Not sure what's best here, behavior with those corner cases of library linking is very poorly defined... :(
2016-07-01 17:51:08 +02:00
|
|
|
|
2024-02-09 15:08:31 +01:00
|
|
|
/** Parameters and result data structure for the 'unused IDs' functions below. */
|
|
|
|
struct LibQueryUnusedIDsData {
|
|
|
|
/** Process local data-blocks. */
|
2024-02-21 13:13:02 +01:00
|
|
|
bool do_local_ids = false;
|
2024-02-09 15:08:31 +01:00
|
|
|
/** Process linked data-blocks. */
|
2024-02-21 13:13:02 +01:00
|
|
|
bool do_linked_ids = false;
|
2024-02-09 15:08:31 +01:00
|
|
|
/**
|
|
|
|
* Process all actually unused data-blocks, including these that are currently only used by
|
|
|
|
* other unused data-blocks, and 'dependency islands' of several data-blocks using each-other,
|
|
|
|
* without any external valid user.
|
|
|
|
*/
|
2024-02-21 13:13:02 +01:00
|
|
|
bool do_recursive = false;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Callback filter, if defined and it returns `true`, the given `id` may be considered as unused,
|
|
|
|
* otherwise it will always be considered as used.
|
|
|
|
*
|
|
|
|
* Allows for more complex handling of which IDs should be deleted, on top of the basic
|
|
|
|
* local/linked choices.
|
|
|
|
*/
|
|
|
|
blender::FunctionRef<bool(ID *id)> filter_fn = nullptr;
|
2024-02-09 15:08:31 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Amount of detected as unused data-blocks, per type and total as the last value of the array
|
|
|
|
* (#INDEX_ID_NULL).
|
|
|
|
*
|
|
|
|
* \note: Return value, set by the executed function.
|
|
|
|
*/
|
|
|
|
std::array<int, INDEX_ID_MAX> num_total;
|
|
|
|
/**
|
|
|
|
* Amount of detected as unused local data-blocks, per type and total as the last value of the
|
|
|
|
* array (#INDEX_ID_NULL).
|
|
|
|
*
|
|
|
|
* \note: Return value, set by the executed function.
|
|
|
|
*/
|
|
|
|
std::array<int, INDEX_ID_MAX> num_local;
|
|
|
|
/**
|
|
|
|
* Amount of detected as unused linked data-blocks, per type and total as the last value of the
|
|
|
|
* array (#INDEX_ID_NULL).
|
|
|
|
*
|
|
|
|
* \note: Return value, set by the executed function.
|
|
|
|
*/
|
|
|
|
std::array<int, INDEX_ID_MAX> num_linked;
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Compute amount of unused IDs (a.k.a 'orphaned').
|
|
|
|
*
|
|
|
|
* By default only consider IDs with `0` user count.
|
|
|
|
* If `do_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.
|
|
|
|
*
|
|
|
|
* \param r_num_total: A zero-initialized array of #INDEX_ID_MAX integers. Number of IDs detected
|
|
|
|
* as unused from given parameters, per ID type in the matching index, and as total in
|
|
|
|
* #INDEX_ID_NULL item.
|
|
|
|
* \param r_num_local: A zero-initialized array of #INDEX_ID_MAX integers. Number of local IDs
|
|
|
|
* detected as unused from given parameters (but assuming \a do_local_ids is true), per ID type in
|
|
|
|
* the matching index, and as total in #INDEX_ID_NULL item.
|
|
|
|
* \param r_num_linked: A zero-initialized array of #INDEX_ID_MAX integers. Number of linked IDs
|
|
|
|
* detected as unused from given parameters (but assuming \a do_linked_ids is true), per ID type in
|
|
|
|
* the matching index, and as total in #INDEX_ID_NULL item.
|
|
|
|
*/
|
|
|
|
void BKE_lib_query_unused_ids_amounts(Main *bmain, LibQueryUnusedIDsData ¶meters);
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* Tag all unused IDs (a.k.a 'orphaned').
|
|
|
|
*
|
|
|
|
* By default only tag IDs with `0` user count.
|
2024-02-09 15:08:31 +01:00
|
|
|
* If `do_recursive` is set, it will check dependencies to detect all IDs that are not actually
|
2021-12-07 07:19:15 +01:00
|
|
|
* 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.
|
|
|
|
*
|
2024-02-09 15:08:31 +01:00
|
|
|
* \param tag: the ID tag to use to mark the ID as unused. Should never be `0`.
|
|
|
|
* \param r_num_tagged_total: A zero-initialized array of #INDEX_ID_MAX integers. Number of IDs
|
|
|
|
* tagged as unused from given parameters, per ID type in the matching index, and as total in
|
2021-12-07 07:19:15 +01:00
|
|
|
* #INDEX_ID_NULL item.
|
|
|
|
*/
|
2024-02-09 15:08:31 +01:00
|
|
|
void BKE_lib_query_unused_ids_tag(Main *bmain, int tag, LibQueryUnusedIDsData ¶meters);
|
2021-02-25 12:37:31 +01:00
|
|
|
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*
|
|
|
|
* \param do_init_tag: if \a true, all linked data are checked, if \a false,
|
|
|
|
* only linked data-blocks already tagged with #LIB_TAG_DOIT are checked.
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
void BKE_library_unused_linked_data_set_tag(Main *bmain, bool do_init_tag);
|
2021-12-07 07:19:15 +01:00
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*/
|
2024-01-18 12:20:42 +01:00
|
|
|
void BKE_library_indirectly_used_data_tag_clear(Main *bmain);
|