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