/* See LICENSE file for copyright and license details. */
#ifndef LIBTRACEBITMAP_H
#define LIBTRACEBITMAP_H

#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


/**
 * Bitmap
 */
struct libtracebitmap_bitmap {
	/**
	 * The height of the bitmap, in pixels
	 */
	size_t height;

	/**
	 * The width of the bitmap, in pixels
	 */
	size_t 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,
	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),
	void *user_data);

#endif