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) 2001-2002 by NaN Holding BV. 17 * All rights reserved. 18 */ 19 #pragma once 20 21 /** \file 22 * \ingroup bke 23 * 24 * API to manage data-blocks inside of Blender's Main data-base, or as independent runtime-only 25 * data. 26 * 27 * \note `BKE_lib_` files are for operations over data-blocks themselves, although they might 28 * alter Main as well (when creating/renaming/deleting an ID e.g.). 29 * 30 * \section Function Names 31 * 32 * \warning Descriptions below is ideal goal, current status of naming does not yet fully follow it 33 * (this is WIP). 34 * 35 * - `BKE_lib_id_` should be used for rather high-level operations, that involve Main database and 36 * relations with other IDs, and can be considered as 'safe' (as in, in themselves, they leave 37 * affected IDs/Main in a consistent status). 38 * - `BKE_lib_libblock_` should be used for lower level operations, that perform some parts of 39 * `BKE_lib_id_` ones, but will generally not ensure caller that affected data is in a consistent 40 * state by their own execution alone. 41 * - `BKE_lib_main_` should be used for operations performed over all IDs of a given Main 42 * data-base. 43 * 44 * \note External code should typically not use `BKE_lib_libblock_` functions, except in some 45 * specific cases requiring advanced (and potentially dangerous) handling. 46 */ 47 48 #include "BLI_compiler_attrs.h" 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 struct BlendDataReader; 55 struct BlendWriter; 56 struct GHash; 57 struct ID; 58 struct Library; 59 struct ListBase; 60 struct Main; 61 struct PointerRNA; 62 struct PropertyRNA; 63 struct bContext; 64 65 size_t BKE_libblock_get_alloc_info(short type, const char **name); 66 void *BKE_libblock_alloc_notest(short type) ATTR_WARN_UNUSED_RESULT; 67 void *BKE_libblock_alloc(struct Main *bmain, short type, const char *name, const int flag) 68 ATTR_WARN_UNUSED_RESULT; 69 void BKE_libblock_init_empty(struct ID *id) ATTR_NONNULL(1); 70 71 /* *** ID's session_uuid management. *** */ 72 73 /* When an ID's uuid is of that value, it is unset/invalid (e.g. for runtime IDs, etc.). */ 74 #define MAIN_ID_SESSION_UUID_UNSET 0 75 76 void BKE_lib_libblock_session_uuid_ensure(struct ID *id); 77 void BKE_lib_libblock_session_uuid_renew(struct ID *id); 78 79 void *BKE_id_new(struct Main *bmain, const short type, const char *name); 80 void *BKE_id_new_nomain(const short type, const char *name); 81 82 /** 83 * New ID creation/copying options. 84 */ 85 enum { 86 /* *** Generic options (should be handled by all ID types copying, ID creation, etc.). *** */ 87 /** Create datablock outside of any main database - 88 * similar to 'localize' functions of materials etc. */ 89 LIB_ID_CREATE_NO_MAIN = 1 << 0, 90 /** Do not affect user refcount of datablocks used by new one 91 * (which also gets zero usercount then). 92 * Implies LIB_ID_CREATE_NO_MAIN. */ 93 LIB_ID_CREATE_NO_USER_REFCOUNT = 1 << 1, 94 /** Assume given 'newid' already points to allocated memory for whole datablock 95 * (ID + data) - USE WITH CAUTION! 96 * Implies LIB_ID_CREATE_NO_MAIN. */ 97 LIB_ID_CREATE_NO_ALLOCATE = 1 << 2, 98 99 /** Do not tag new ID for update in depsgraph. */ 100 LIB_ID_CREATE_NO_DEG_TAG = 1 << 8, 101 102 /** Very similar to #LIB_ID_CREATE_NO_MAIN, and should never be used with it (typically combined 103 * with #LIB_ID_CREATE_LOCALIZE or #LIB_ID_COPY_LOCALIZE in fact). 104 * It ensures that IDs created with it will get the #LIB_TAG_LOCALIZED tag, and uses some 105 * specific code in some copy cases (mostly for node trees). */ 106 LIB_ID_CREATE_LOCAL = 1 << 9, 107 108 /* *** Specific options to some ID types or usages. *** */ 109 /* *** May be ignored by unrelated ID copying functions. *** */ 110 /** Object only, needed by make_local code. */ 111 /* LIB_ID_COPY_NO_PROXY_CLEAR = 1 << 16, */ /* UNUSED */ 112 /** Do not copy preview data, when supported. */ 113 LIB_ID_COPY_NO_PREVIEW = 1 << 17, 114 /** Copy runtime data caches. */ 115 LIB_ID_COPY_CACHES = 1 << 18, 116 /** Don't copy id->adt, used by ID datablock localization routines. */ 117 LIB_ID_COPY_NO_ANIMDATA = 1 << 19, 118 /** Mesh: Reference CD data layers instead of doing real copy - USE WITH CAUTION! */ 119 LIB_ID_COPY_CD_REFERENCE = 1 << 20, 120 121 /* *** XXX Hackish/not-so-nice specific behaviors needed for some corner cases. *** */ 122 /* *** Ideally we should not have those, but we need them for now... *** */ 123 /** EXCEPTION! Deep-copy actions used by animdata of copied ID. */ 124 LIB_ID_COPY_ACTIONS = 1 << 24, 125 /** Keep the library pointer when copying datablock outside of bmain. */ 126 LIB_ID_COPY_KEEP_LIB = 1 << 25, 127 /** EXCEPTION! Deep-copy shapekeys used by copied obdata ID. */ 128 LIB_ID_COPY_SHAPEKEY = 1 << 26, 129 /** EXCEPTION! Specific deep-copy of node trees used e.g. for rendering purposes. */ 130 LIB_ID_COPY_NODETREE_LOCALIZE = 1 << 27, 131 132 /* *** Helper 'defines' gathering most common flag sets. *** */ 133 /** Shapekeys are not real ID's, more like local data to geometry IDs... */ 134 LIB_ID_COPY_DEFAULT = LIB_ID_COPY_SHAPEKEY, 135 136 /** Create a local, outside of bmain, data-block to work on. */ 137 LIB_ID_CREATE_LOCALIZE = LIB_ID_CREATE_NO_MAIN | LIB_ID_CREATE_NO_USER_REFCOUNT | 138 LIB_ID_CREATE_NO_DEG_TAG, 139 /** Generate a local copy, outside of bmain, to work on (used by COW e.g.). */ 140 LIB_ID_COPY_LOCALIZE = LIB_ID_CREATE_LOCALIZE | LIB_ID_COPY_NO_PREVIEW | LIB_ID_COPY_CACHES, 141 }; 142 143 void BKE_libblock_copy_ex(struct Main *bmain, 144 const struct ID *id, 145 struct ID **r_newid, 146 const int orig_flag); 147 void *BKE_libblock_copy(struct Main *bmain, const struct ID *id) ATTR_WARN_UNUSED_RESULT 148 ATTR_NONNULL(); 149 /* Special version: used by data-block localization. */ 150 void *BKE_libblock_copy_for_localize(const struct ID *id); 151 152 void BKE_libblock_rename(struct Main *bmain, struct ID *id, const char *name) ATTR_NONNULL(); 153 void BLI_libblock_ensure_unique_name(struct Main *bmain, const char *name) ATTR_NONNULL(); 154 155 struct ID *BKE_libblock_find_name(struct Main *bmain, 156 const short type, 157 const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); 158 159 /** 160 * Duplicate (a.k.a. deep copy) common processing options. 161 * See also eDupli_ID_Flags for options controlling what kind of IDs to duplicate. 162 */ 163 typedef enum eLibIDDuplicateFlags { 164 /** This call to a duplicate function is part of another call for some parent ID. 165 * Therefore, this sub-process should not clear `newid` pointers, nor handle remapping itself. */ 166 LIB_ID_DUPLICATE_IS_SUBPROCESS = 1 << 0, 167 } eLibIDDuplicateFlags; 168 169 /* lib_remap.c (keep here since they're general functions) */ 170 /** 171 * New freeing logic options. 172 */ 173 enum { 174 /* *** Generic options (should be handled by all ID types freeing). *** */ 175 /** Do not try to remove freed ID from given Main (passed Main may be NULL). */ 176 LIB_ID_FREE_NO_MAIN = 1 << 0, 177 /** 178 * Do not affect user refcount of datablocks used by freed one. 179 * Implies LIB_ID_FREE_NO_MAIN. 180 */ 181 LIB_ID_FREE_NO_USER_REFCOUNT = 1 << 1, 182 /** 183 * Assume freed ID datablock memory is managed elsewhere, do not free it 184 * (still calls relevant ID type's freeing function though) - USE WITH CAUTION! 185 * Implies LIB_ID_FREE_NO_MAIN. 186 */ 187 LIB_ID_FREE_NOT_ALLOCATED = 1 << 2, 188 189 /** Do not tag freed ID for update in depsgraph. */ 190 LIB_ID_FREE_NO_DEG_TAG = 1 << 8, 191 /** Do not attempt to remove freed ID from UI data/notifiers/... */ 192 LIB_ID_FREE_NO_UI_USER = 1 << 9, 193 }; 194 195 void BKE_libblock_free_datablock(struct ID *id, const int flag) ATTR_NONNULL(); 196 void BKE_libblock_free_data(struct ID *id, const bool do_id_user) ATTR_NONNULL(); 197 198 void BKE_id_free_ex(struct Main *bmain, void *idv, int flag, const bool use_flag_from_idtag); 199 void BKE_id_free(struct Main *bmain, void *idv); 200 201 void BKE_id_free_us(struct Main *bmain, void *idv) ATTR_NONNULL(); 202 203 void BKE_id_delete(struct Main *bmain, void *idv) ATTR_NONNULL(); 204 void BKE_id_multi_tagged_delete(struct Main *bmain) ATTR_NONNULL(); 205 206 void BKE_libblock_management_main_add(struct Main *bmain, void *idv); 207 void BKE_libblock_management_main_remove(struct Main *bmain, void *idv); 208 209 void BKE_libblock_management_usercounts_set(struct Main *bmain, void *idv); 210 void BKE_libblock_management_usercounts_clear(struct Main *bmain, void *idv); 211 212 void id_lib_extern(struct ID *id); 213 void id_lib_indirect_weak_link(struct ID *id); 214 void id_us_ensure_real(struct ID *id); 215 void id_us_clear_real(struct ID *id); 216 void id_us_plus_no_lib(struct ID *id); 217 void id_us_plus(struct ID *id); 218 void id_us_min(struct ID *id); 219 void id_fake_user_set(struct ID *id); 220 void id_fake_user_clear(struct ID *id); 221 void BKE_id_clear_newpoin(struct ID *id); 222 223 /** Flags to control make local code behaviour. */ 224 enum { 225 /** Making that ID local is part of making local a whole library. */ 226 LIB_ID_MAKELOCAL_FULL_LIBRARY = 1 << 0, 227 228 /* Special type-specific options. */ 229 /** For Objects, do not clear the proxy pointers while making the data-block local. */ 230 LIB_ID_MAKELOCAL_OBJECT_NO_PROXY_CLEARING = 1 << 16, 231 }; 232 233 void BKE_lib_id_make_local_generic(struct Main *bmain, struct ID *id, const int flags); 234 bool BKE_lib_id_make_local(struct Main *bmain, struct ID *id, const bool test, const int flags); 235 bool id_single_user(struct bContext *C, 236 struct ID *id, 237 struct PointerRNA *ptr, 238 struct PropertyRNA *prop); 239 bool BKE_id_copy_is_allowed(const struct ID *id); 240 struct ID *BKE_id_copy(struct Main *bmain, const struct ID *id); 241 struct ID *BKE_id_copy_ex(struct Main *bmain, 242 const struct ID *id, 243 struct ID **r_newid, 244 const int flag); 245 struct ID *BKE_id_copy_for_duplicate(struct Main *bmain, 246 struct ID *id, 247 const uint duplicate_flags); 248 249 void BKE_lib_id_swap(struct Main *bmain, struct ID *id_a, struct ID *id_b); 250 void BKE_lib_id_swap_full(struct Main *bmain, struct ID *id_a, struct ID *id_b); 251 252 void id_sort_by_name(struct ListBase *lb, struct ID *id, struct ID *id_sorting_hint); 253 void BKE_lib_id_expand_local(struct Main *bmain, struct ID *id); 254 255 bool BKE_id_new_name_validate(struct ListBase *lb, struct ID *id, const char *name) 256 ATTR_NONNULL(1, 2); 257 void BKE_lib_id_clear_library_data(struct Main *bmain, struct ID *id); 258 259 /* Affect whole Main database. */ 260 void BKE_main_id_tag_idcode(struct Main *mainvar, 261 const short type, 262 const int tag, 263 const bool value); 264 void BKE_main_id_tag_listbase(struct ListBase *lb, const int tag, const bool value); 265 void BKE_main_id_tag_all(struct Main *mainvar, const int tag, const bool value); 266 267 void BKE_main_id_flag_listbase(struct ListBase *lb, const int flag, const bool value); 268 void BKE_main_id_flag_all(struct Main *bmain, const int flag, const bool value); 269 270 void BKE_main_id_clear_newpoins(struct Main *bmain); 271 272 void BKE_main_id_refcount_recompute(struct Main *bmain, const bool do_linked_only); 273 274 void BKE_main_lib_objects_recalc_all(struct Main *bmain); 275 276 /* Only for repairing files via versioning, avoid for general use. */ 277 void BKE_main_id_repair_duplicate_names_listbase(struct ListBase *lb); 278 279 #define MAX_ID_FULL_NAME (64 + 64 + 3 + 1) /* 64 is MAX_ID_NAME - 2 */ 280 #define MAX_ID_FULL_NAME_UI (MAX_ID_FULL_NAME + 3) /* Adds 'keycode' two letters at beginning. */ 281 void BKE_id_full_name_get(char name[MAX_ID_FULL_NAME], const struct ID *id, char separator_char); 282 void BKE_id_full_name_ui_prefix_get(char name[MAX_ID_FULL_NAME_UI], 283 const struct ID *id, 284 const bool add_lib_hint, 285 char separator_char, 286 int *r_prefix_len); 287 288 char *BKE_id_to_unique_string_key(const struct ID *id); 289 290 void BKE_library_make_local(struct Main *bmain, 291 const struct Library *lib, 292 struct GHash *old_to_new_ids, 293 const bool untagged_only, 294 const bool set_fake); 295 296 void BKE_id_tag_set_atomic(struct ID *id, int tag); 297 void BKE_id_tag_clear_atomic(struct ID *id, int tag); 298 299 bool BKE_id_is_in_global_main(struct ID *id); 300 301 void BKE_id_ordered_list(struct ListBase *ordered_lb, const struct ListBase *lb); 302 void BKE_id_reorder(const struct ListBase *lb, struct ID *id, struct ID *relative, bool after); 303 304 void BKE_id_blend_write(struct BlendWriter *writer, struct ID *id); 305 306 #define IS_TAGGED(_id) ((_id) && (((ID *)_id)->tag & LIB_TAG_DOIT)) 307 308 #ifdef __cplusplus 309 } 310 #endif 311