1 /* 2 * This program is free software; you can redistribute it and/or 3 * modify it under the terms of the GNU General Public License 4 * as published by the Free Software Foundation; either version 2 5 * of the License, or (at your option) any later version. 6 * 7 * This program is distributed in the hope that it will be useful, 8 * but WITHOUT ANY WARRANTY; without even the implied warranty of 9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 10 * GNU General Public License for more details. 11 * 12 * You should have received a copy of the GNU General Public License 13 * along with this program; if not, write to the Free Software Foundation, 14 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 15 * 16 * The Original Code is Copyright (C) 2014 by Blender Foundation. 17 * All rights reserved. 18 */ 19 #pragma once 20 21 /** \file 22 * \ingroup bke 23 * 24 * API to perform operations over all ID pointers used by a given data-block. 25 * 26 * \note `BKE_lib_` files are for operations over data-blocks themselves, although they might 27 * alter Main as well (when creating/renaming/deleting an ID e.g.). 28 * 29 * \section Function Names 30 * 31 * \warning Descriptions below is ideal goal, current status of naming does not yet fully follow it 32 * (this is WIP). 33 * 34 * - `BKE_lib_query_` should be used for functions in that file. 35 */ 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 struct ID; 42 struct IDProperty; 43 struct Main; 44 45 /* Tips for the callback for cases it's gonna to modify the pointer. */ 46 enum { 47 IDWALK_CB_NOP = 0, 48 IDWALK_CB_NEVER_NULL = (1 << 0), 49 IDWALK_CB_NEVER_SELF = (1 << 1), 50 51 /** 52 * Indicates whether this is direct (i.e. by local data) or indirect (i.e. by linked data) usage. 53 * \note Object proxies are half-local, half-linked... 54 */ 55 IDWALK_CB_INDIRECT_USAGE = (1 << 2), 56 57 /** 58 * That ID is used as mere sub-data by its owner (only case currently: those root nodetrees in 59 * materials etc., and the Scene's master collections). 60 * This means callback shall not *do* anything, only use this as informative data if it needs it. 61 */ 62 IDWALK_CB_EMBEDDED = (1 << 3), 63 64 /** 65 * That ID is not really used by its owner, it's just an internal hint/helper. 66 * This addresses Their Highest Ugliness the 'from' pointers: Object->from_proxy and Key->from. 67 * How to handle that kind of cases totally depends on what caller code is doing... */ 68 IDWALK_CB_LOOPBACK = (1 << 4), 69 70 /** That ID is used as library override's reference by its owner. */ 71 IDWALK_CB_OVERRIDE_LIBRARY_REFERENCE = (1 << 5), 72 73 /** 74 * This ID usage is fully refcounted. 75 * Callback is responsible to deal accordingly with #ID.us if needed. 76 */ 77 IDWALK_CB_USER = (1 << 8), 78 /** 79 * This ID usage is not refcounted, but at least one user should be generated by it (to avoid 80 * e.g. loosing the used ID on save/reload). 81 * Callback is responsible to deal accordingly with #ID.us if needed. 82 */ 83 IDWALK_CB_USER_ONE = (1 << 9), 84 }; 85 86 enum { 87 IDWALK_RET_NOP = 0, 88 /** Completely stop iteration. */ 89 IDWALK_RET_STOP_ITER = 1 << 0, 90 /** Stop recursion, that is, do not loop over ID used by current one. */ 91 IDWALK_RET_STOP_RECURSION = 1 << 1, 92 }; 93 94 typedef struct LibraryIDLinkCallbackData { 95 void *user_data; 96 /** Main database used to call `BKE_library_foreach_ID_link()`. */ 97 struct Main *bmain; 98 /** 99 * 'Real' ID, the one that might be in bmain, only differs from self_id when the later is an 100 * embedded one. 101 */ 102 struct ID *id_owner; 103 /** 104 * ID from which the current ID pointer is being processed. It may be an embedded ID like master 105 * collection or root node tree. 106 */ 107 struct ID *id_self; 108 struct ID **id_pointer; 109 int cb_flag; 110 } LibraryIDLinkCallbackData; 111 112 /** 113 * Call a callback for each ID link which the given ID uses. 114 * 115 * \return a set of flags to control further iteration (0 to keep going). 116 */ 117 typedef int (*LibraryIDLinkCallback)(LibraryIDLinkCallbackData *cb_data); 118 119 /* Flags for the foreach function itself. */ 120 enum { 121 IDWALK_NOP = 0, 122 IDWALK_READONLY = (1 << 0), 123 IDWALK_RECURSE = (1 << 1), /* Also implies IDWALK_READONLY. */ 124 IDWALK_INCLUDE_UI = (1 << 2), /* Include UI pointers (from WM and screens editors). */ 125 /** Do not process ID pointers inside embedded IDs. Needed by depsgraph processing e.g. */ 126 IDWALK_IGNORE_EMBEDDED_ID = (1 << 3), 127 128 IDWALK_NO_INDIRECT_PROXY_DATA_USAGE = (1 << 8), /* Ugly special case :(((( */ 129 }; 130 131 typedef struct LibraryForeachIDData LibraryForeachIDData; 132 133 bool BKE_lib_query_foreachid_process(struct LibraryForeachIDData *data, 134 struct ID **id_pp, 135 int cb_flag); 136 int BKE_lib_query_foreachid_process_flags_get(struct LibraryForeachIDData *data); 137 int BKE_lib_query_foreachid_process_callback_flag_override(struct LibraryForeachIDData *data, 138 const int cb_flag, 139 const bool do_replace); 140 141 #define BKE_LIB_FOREACHID_PROCESS_ID(_data, _id, _cb_flag) \ 142 { \ 143 CHECK_TYPE_ANY((_id), ID *, void *); \ 144 if (!BKE_lib_query_foreachid_process((_data), (ID **)&(_id), (_cb_flag))) { \ 145 return; \ 146 } \ 147 } \ 148 ((void)0) 149 150 #define BKE_LIB_FOREACHID_PROCESS(_data, _id_super, _cb_flag) \ 151 { \ 152 CHECK_TYPE(&((_id_super)->id), ID *); \ 153 if (!BKE_lib_query_foreachid_process((_data), (ID **)&(_id_super), (_cb_flag))) { \ 154 return; \ 155 } \ 156 } \ 157 ((void)0) 158 159 bool BKE_library_foreach_ID_embedded(struct LibraryForeachIDData *data, struct ID **id_pp); 160 void BKE_lib_query_idpropertiesForeachIDLink_callback(struct IDProperty *id_prop, void *user_data); 161 162 /* Loop over all of the ID's this datablock links to. */ 163 void BKE_library_foreach_ID_link( 164 struct Main *bmain, struct ID *id, LibraryIDLinkCallback callback, void *user_data, int flag); 165 void BKE_library_update_ID_link_user(struct ID *id_dst, struct ID *id_src, const int cb_flag); 166 167 int BKE_library_ID_use_ID(struct ID *id_user, struct ID *id_used); 168 169 bool BKE_library_id_can_use_idtype(struct ID *id_owner, const short id_type_used); 170 171 bool BKE_library_ID_is_locally_used(struct Main *bmain, void *idv); 172 bool BKE_library_ID_is_indirectly_used(struct Main *bmain, void *idv); 173 void BKE_library_ID_test_usages(struct Main *bmain, 174 void *idv, 175 bool *is_used_local, 176 bool *is_used_linked); 177 178 void BKE_library_unused_linked_data_set_tag(struct Main *bmain, const bool do_init_tag); 179 void BKE_library_indirectly_used_data_tag_clear(struct Main *bmain); 180 181 #ifdef __cplusplus 182 } 183 #endif 184