diff options
author | Bastien Montagne <montagne29@wanadoo.fr> | 2015-10-12 15:21:34 +0300 |
---|---|---|
committer | Bastien Montagne <montagne29@wanadoo.fr> | 2015-10-12 15:30:00 +0300 |
commit | 6f41febff17f80485485a4dbadf483617f3901be (patch) | |
tree | 02265cc4a0a3a6e64fd98d7986d42d1a3d1d83a1 /source/blender/blenloader | |
parent | 4bc08d09aedafb8986eb742b8d8c1a0a58876cd5 (diff) |
Cleanup: BLO: move func doc comments to definitions of functions.
Follows our conventions and makes include file itself much cleaner.
Diffstat (limited to 'source/blender/blenloader')
-rw-r--r-- | source/blender/blenloader/BLO_readfile.h | 189 | ||||
-rw-r--r-- | source/blender/blenloader/intern/readblenentry.c | 71 | ||||
-rw-r--r-- | source/blender/blenloader/intern/readfile.c | 81 |
3 files changed, 159 insertions, 182 deletions
diff --git a/source/blender/blenloader/BLO_readfile.h b/source/blender/blenloader/BLO_readfile.h index 1ab83a503ec..44c6d270cf5 100644 --- a/source/blender/blenloader/BLO_readfile.h +++ b/source/blender/blenloader/BLO_readfile.h @@ -70,183 +70,35 @@ typedef struct BlendFileData { BlenFileType type; } BlendFileData; -/** - * Open a blender file from a pathname. The function - * returns NULL and sets a report in the list if - * it cannot open the file. - * - * \param filepath The path of the file to open. - * \param reports If the return value is NULL, errors - * indicating the cause of the failure. - * \return The data of the file. - */ -BlendFileData *BLO_read_from_file( - const char *filepath, - struct ReportList *reports); - -/** - * Open a blender file from memory. The function - * returns NULL and sets a report in the list if - * it cannot open the file. - * - * \param mem The file data. - * \param memsize The length of \a mem. - * \param reports If the return value is NULL, errors - * indicating the cause of the failure. - * \return The data of the file. - */ -BlendFileData *BLO_read_from_memory( - const void *mem, int memsize, - struct ReportList *reports); - -/** - * oldmain is old main, from which we will keep libraries, images, .. - * file name is current file, only for retrieving library data */ - +BlendFileData *BLO_read_from_file(const char *filepath, struct ReportList *reports); +BlendFileData *BLO_read_from_memory(const void *mem, int memsize, struct ReportList *reports); BlendFileData *BLO_read_from_memfile( struct Main *oldmain, const char *filename, struct MemFile *memfile, struct ReportList *reports); -/** - * Free's a BlendFileData structure and _all_ the - * data associated with it (the userdef data, and - * the main libblock data). - * - * \param bfd The structure to free. - */ -void -BLO_blendfiledata_free(BlendFileData *bfd); - -/** - * Open a blendhandle from a file path. - * - * \param filepath: The file path to open. - * \param reports: Report errors in opening the file (can be NULL). - * \return A handle on success, or NULL on failure. - */ -BlendHandle *BLO_blendhandle_from_file( - const char *filepath, - struct ReportList *reports); - -/** - * Open a blendhandle from memory. - * - * \param mem The data to load from. - * \param memsize The size of the data. - * \return A handle on success, or NULL on failure. - */ - -BlendHandle *BLO_blendhandle_from_memory( - const void *mem, int memsize); - -/** - * Gets the names of all the datablocks in a file - * of a certain type (ie. All the scene names in - * a file). - * - * \param bh The blendhandle to access. - * \param ofblocktype The type of names to get. - * \param tot_names The length of the returned list. - * \return A BLI_linklist of strings. The string links - * should be freed with malloc. - */ -struct LinkNode *BLO_blendhandle_get_datablock_names( - BlendHandle *bh, - int ofblocktype, int *tot_names); +void BLO_blendfiledata_free(BlendFileData *bfd); -/** - * Gets the previews of all the datablocks in a file - * of a certain type (ie. All the scene names in - * a file). - * - * \param bh The blendhandle to access. - * \param ofblocktype The type of names to get. - * \param tot_prev The length of the returned list. - * \return A BLI_linklist of PreviewImage. The PreviewImage links - * should be freed with malloc. - */ -struct LinkNode *BLO_blendhandle_get_previews( - BlendHandle *bh, - int ofblocktype, int *tot_prev); +BlendHandle *BLO_blendhandle_from_file(const char *filepath, struct ReportList *reports); +BlendHandle *BLO_blendhandle_from_memory(const void *mem, int memsize); -/** - * Gets the names of all the datablock groups in a - * file. (ie. file contains Scene, Mesh, and Lamp - * datablocks). - * - * \param bh The blendhandle to access. - * \return A BLI_linklist of strings. The string links - * should be freed with malloc. - */ +struct LinkNode *BLO_blendhandle_get_datablock_names(BlendHandle *bh, int ofblocktype, int *tot_names); +struct LinkNode *BLO_blendhandle_get_previews(BlendHandle *bh, int ofblocktype, int *tot_prev); struct LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh); -/** - * Close and free a blendhandle. The handle - * becomes invalid after this call. - * - * \param bh The handle to close. - */ -void -BLO_blendhandle_close(BlendHandle *bh); +void BLO_blendhandle_close(BlendHandle *bh); /***/ #define BLO_GROUP_MAX 32 bool BLO_has_bfile_extension(const char *str); - -/** - * \param path the full path to explode. - * \param r_dir the string that'll contain path up to blend file itself ('library' path). - * \param r_group the string that'll contain 'group' part of the path, if any. May be NULL. - * \param r_name the string that'll contain data's name part of the path, if any. May be NULL. - * \return true if path contains a blend file. - */ bool BLO_library_path_explode(const char *path, char *r_dir, char **r_group, char **r_name); - -/** - * Initialize the BlendHandle for appending or linking library data. - * - * \param mainvar The current main database eg G.main or CTX_data_main(C). - * \param bh A blender file handle as returned by BLO_blendhandle_from_file or BLO_blendhandle_from_memory. - * \param filepath Used for relative linking, copied to the lib->name - * \return the library Main, to be passed to BLO_library_append_named_part as mainl. - */ -struct Main *BLO_library_link_begin( - struct Main *mainvar, BlendHandle **bh, - const char *filepath); - - -/** - * Link a named datablock from an external blend file. - * - * \param mainl The main database to link from (not the active one). - * \param bh The blender file handle. - * \param idname The name of the datablock (without the 2 char ID prefix) - * \param idcode The kind of datablock to link. - * \return the appended ID when found. - */ -struct ID *BLO_library_link_named_part( - struct Main *mainl, BlendHandle **bh, - const char *idname, const int idcode); - -/** - * Link a named datablock from an external blend file. - * optionally instantiate the object/group in the scene when the flags are set. - * - * \param C The context, when NULL instancing object in the scene isn't done. - * \param mainl The main database to link from (not the active one). - * \param bh The blender file handle. - * \param idname The name of the datablock (without the 2 char ID prefix) - * \param idcode The kind of datablock to link. - * \param flag Options for linking, used for instancing. - * \return the appended ID when found. - */ +struct Main *BLO_library_link_begin(struct Main *mainvar, BlendHandle **bh, const char *filepath); +struct ID *BLO_library_link_named_part(struct Main *mainl, BlendHandle **bh, const char *idname, const int idcode); struct ID *BLO_library_link_named_part_ex( const struct bContext *C, struct Main *mainl, BlendHandle **bh, const char *idname, const int idcode, const short flag); - void BLO_library_link_end(const struct bContext *C, struct Main *mainl, BlendHandle **bh, int idcode, short flag); void BLO_library_link_all(struct Main *mainl, BlendHandle *bh); @@ -258,34 +110,13 @@ BlendFileData *blo_read_blendafterruntime(int file, const char *name, int actual /* internal function but we need to expose it */ void blo_lib_link_screen_restore(struct Main *newmain, struct bScreen *curscreen, struct Scene *curscene); -/** - * BLO_expand_main() loops over all ID data in Main to mark relations. - * Set (id->flag & LIB_NEED_EXPAND) to mark expanding. Flags get cleared after expanding. - * - * \param expand_doit_func() gets called for each ID block it finds - */ void BLO_main_expander(void (*expand_doit_func)(void *, struct Main *, void *)); - -/** - * BLO_expand_main() loops over all ID data in Main to mark relations. - * Set (id->flag & LIB_NEED_EXPAND) to mark expanding. Flags get cleared after expanding. - * - * \param fdhandle usually filedata, or own handle - * \param mainvar the Main database to expand - */ void BLO_expand_main(void *fdhandle, struct Main *mainvar); /* Update defaults in startup.blend & userprefs.blend, without having to save and embed it */ void BLO_update_defaults_userpref_blend(void); void BLO_update_defaults_startup_blend(struct Main *mainvar); -/** - * Does a very light reading of given .blend file to extract its stored thumbnail. - * - * \param filepath The path of the file to extract thumbnail from. - * \return The raw thumbnail - * (MEM-allocated, as stored in file, use BKE_main_thumbnail_to_imbuf() to convert it to ImBuf image). - */ struct BlendThumbnail *BLO_thumbnail_from_file(const char *filepath); #ifdef __cplusplus diff --git a/source/blender/blenloader/intern/readblenentry.c b/source/blender/blenloader/intern/readblenentry.c index 6132a091116..cd6df354ca7 100644 --- a/source/blender/blenloader/intern/readblenentry.c +++ b/source/blender/blenloader/intern/readblenentry.c @@ -72,6 +72,13 @@ void BLO_blendhandle_print_sizes(BlendHandle *, void *); /* Access routines used by filesel. */ +/** + * Open a blendhandle from a file path. + * + * \param filepath The file path to open. + * \param reports Report errors in opening the file (can be NULL). + * \return A handle on success, or NULL on failure. + */ BlendHandle *BLO_blendhandle_from_file(const char *filepath, ReportList *reports) { BlendHandle *bh; @@ -81,6 +88,13 @@ BlendHandle *BLO_blendhandle_from_file(const char *filepath, ReportList *reports return bh; } +/** + * Open a blendhandle from memory. + * + * \param mem The data to load from. + * \param memsize The size of the data. + * \return A handle on success, or NULL on failure. + */ BlendHandle *BLO_blendhandle_from_memory(const void *mem, int memsize) { BlendHandle *bh; @@ -120,6 +134,14 @@ void BLO_blendhandle_print_sizes(BlendHandle *bh, void *fp) fprintf(fp, "]\n"); } +/** + * Gets the names of all the datablocks in a file of a certain type (e.g. all the scene names in a file). + * + * \param bh The blendhandle to access. + * \param ofblocktype The type of names to get. + * \param tot_names The length of the returned list. + * \return A BLI_linklist of strings. The string links should be freed with malloc. + */ LinkNode *BLO_blendhandle_get_datablock_names(BlendHandle *bh, int ofblocktype, int *tot_names) { FileData *fd = (FileData *) bh; @@ -142,6 +164,14 @@ LinkNode *BLO_blendhandle_get_datablock_names(BlendHandle *bh, int ofblocktype, return names; } +/** + * Gets the previews of all the datablocks in a file of a certain type (e.g. all the scene previews in a file). + * + * \param bh The blendhandle to access. + * \param ofblocktype The type of names to get. + * \param tot_prev The length of the returned list. + * \return A BLI_linklist of PreviewImage. The PreviewImage links should be freed with malloc. + */ LinkNode *BLO_blendhandle_get_previews(BlendHandle *bh, int ofblocktype, int *tot_prev) { FileData *fd = (FileData *) bh; @@ -232,7 +262,13 @@ LinkNode *BLO_blendhandle_get_previews(BlendHandle *bh, int ofblocktype, int *to return previews; } -LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh) +/** + * Gets the names of all the linkable datablock types available in a file. (e.g. "Scene", "Mesh", "Lamp", etc.). + * + * \param bh The blendhandle to access. + * \return A BLI_linklist of strings. The string links should be freed with malloc. + */ +LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh) { FileData *fd = (FileData *) bh; GSet *gathered = BLI_gset_ptr_new("linkable_groups gh"); @@ -260,6 +296,11 @@ LinkNode *BLO_blendhandle_get_linkable_groups(BlendHandle *bh) return names; } +/** + * Close and free a blendhandle. The handle becomes invalid after this call. + * + * \param bh The handle to close. + */ void BLO_blendhandle_close(BlendHandle *bh) { FileData *fd = (FileData *) bh; @@ -269,6 +310,14 @@ void BLO_blendhandle_close(BlendHandle *bh) /**********/ +/** + * Open a blender file from a pathname. The function returns NULL + * and sets a report in the list if it cannot open the file. + * + * \param filepath The path of the file to open. + * \param reports If the return value is NULL, errors indicating the cause of the failure. + * \return The data of the file. + */ BlendFileData *BLO_read_from_file(const char *filepath, ReportList *reports) { BlendFileData *bfd = NULL; @@ -284,6 +333,15 @@ BlendFileData *BLO_read_from_file(const char *filepath, ReportList *reports) return bfd; } +/** + * Open a blender file from memory. The function returns NULL + * and sets a report in the list if it cannot open the file. + * + * \param mem The file data. + * \param memsize The length of \a mem. + * \param reports If the return value is NULL, errors indicating the cause of the failure. + * \return The data of the file. + */ BlendFileData *BLO_read_from_memory(const void *mem, int memsize, ReportList *reports) { BlendFileData *bfd = NULL; @@ -299,6 +357,12 @@ BlendFileData *BLO_read_from_memory(const void *mem, int memsize, ReportList *re return bfd; } +/** + * Used for undo/redo, skips part of libraries reading (assuming their data are already loaded & valid). + * + * \param oldmain old main, from which we will keep libraries and other datablocks that should not have changed. + * \param filename current file, only for retrieving library data. + */ BlendFileData *BLO_read_from_memfile(Main *oldmain, const char *filename, MemFile *memfile, ReportList *reports) { BlendFileData *bfd = NULL; @@ -384,6 +448,11 @@ BlendFileData *BLO_read_from_memfile(Main *oldmain, const char *filename, MemFil return bfd; } +/** + * Frees a BlendFileData structure and *all* the data associated with it (the userdef data, and the main libblock data). + * + * \param bfd The structure to free. + */ void BLO_blendfiledata_free(BlendFileData *bfd) { if (bfd->main) { diff --git a/source/blender/blenloader/intern/readfile.c b/source/blender/blenloader/intern/readfile.c index 835bd59fb31..b4965da345d 100644 --- a/source/blender/blenloader/intern/readfile.c +++ b/source/blender/blenloader/intern/readfile.c @@ -1299,12 +1299,27 @@ void blo_freefiledata(FileData *fd) /* ************ DIV ****************** */ +/** + * Check whether given path ends with a blend file compatible extension (.blend, .ble or .blend.gz). + * + * \param str The path to check. + * \return true is this path ends with a blender file extension. + */ bool BLO_has_bfile_extension(const char *str) { const char *ext_test[4] = {".blend", ".ble", ".blend.gz", NULL}; return BLI_testextensie_array(str, ext_test); } +/** + * Try to explode given path into its 'library components' (i.e. a .blend file, id type/group, and datablock itself). + * + * \param path the full path to explode. + * \param r_dir the string that'll contain path up to blend file itself ('library' path). + * \param r_group the string that'll contain 'group' part of the path, if any. May be NULL. + * \param r_name the string that'll contain data's name part of the path, if any. May be NULL. + * \return true if path contains a blend file. + */ bool BLO_library_path_explode(const char *path, char *r_dir, char **r_group, char **r_name) { /* We might get some data names with slashes, so we have to go up in path until we find blend file itself, @@ -1361,6 +1376,13 @@ bool BLO_library_path_explode(const char *path, char *r_dir, char **r_group, cha return true; } +/** + * Does a very light reading of given .blend file to extract its stored thumbnail. + * + * \param filepath The path of the file to extract thumbnail from. + * \return The raw thumbnail + * (MEM-allocated, as stored in file, use BKE_main_thumbnail_to_imbuf() to convert it to ImBuf image). + */ BlendThumbnail *BLO_thumbnail_from_file(const char *filepath) { FileData *fd; @@ -9377,11 +9399,23 @@ static void expand_gpencil(FileData *fd, Main *mainvar, bGPdata *gpd) expand_animdata(fd, mainvar, gpd->adt); } +/** + * Set the callback func used over all ID data found by \a BLO_expand_main func. + * + * \param expand_doit_func Called for each ID block it finds. + */ void BLO_main_expander(void (*expand_doit_func)(void *, Main *, void *)) { expand_doit = expand_doit_func; } +/** + * Loop over all ID data in Main to mark relations. + * Set (id->flag & LIB_NEED_EXPAND) to mark expanding. Flags get cleared after expanding. + * + * \param fdhandle usually filedata, or own handle. + * \param mainvar the Main database to expand. + */ void BLO_expand_main(void *fdhandle, Main *mainvar) { ListBase *lbarray[MAX_LIBARRAY]; @@ -9637,7 +9671,9 @@ static ID *link_named_part(Main *mainl, FileData *fd, const char *idname, const return id; } -/* simple reader for copy/paste buffers */ +/** + * Simple reader for copy/paste buffers. + */ void BLO_library_link_all(Main *mainl, BlendHandle *bh) { FileData *fd = (FileData *)(bh); @@ -9701,13 +9737,36 @@ static ID *link_named_part_ex(const bContext *C, Main *mainl, FileData *fd, cons return id; } +/** + * Link a named datablock from an external blend file. + * + * \param mainl The main database to link from (not the active one). + * \param bh The blender file handle. + * \param idname The name of the datablock (without the 2 char ID prefix). + * \param idcode The kind of datablock to link. + * \return the appended ID when found. + */ ID *BLO_library_link_named_part(Main *mainl, BlendHandle **bh, const char *idname, const int idcode) { FileData *fd = (FileData*)(*bh); return link_named_part(mainl, fd, idname, idcode); } -ID *BLO_library_link_named_part_ex(const bContext *C, Main *mainl, BlendHandle **bh, const char *idname, const int idcode, const short flag) +/** + * Link a named datablock from an external blend file. + * Optionally instantiate the object/group in the scene when the flags are set. + * + * \param C The context, when NULL instantiating object in the scene isn't done. + * \param mainl The main database to link from (not the active one). + * \param bh The blender file handle. + * \param idname The name of the datablock (without the 2 char ID prefix). + * \param idcode The kind of datablock to link. + * \param flag Options for linking, used for instantiating. + * \return the appended ID when found. + */ +ID *BLO_library_link_named_part_ex( + const bContext *C, Main *mainl, BlendHandle **bh, + const char *idname, const int idcode, const short flag) { FileData *fd = (FileData*)(*bh); return link_named_part_ex(C, mainl, fd, idname, idcode, flag); @@ -9752,6 +9811,14 @@ static Main *library_link_begin(Main *mainvar, FileData **fd, const char *filepa return mainl; } +/** + * Initialize the BlendHandle for linking library data. + * + * \param mainvar The current main database, e.g. G.main or CTX_data_main(C). + * \param bh A blender file handle as returned by \a BLO_blendhandle_from_file or \a BLO_blendhandle_from_memory. + * \param filepath Used for relative linking, copied to the \a lib->name. + * \return the library Main, to be passed to \a BLO_library_append_named_part as \a mainl. + */ Main *BLO_library_link_begin(Main *mainvar, BlendHandle **bh, const char *filepath) { FileData *fd = (FileData*)(*bh); @@ -9830,6 +9897,16 @@ static void library_link_end(const bContext *C, Main *mainl, FileData **fd, int } } +/** + * Finalize the linking process (among other things, ensures remaining needed intantiation is done). + * \note Do not use \a bh after calling this function, it may frees it. + * + * \param C The context, when NULL instantiating object in the scene isn't done. + * \param mainl The main database to link from (not the active one). + * \param bh The blender file handle. + * \param idcode The kind of datablock that has been linked. + * \param flag Options for for instantiating. + */ void BLO_library_link_end(const bContext *C, struct Main *mainl, BlendHandle **bh, int idcode, short flag) { FileData *fd = (FileData*)(*bh); |