BKE_lib_id.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2001-2002 NaN Holding BV. All rights reserved.
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
#pragma once

 
#include <optional>
 
#include "BLI_compiler_attrs.h"
#include "BLI_set.hh"
#include "BLI_string_ref.hh"
#include "BLI_utildefines.h"
#include "BLI_vector.hh"
 
#include "DNA_ID.h"
#include "DNA_userdef_enums.h"
 
struct BlendWriter;
struct GHash;
struct ID;
struct Library;
struct ListBase;
struct Main;
struct PointerRNA;
struct PropertyRNA;
struct bContext;

size_t BKE_libblock_get_alloc_info(short type, const char **r_name);
ID *BKE_libblock_alloc_notest(short type) ATTR_WARN_UNUSED_RESULT;
void *BKE_libblock_alloc(Main *bmain, short type, const char *name, int flag)
    ATTR_WARN_UNUSED_RESULT;
void *BKE_libblock_alloc_in_lib(Main *bmain,
                                std::optional<Library *> owner_library,
                                short type,
                                const char *name,
                                int flag) ATTR_WARN_UNUSED_RESULT;
void BKE_libblock_init_empty(ID *id) ATTR_NONNULL(1);

void BKE_libblock_runtime_reset_remapping_status(ID *id) ATTR_NONNULL(1);
 
/* *** ID's session_uid management. *** */

#define MAIN_ID_SESSION_UID_UNSET 0

void BKE_lib_libblock_session_uid_ensure(ID *id);
void BKE_lib_libblock_session_uid_renew(ID *id);

void *BKE_id_new(Main *bmain, short type, const char *name);
 
template<typename T> inline T *BKE_id_new(Main *bmain, const char *name)
{
  const ID_Type id_type = T::id_type;
  return static_cast<T *>(BKE_id_new(bmain, id_type, name));
}

void *BKE_id_new_in_lib(Main *bmain,
                        std::optional<Library *> owner_library,
                        short type,
                        const char *name);
void *BKE_id_new_nomain(short type, const char *name);
 
template<typename T> inline T *BKE_id_new_nomain(const char *name)
{
  const ID_Type id_type = T::id_type;
  return static_cast<T *>(BKE_id_new_nomain(id_type, name));
}

enum {
  /* *** Generic options (should be handled by all ID types copying, ID creation, etc.). *** */
  LIB_ID_CREATE_NO_MAIN = 1 << 0,
  LIB_ID_CREATE_NO_USER_REFCOUNT = 1 << 1,
  LIB_ID_CREATE_NO_ALLOCATE = 1 << 2,

  LIB_ID_CREATE_NO_DEG_TAG = 1 << 8,

  LIB_ID_CREATE_LOCAL = 1 << 9,

  LIB_ID_COPY_SET_COPIED_ON_WRITE = 1 << 10,
 
  /* *** Specific options to some ID types or usages. *** */
  /* *** May be ignored by unrelated ID copying functions. *** */
  /* LIB_ID_COPY_NO_PROXY_CLEAR = 1 << 16, */ /* UNUSED */
  LIB_ID_COPY_NO_PREVIEW = 1 << 17,
  LIB_ID_COPY_CACHES = 1 << 18,
  LIB_ID_COPY_NO_ANIMDATA = 1 << 19,
  LIB_ID_COPY_NO_LIB_OVERRIDE = 1 << 21,
  LIB_ID_COPY_NO_LIB_OVERRIDE_LOCAL_DATA_FLAG = 1 << 22,
 
  /* *** XXX Hackish/not-so-nice specific behaviors needed for some corner cases. *** */
  /* *** Ideally we should not have those, but we need them for now... *** */
  LIB_ID_COPY_ACTIONS = 1 << 24,
  LIB_ID_COPY_SHAPEKEY = 1 << 26,
  LIB_ID_COPY_NODETREE_LOCALIZE = 1 << 27,
  LIB_ID_COPY_RIGID_BODY_NO_COLLECTION_HANDLING = 1 << 28,
  /* Copy asset metadata. */
  LIB_ID_COPY_ASSET_METADATA = 1 << 29,
 
  /* *** Helper 'defines' gathering most common flag sets. *** */
  LIB_ID_COPY_DEFAULT = LIB_ID_COPY_SHAPEKEY,

  LIB_ID_CREATE_LOCALIZE = LIB_ID_CREATE_NO_MAIN | LIB_ID_CREATE_NO_USER_REFCOUNT |
                           LIB_ID_CREATE_NO_DEG_TAG,
  LIB_ID_COPY_LOCALIZE = LIB_ID_CREATE_LOCALIZE | LIB_ID_COPY_NO_PREVIEW | LIB_ID_COPY_CACHES |
                         LIB_ID_COPY_NO_LIB_OVERRIDE,
};
 
void BKE_libblock_copy_ex(Main *bmain, const ID *id, ID **new_id_p, int orig_flag);
void BKE_libblock_copy_in_lib(Main *bmain,
                              std::optional<Library *> owner_library,
                              const ID *id,
                              std::optional<const ID *> new_owner_id,
                              ID **new_id_p,
                              int orig_flag);

void *BKE_libblock_copy(Main *bmain, const ID *id) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();

void BKE_id_move_to_same_lib(Main &bmain, ID &id, const ID &owner_id);

enum class IDNewNameMode {
  RenameExistingNever = 0,
  RenameExistingAlways = 1,
  RenameExistingSameRoot = 2,
};

struct IDNewNameResult {
  enum class Action {
    UNCHANGED = 0,
    UNCHANGED_COLLISION = 1,
    RENAMED_NO_COLLISION = 2,
    RENAMED_COLLISION_ADJUSTED = 3,
    RENAMED_COLLISION_FORCED = 4,
  } action = Action::UNCHANGED;

  ID *other_id = nullptr;
};

IDNewNameResult BKE_libblock_rename(Main &bmain,
                                    ID &id,
                                    blender::StringRefNull name,
                                    const IDNewNameMode mode = IDNewNameMode::RenameExistingNever);

IDNewNameResult BKE_id_rename(Main &bmain,
                              ID &id,
                              blender::StringRefNull name,
                              const IDNewNameMode mode = IDNewNameMode::RenameExistingNever);
 
ID *BKE_libblock_find_name(Main *bmain,
                           short type,
                           const char *name,
                           const std::optional<Library *> lib = std::nullopt)
    ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
ID *BKE_libblock_find_session_uid(Main *bmain, short type, uint32_t session_uid);
ID *BKE_libblock_find_session_uid(Main *bmain, uint32_t session_uid);
ID *BKE_libblock_find_name_and_library(Main *bmain,
                                       short type,
                                       const char *name,
                                       const char *lib_name);
ID *BKE_libblock_find_name_and_library_filepath(Main *bmain,
                                                short type,
                                                const char *name,
                                                const char *lib_filepath_abs);

enum eLibIDDuplicateFlags {
  LIB_ID_DUPLICATE_IS_SUBPROCESS = 1 << 0,
  LIB_ID_DUPLICATE_IS_ROOT_ID = 1 << 1,
};
 
ENUM_OPERATORS(eLibIDDuplicateFlags, LIB_ID_DUPLICATE_IS_ROOT_ID)
 
/* `lib_remap.cc` (keep here since they're general functions) */
enum {
  /* *** Generic options (should be handled by all ID types freeing). *** */
  LIB_ID_FREE_NO_MAIN = 1 << 0,
  LIB_ID_FREE_NO_USER_REFCOUNT = 1 << 1,
  LIB_ID_FREE_NOT_ALLOCATED = 1 << 2,

  LIB_ID_FREE_NO_DEG_TAG = 1 << 8,
  LIB_ID_FREE_NO_UI_USER = 1 << 9,
  LIB_ID_FREE_NO_NAMEMAP_REMOVE = 1 << 10,
};

void BKE_libblock_free_datablock(ID *id, int flag) ATTR_NONNULL();
void BKE_libblock_free_data(ID *id, bool do_id_user) ATTR_NONNULL();
void BKE_libblock_free_runtime_data(ID *id) ATTR_NONNULL();

void BKE_libblock_free_data_py(ID *id);

void BKE_id_free_ex(Main *bmain, void *idv, int flag_orig, bool use_flag_from_idtag);
void BKE_id_free(Main *bmain, void *idv);

void BKE_id_free_us(Main *bmain, void *idv) ATTR_NONNULL();

void BKE_id_delete(Main *bmain, void *idv) ATTR_NONNULL();
void BKE_id_delete_ex(Main *bmain, void *idv, const int extra_remapping_flags) ATTR_NONNULL(1, 2);
size_t BKE_id_multi_tagged_delete(Main *bmain) ATTR_NONNULL();
size_t BKE_id_multi_delete(Main *bmain, blender::Set<ID *> &ids_to_delete);

void BKE_libblock_management_main_add(Main *bmain, void *idv);
void BKE_libblock_management_main_remove(Main *bmain, void *idv);
 
void BKE_libblock_management_usercounts_set(Main *bmain, void *idv);
void BKE_libblock_management_usercounts_clear(Main *bmain, void *idv);
 
void id_lib_extern(ID *id);
void id_lib_indirect_weak_link(ID *id);
void id_us_ensure_real(ID *id);
void id_us_clear_real(ID *id);
void id_us_plus_no_lib(ID *id);
void id_us_plus(ID *id);
/* decrements the user count for *id. */
void id_us_min(ID *id);
void id_fake_user_set(ID *id);
void id_fake_user_clear(ID *id);
void BKE_id_newptr_and_tag_clear(ID *id);

enum {
  LIB_ID_MAKELOCAL_FULL_LIBRARY = 1 << 0,
  LIB_ID_MAKELOCAL_INDIRECT = 1 << 1,

  LIB_ID_MAKELOCAL_FORCE_LOCAL = 1 << 8,
  LIB_ID_MAKELOCAL_FORCE_COPY = 1 << 9,

  LIB_ID_MAKELOCAL_ASSET_DATA_CLEAR = 1 << 16,

  LIB_ID_MAKELOCAL_LIBOVERRIDE_CLEAR = 1 << 17,
};

void BKE_lib_id_make_local_generic_action_define(
    Main *bmain, ID *id, int flags, bool *r_force_local, bool *r_force_copy);
void BKE_lib_id_make_local_generic(Main *bmain, ID *id, int flags);
bool BKE_lib_id_make_local(Main *bmain, ID *id, int flags);
bool id_single_user(bContext *C, ID *id, PointerRNA *ptr, PropertyRNA *prop);

bool BKE_id_copy_is_allowed(const ID *id);
ID *BKE_id_copy_ex(Main *bmain, const ID *id, ID **new_id_p, int flag);
struct ID *BKE_id_copy_in_lib(Main *bmain,
                              std::optional<Library *> owner_library,
                              const ID *id,
                              std::optional<const ID *> new_owner_id,
                              ID **new_id_p,
                              int flag);
ID *BKE_id_copy(Main *bmain, const ID *id);

ID *BKE_id_copy_for_duplicate(Main *bmain,
                              ID *id,
                              eDupli_ID_Flags duplicate_flags,
                              int copy_flags);

ID *BKE_id_copy_for_use_in_bmain(Main *bmain, const ID *id);

void BKE_lib_id_swap(
    Main *bmain, ID *id_a, ID *id_b, const bool do_self_remap, const int self_remap_flags);
void BKE_lib_id_swap_full(
    Main *bmain, ID *id_a, ID *id_b, const bool do_self_remap, const int self_remap_flags);

void id_sort_by_name(ListBase *lb, ID *id, ID *id_sorting_hint);
void BKE_lib_id_expand_local(Main *bmain, ID *id, int flags);

IDNewNameResult BKE_id_new_name_validate(Main &bmain,
                                         ListBase &lb,
                                         ID &id,
                                         const char *newname,
                                         IDNewNameMode mode,
                                         bool do_linked_data);

void BKE_lib_id_clear_library_data(Main *bmain, ID *id, int flags);

void BKE_main_id_tag_idcode(Main *mainvar, short type, int tag, bool value);
void BKE_main_id_tag_listbase(ListBase *lb, int tag, bool value);
void BKE_main_id_tag_all(Main *mainvar, int tag, bool value);

void BKE_main_id_flag_listbase(ListBase *lb, int flag, bool value);
void BKE_main_id_flag_all(Main *bmain, int flag, bool value);

void BKE_main_id_newptr_and_tag_clear(Main *bmain);
 
void BKE_main_id_refcount_recompute(Main *bmain, bool do_linked_only);
 
void BKE_main_lib_objects_recalc_all(Main *bmain);

void BKE_main_id_repair_duplicate_names_listbase(Main *bmain, 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. */
void BKE_id_full_name_get(char name[MAX_ID_FULL_NAME], const ID *id, char separator_char);
void BKE_id_full_name_ui_prefix_get(char name[MAX_ID_FULL_NAME_UI],
                                    const ID *id,
                                    bool add_lib_hint,
                                    char separator_char,
                                    int *r_prefix_len);

inline const char *BKE_id_name(const ID &id)
{
  return id.name + 2;
}
inline char *BKE_id_name(ID &id)
{
  return id.name + 2;
}

char *BKE_id_to_unique_string_key(const ID *id);

void BKE_library_make_local(Main *bmain,
                            const Library *lib,
                            GHash *old_to_new_ids,
                            bool untagged_only,
                            bool set_fake,
                            bool clear_asset_data);
 
void BKE_id_tag_set_atomic(ID *id, int tag);
void BKE_id_tag_clear_atomic(ID *id, int tag);

bool BKE_id_is_in_main(Main *bmain, ID *id);
bool BKE_id_is_in_global_main(ID *id);
 
bool BKE_id_can_be_asset(const ID *id);

ID *BKE_id_owner_get(ID *id, const bool debug_relationship_assert = true);

bool BKE_id_is_editable(const Main *bmain, const ID *id);

bool BKE_id_can_use_id(const ID &id_from, const ID &id_to);

blender::Vector<ID *> BKE_id_ordered_list(const ListBase *lb);
void BKE_id_reorder(const ListBase *lb, ID *id, ID *relative, bool after);
 
void BKE_id_blend_write(BlendWriter *writer, ID *id);
 
#define IS_TAGGED(_id) ((_id) && (((ID *)_id)->tag & ID_TAG_DOIT))
 
/* `lib_id_eval.cc` */

void BKE_id_eval_properties_copy(ID *id_cow, ID *id);