From e0193a071feaf04b54c65348bf11db0d8db6c4ac Mon Sep 17 00:00:00 2001 From: Cyril Hrubis Date: Fri, 13 Jun 2014 23:38:58 +0200 Subject: [PATCH] loaders: Rename Match functions + constify + doc * Rename MatchExtension to LoaderByFilename and MatchSignature to LoaderBySignature * Constify GP_Loader arguments where possible * Update loaders docs Signed-off-by: Cyril Hrubis --- build/syms/Loaders_symbols.txt | 5 ++- demos/spiv/image_list.c | 2 +- doc/loaders.txt | 97 ++++++++++++++++++++++++++---------------- include/loaders/GP_Loader.h | 11 ++--- libs/loaders/GP_Loader.c | 25 +++++------ tests/loaders/Loader.c | 6 +-- 6 files changed, 83 insertions(+), 63 deletions(-) diff --git a/build/syms/Loaders_symbols.txt b/build/syms/Loaders_symbols.txt index 20b54d9d..bb834f97 100644 --- a/build/syms/Loaders_symbols.txt +++ b/build/syms/Loaders_symbols.txt @@ -81,8 +81,9 @@ GP_PSD GP_SaveTmpFile GP_LoadTmpFile -GP_MatchSignature -GP_MatchExtension +GP_LoaderBySignature +GP_LoaderByFilename +GP_LoaderLoadImage GP_ReadImage GP_LoadImage GP_SaveImage diff --git a/demos/spiv/image_list.c b/demos/spiv/image_list.c index 9d7a3ff4..be6532c0 100644 --- a/demos/spiv/image_list.c +++ b/demos/spiv/image_list.c @@ -69,7 +69,7 @@ static int dir_filter(const struct dirent *d) //TODO: filter out directories - if (GP_MatchExtension(d->d_name) == NULL) + if (!GP_LoaderByFilename(d->d_name)) return 0; GP_DEBUG(4, "Adding file '%s'", d->d_name); diff --git a/doc/loaders.txt b/doc/loaders.txt index c1d94e8e..0b83df55 100644 --- a/doc/loaders.txt +++ b/doc/loaders.txt @@ -36,7 +36,7 @@ returned. 'write()', ... | 'ENOENT' if file doesn't exist | 'EACCES' if process doesn't have rights to open the file -| 'ENOSYS' if GFXprim wasn't compiled with particular library support +| 'ENOSYS' if GFXprim wasn't compiled with particular format support | 'ENOMEM' if returned by 'malloc()' | 'EIO', 'EINVAL' invalid image data (wrong signature, wrong or too short header or image data) @@ -110,12 +110,12 @@ Advanced Interface ------------------------------------------------------------------------------- typedef struct GP_Loader { /* - * Loads an image. + * Reads an image from an IO stream. * - * Returns allocated and initialized bitmap on success, NULL on failure - * and errno must be set. + * Returns newly allocated context cotaining the loaded image or in + * case of failure NULL and errno is set. */ - GP_Context *(*Load)(const char *src_path, GP_ProgressCallback *callback); + GP_Context *(*Read)(GP_IO *io, GP_ProgressCallback *callback); /* * Save an image. @@ -126,6 +126,14 @@ typedef struct GP_Loader { GP_ProgressCallback *callback); /* + * GP_PIXEL_UNKNOWN terminated array of formats loader supports for save. + * + * This is _NOT_ a complete list loaders is able to save, due to automatic + * conversions (i.e. RGB888 vs BRG888). + */ + const GP_PixelType *save_ptypes; + + /* * The buffer is filled with 32 bytes from an image start, returns 1 if * image signature was found zero otherwise. */ @@ -136,49 +144,49 @@ typedef struct GP_Loader { */ const char *fmt_name; - /* don't touch */ - struct GP_Loader *next; - /* * NULL terminated array of file extensions. */ const char *extensions[]; } GP_Loader; - -/* - * List loaders into the stdout. - */ -void GP_ListLoaders(void); - -/* - * Register a loader. - */ -void GP_LoaderRegister(GP_Loader *self); - -/* - * Unregister loader. - */ -void GP_LoaderUnregister(GP_Loader *self); ------------------------------------------------------------------------------- The 'GP_Loader' structure describes an image loader. -The 'Load', 'Save' and 'Match' functions could be NULL if the particular +The 'Read', 'Save' and 'Match' functions could be NULL if the particular functionality is not implemented. The 'fmt_name' is a short string that describes the format. For example: 'Netbpm portable pixmap'. -The extensions is NULL-terminated array of strings that holds all possible +The 'extensions' is NULL-terminated array of strings that holds all possible extensions that are commonly used for this image format. -All internal loaders are all described in list of this structures which is -used to implement functions such as 'GP_LoadImage()'. +[source,c] +------------------------------------------------------------------------------- +#include +/* or */ +#include + +void GP_ListLoaders(void); -You can print currently active loaders via the 'GP_ListLoaders()'. Register and -unregister your own loaders by 'GP_LoaderRegister()' and -'GP_LoaderUnregister()'. Once image loader is registered the generic loading -functions can use it to load and save images. +int GP_LoaderRegister(const GP_Loader *self); + +void GP_LoaderUnregister(const GP_Loader *self); +------------------------------------------------------------------------------- + +The 'GP_ListLoaders()' function prints all currently registered loaders and +their capabilities into the stdout. + +You can register and unregister your own loader by 'GP_LoaderRegister()' and +'GP_LoaderUnregister()'. Once image loader is registered it's automatically +used by all loaders functions. + +The 'GP_LoaderRegister()' can fail (return non-zero) if you try to register +loader that is allready registered or if the loaders table is full (the table +size is compile time constant and there should be space for at least fifty +user defined loaders). I this cases the errno would be set to 'EEXIST' or +'ENOSPC' respectively. TIP: For example usage see image loader registration link:example_loader_registration.html[example]. @@ -189,7 +197,7 @@ link:example_loader_registration.html[example]. /* or */ #include -const GP_Loader *GP_MatchSignature(const void *buf) +const GP_Loader *GP_LoaderBySignature(const void *buf) ------------------------------------------------------------------------------- Returns pointer to image loader accordingly to image signature or NULL if no @@ -202,15 +210,30 @@ bytes long. /* or */ #include -const GP_Loader *GP_MatchExtension(const char *path) +const GP_Loader *GP_LoaderByFilename(const char *path) ------------------------------------------------------------------------------- Matches loader by the file extension. This function does not check that the -file exists or that it could be opened it only looks at the extension (i.e. -string after the dot) and matches it against known extensions. +file exists or that it could be opened etc. It only looks at the file +extension (i.e. string at the end of the path after a dot) and matches it +against extensions defined by loaders. + +[source,c] +------------------------------------------------------------------------------- +#include +/* or */ +#include + +GP_Context *GP_LoaderLoadImage(const GP_Loader *self, const char *src_path, + GP_ProgressCallback *callback); +------------------------------------------------------------------------------- + +Loads an image given a loader structure. + +Returns NULL and sets errno to 'ENOSYS' loader 'Read()' callback is NULL. -WARNING: If you attempt to modify the content of the structure the behavior is - undefined. Most likely the program will crash. +Otherwise prepares a link:loaders_io.html[GP_IO] from the 'src_path' file, +calls the 'Read()' callbacks and closes the 'IO' before the call returns. [[PNG]] PNG Loader diff --git a/include/loaders/GP_Loader.h b/include/loaders/GP_Loader.h index 5277fb41..90aeebb7 100644 --- a/include/loaders/GP_Loader.h +++ b/include/loaders/GP_Loader.h @@ -120,19 +120,20 @@ typedef struct GP_Loader { * Takes pointer to buffer at least 32 bytes long and returns a pointer to * matched loader or NULL. */ -const GP_Loader *GP_MatchSignature(const void *buf); +const GP_Loader *GP_LoaderBySignature(const void *buf); /* - * Tries to match loader by extension. Returns NULL if no loader was found. + * Tries to match loader by filename extension. Returns NULL if no loader was + * found. */ -const GP_Loader *GP_MatchExtension(const char *path); +const GP_Loader *GP_LoaderByFilename(const char *path); /* * Registers additional loader. * * Returns zero on success, non-zero if table of loaders was is full. */ -int GP_LoaderRegister(GP_Loader *self); +int GP_LoaderRegister(const GP_Loader *self); /* * Unregisters a loader. @@ -141,7 +142,7 @@ int GP_LoaderRegister(GP_Loader *self); * * You can unregister them using this function if you want. */ -void GP_LoaderUnregister(GP_Loader *self); +void GP_LoaderUnregister(const GP_Loader *self); /* * Generic LoadImage for a given loader. diff --git a/libs/loaders/GP_Loader.c b/libs/loaders/GP_Loader.c index aa8911b2..12ca2fc8 100644 --- a/libs/loaders/GP_Loader.c +++ b/libs/loaders/GP_Loader.c @@ -41,7 +41,7 @@ #define MAX_LOADERS 64 -static GP_Loader *loaders[MAX_LOADERS] = { +static const GP_Loader *loaders[MAX_LOADERS] = { &GP_JPG, &GP_PNG, &GP_TIFF, @@ -69,7 +69,7 @@ static unsigned int get_last_loader(void) return i - 1; } -int GP_LoaderRegister(GP_Loader *self) +int GP_LoaderRegister(const GP_Loader *self) { unsigned int i; @@ -99,7 +99,7 @@ int GP_LoaderRegister(GP_Loader *self) return 0; } -void GP_LoaderUnregister(GP_Loader *self) +void GP_LoaderUnregister(const GP_Loader *self) { unsigned int i, last = get_last_loader(); @@ -146,7 +146,7 @@ void GP_ListLoaders(void) } } -static struct GP_Loader *loader_by_extension(const char *ext) +static const GP_Loader *loader_by_extension(const char *ext) { unsigned int i, j; @@ -178,7 +178,7 @@ static const char *get_ext(const char *path) return path + i + 1; } -static struct GP_Loader *loader_by_filename(const char *path) +const GP_Loader *GP_LoaderByFilename(const char *path) { const char *ext = get_ext(path); @@ -216,7 +216,7 @@ static const GP_Loader *loader_by_signature(const char *path) fclose(f); - ret = GP_MatchSignature(buf); + ret = GP_LoaderBySignature(buf); if (ret == NULL) errno = ENOSYS; @@ -254,7 +254,7 @@ GP_Context *GP_ReadImage(GP_IO *io, GP_ProgressCallback *callback) return NULL; } - loader = GP_MatchSignature(buf); + loader = GP_LoaderBySignature(buf); if (!loader) { GP_DEBUG(1, "Failed to find a loader by signature for" @@ -325,7 +325,7 @@ GP_Context *GP_LoadImage(const char *src_path, GP_ProgressCallback *callback) GP_Context *img; const GP_Loader *ext_load = NULL, *sig_load; - ext_load = loader_by_filename(src_path); + ext_load = GP_LoaderByFilename(src_path); if (ext_load) { img = GP_LoaderLoadImage(ext_load, src_path, callback); @@ -387,7 +387,7 @@ out: int GP_SaveImage(const GP_Context *src, const char *dst_path, GP_ProgressCallback *callback) { - struct GP_Loader *l = loader_by_filename(dst_path); + const GP_Loader *l = GP_LoaderByFilename(dst_path); if (l == NULL) { errno = EINVAL; @@ -401,7 +401,7 @@ int GP_SaveImage(const GP_Context *src, const char *dst_path, return 1; } -const GP_Loader *GP_MatchSignature(const void *buf) +const GP_Loader *GP_LoaderBySignature(const void *buf) { unsigned int i; @@ -416,8 +416,3 @@ const GP_Loader *GP_MatchSignature(const void *buf) return NULL; } - -const GP_Loader *GP_MatchExtension(const char *path) -{ - return loader_by_filename(path); -} diff --git a/tests/loaders/Loader.c b/tests/loaders/Loader.c index 4494825e..dcc9b921 100644 --- a/tests/loaders/Loader.c +++ b/tests/loaders/Loader.c @@ -117,7 +117,7 @@ static int loader_by_extension(void) return TST_FAILED; } - loader = GP_MatchExtension("file.jpg"); + loader = GP_LoaderByFilename("file.jpg"); if (loader != &GP_JPG) { tst_msg("Failed to get JPEG loader"); @@ -126,7 +126,7 @@ static int loader_by_extension(void) tst_msg("Succeded to get JPEG loader"); } - loader = GP_MatchExtension("file.test"); + loader = GP_LoaderByFilename("file.test"); if (loader != &test_loader) { tst_msg("Failed to get registered TEST loader"); @@ -155,7 +155,7 @@ const struct tst_suite tst_suite = { .tst_fn = register_loader_twice, .flags = TST_CHECK_MALLOC}, - {.name = "MatchExtension()", + {.name = "LoaderByFilename()", .tst_fn = loader_by_extension, .flags = TST_CHECK_MALLOC}, -- 2.11.4.GIT