source/blender/blenkernel/BKE_library.h

   1 /*
   2  * ***** BEGIN GPL LICENSE BLOCK *****
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software Foundation,
  16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  17  *
  18  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
  19  * All rights reserved.
  20  *
  21  * The Original Code is: all of this file.
  22  *
  23  * Contributor(s): none yet.
  24  *
  25  * ***** END GPL LICENSE BLOCK *****
  26  */
  27 #ifndef __BKE_LIBRARY_H__
  28 #define __BKE_LIBRARY_H__
  29
  30 /** \file BKE_library.h
  31  *  \ingroup bke
  32  *  \since March 2001
  33  *  \author nzc
  34  */
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 #include "BLI_compiler_attrs.h"
  40
  41 /**
  42  * Naming: BKE_id_ vs BKE_libblock_
  43  *
  44  * WARNING: description below is ideal goal, current status of naming does not yet
  45  * fully follow it (this is WIP).
  46  *
  47  * BKE_id_ should be used for rather high-level operations, that involve Main database and
  48  * relations with other IDs, and can be considered as 'safe' (as in, in themselves, they leave
  49  * affected IDs/Main in a consistent status).
  50  *
  51  * BKE_libblock_ should be used for lower level operations, that perform some parts of BKE_id_ ones,
  52  * but will generally not ensure caller that affected data is in a consistent state
  53  * by their own execution alone.
  54  *
  55  * Consequently, external code should not typically use BKE_libblock_ functions,
  56  * except in some specific cases requiring advanced (and potentially dangerous) handling.
  57  */
  58
  59 struct BlendThumbnail;
  60 struct GHash;
  61 struct ListBase;
  62 struct ID;
  63 struct ImBuf;
  64 struct Main;
  65 struct Library;
  66 struct wmWindowManager;
  67 struct bContext;
  68 struct PointerRNA;
  69 struct PropertyRNA;
  70
  71 size_t BKE_libblock_get_alloc_info(short type, const char **name);
  72 void *BKE_libblock_alloc_notest(short type) ATTR_WARN_UNUSED_RESULT;
  73 void *BKE_libblock_alloc(struct Main *bmain, short type, const char *name, const int flag) ATTR_WARN_UNUSED_RESULT;
  74 void  BKE_libblock_init_empty(struct ID *id) ATTR_NONNULL(1);
  75
  76 void *BKE_id_new(struct Main *bmain, const short type, const char *name);
  77 void *BKE_id_new_nomain(const short type, const char *name);
  78
  79
  80 /**
  81  * New ID creation/copying options.
  82  */
  83 enum {
  84         /* *** Generic options (should be handled by all ID types copying, ID creation, etc.). *** */
  85         /* Create datablock outside of any main database - similar to 'localize' functions of materials etc. */
  86         LIB_ID_CREATE_NO_MAIN            = 1 << 0,
  87         /* Do not affect user refcount of datablocks used by new one (which also gets zero usercount then).
  88          * Implies LIB_ID_CREATE_NO_MAIN. */
  89         LIB_ID_CREATE_NO_USER_REFCOUNT   = 1 << 1,
  90         /* Assume given 'newid' already points to allocated memory for whole datablock (ID + data) - USE WITH CAUTION!
  91          * Implies LIB_ID_CREATE_NO_MAIN. */
  92         LIB_ID_CREATE_NO_ALLOCATE        = 1 << 2,
  93
  94         LIB_ID_CREATE_NO_DEG_TAG         = 1 << 8,  /* Do not tag new ID for update in depsgraph. */
  95
  96         /*** Specific options to some ID types or usages. ***/
  97         /* May be ignored by unrelated ID copying functions. */
  98         LIB_ID_COPY_NO_PROXY_CLEAR     = 1 << 16,  /* Object only, needed by make_local code. */
  99         LIB_ID_COPY_NO_PREVIEW         = 1 << 17,  /* Do not copy preview data, when supported. */
 100         LIB_ID_COPY_CACHES             = 1 << 18,  /* Copy runtime data caches. */
 101         LIB_ID_COPY_NO_ANIMDATA        = 1 << 19,  /* Don't copy id->adt, used by ID datablock localization routines. */
 102         LIB_ID_COPY_CD_REFERENCE       = 1 << 20,  /* Mesh: Reference CD data layers instead of doing real copy. */
 103
 104         /*** XXX Hackish/not-so-nice specific behaviors needed for some corner cases. ***/
 105         /* Ideally we should not have those, but we need them for now... */
 106         LIB_ID_COPY_ACTIONS            = 1 << 24,  /* EXCEPTION! Deep-copy actions used by animdata of copied ID. */
 107         LIB_ID_COPY_KEEP_LIB           = 1 << 25,  /* Keep the library pointer when copying datablock outside of bmain. */
 108         LIB_ID_COPY_SHAPEKEY           = 1 << 26,  /* EXCEPTION! Deep-copy shapekeys used by copied obdata ID. */
 109 };
 110
 111 void BKE_libblock_copy_ex(struct Main *bmain, const struct ID *id, struct ID **r_newid, const int flag);
 112 void *BKE_libblock_copy(struct Main *bmain, const struct ID *id) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
 113 /* "Deprecated" old API. */
 114 void *BKE_libblock_copy_nolib(const struct ID *id, const bool do_action) ATTR_NONNULL();
 115 /* Special version. sued by datablock localization. */
 116 void *BKE_libblock_copy_for_localize(const struct ID *id);
 117
 118 void  BKE_libblock_rename(struct Main *bmain, struct ID *id, const char *name) ATTR_NONNULL();
 119 void  BLI_libblock_ensure_unique_name(struct Main *bmain, const char *name) ATTR_NONNULL();
 120
 121 struct ID *BKE_libblock_find_name(struct Main *bmain, const short type, const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
 122
 123 /* library_remap.c (keep here since they're general functions) */
 124 /**
 125  * New freeing logic options.
 126  */
 127 enum {
 128         /* *** Generic options (should be handled by all ID types freeing). *** */
 129         /* Do not try to remove freed ID from given Main (passed Main may be NULL). */
 130         LIB_ID_FREE_NO_MAIN            = 1 << 0,
 131         /* Do not affect user refcount of datablocks used by freed one.
 132          * Implies LIB_ID_FREE_NO_MAIN. */
 133         LIB_ID_FREE_NO_USER_REFCOUNT   = 1 << 1,
 134         /* Assume freed ID datablock memory is managed elsewhere, do not free it
 135          * (still calls relevant ID type's freeing function though) - USE WITH CAUTION!
 136          * Implies LIB_ID_FREE_NO_MAIN. */
 137         LIB_ID_FREE_NOT_ALLOCATED      = 1 << 2,
 138
 139         LIB_ID_FREE_NO_DEG_TAG         = 1 << 8,  /* Do not tag freed ID for update in depsgraph. */
 140         LIB_ID_FREE_NO_UI_USER         = 1 << 9,  /* Do not attempt to remove freed ID from UI data/notifiers/... */
 141 };
 142
 143 void BKE_id_free_ex(struct Main *bmain, void *idv, int flag, const bool use_flag_from_idtag);
 144 void BKE_id_free(struct Main *bmain, void *idv);
 145
 146 void  BKE_id_free_us(struct Main *bmain, void *idv) ATTR_NONNULL();
 147
 148 void BKE_libblock_management_main_add(struct Main *bmain, void *idv);
 149 void BKE_libblock_management_main_remove(struct Main *bmain, void *idv);
 150
 151 void BKE_libblock_management_usercounts_set(struct Main *bmain, void *idv);
 152 void BKE_libblock_management_usercounts_clear(struct Main *bmain, void *idv);
 153
 154 /* TODO should be named "BKE_id_delete()". */
 155 void  BKE_libblock_delete(struct Main *bmain, void *idv) ATTR_NONNULL();
 156
 157 void  BKE_libblock_free_datablock(struct ID *id, const int flag) ATTR_NONNULL();
 158 void  BKE_libblock_free_data(struct ID *id, const bool do_id_user) ATTR_NONNULL();
 159
 160 void BKE_id_lib_local_paths(struct Main *bmain, struct Library *lib, struct ID *id);
 161 void id_lib_extern(struct ID *id);
 162 void BKE_library_filepath_set(struct Main *bmain, struct Library *lib, const char *filepath);
 163 void id_us_ensure_real(struct ID *id);
 164 void id_us_clear_real(struct ID *id);
 165 void id_us_plus_no_lib(struct ID *id);
 166 void id_us_plus(struct ID *id);
 167 void id_us_min(struct ID *id);
 168 void id_fake_user_set(struct ID *id);
 169 void id_fake_user_clear(struct ID *id);
 170 void BKE_id_clear_newpoin(struct ID *id);
 171
 172 void BKE_id_make_local_generic(struct Main *bmain, struct ID *id, const bool id_in_mainlist, const bool lib_local);
 173 bool id_make_local(struct Main *bmain, struct ID *id, const bool test, const bool force_local);
 174 bool id_single_user(struct bContext *C, struct ID *id, struct PointerRNA *ptr, struct PropertyRNA *prop);
 175 bool id_copy(struct Main *bmain, const struct ID *id, struct ID **newid, bool test);
 176 bool BKE_id_copy_ex(struct Main *bmain, const struct ID *id, struct ID **r_newid, const int flag, const bool test);
 177 void BKE_id_swap(struct Main *bmain, struct ID *id_a, struct ID *id_b);
 178 void id_sort_by_name(struct ListBase *lb, struct ID *id);
 179 void BKE_id_expand_local(struct Main *bmain, struct ID *id);
 180 void BKE_id_copy_ensure_local(struct Main *bmain, const struct ID *old_id, struct ID *new_id);
 181
 182 bool new_id(struct ListBase *lb, struct ID *id, const char *name) ATTR_NONNULL(1, 2);
 183 void id_clear_lib_data(struct Main *bmain, struct ID *id);
 184 void id_clear_lib_data_ex(struct Main *bmain, struct ID *id, const bool id_in_mainlist);
 185
 186 /* Affect whole Main database. */
 187 void BKE_main_id_tag_idcode(struct Main *mainvar, const short type, const int tag, const bool value);
 188 void BKE_main_id_tag_listbase(struct ListBase *lb, const int tag, const bool value);
 189 void BKE_main_id_tag_all(struct Main *mainvar, const int tag, const bool value);
 190
 191 void BKE_main_id_flag_listbase(struct ListBase *lb, const int flag, const bool value);
 192 void BKE_main_id_flag_all(struct Main *bmain, const int flag, const bool value);
 193
 194 void BKE_main_id_clear_newpoins(struct Main *bmain);
 195
 196 void BKE_main_lib_objects_recalc_all(struct Main *bmain);
 197
 198 #define MAX_ID_FULL_NAME (64 + 64 + 3 + 1)  /* 64 is MAX_ID_NAME - 2 */
 199 #define MAX_ID_FULL_NAME_UI (MAX_ID_FULL_NAME + 3)  /* Adds 'keycode' two letters at begining. */
 200 void BKE_id_full_name_get(char name[MAX_ID_FULL_NAME], const struct ID *id);
 201 void BKE_id_full_name_ui_prefix_get(char name[MAX_ID_FULL_NAME_UI], const struct ID *id);
 202
 203 char *BKE_id_to_unique_string_key(const struct ID *id);
 204
 205 void BKE_library_free(struct Library *lib);
 206
 207 void BKE_library_make_local(
 208         struct Main *bmain, const struct Library *lib, struct GHash *old_to_new_ids,
 209         const bool untagged_only, const bool set_fake);
 210
 211 void BKE_id_tag_set_atomic(struct ID *id, int tag);
 212 void BKE_id_tag_clear_atomic(struct ID *id, int tag);
 213
 214 bool BKE_id_is_in_global_main(struct ID *id);
 215
 216 void BKE_id_ordered_list(struct ListBase *ordered_lb, const struct ListBase *lb);
 217 void BKE_id_reorder(const struct ListBase *lb, struct ID *id, struct ID *relative, bool after);
 218
 219 /* use when "" is given to new_id() */
 220 #define ID_FALLBACK_NAME N_("Untitled")
 221
 222 #define IS_TAGGED(_id) ((_id) && (((ID *)_id)->tag & LIB_TAG_DOIT))
 223
 224 #ifdef __cplusplus
 225 }
 226 #endif
 227
 228 #endif  /* __BKE_LIBRARY_H__ */