Cleanup: BLO: move func doc comments to definitions of functions.

Follows our conventions and makes include file itself much cleaner.
This commit is contained in:
Bastien Montagne 2015-10-12 14:21:34 +02:00
parent 4bc08d09ae
commit 6f41febff1
3 changed files with 159 additions and 182 deletions

View File

@ -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);
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);
BlendHandle *BLO_blendhandle_from_file(const char *filepath, struct ReportList *reports);
BlendHandle *BLO_blendhandle_from_memory(const void *mem, int memsize);
/**
* 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);
/**
* 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);
/**
* 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

View File

@ -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) {

View File

@ -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);