diff options
| -rw-r--r-- | libtracebitmap.h | 71 |
1 files changed, 68 insertions, 3 deletions
diff --git a/libtracebitmap.h b/libtracebitmap.h index 1f8b13e..144f347 100644 --- a/libtracebitmap.h +++ b/libtracebitmap.h @@ -5,18 +5,83 @@ #include <stddef.h> #include <stdint.h> + +/** + * The background is show for pixels with this value + */ #define LIBTRACEBITMAP_INK_OFF 0 + +/** + * The foreground is show for pixels with this value + */ #define LIBTRACEBITMAP_INK_ON 1 -/* Other values in (struct libtracebitmap_bitmap).image invoke undefined behaviour */ + +/** + * Bitmap + */ struct libtracebitmap_bitmap { + /** + * The height of the bitmap, in pixels + */ size_t height; + + /** + * The width of the bitmap, in pixels + */ size_t width; - uint8_t *image; /* (uint8_t [.height][.width]) */ + + /** + * The bitmap + * + * Row-major order oriented and non-packed, meaning + * that for an y-position `y` and an x-position `x`, + * `.image[y * .width + x]` returns the pixel value, + * which must either be `LIBTRACEBITMAP_INK_OFF` or + * `LIBTRACEBITMAP_INK_ON` + */ + uint8_t *image; }; + +/** + * Vectorise a bitmap + * + * @param bitmap The bitmap to vectorise; `bitmap->image` will be + * be erased, but not deallocated + * @param new_component Callback function that will be called each time the function + * starts vectorising a separate component in the bitmap; the + * first argument will be the 0 if the component shall be drawn, + * and 1 if the component shall erase from a drawn component; + * the second argument will be `user_data`; assuming the bitmap + * is not empty, this will be the first callback the function calls; + * the callback function shall return 0 upon successful completion + * and any other value on failure + * @param new_stop Callback function that is called each time the function finds + * a node for the vector image; the first argument will be the + * node's y-position (0 at the top, positive downwards); the second + * argument will be the node's x-position (0 at the far left, + * positive rightwards); the third argument will be `user_data`; + * the callback function shall return 0 upon successful completion + * and any other value on failure: Lines between adjecent nodes + * within the same component (the initial and the final nodes are + * adjacent) are always either horizontal or vertical, with no + * other nodes between the them. + * @param component_finished Callback function that is called each time the function is + * finished with a component. The function will only vectorise + * one component at a time, so after calling this callback, the + * function will either return or immediate call `*new_component`, + * and after calling `*new_component`, it will never `*new_component` + * again before calling `*component_finished`; additionally, + * `*component_finished` is called once for every call to + * `*new_component`; the callback function shall return 0 upon + * successful completion and any other value on failure + * @param user_data Value to pass as the last argument for each callback function + * @return 0 upon success, and the value returned by a callback function + * if it returns a non-zero value + */ int libtracebitmap_trace( - struct libtracebitmap_bitmap *bitmap, /* image will be erased, but not deallocated */ + struct libtracebitmap_bitmap *bitmap, int (*new_component)(int negative, void *user_data), int (*new_stop)(size_t y, size_t x, void *user_data), int (*component_finished)(void *user_data), |