aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorHarry Jeffery <harry@exec64.co.uk>2019-09-02 22:47:40 +0100
committerHarry Jeffery <harry@exec64.co.uk>2019-09-02 22:47:40 +0100
commit7dcb1a534249fc4f3ea37f6197228754fb831dd8 (patch)
tree3cd23ceb81e2e987b9cdbc88d02950c1e6f09d4c
parenta6deca0ad390d29ada6d72584a1be835a3913139 (diff)
downloadimv-7dcb1a534249fc4f3ea37f6197228754fb831dd8.tar.gz
source/backend: Improve comments
-rw-r--r--src/backend.h23
-rw-r--r--src/backend_libnsgif.c2
-rw-r--r--src/source_private.h11
3 files changed, 27 insertions, 9 deletions
diff --git a/src/backend.h b/src/backend.h
index 85e3b34..46a8642 100644
--- a/src/backend.h
+++ b/src/backend.h
@@ -6,9 +6,17 @@
struct imv_source;
enum backend_result {
- BACKEND_SUCCESS = 0, /* successful load */
- BACKEND_BAD_PATH = 1, /* no such file, bad permissions, etc. */
- BACKEND_UNSUPPORTED = 2, /* unsupported file format */
+
+ /* The backend recognises the file's data and thinks it can load it */
+ BACKEND_SUCCESS = 0,
+
+ /* Represents a bad file or path, implies that other backends would also fail
+ * and shouln't be tried.
+ */
+ BACKEND_BAD_PATH = 1,
+
+ /* There's data, but this backend doesn't understand it. */
+ BACKEND_UNSUPPORTED = 2,
};
/* A backend is responsible for taking a path, or a raw data pointer, and
@@ -16,6 +24,7 @@ enum backend_result {
* different image library and support different image formats.
*/
struct imv_backend {
+
/* Name of the backend, for debug and user informational purposes */
const char *name;
@@ -28,13 +37,13 @@ struct imv_backend {
/* License the backend is used under */
const char *license;
- /* Input: path to open
- * Output: initialises the imv_source instance passed in
+ /* Tries to open the given path. If successful, BACKEND_SUCCESS is returned
+ * and src will point to an imv_source instance for the given path.
*/
enum backend_result (*open_path)(const char *path, struct imv_source **src);
- /* Input: pointer to data and length of data
- * Output: initialises the imv_source instance passed in
+ /* Tries to read the passed data. If successful, BACKEND_SUCCESS is returned
+ * and src will point to an imv_source instance for the given data.
*/
enum backend_result (*open_memory)(void *data, size_t len, struct imv_source **src);
};
diff --git a/src/backend_libnsgif.c b/src/backend_libnsgif.c
index f5fcd3a..5c5995b 100644
--- a/src/backend_libnsgif.c
+++ b/src/backend_libnsgif.c
@@ -118,7 +118,7 @@ static void next_frame(void *raw_private, struct imv_image **image, int *frameti
gif_result code = gif_decode_frame(&private->gif, private->current_frame);
if (code != GIF_OK) {
- imv_log(IMV_DEBUG, "libnsgif: failed to decode first frame\n");
+ imv_log(IMV_DEBUG, "libnsgif: failed to decode a frame\n");
return;
}
diff --git a/src/source_private.h b/src/source_private.h
index 39b41fe..ed77534 100644
--- a/src/source_private.h
+++ b/src/source_private.h
@@ -4,17 +4,26 @@
struct imv_image;
struct imv_source;
+/* This is the interface a source needs to implement to function correctly.
+ * Backends act as a "factory" for sources by calling imv_source_create
+ * with a pointer to a static vtable, and a pointer to that implementation's
+ * private data, pre-initialised.
+ */
+
struct imv_source_vtable {
+
/* Loads the first frame, if successful puts output in image and duration
* (in milliseconds) in frametime. If unsuccessful, image shall be NULL. A
* still image should use a frametime of 0.
*/
void (*load_first_frame)(void *private, struct imv_image **image, int *frametime);
+
/* Loads the next frame, if successful puts output in image and duration
* (in milliseconds) in frametime. If unsuccessful, image shall be NULL.
*/
void (*load_next_frame)(void *private, struct imv_image **image, int *frametime);
- /* Cleans up the private section of a source */
+
+ /* Cleans up the private data of a source */
void (*free)(void *private);
};