diff options
Diffstat (limited to 'source/blender/blenkernel/BKE_lib_id.h')
| -rw-r--r-- | source/blender/blenkernel/BKE_lib_id.h | 289 |
1 files changed, 286 insertions, 3 deletions
diff --git a/source/blender/blenkernel/BKE_lib_id.h b/source/blender/blenkernel/BKE_lib_id.h index 359fb72534a..34339c4ff9f 100644 --- a/source/blender/blenkernel/BKE_lib_id.h +++ b/source/blender/blenkernel/BKE_lib_id.h @@ -62,21 +62,65 @@ struct PointerRNA; struct PropertyRNA; struct bContext; +/** + * Get allocation size of a given data-block type and optionally allocation name. + */ size_t BKE_libblock_get_alloc_info(short type, const char **name); +/** + * Allocates and returns memory of the right size for the specified block type, + * initialized to zero. + */ void *BKE_libblock_alloc_notest(short type) ATTR_WARN_UNUSED_RESULT; +/** + * Allocates and returns a block of the specified type, with the specified name + * (adjusted as necessary to ensure uniqueness), and appended to the specified list. + * The user count is set to 1, all other content (apart from name and links) being + * initialized to zero. + */ void *BKE_libblock_alloc(struct Main *bmain, short type, const char *name, const int flag) ATTR_WARN_UNUSED_RESULT; +/** + * Initialize an ID of given type, such that it has valid 'empty' data. + * ID is assumed to be just calloc'ed. + */ void BKE_libblock_init_empty(struct ID *id) ATTR_NONNULL(1); /* *** ID's session_uuid management. *** */ -/* When an ID's uuid is of that value, it is unset/invalid (e.g. for runtime IDs, etc.). */ +/** + * When an ID's uuid is of that value, it is unset/invalid (e.g. for runtime IDs, etc.). + */ #define MAIN_ID_SESSION_UUID_UNSET 0 +/** + * Generate a session-wise uuid for the given \a id. + * + * \note "session-wise" here means while editing a given .blend file. Once a new .blend file is + * loaded or created, undo history is cleared/reset, and so is the uuid counter. + */ void BKE_lib_libblock_session_uuid_ensure(struct ID *id); +/** + * Re-generate a new session-wise uuid for the given \a id. + * + * \warning This has a few very specific use-cases, no other usage is expected currently: + * - To handle UI-related data-blocks that are kept across new file reading, when we do keep + * existing UI. + * - For IDs that are made local without needing any copying. + */ void BKE_lib_libblock_session_uuid_renew(struct ID *id); +/** + * Generic helper to create a new empty data-block of given type in given \a bmain database. + * + * \param name: can be NULL, in which case we get default name for this ID type. + */ void *BKE_id_new(struct Main *bmain, const short type, const char *name); +/** + * Generic helper to create a new temporary empty data-block of given type, + * *outside* of any Main database. + * + * \param name: can be NULL, in which case we get default name for this ID type. + */ void *BKE_id_new_nomain(const short type, const char *name); /** @@ -159,10 +203,20 @@ void BKE_libblock_copy_ex(struct Main *bmain, const struct ID *id, struct ID **r_newid, const int orig_flag); +/** + * Used everywhere in blenkernel. + */ void *BKE_libblock_copy(struct Main *bmain, const struct ID *id) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(); +/** + * Sets the name of a block to name, suitably adjusted for uniqueness. + */ void BKE_libblock_rename(struct Main *bmain, struct ID *id, const char *name) ATTR_NONNULL(); +/** + * Use after setting the ID's name + * When name exists: call 'new_id' + */ void BLI_libblock_ensure_unique_name(struct Main *bmain, const char *name) ATTR_NONNULL(); struct ID *BKE_libblock_find_name(struct Main *bmain, @@ -216,17 +270,70 @@ enum { void BKE_libblock_free_datablock(struct ID *id, const int flag) ATTR_NONNULL(); void BKE_libblock_free_data(struct ID *id, const bool do_id_user) ATTR_NONNULL(); +/** + * In most cases #BKE_id_free_ex handles this, when lower level functions are called directly + * this function will need to be called too, if Python has access to the data. + * + * ID data-blocks such as #Material.nodetree are not stored in #Main. + */ void BKE_libblock_free_data_py(struct ID *id); +/** + * Complete ID freeing, extended version for corner cases. + * Can override default (and safe!) freeing process, to gain some speed up. + * + * At that point, given id is assumed to not be used by any other data-block already + * (might not be actually true, in case e.g. several inter-related IDs get freed together...). + * However, they might still be using (referencing) other IDs, this code takes care of it if + * #LIB_TAG_NO_USER_REFCOUNT is not defined. + * + * \param bmain: #Main database containing the freed #ID, + * can be NULL in case it's a temp ID outside of any #Main. + * \param idv: Pointer to ID to be freed. + * \param flag: Set of \a LIB_ID_FREE_... flags controlling/overriding usual freeing process, + * 0 to get default safe behavior. + * \param use_flag_from_idtag: Still use freeing info flags from given #ID datablock, + * even if some overriding ones are passed in \a flag parameter. + */ void BKE_id_free_ex(struct Main *bmain, void *idv, int flag, const bool use_flag_from_idtag); +/** + * Complete ID freeing, should be usable in most cases (even for out-of-Main IDs). + * + * See #BKE_id_free_ex description for full details. + * + * \param bmain: Main database containing the freed ID, + * can be NULL in case it's a temp ID outside of any Main. + * \param idv: Pointer to ID to be freed. + */ void BKE_id_free(struct Main *bmain, void *idv); +/** + * Not really a freeing function by itself, + * it decrements usercount of given id, and only frees it if it reaches 0. + */ void BKE_id_free_us(struct Main *bmain, void *idv) ATTR_NONNULL(); +/** + * Properly delete a single ID from given \a bmain database. + */ void BKE_id_delete(struct Main *bmain, void *idv) ATTR_NONNULL(); +/** + * Properly delete all IDs tagged with \a LIB_TAG_DOIT, in given \a bmain database. + * + * This is more efficient than calling #BKE_id_delete repetitively on a large set of IDs + * (several times faster when deleting most of the IDs at once). + * + * \warning Considered experimental for now, seems to be working OK but this is + * risky code in a complicated area. + * \return Number of deleted datablocks. + */ size_t BKE_id_multi_tagged_delete(struct Main *bmain) ATTR_NONNULL(); +/** + * Add a 'NO_MAIN' data-block to given main (also sets usercounts of its IDs if needed). + */ void BKE_libblock_management_main_add(struct Main *bmain, void *idv); +/** Remove a data-block from given main (set it to 'NO_MAIN' status). */ void BKE_libblock_management_main_remove(struct Main *bmain, void *idv); void BKE_libblock_management_usercounts_set(struct Main *bmain, void *idv); @@ -234,10 +341,23 @@ void BKE_libblock_management_usercounts_clear(struct Main *bmain, void *idv); void id_lib_extern(struct ID *id); void id_lib_indirect_weak_link(struct ID *id); +/** + * Ensure we have a real user + * + * \note Now that we have flags, we could get rid of the 'fake_user' special case, + * flags are enough to ensure we always have a real user. + * However, #ID_REAL_USERS is used in several places outside of core lib.c, + * so think we can wait later to make this change. + */ void id_us_ensure_real(struct ID *id); void id_us_clear_real(struct ID *id); +/** + * Same as \a id_us_plus, but does not handle lib indirect -> extern. + * Only used by readfile.c so far, but simpler/safer to keep it here nonetheless. + */ void id_us_plus_no_lib(struct ID *id); void id_us_plus(struct ID *id); +/* decrements the user count for *id. */ void id_us_min(struct ID *id); void id_fake_user_set(struct ID *id); void id_fake_user_clear(struct ID *id); @@ -262,66 +382,212 @@ enum { LIB_ID_MAKELOCAL_OBJECT_NO_PROXY_CLEARING = 1 << 16, }; +/** + * Generic 'make local' function, works for most of data-block types. + */ void BKE_lib_id_make_local_generic(struct Main *bmain, struct ID *id, const int flags); +/** + * Calls the appropriate make_local method for the block, unless test is set. + * + * \note Always set #ID.newid pointer in case it gets duplicated. + * + * \param flags: Special flag used when making a whole library's content local, + * it needs specific handling. + * \return true is the ID has successfully been made local. + */ bool BKE_lib_id_make_local(struct Main *bmain, struct ID *id, const int flags); +/** + * \note Does *not* set #ID.newid pointer. + */ bool id_single_user(struct bContext *C, struct ID *id, struct PointerRNA *ptr, struct PropertyRNA *prop); bool BKE_id_copy_is_allowed(const struct ID *id); +/** + * Invokes the appropriate copy method for the block and returns the result in + * #ID.newid, unless test. Returns true if the block can be copied. + */ struct ID *BKE_id_copy(struct Main *bmain, const struct ID *id); +/** + * Generic entry point for copying a data-block (new API). + * + * \note Copy is generally only affecting the given data-block + * (no ID used by copied one will be affected, besides user-count). + * + * There are exceptions though: + * - Embedded IDs (root node trees and master collections) are always copied with their owner. + * - If #LIB_ID_COPY_ACTIONS is defined, actions used by animdata will be duplicated. + * - If #LIB_ID_COPY_SHAPEKEY is defined, shape-keys will be duplicated. + * - If #LIB_ID_CREATE_LOCAL is defined, root node trees will be deep-duplicated recursively. + * + * \note User-count of new copy is always set to 1. + * + * \param bmain: Main database, may be NULL only if LIB_ID_CREATE_NO_MAIN is specified. + * \param id: Source data-block. + * \param r_newid: Pointer to new (copied) ID pointer, may be NULL. + * Used to allow copying into already allocated memory. + * \param flag: Set of copy options, see `DNA_ID.h` enum for details + * (leave to zero for default, full copy). + * \return NULL when copying that ID type is not supported, the new copy otherwise. + */ struct ID *BKE_id_copy_ex(struct Main *bmain, const struct ID *id, struct ID **r_newid, const int flag); +/** + * Invokes the appropriate copy method for the block and returns the result in + * newid, unless test. Returns true if the block can be copied. + */ struct ID *BKE_id_copy_for_duplicate(struct Main *bmain, struct ID *id, const uint duplicate_flags, const int copy_flags); +/** + * Does a mere memory swap over the whole IDs data (including type-specific memory). + * \note Most internal ID data itself is not swapped (only IDProperties are). + * + * \param bmain: May be NULL, in which case there will be no remapping of internal pointers to + * itself. + */ void BKE_lib_id_swap(struct Main *bmain, struct ID *id_a, struct ID *id_b); +/** + * Does a mere memory swap over the whole IDs data (including type-specific memory). + * \note All internal ID data itself is also swapped. + * + * \param bmain: May be NULL, in which case there will be no remapping of internal pointers to + * itself. + */ void BKE_lib_id_swap_full(struct Main *bmain, struct ID *id_a, struct ID *id_b); +/** + * Sort given \a id into given \a lb list, using case-insensitive comparison of the id names. + * + * \note All other IDs beside given one are assumed already properly sorted in the list. + * + * \param id_sorting_hint: Ignored if NULL. Otherwise, used to check if we can insert \a id + * immediately before or after that pointer. It must always be into given \a lb list. + */ void id_sort_by_name(struct ListBase *lb, struct ID *id, struct ID *id_sorting_hint); +/** + * Expand ID usages of given id as 'extern' (and no more indirect) linked data. + * Used by ID copy/make_local functions. + */ void BKE_lib_id_expand_local(struct Main *bmain, struct ID *id, const int flags); +/** + * Ensures given ID has a unique name in given listbase. + * + * Only for local IDs (linked ones already have a unique ID in their library). + * + * \param do_linked_data: if true, also ensure a unique name in case the given \a id is linked + * (otherwise, just ensure that it is properly sorted). + * + * \return true if a new name had to be created. + */ bool BKE_id_new_name_validate(struct ListBase *lb, struct ID *id, const char *name, const bool do_linked_data) ATTR_NONNULL(1, 2); +/** + * Pull an ID out of a library (make it local). Only call this for IDs that + * don't have other library users. + * + * \param flags: Same set of `LIB_ID_MAKELOCAL_` flags as passed to #BKE_lib_id_make_local. + */ void BKE_lib_id_clear_library_data(struct Main *bmain, struct ID *id, const int flags); -/* Affect whole Main database. */ +/** + * Clear or set given tags for all ids of given type in `bmain` (runtime tags). + * + * \note Affect whole Main database. + */ void BKE_main_id_tag_idcode(struct Main *mainvar, const short type, const int tag, const bool value); +/** + * Clear or set given tags for all ids in listbase (runtime tags). + */ void BKE_main_id_tag_listbase(struct ListBase *lb, const int tag, const bool value); +/** + * Clear or set given tags for all ids in bmain (runtime tags). + */ void BKE_main_id_tag_all(struct Main *mainvar, const int tag, const bool value); +/** + * Clear or set given flags for all ids in listbase (persistent flags). + */ void BKE_main_id_flag_listbase(struct ListBase *lb, const int flag, const bool value); +/** + * Clear or set given flags for all ids in bmain (persistent flags). + */ void BKE_main_id_flag_all(struct Main *bmain, const int flag, const bool value); +/** + * Next to indirect usage in `readfile.c/writefile.c` also in `editobject.c`, `scene.c`. + */ void BKE_main_id_newptr_and_tag_clear(struct Main *bmain); void BKE_main_id_refcount_recompute(struct Main *bmain, const bool do_linked_only); void BKE_main_lib_objects_recalc_all(struct Main *bmain); -/* Only for repairing files via versioning, avoid for general use. */ +/** + * Only for repairing files via versioning, avoid for general use. + */ void BKE_main_id_repair_duplicate_names_listbase(struct ListBase *lb); #define MAX_ID_FULL_NAME (64 + 64 + 3 + 1) /* 64 is MAX_ID_NAME - 2 */ #define MAX_ID_FULL_NAME_UI (MAX_ID_FULL_NAME + 3) /* Adds 'keycode' two letters at beginning. */ +/** + * Generate full name of the data-block (without ID code, but with library if any). + * + * \note Result is unique to a given ID type in a given Main database. + * + * \param name: An allocated string of minimal length #MAX_ID_FULL_NAME, + * will be filled with generated string. + * \param separator_char: Character to use for separating name and library name. + * Can be 0 to use default (' '). + */ void BKE_id_full_name_get(char name[MAX_ID_FULL_NAME], const struct ID *id, char separator_char); +/** + * Generate full name of the data-block (without ID code, but with library if any), + * with a 2 to 3 character prefix prepended indicating whether it comes from a library, + * is overriding, has a fake or no user, etc. + * + * \note Result is unique to a given ID type in a given Main database. + * + * \param name: An allocated string of minimal length #MAX_ID_FULL_NAME_UI, + * will be filled with generated string. + * \param separator_char: Character to use for separating name and library name. + * Can be 0 to use default (' '). + * \param r_prefix_len: The length of the prefix added. + */ void BKE_id_full_name_ui_prefix_get(char name[MAX_ID_FULL_NAME_UI], const struct ID *id, const bool add_lib_hint, char separator_char, int *r_prefix_len); +/** + * Generate a concatenation of ID name (including two-chars type code) and its lib name, if any. + * + * \return A unique allocated string key for any ID in the whole Main database. + */ char *BKE_id_to_unique_string_key(const struct ID *id); +/** + * Make linked data-blocks local. + * + * \param bmain: Almost certainly global main. + * \param lib: If not NULL, only make local data-blocks from this library. + * \param untagged_only: If true, only make local data-blocks not tagged with + * #LIB_TAG_PRE_EXISTING. + * \param set_fake: If true, set fake user on all localized data-blocks + * (except group and objects ones). + */ void BKE_library_make_local(struct Main *bmain, const struct Library *lib, struct GHash *old_to_new_ids, @@ -331,11 +597,22 @@ void BKE_library_make_local(struct Main *bmain, void BKE_id_tag_set_atomic(struct ID *id, int tag); void BKE_id_tag_clear_atomic(struct ID *id, int tag); +/** + * Check that given ID pointer actually is in G_MAIN. + * Main intended use is for debug asserts in places we cannot easily get rid of #G_Main. + */ bool BKE_id_is_in_global_main(struct ID *id); bool BKE_id_can_be_asset(const struct ID *id); +/** + * Returns ordered list of data-blocks for display in the UI. + * Result is list of #LinkData of IDs that must be freed. + */ void BKE_id_ordered_list(struct ListBase *ordered_lb, const struct ListBase *lb); +/** + * Reorder ID in the list, before or after the "relative" ID. + */ void BKE_id_reorder(const struct ListBase *lb, struct ID *id, struct ID *relative, bool after); void BKE_id_blend_write(struct BlendWriter *writer, struct ID *id); @@ -343,6 +620,12 @@ void BKE_id_blend_write(struct BlendWriter *writer, struct ID *id); #define IS_TAGGED(_id) ((_id) && (((ID *)_id)->tag & LIB_TAG_DOIT)) /* lib_id_eval.c */ + +/** + * Copy relatives parameters, from `id` to `id_cow`. + * Use handle the #ID_RECALC_PARAMETERS tag. + * \note Keep in sync with #ID_TYPE_SUPPORTS_PARAMS_WITHOUT_COW. + */ void BKE_id_eval_properties_copy(struct ID *id_cow, struct ID *id); #ifdef __cplusplus |