From d2f5deb27816889cdc9b25e868557f0bcd23e163 Mon Sep 17 00:00:00 2001 From: Harry Jeffery Date: Wed, 21 Aug 2019 20:16:43 +0100 Subject: Improve header commenting --- src/backend.h | 5 ++--- src/bitmap.h | 3 +++ src/commands.c | 4 ++++ src/commands.h | 23 ++++++++++++++++++----- src/ipc.h | 12 ++++++++++++ src/list.h | 21 +++++++++++++++++++++ src/source.h | 5 ++++- src/window.h | 20 ++++++++++++++++++++ 8 files changed, 84 insertions(+), 9 deletions(-) (limited to 'src') 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 #include +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 +/* 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 #include +/* 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 -- cgit v1.2.3