Refactor ID copying (and to some extent, ID freeing).
[blender.git] / 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 struct BlendThumbnail;
42 struct GHash;
43 struct ListBase;
44 struct ID;
45 struct ImBuf;
46 struct Main;
47 struct Library;
48 struct wmWindowManager;
49 struct bContext;
50 struct PointerRNA;
51 struct PropertyRNA;
52
53 size_t BKE_libblock_get_alloc_info(short type, const char **name);
54 void *BKE_libblock_alloc_notest(short type);
55 void *BKE_libblock_alloc(struct Main *bmain, short type, const char *name, const int flag) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
56 void  BKE_libblock_init_empty(struct ID *id);
57
58 /**
59  * New ID creation/copying options.
60  */
61 enum {
62         /* *** Generic options (should be handled by all ID types copying, ID creation, etc.). *** */
63         /* Create datablock outside of any main database - similar to 'localize' functions of materials etc. */
64         LIB_ID_CREATE_NO_MAIN            = 1 << 0,
65         /* Do not affect user refcount of datablocks used by new one (which also gets zero usercount then).
66          * Implies LIB_ID_CREATE_NO_MAIN. */
67         LIB_ID_CREATE_NO_USER_REFCOUNT   = 1 << 1,
68         /* Assume given 'newid' already points to allocated memory for whole datablock (ID + data) - USE WITH CAUTION!
69          * Implies LIB_ID_CREATE_NO_MAIN. */
70         LIB_ID_CREATE_NO_ALLOCATE        = 1 << 2,
71
72         LIB_ID_CREATE_NO_DEG_TAG         = 1 << 8,  /* Do not tag new ID for update in depsgraph. */
73
74         /* Specific options to some ID types or usages, may be ignored by unrelated ID copying functions. */
75         LIB_ID_COPY_NO_PROXY_CLEAR     = 1 << 16,  /* Object only, needed by make_local code. */
76         LIB_ID_COPY_NO_PREVIEW         = 1 << 17,  /* Do not copy preview data, when supported. */
77         LIB_ID_COPY_CACHES             = 1 << 18,  /* Copy runtime data caches. */
78         /* XXX TODO Do we want to keep that? would rather try to get rid of it... */
79         LIB_ID_COPY_ACTIONS            = 1 << 19,  /* EXCEPTION! Deep-copy actions used by animdata of copied ID. */
80 };
81
82 void BKE_libblock_copy_ex(struct Main *bmain, const struct ID *id, struct ID **r_newid, const int flag);
83 void *BKE_libblock_copy(struct Main *bmain, const struct ID *id) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
84 /* "Deprecated" old API. */
85 void *BKE_libblock_copy_nolib(const struct ID *id, const bool do_action) ATTR_NONNULL();
86
87 void  BKE_libblock_rename(struct Main *bmain, struct ID *id, const char *name) ATTR_NONNULL();
88 void  BLI_libblock_ensure_unique_name(struct Main *bmain, const char *name) ATTR_NONNULL();
89
90 struct ID *BKE_libblock_find_name_ex(struct Main *bmain, const short type, const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
91 struct ID *BKE_libblock_find_name(const short type, const char *name) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
92
93 /* library_remap.c (keep here since they're general functions) */
94 /**
95  * New freeing logic options.
96  */
97 enum {
98         /* *** Generic options (should be handled by all ID types freeing). *** */
99         /* Do not try to remove freed ID from given Main (passed Main may be NULL). */
100         LIB_ID_FREE_NO_MAIN            = 1 << 0,
101         /* Do not affect user refcount of datablocks used by freed one.
102          * Implies LIB_ID_FREE_NO_MAIN. */
103         LIB_ID_FREE_NO_USER_REFCOUNT   = 1 << 1,
104         /* Assume freed ID datablock memory is managed elsewhere, do not free it
105          * (still calls relevant ID type's freeing function though) - USE WITH CAUTION!
106          * Implies LIB_ID_FREE_NO_MAIN. */
107         LIB_ID_FREE_NOT_ALLOCATED      = 1 << 2,
108
109         LIB_ID_FREE_NO_DEG_TAG         = 1 << 8,  /* Do not tag freed ID for update in depsgraph. */
110         LIB_ID_FREE_NO_UI_USER         = 1 << 9,  /* Do not attempt to remove freed ID from UI data/notifiers/... */
111 };
112
113 void BKE_id_free_ex(struct Main *bmain, void *idv, int flag, const bool use_flag_from_idtag);
114 void BKE_id_free(struct Main *bmain, void *idv);
115 /* Those three naming are bad actually, should be BKE_id_free... (since it goes beyond mere datablock). */
116 /* "Deprecated" old API */
117 void  BKE_libblock_free_ex(struct Main *bmain, void *idv, const bool do_id_user, const bool do_ui_user) ATTR_NONNULL();
118 void  BKE_libblock_free(struct Main *bmain, void *idv) ATTR_NONNULL();
119 void  BKE_libblock_free_us(struct Main *bmain, void *idv) ATTR_NONNULL();
120
121 void BKE_libblock_management_main_add(struct Main *bmain, void *idv);
122 void BKE_libblock_management_main_remove(struct Main *bmain, void *idv);
123
124 void BKE_libblock_management_usercounts_set(struct Main *bmain, void *idv);
125 void BKE_libblock_management_usercounts_clear(struct Main *bmain, void *idv);
126
127 /* TODO should be named "BKE_id_delete()". */
128 void  BKE_libblock_delete(struct Main *bmain, void *idv) ATTR_NONNULL();
129
130 void  BKE_libblock_free_datablock(struct ID *id, const int flag) ATTR_NONNULL();
131 void  BKE_libblock_free_data(struct ID *id, const bool do_id_user) ATTR_NONNULL();
132
133 void BKE_id_lib_local_paths(struct Main *bmain, struct Library *lib, struct ID *id);
134 void id_lib_extern(struct ID *id);
135 void BKE_library_filepath_set(struct Library *lib, const char *filepath);
136 void id_us_ensure_real(struct ID *id);
137 void id_us_clear_real(struct ID *id);
138 void id_us_plus_no_lib(struct ID *id);
139 void id_us_plus(struct ID *id);
140 void id_us_min(struct ID *id);
141 void id_fake_user_set(struct ID *id);
142 void id_fake_user_clear(struct ID *id);
143 void BKE_id_clear_newpoin(struct ID *id);
144
145 void BKE_id_make_local_generic(struct Main *bmain, struct ID *id, const bool id_in_mainlist, const bool lib_local);
146 bool id_make_local(struct Main *bmain, struct ID *id, const bool test, const bool force_local);
147 bool id_single_user(struct bContext *C, struct ID *id, struct PointerRNA *ptr, struct PropertyRNA *prop);
148 bool id_copy(struct Main *bmain, const struct ID *id, struct ID **newid, bool test);
149 bool BKE_id_copy_ex(struct Main *bmain, const struct ID *id, struct ID **r_newid, const int flag, const bool test);
150 void id_sort_by_name(struct ListBase *lb, struct ID *id);
151 void BKE_id_expand_local(struct Main *bmain, struct ID *id);
152 void BKE_id_copy_ensure_local(struct Main *bmain, const struct ID *old_id, struct ID *new_id);
153
154 bool new_id(struct ListBase *lb, struct ID *id, const char *name);
155 void id_clear_lib_data(struct Main *bmain, struct ID *id);
156 void id_clear_lib_data_ex(struct Main *bmain, struct ID *id, const bool id_in_mainlist);
157
158 struct ListBase *which_libbase(struct Main *mainlib, short type);
159
160 #define MAX_LIBARRAY    35
161 int set_listbasepointers(struct Main *main, struct ListBase *lb[MAX_LIBARRAY]);
162
163 /* Main API */
164 struct Main *BKE_main_new(void);
165 void BKE_main_free(struct Main *mainvar);
166
167 void BKE_main_lock(struct Main *bmain);
168 void BKE_main_unlock(struct Main *bmain);
169
170 void BKE_main_relations_create(struct Main *bmain);
171 void BKE_main_relations_free(struct Main *bmain);
172
173 struct BlendThumbnail *BKE_main_thumbnail_from_imbuf(struct Main *bmain, struct ImBuf *img);
174 struct ImBuf *BKE_main_thumbnail_to_imbuf(struct Main *bmain, struct BlendThumbnail *data);
175 void BKE_main_thumbnail_create(struct Main *bmain);
176
177 void BKE_main_id_tag_idcode(struct Main *mainvar, const short type, const int tag, const bool value);
178 void BKE_main_id_tag_listbase(struct ListBase *lb, const int tag, const bool value);
179 void BKE_main_id_tag_all(struct Main *mainvar, const int tag, const bool value);
180
181 void BKE_main_id_flag_listbase(struct ListBase *lb, const int flag, const bool value);
182 void BKE_main_id_flag_all(struct Main *bmain, const int flag, const bool value);
183
184 void BKE_main_id_clear_newpoins(struct Main *bmain);
185
186 void BKE_main_lib_objects_recalc_all(struct Main *bmain);
187
188 /* (MAX_ID_NAME - 2) + 3 */
189 void BKE_id_ui_prefix(char name[66 + 1], const struct ID *id);
190
191 void BKE_library_free(struct Library *lib);
192
193 void BKE_library_make_local(
194         struct Main *bmain, const struct Library *lib, struct GHash *old_to_new_ids,
195         const bool untagged_only, const bool set_fake);
196
197 void BKE_id_tag_set_atomic(struct ID *id, int tag);
198 void BKE_id_tag_clear_atomic(struct ID *id, int tag);
199
200 /* use when "" is given to new_id() */
201 #define ID_FALLBACK_NAME N_("Untitled")
202
203 #define IS_TAGGED(_id) ((_id) && (((ID *)_id)->tag & LIB_TAG_DOIT))
204
205 #ifdef __cplusplus
206 }
207 #endif
208
209 #endif  /* __BKE_LIBRARY_H__ */