aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorHarry Jeffery <harry@exec64.co.uk>2019-08-21 20:16:43 +0100
committerHarry Jeffery <harry@exec64.co.uk>2019-08-21 20:16:43 +0100
commitd2f5deb27816889cdc9b25e868557f0bcd23e163 (patch)
treeb5709f59f5b5d0fe7c2735f01e79ffe5d6df2844
parentcf7f3127cbde7354f1b592af0d23de4d7cd1123f (diff)
downloadimv-d2f5deb27816889cdc9b25e868557f0bcd23e163.tar.gz
Improve header commenting
-rw-r--r--src/backend.h5
-rw-r--r--src/bitmap.h3
-rw-r--r--src/commands.c4
-rw-r--r--src/commands.h23
-rw-r--r--src/ipc.h12
-rw-r--r--src/list.h21
-rw-r--r--src/source.h5
-rw-r--r--src/window.h20
8 files changed, 84 insertions, 9 deletions
diff --git a/src/backend.h b/src/backend.h
index 0ec7c01..85e3b34 100644
--- a/src/backend.h
+++ b/src/backend.h
@@ -12,9 +12,8 @@ enum backend_result {
};
/* A backend is responsible for taking a path, or a raw data pointer, and
- * converting that into a source that imv can handle. Each backend
- * may be powered by a different image library and support different
- * image formats.
+ * converting that into an imv_source. Each backend may be powered by a
+ * different image library and support different image formats.
*/
struct imv_backend {
/* Name of the backend, for debug and user informational purposes */
diff --git a/src/bitmap.h b/src/bitmap.h
index 61ef0ce..c41b8ff 100644
--- a/src/bitmap.h
+++ b/src/bitmap.h
@@ -13,7 +13,10 @@ struct imv_bitmap {
unsigned char *data;
};
+/* Copy an imv_bitmap */
struct imv_bitmap *imv_bitmap_clone(struct imv_bitmap *bmp);
+
+/* Clean up a bitmap */
void imv_bitmap_free(struct imv_bitmap *bmp);
#endif
diff --git a/src/commands.c b/src/commands.c
index e72b9e0..5527e2e 100644
--- a/src/commands.c
+++ b/src/commands.c
@@ -5,6 +5,10 @@
#include <stdio.h>
#include <string.h>
+struct imv_commands {
+ struct list *command_list;
+};
+
struct command {
char* command;
void (*handler)(struct list *args, const char *argstr, void *data);
diff --git a/src/commands.h b/src/commands.h
index cf81f68..3bd7650 100644
--- a/src/commands.h
+++ b/src/commands.h
@@ -2,16 +2,29 @@
#define COMMANDS_H
struct list;
+struct imv_commands;
-struct imv_commands {
- struct list *command_list;
-};
-
+/* Create an imv_commands instance */
struct imv_commands *imv_commands_create(void);
+
+/* Cleans up an imv_commands instance */
void imv_commands_free(struct imv_commands *cmds);
-void imv_command_register(struct imv_commands *cmds, const char *command, void (*handler)(struct list*, const char*, void*));
+
+/* Register a new command. When a command is executed, the appropriate handler
+ * is called, with a void* for passing context.
+ */
+void imv_command_register(struct imv_commands *cmds, const char *command,
+ void (*handler)(struct list*, const char*, void*));
+
+/* Add a command alias. Any arguments provided when invoking an alias are
+ * appended to the arguments being passed to the command.
+ */
void imv_command_alias(struct imv_commands *cmds, const char *command, const char *alias);
+
+/* Execute a single command */
int imv_command_exec(struct imv_commands *cmds, const char *command, void *data);
+
+/* Execute a list of commands */
int imv_command_exec_list(struct imv_commands *cmds, struct list *commands, void *data);
#endif
diff --git a/src/ipc.h b/src/ipc.h
index 539b684..3b93bc3 100644
--- a/src/ipc.h
+++ b/src/ipc.h
@@ -3,17 +3,29 @@
#include <unistd.h>
+/* imv_ipc provides a listener on a unix socket that listens for commands.
+ * When a command is received, a callback function is called.
+ */
struct imv_ipc;
+/* Creates an imv_ipc instance */
struct imv_ipc *imv_ipc_create(void);
+/* Cleans up an imv_ipc instance */
void imv_ipc_free(struct imv_ipc *ipc);
typedef void (*imv_ipc_callback)(const char *command, void *data);
+/* When a command is received, imv_ipc will call the callback function passed
+ * in. Only one callback function at a time can be connected. The data argument
+ * is passed back to the callback to allow for context passing
+ */
void imv_ipc_set_command_callback(struct imv_ipc *ipc,
imv_ipc_callback callback, void *data);
+/* Given a pid, emits the path of the unix socket that would connect to an imv
+ * instance with that pid
+ */
void imv_ipc_path(char *buf, size_t len, int pid);
#endif
diff --git a/src/list.h b/src/list.h
index 069aea1..d62f41a 100644
--- a/src/list.h
+++ b/src/list.h
@@ -4,36 +4,57 @@
#include <stdlib.h>
#include <string.h>
+/* Generic list. You know what this is. */
struct list {
size_t len;
size_t cap;
void **items;
};
+/* Create a list instance */
struct list *list_create(void);
+/* Clean up a list, caller should clean up contents of the list first */
void list_free(struct list *list);
+/* Clean up a list, calling free() on each item first */
void list_deep_free(struct list *list);
+/* Append an item to the list. Automatically resizes the list if needed */
void list_append(struct list *list, void *item);
+/* Grow the list's storage to a given size, useful for avoiding unneccessary
+ * reallocations prior to inserting many items
+ */
void list_grow(struct list *list, size_t min_size);
+/* Remove an item from the list at a given 0-based index */
void list_remove(struct list *list, size_t index);
+/* Insert an item into the list before the given index */
void list_insert(struct list *list, size_t index, void *item);
+/* Empty the list. Caller should clean up the contents of the list first */
void list_clear(struct list *list);
+/* Split a null-terminated string, separating by the given delimiter.
+ * Multiple consecutive delimiters count as a single delimiter, so no empty
+ * string list items are emitted
+ */
struct list *list_from_string(const char *string, char delim);
+/* Returns the index of the first item to match key, determined by the cmp
+ * function
+ */
int list_find(
struct list *list,
int (*cmp)(const void *item, const void *key),
const void *key
);
+/* Assumes all list items are null-terminated strings, and concatenates them
+ * separated by sep, starting at the index given by start
+ */
char *list_to_string(struct list *list, const char *sep, size_t start);
#endif
diff --git a/src/source.h b/src/source.h
index eed95c4..d55e560 100644
--- a/src/source.h
+++ b/src/source.h
@@ -22,7 +22,10 @@ struct imv_source_message {
const char *error;
};
-/* Generic source of one or more images. Essentially a single image file */
+/* While imv_image represents a single frame of an image, be it a bitmap or
+ * vector image, imv_source represents an open handle to an image file, which
+ * can emit one or more imv_images.
+ */
struct imv_source {
/* usually the path of the image this is the source of */
char *name;
diff --git a/src/window.h b/src/window.h
index a496655..978278c 100644
--- a/src/window.h
+++ b/src/window.h
@@ -42,37 +42,57 @@ struct imv_event {
} data;
};
+/* Create a new window */
struct imv_window *imv_window_create(int w, int h, const char *title);
+/* Clean up an imv_window instance */
void imv_window_free(struct imv_window *window);
+/* Clears the window with the given colour */
void imv_window_clear(struct imv_window *window, unsigned char r,
unsigned char g, unsigned char b);
+/* Get the logical/event/window manager size of the window */
void imv_window_get_size(struct imv_window *window, int *w, int *h);
+/* Get the pixel dimensions that the window is rendered at */
void imv_window_get_framebuffer_size(struct imv_window *window, int *w, int *h);
+/* Set the window's title */
void imv_window_set_title(struct imv_window *window, const char *title);
+/* Returns true if the window is fullscreen */
bool imv_window_is_fullscreen(struct imv_window *window);
+/* Set the window's fullscreen state */
void imv_window_set_fullscreen(struct imv_window *window, bool fullscreen);
+/* Check whether a given mouse button is pressed */
bool imv_window_get_mouse_button(struct imv_window *window, int button);
+/* Gets the mouse's position */
void imv_window_get_mouse_position(struct imv_window *window, double *x, double *y);
+/* Swap the framebuffers. Present anything rendered since the last call. */
void imv_window_present(struct imv_window *window);
+/* Blocks until an event is received, or the timeout (in seconds) expires */
void imv_window_wait_for_event(struct imv_window *window, double timeout);
+/* Push an event to the event queue. An internal copy of the event is made.
+ * Wakes up imv_window_wait_for_event */
void imv_window_push_event(struct imv_window *window, struct imv_event *e);
typedef void (*imv_event_handler)(void *data, const struct imv_event *e);
+/* When called, the handler function is called for each event on the event
+ * queue */
void imv_window_pump_events(struct imv_window *window, imv_event_handler handler, void *data);
+/* If the current keyboard layout is known, returns a null-terminated string
+ * describing the keyboard layout and options, suitable for libxkbcommon to
+ * parse. If unknown, returns NULL.
+ */
const char *imv_window_get_keymap(struct imv_window *window);
#endif