From f33af8ecd7dae0b663b0eb99474d16403faaf4e1 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Mon, 18 Jul 2022 23:18:48 +0200 Subject: Add man pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- libtracebitmap_trace.3 | 144 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 libtracebitmap_trace.3 (limited to 'libtracebitmap_trace.3') diff --git a/libtracebitmap_trace.3 b/libtracebitmap_trace.3 new file mode 100644 index 0000000..dc76bf3 --- /dev/null +++ b/libtracebitmap_trace.3 @@ -0,0 +1,144 @@ +.TH LIBTRACEBITMAP_TRACE 3 LIBTRACEBITMAP +.SH NAME +libtracebitmap_trace \- Vectorise a bitmap +.SH SYNOPSIS +.nf +#include + +#define LIBTRACEBITMAP_INK_OFF 0 +#define LIBTRACEBITMAP_INK_ON 1 + +struct libtracebitmap_bitmap { + size_t \fIheight\fP; + size_t \fIwidth\fP; + uint8_t *\fIimage\fP; +}; + +int libtracebitmap_trace( + struct libtracebitmap_bitmap *\fIbitmap\fP, + int (*\fInew_component\fP)(int \fInegative\fP, void *\fIuser_data\fP), + int (*\fInew_stop\fP)(size_t \fIy\fP, size_t \fIx\fP, void *\fIuser_data\fP), + int (*\fIcomponent_finished\fP)(void *\fIuser_data\fP), + void *\fIuser_data\fP); +.fi +.PP +Link with +.IR -ltracebitmap . +.SH DESCRIPTION +The +.B libtracebitmap_trace +function vectorises a bitmap image into horizonal and +vertical vectors. +.PP +The image to vectorise is given via the +.I bitmap +parameter. +.I bitmap->height +shall be the bitmap's height, measured in pixels, and +.I bitmap->width +shall be the bitmap's width. +.I bitmap->image +shall be a pointer to a memory segment of +.I bitmap->height*bitmap->width +.BR uint8_t s, +here for an y-position +.I y +and an x-position +.I x +the ink status of the pixel at that position is +specified by the value of +.IR bitmap->image[y*bitmap->width+x] , +which shall have the value +.I LIBTRACEBITMAP_INK_OFF +if the image is transparent at that pixel and +.I LIBTRACEBITMAP_INK_ON +if the image is opaque at that pixel, no other +values are allowed. The contents of +.IR bitmap->image +will be erased during execution (which stops +whenever a callback function returns a non-zero +value), however the memory is not deallocated. +.PP +.I *new_component +shall be a callback function for +.B libtracebitmap_trace +to invoke whenever it starts tracing a new +part of the bitmap, which it will only do at +the beginning or immediately after finishing +tracing a part indicated by a previous call to +the callback function. Its +.I negative +parameter will be 0 if the traced area shall +be drawn, and 1 if the traced area shall be +erased from a previously drawn area. It is safe +to ignore this argument and draw with XOR. +.PP +The +.B libtracebitmap_trace +function will call +.I *component_finished +when it has traced a part of the bitmap, at +this point, the application shall connect the +the stop indicated by the first invocation to +.IR *new_stop , +after the previous invocation of +.IR *new_component , +and the stop indicated by the previous +invocation to +.IR *new_stop . +.PP +After invoking +.I *new_component +but before the corresponding invocation of +.IR *component_finished , +the +.B libtracebitmap_trace +function will invoke +.I *new_stop +at least four times, each time indicating a stop +in the vectorisation adjacent to the previous stop +(or in the case of the first stop since the previous +invocation of +.IR *new_component , +the last stop before the next invocation of +.IR *component_component ). +The adjacent stops creates a vector which will not +cross any other vector, however two stops may share +location. Each stop's location is indicated by the +.I y +(values will be integers in [0, +.IR bitmap->height ]) +and +.I x +(values will be integers in [0, +.IR bitmap->width ]) +arguments. +.PP +.I user_data +will be passed on as is as the last argument to +.IR *new_component , +.IR *new_stop , +and +.IR *component_finished . +.PP +Only +.I user_data +parameter may be +.IR NULL . +.SH RETURN VALUE +The +.B libtracebitmap_trace +function will return any non-zero value returned by a +callback function, indicating failure; if all invocations +to callback functions return zero, the function returns +zero indicating successful completion. +.SH ERRORS +The +.B libtracebitmap_trace +function cannot itself fail and will not modify +.IR errno , +it will however let its callback functions modify +.IR errno . +.SH SEE ALSO +.BR libtracebitmap (7), +.BR libtracebitmap.h (0) -- cgit v1.2.3-70-g09d2