1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
.TH LIBTRACEBITMAP_TRACE 3 LIBTRACEBITMAP
.SH NAME
libtracebitmap_trace \- Vectorise a bitmap
.SH SYNOPSIS
.nf
#include <libtracebitmap.h>
#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)
|
