diff options
Diffstat (limited to 'source/blender/blenkernel/BKE_main.h')
| -rw-r--r-- | source/blender/blenkernel/BKE_main.h | 114 |
1 files changed, 108 insertions, 6 deletions
diff --git a/source/blender/blenkernel/BKE_main.h b/source/blender/blenkernel/BKE_main.h index 9ded97e0003..41ef5e3f5ba 100644 --- a/source/blender/blenkernel/BKE_main.h +++ b/source/blender/blenkernel/BKE_main.h @@ -116,12 +116,14 @@ enum { typedef struct Main { struct Main *next, *prev; - char name[1024]; /* 1024 = FILE_MAX */ + /** The file-path of this blend file, an empty string indicates an unsaved file. */ + char filepath[1024]; /* 1024 = FILE_MAX */ short versionfile, subversionfile; /* see BLENDER_FILE_VERSION, BLENDER_FILE_SUBVERSION */ short minversionfile, minsubversionfile; uint64_t build_commit_timestamp; /* commit's timestamp from buildinfo */ char build_hash[16]; /* hash from buildinfo */ - char recovered; /* indicate the main->name (file) is the recovered one */ + /** Indicate the #Main.filepath (file) is the recovered one. */ + char recovered; /** All current ID's exist in the last memfile undo step. */ char is_memfile_undo_written; /** @@ -201,40 +203,99 @@ typedef struct Main { struct Main *BKE_main_new(void); void BKE_main_free(struct Main *mainvar); +/** + * Check whether given `bmain` is empty or contains some IDs. + */ bool BKE_main_is_empty(struct Main *bmain); void BKE_main_lock(struct Main *bmain); void BKE_main_unlock(struct Main *bmain); +/** Generate the mappings between used IDs and their users, and vice-versa. */ void BKE_main_relations_create(struct Main *bmain, const short flag); void BKE_main_relations_free(struct Main *bmain); +/** Set or clear given `tag` in all relation entries of given `bmain`. */ void BKE_main_relations_tag_set(struct Main *bmain, const eMainIDRelationsEntryTags tag, const bool value); +/** + * Create a #GSet storing all IDs present in given \a bmain, by their pointers. + * + * \param gset: If not NULL, given GSet will be extended with IDs from given \a bmain, + * instead of creating a new one. + */ struct GSet *BKE_main_gset_create(struct Main *bmain, struct GSet *gset); -/* - * Temporary runtime API to allow re-using local (already appended) IDs instead of appending a new - * copy again. - */ +/* Temporary runtime API to allow re-using local (already appended) + * IDs instead of appending a new copy again. */ +/** + * Generate a mapping between 'library path' of an ID + * (as a pair (relative blend file path, id name)), and a current local ID, if any. + * + * This uses the information stored in `ID.library_weak_reference`. + */ struct GHash *BKE_main_library_weak_reference_create(struct Main *bmain) ATTR_NONNULL(); +/** + * Destroy the data generated by #BKE_main_library_weak_reference_create. + */ void BKE_main_library_weak_reference_destroy(struct GHash *library_weak_reference_mapping) ATTR_NONNULL(); +/** + * Search for a local ID matching the given linked ID reference. + * + * \param library_weak_reference_mapping: the mapping data generated by + * #BKE_main_library_weak_reference_create. + * \param library_filepath: the path of a blend file library (relative to current working one). + * \param library_id_name: the full ID name, including the leading two chars encoding the ID + * type. + */ struct ID *BKE_main_library_weak_reference_search_item( struct GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name) ATTR_NONNULL(); +/** + * Add the given ID weak library reference to given local ID and the runtime mapping. + * + * \param library_weak_reference_mapping: the mapping data generated by + * #BKE_main_library_weak_reference_create. + * \param library_filepath: the path of a blend file library (relative to current working one). + * \param library_id_name: the full ID name, including the leading two chars encoding the ID type. + * \param new_id: New local ID matching given weak reference. + */ void BKE_main_library_weak_reference_add_item(struct GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name, struct ID *new_id) ATTR_NONNULL(); +/** + * Update the status of the given ID weak library reference in current local IDs and the runtime + * mapping. + * + * This effectively transfers the 'ownership' of the given weak reference from `old_id` to + * `new_id`. + * + * \param library_weak_reference_mapping: the mapping data generated by + * #BKE_main_library_weak_reference_create. + * \param library_filepath: the path of a blend file library (relative to current working one). + * \param library_id_name: the full ID name, including the leading two chars encoding the ID type. + * \param old_id: Existing local ID matching given weak reference. + * \param new_id: New local ID matching given weak reference. + */ void BKE_main_library_weak_reference_update_item(struct GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name, struct ID *old_id, struct ID *new_id) ATTR_NONNULL(); +/** + * Remove the given ID weak library reference from the given local ID and the runtime mapping. + * + * \param library_weak_reference_mapping: the mapping data generated by + * #BKE_main_library_weak_reference_create. + * \param library_filepath: the path of a blend file library (relative to current working one). + * \param library_id_name: the full ID name, including the leading two chars encoding the ID type. + * \param old_id: Existing local ID matching given weak reference. + */ void BKE_main_library_weak_reference_remove_item(struct GHash *library_weak_reference_mapping, const char *library_filepath, const char *library_id_name, @@ -286,16 +347,57 @@ void BKE_main_library_weak_reference_remove_item(struct GHash *library_weak_refe } \ ((void)0) +/** + * Generates a raw .blend file thumbnail data from given image. + * + * \param bmain: If not NULL, also store generated data in this Main. + * \param img: ImBuf image to generate thumbnail data from. + * \return The generated .blend file raw thumbnail data. + */ struct BlendThumbnail *BKE_main_thumbnail_from_imbuf(struct Main *bmain, struct ImBuf *img); +/** + * Generates an image from raw .blend file thumbnail \a data. + * + * \param bmain: Use this bmain->blen_thumb data if given \a data is NULL. + * \param data: Raw .blend file thumbnail data. + * \return An ImBuf from given data, or NULL if invalid. + */ struct ImBuf *BKE_main_thumbnail_to_imbuf(struct Main *bmain, struct BlendThumbnail *data); +/** + * Generates an empty (black) thumbnail for given Main. + */ void BKE_main_thumbnail_create(struct Main *bmain); +/** + * Return file-path of given \a main. + */ const char *BKE_main_blendfile_path(const struct Main *bmain) ATTR_NONNULL(); +/** + * Return file-path of global main #G_MAIN. + * + * \warning Usage is not recommended, + * you should always try to get a valid Main pointer from context. + */ const char *BKE_main_blendfile_path_from_global(void); +/** + * \return A pointer to the \a ListBase of given \a bmain for requested \a type ID type. + */ struct ListBase *which_libbase(struct Main *bmain, short type); //#define INDEX_ID_MAX 41 +/** + * Put the pointers to all the #ListBase structs in given `bmain` into the `*lb[INDEX_ID_MAX]` + * array, and return the number of those for convenience. + * + * This is useful for generic traversal of all the blocks in a #Main (by traversing all the lists + * in turn), without worrying about block types. + * + * \param lb: Array of lists #INDEX_ID_MAX in length. + * + * \note The order of each ID type #ListBase in the array is determined by the `INDEX_ID_<IDTYPE>` + * enum definitions in `DNA_ID.h`. See also the #FOREACH_MAIN_ID_BEGIN macro in `BKE_main.h` + */ int set_listbasepointers(struct Main *main, struct ListBase *lb[]); #define MAIN_VERSION_ATLEAST(main, ver, subver) \ |