forked from sirjofri/ff-tools
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathff-tools.l.in
159 lines (159 loc) · 4.6 KB
/
ff-tools.l.in
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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
.TH tools.h l "DATE" "Version VNUM" "Library Functions"
.SH NAME
tools.h \- ff-tools library functions
.SH SYNOPSIS
.B #include \(dqtools.h\(dq
.PP
.B M_PI
.br
.B OK
.br
.B USERERR
.br
.B READERR
.br
.B WRITERR
.br
.B MEMERR
.PP
.B typedef struct Coords;
.br
.B set_c(\fICoords\fB, \fIuint32_t x\fB, \fIuint32_t y\fB);
.br
.B typedef struct Rgba;
.br
.B typedef struct RgbaD;
.PP
.B int ff_print_header(Coords \fIsize\fB);
.br
.B int ff_print_rgba(Rgba \fIrgba\fB);
.br
.B int ff_print_value(uint16_t *\fIvalue\fB);
.br
.B int ff_print_bw(uint16_t *\fIbw_value\fB);
.PP
.B int ff_err_msg(int \fIerror\fB, char *\fImessage\fB);
.br
.B int ff_err(int \fIerror\fB);
.PP
.B int ff_read_header(Coords *\fIsize\fB);
.br
.B int ff_read_content(uint16_t *\fItarget\fB, Coords \fIsize\fB);
.br
.B int ff_read_rgba_content(Rgba *\fItarget\fB, Coords \fIsize\fB);
.PP
.B Rgba ff_coords(uint16_t *\fIorigin\fB, Coords \fIpos\fB);
.br
.B uint16_t *ff_coords_ptr(uint16_t *\fIorigin\fB, Coords \fIpos\fB);
.br
.B Coords ff_get_rel_coords(Coords \fIpos\fB, Coords \fIsize\fB, Coords \fIrel_pos\fB);
.PP
.B double ff_clamp(double \fIvalue\fB);
.PP
.B LEN(\fIx\fB)
.br
.B FOR_X_Y(\fIwidth\fR, \fIheight\fR, fIbody\fB)
.SH DESCRIPTION
.B Coords
and
.B Rgba
are predefined structs that contain coordinates (x, y) and rgba values (r, g, b, a). According to the \fBfarbfeld\fR definition the coordinates are \fBuint32_t\fR values while rgba uses \fBuint16_t\fR types. Please note that \fBset_c\fR is actually a macro (no type checking).
.PP
.B M_PI
is the constant PI (3.14159...).
.B USERERR\fR, \fBREADERR\fR, \fBWRITERR
are predefined error codes.
Functions that start with
.B ff_print_
return one of these error codes.
These error codes can automatically produce some apropriate output to
.I stderr
with the
.B ff_err
functions (\fBff_err_msg\fR is able to output a custom \fImessage\fR, too).
.PP
A working example would be:
.PP
.nf
.RS
int ret = ff_print_value(value);
if (ret != 0) {
ff_err(ret);
return ret;
}
.RE
.fi
.PP
The \fBLEN()\fR macro is equivalent to the length of the given array.
.PP
The \fBFOR_X_Y()\fR macro produces a for loop for iterating over every pixel of an image. The input
.PP
.nf
.RS
FOR_X_Y(width, height,
// Loop body
)
.RE
.fi
.PP
produces
.PP
.nf
.RS
for (uint32_t y=0; y<height; y++)
for (uint32_t x=0; x<width; x++) {
// Loop body
}
.RE
.fi
.PP
All \fBff_print\fR functions output directly to \fIstdout\fR.
.PP
.B ff_print_header()
prints a valid \fBfarbfeld\fR header with the correct \fIsize\fR \fBCoords\fR.
.PP
.B ff_print_rgba()
prints the given \fIrgba\fR pixel.
.PP
.B ff_print_value()
prints the given \fIvalue\fR as a simple value (not a full pixel).
This is useful if you can stream in data, process it channel by channel and output it without going pixel by pixel.
.PP
.B ff_print_bw()
prints the given \fIbw_value\fR as a full pixel.
It creates a pixel with RGBA\ =\ (\fIbw_value\fR, \fIbw_value\fR, \fIbw_value\fR, \fBUINT16_MAX\fR) and outputs it.
.PP
.B ff_read_header()
reads a header from \fBstdin\fR, validates its magic value ("farbfeld") and puts its size information into the given \fIsize\fR.
.B ff_read_header()
returns \fBOK\fR state if everything is ok, or one of the other error values if not.
.PP
.B ff_malloc()
is a macro that provides allocating an image buffer with \fBCoords\fR instead of memory size. Use it instead of \fBmalloc\fR.
.PP
.B ff_read_content()
reads in \fIsize\fR image data from \fBstdin\fR into memory located at \fItarget\fR.
.PP
.B ff_read_rgba_content()
reads in \fIsize\fR image data from \fbstdin\fR into an \fBRgba\fR memory buffer at location \fItarget\fR. You can then use \fIx\fR and \fIy\fR coordinates to access these pixels (target[width*y + x].r, target[width*y + x].g, etc.).
.PP
.B ff_coords()
returns the rgba pixel at \fIpos\fR relative to \fIorigin\fR.
.PP
.B ff_coords_ptr()
returns the correct memory location of the red value of the \fIpos\fR pixel relative to \fIorigin\fR.
.PP
.B ff_get_rel_coords()
calculates the correct position relative to \fIpos\fB of the image with the given \fIsize\fR and relative coordinates \fIrel_pos\fB. This function is mainly used internally, but you can use it outside as well.
.PP
.B ff_clamp()
clamps the given double value to [0..1] and returns the clamped value. This is espacially helpful in preventing overflows when multiplying with \fBUINT16_MAX\fR.
.SH NOTES
This library is in heavy development and can change every day!
.SH BUGS
I'm pretty sure there are some. Feel free to report/fix them.
.SH AUTHOR
The author of this package is known as \fIsirjofri\fR and the source is hosted
.UR https://\:github.com/\:sirjofri/\:ff-tools/
here
.UE . Feel free to contribute and fork it.