Add man pages

Signed-off-by: Mattias Andrée <maandree@kth.se>

11 files changed, 368 insertions, 3 deletions

diff --git a/Makefile b/Makefile
index f96c012..96cd2da 100644
--- a/Makefile
+++ b/Makefile
@@ -38,6 +38,18 @@ HDR =\
 LOBJ = $(OBJ:.o=.lo)
 TESTS = $(OBJ:.o=.test)
 
+MAN3 =\
+	rtgrpblib_create_raster.3\
+	rtgrpblib_reset_raster.3\
+	rtgrpblib_set_draftness.3\
+	rtgrpblib_draw_elliptical_arc.3\
+	rtgrpblib_draw_linear_bezier.3\
+	rtgrpblib_draw_quadratic_bezier.3\
+	rtgrpblib_draw_cubic_bezier.3\
+	rtgrpblib_fill_shapes.3
+
+MAN7 = lib$(LIB_NAME).7
+
 
 all: lib$(LIB_NAME).a lib$(LIB_NAME).$(LIBEXT) $(TESTS)
 $(OBJ): $(HDR)
@@ -73,6 +85,10 @@ install: lib$(LIB_NAME).a lib$(LIB_NAME).$(LIBEXT)
 	ln -sf -- lib$(LIB_NAME).$(LIBMINOREXT) "$(DESTDIR)$(PREFIX)/lib/lib$(LIB_NAME).$(LIBMAJOREXT)"
 	ln -sf -- lib$(LIB_NAME).$(LIBMAJOREXT) "$(DESTDIR)$(PREFIX)/lib/lib$(LIB_NAME).$(LIBEXT)"
 	cp -- lib$(LIB_NAME).h "$(DESTDIR)$(PREFIX)/include/"
+	mkdir -- "$(DESTDIR)$(MANPREFIX)/man3/"
+	mkdir -- "$(DESTDIR)$(MANPREFIX)/man7/"
+	cp -- $(MAN2) "$(DESTDIR)$(MANPREFIX)/man3/"
+	cp -- $(MAN7) "$(DESTDIR)$(MANPREFIX)/man7/"
 
 uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/lib$(LIB_NAME).a"
@@ -80,6 +96,8 @@ uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/lib$(LIB_NAME).$(LIBMINOREXT)"
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/lib$(LIB_NAME).$(LIBEXT)"
 	-rm -f -- "$(DESTDIR)$(PREFIX)/include/lib$(LIB_NAME).h"
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man3/" && rm -f -- $(MAN3)
+	-cd -- "$(DESTDIR)$(MANPREFIX)/man7/" && rm -f -- $(MAN7)
 
 clean:
 	-rm -f -- *.o *.a *.lo *.su *.so *.so.* *.dll *.dylib *.test
diff --git a/README b/README
index f9fe974..4f8d93a 100644
--- a/README
+++ b/README
@@ -9,7 +9,7 @@ DESCRIPTION
 	values of the result is used in the image). Furthermore this means that the
 	library only supports curve types that are used for drawing glyphs; specifically
 	this means that lines and quadratic Bézier curves are supported by cause this
-	is what is requied to draw vectorised bitmap fonts and TrueType fonts, but also
+	is what is required to draw vectorised bitmap fonts and TrueType fonts, but also
 	cubic Bézier curves as this is required for OpenType fonts and elliptical arcs
 	(elliptical rather than circular because it may be need required to strech the
 	circle to support outputs with different vertical and horizontal dot density
diff --git a/librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.7 b/librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.7
new file mode 100644
index 0000000..a0fe3d0
--- /dev/null
+++ b/librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.7
@@ -0,0 +1,48 @@
+.TH LIBRIFUNKTIONSTECKENSNITTSGLYFRASTERISERINGSPROGRAMBIBLIOTEKET 7 LIBRIFUNKTIONSTECKENSNITTSGLYFRASTERISERINGSPROGRAMBIBLIOTEKET
+.SH NAME
+librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket - Font rasterisation library
+
+.SH DESCRIPTION
+.B librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket
+is a C library for converting shape outlines to filled shapes,
+with a focus on fonts, which that it only supports filled,
+closed shapes and that the direction of the outline determines
+whether a shape adds or subtracts to the image (the absolute
+values of the result is used in the image). Furthermore this
+means that the library only supports curve types that are used
+for drawing glyphs; specifically this means that lines and
+quadratic Bézier curves are supported by cause this is what is
+required to draw vectorised bitmap fonts and TrueType fonts,
+but also cubic Bézier curves as this is required for OpenType
+fonts and elliptical arcs (elliptical rather than circular
+because it may be need required to strech the circle to support
+outputs with different vertical and horizontal dot density and
+to support subpixel antialiasing) as this is commonly used for
+corners when stroking the outline of a glyph.
+.PP
+The create an image, first create a buffer using
+.BR rtgrpblib_create_raster (3)
+(if you already have one that is large enough, you can
+reinitialise it with
+.BR rtgrpblib_reset_raster (3)),
+and than using the drawing functions
+.RB ( rtgrpblib_draw_linear_bezier (3),
+.BR rtgrpblib_draw_quadratic_bezier (3),
+.BR rtgrpblib_draw_cubic_bezier (3),
+and
+.BR rtgrpblib_draw_elliptical_arc (3))
+to draw the components of each shape's outline. When done,
+create an image using the
+.BR rtgrpblib_fill_shapes (3)
+function: you will receive a ink-level map, where the value
+0 means background, and 1 means foreground, and values between
+are colours between (no transfer function is applied).
+
+.SH NOTES
+Rifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket (hyphenation:
+ri|funk¦tions-tec¦ken|snit¦ts-glyf-ras¦ter¦iser¦ings-prog¦ram|bib¦lio¦te¦ket)
+is Swedish for \(dqthe library for rasterising glyphs from spline fonts\(dq.
+.PP
+Because of the length of the library name, and length limitation
+on function names, the functions in this library are namespaced
+with the prefix \(dqrtgrpblib_\(dq.
diff --git a/librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.h b/librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.h
index 2ba9065..aa6f4ce 100644
--- a/librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.h
+++ b/librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.h
@@ -27,8 +27,8 @@ typedef struct rtgrpblib_raster RTGRPBLIB_RASTER;
  *
  * @param   width   The width of the buffer
  * @param   height  The height of the buffer
- * @return          Drawing buffer, which can be deallocated with (3),
- *                  or `NULL` on failure
+ * @return          Drawing buffer, which can be deallocated with
+ *                  free(3), or `NULL` on failure
  * 
  * @throws  EINVAL  `width` or `height` is zero
  * @throws  ENOMEM  Cannot allocate enough memory
diff --git a/rtgrpblib_create_raster.3 b/rtgrpblib_create_raster.3
new file mode 100644
index 0000000..63250e9
--- /dev/null
+++ b/rtgrpblib_create_raster.3
@@ -0,0 +1,67 @@
+.TH RTGRPBLIB_CREATE_RASTER 3 LIBRIFUNKTIONSTECKENSNITTSGLYFRASTERISERINGSPROGRAMBIBLIOTEKET
+.SH NAME
+rtgrpblib_create_raster - Create a drawing buffer
+
+.SH DESCRIPTION
+.LP
+.nf
+#include <librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.h>
+
+typedef struct rtgrpblib_raster RTGRPBLIB_RASTER;
+
+RTGRPBLIB_RASTER *rtgrpblib_create_raster(size_t \fIwidth\fP, size_t \fIheight\fP);
+.fi
+.PP
+Link with
+.IR "-lrifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket" .
+
+.SH DESCRIPTION
+The
+.BR rtgrpblib_create_raster ()
+function creates a buffer, with configurations, that the
+library's drawing functions can draw curves in, which the
+.BR rtgrpblib_fill_shapes (3)
+function can ultimately process to generate a image.
+.PP
+The created buffer will be
+.I width
+cells wide, and
+.I height
+cells tall.
+.PP
+The returned object can be deallocated using the
+.BR free (3)
+function, it can also be reinitialised and reshaped
+using the
+.BR rtgrpblib_reset_raster (3)
+function.
+
+.SH RETURN VALUES
+The
+.BR rtgrpblib_create_raster ()
+function returns a pointer to a newly allocated object
+upon successful completion, and
+.I NULL
+on failure.
+
+.SH ERRORS
+The
+.BR rtgrpblib_create_raster ()
+function will fail if:
+.TP
+.B EINVAL
+.I width
+or
+.I height
+is zero.
+.LP
+and may fail if:
+.TP
+.B ENOMEM
+Cannot allocate enough memory.
+
+.SH SEE ALSO
+.BR librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket (7),
+.BR rtgrpblib_reset_raster (3),
+.BR rtgrpblib_set_draftness (3),
+.BR rtgrpblib_fill_shapes (3)
diff --git a/rtgrpblib_draw_cubic_bezier.c b/rtgrpblib_draw_cubic_bezier.c
index 8e56474..c68ad88 100644
--- a/rtgrpblib_draw_cubic_bezier.c
+++ b/rtgrpblib_draw_cubic_bezier.c
@@ -88,6 +88,7 @@ draw_bounded_cubic_bezier(RASTER *restrict raster, double x1, double y1, double
 		dy = evaluate_cubic_bezier_derivative(t, y1, y2, y3, y4);
 
 		t += raster->draftness / hypot(dx, dy);
+		/* TODO deal with unchanged t and oversized steps (e.g. locally zero derivative) */
 		t = fmin(t, t2);
 		x = evaluate_cubic_bezier(t, x1, x2, x3, x4);
 		y = evaluate_cubic_bezier(t, y1, y2, y3, y4);
diff --git a/rtgrpblib_draw_linear_bezier.3 b/rtgrpblib_draw_linear_bezier.3
new file mode 100644
index 0000000..7cc67c9
--- /dev/null
+++ b/rtgrpblib_draw_linear_bezier.3
@@ -0,0 +1,42 @@
+.TH RTGRPBLIB_DRAW_LINEAR_BEZIER 3 LIBRIFUNKTIONSTECKENSNITTSGLYFRASTERISERINGSPROGRAMBIBLIOTEKET
+.SH NAME
+rtgrpblib_draw_linear_bezier - Draw a line segment
+
+.SH DESCRIPTION
+.LP
+.nf
+#include <librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.h>
+
+void rtgrpblib_draw_linear_bezier(RTGRPBLIB_RASTER *\fIraster\fP,
+                                  double \fIx1\fP, double \fIy1\fP,
+                                  double \fIx2\fP, double \fIy2\fP);
+.fi
+.PP
+Link with
+.IR "-lrifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket -lm" .
+
+.SH DESCRIPTION
+The
+.BR rtgrpblib_draw_linear_bezier ()
+function draws onto
+.I raster
+a line segment from
+.RI ( x1 ,
+.IR y1 )
+to
+.RI ( x2 ,
+.IR y2 ).
+
+.SH RETURN VALUES
+None.
+
+.SH ERRORS
+None.
+
+.SH SEE ALSO
+.BR librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket (7),
+.BR rtgrpblib_create_raster (3),
+.BR rtgrpblib_fill_shapes (3),
+.BR rtgrpblib_draw_quadratic_bezier (3),
+.BR rtgrpblib_draw_cubic_bezier (3),
+.BR rtgrpblib_draw_elliptical_arc (3)
diff --git a/rtgrpblib_draw_quadratic_bezier.c b/rtgrpblib_draw_quadratic_bezier.c
index af5607d..8aae11e 100644
--- a/rtgrpblib_draw_quadratic_bezier.c
+++ b/rtgrpblib_draw_quadratic_bezier.c
@@ -68,6 +68,7 @@ draw_bounded_quadratic_bezier(RASTER *restrict raster, double x1, double y1, dou
 		dy = fma(t, ky, my);
 
 		t += raster->draftness / hypot(dx, dy);
+		/* TODO deal with unchanged t and oversized steps (e.g. locally zero derivative) */
 		t = fmin(t, t2);
 		x = evaluate_quadratic_bezier(t, x1, x2, x3);
 		y = evaluate_quadratic_bezier(t, y1, y2, y3);
diff --git a/rtgrpblib_fill_shapes.3 b/rtgrpblib_fill_shapes.3
new file mode 100644
index 0000000..7bd58b5
--- /dev/null
+++ b/rtgrpblib_fill_shapes.3
@@ -0,0 +1,85 @@
+.TH RTGRPBLIB_FILL_SHAPES 3 LIBRIFUNKTIONSTECKENSNITTSGLYFRASTERISERINGSPROGRAMBIBLIOTEKET
+.SH NAME
+rtgrpblib_fill_shapes - Generate image from applied drawing of filled shapes
+
+.SH DESCRIPTION
+.LP
+.nf
+#include <librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.h>
+
+void rtgrpblib_fill_shapes(double *image, size_t rowsize, const RTGRPBLIB_RASTER *\fIraster\fP);
+.fi
+.PP
+Link with
+.IR "-lrifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket -lm" .
+
+.SH DESCRIPTION
+The
+.BR rtgrpblib_fill_shapes ()
+function creates an user-usable image from a drawing.
+After drawing each shapes component curves, to
+.IR raster ,
+this function creates an image of these shapes filled in,
+and stores the image in the
+.I image
+buffer.
+.PP
+All drawn shapes must be closed. When shapes overlap,
+the subtract from each other if the are drawn in opposite
+angular direction, and add to each other if the are drawn
+in angular direction.
+.PP
+.I image
+shall be a row-major ordered buffer of single-element cells
+that is at least as wide as
+.I raster
+and at least as tall as
+.IR raster .
+The actual width shall be specified in the
+.I rowsize
+parameter, however the function will only use area
+specified by the size of
+.IR raster ,
+meaning that is, for example,
+.I raster
+is 10 cells wide, but
+.I rowsize
+is 15, only the 10 first columns in
+.I image
+will be written to, and the 5 last columns
+will remain untouched.
+
+.SH RETURN VALUES
+None.
+
+.SH ERRORS
+None.
+
+.SH APPLICATION USAGE
+As librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket
+is a font rasterisation library it is not designed to deal
+with overlapping shapes other than removing a shape from
+inside another shape (e.g. making the hole in the O). For the
+best result in other cases, it is recommended to create a
+union shape of overlapping shapes rather than drawing them
+independently (this should not be necessarily for rastersing
+text).
+
+.SH NOTES
+Row-major order means that each row is contiguously index,
+if a row-major ordered buffer is
+.I w
+cells wide, the point
+.RI ( x ,
+.IR y )
+has the index
+.IR (y*w+x) .
+
+.SH SEE ALSO
+.BR librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket (7),
+.BR rtgrpblib_create_raster (3),
+.BR rtgrpblib_reset_raster (3),
+.BR rtgrpblib_draw_linear_bezier (3),
+.BR rtgrpblib_draw_quadratic_bezier (3),
+.BR rtgrpblib_draw_cubic_bezier (3),
+.BR rtgrpblib_draw_elliptical_arc (3)
diff --git a/rtgrpblib_reset_raster.3 b/rtgrpblib_reset_raster.3
new file mode 100644
index 0000000..6681757
--- /dev/null
+++ b/rtgrpblib_reset_raster.3
@@ -0,0 +1,61 @@
+.TH RTGRPBLIB_RESET_RASTER 3 LIBRIFUNKTIONSTECKENSNITTSGLYFRASTERISERINGSPROGRAMBIBLIOTEKET
+.SH NAME
+rtgrpblib_reset_raster - Reuse a drawing buffer
+
+.SH DESCRIPTION
+.LP
+.nf
+#include <librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.h>
+
+int rtgrpblib_reset_raster(RTGRPBLIB_RASTER *\fIraster\fP, size_t \fIwidth\fP, size_t \fIheight\fP);
+.fi
+.PP
+Link with
+.IR "-lrifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket" .
+
+.SH DESCRIPTION
+The
+.BR rtgrpblib_reset_raster ()
+function changes a buffer's
+.RI ( raster 's)
+width and height, to
+.I width
+and
+.IR height ,
+respectively, and clears the buffer as if recently
+created. However, the function cannot reallocate
+the buffer, which means that the new area cannot
+be greater than the original area, however it can
+be greater than the current area.
+.PP
+Other configurations in
+.I raster
+are kept as is.
+
+.SH RETURN VALUES
+The
+.BR rtgrpblib_reset_raster ()
+function returns 0 upon successful completion,
+and -1 on failure.
+
+.SH ERRORS
+The
+.BR rtgrpblib_reset_raster ()
+function will fail if:
+.TP
+.B EINVAL
+.I width
+or
+.I height
+is zero.
+.TP
+.B EINVAL
+The product
+.I width
+and
+.I height
+exceeds the original size of the buffer.
+
+.SH SEE ALSO
+.BR librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket (7),
+.BR rtgrpblib_create_raster (3)
diff --git a/rtgrpblib_set_draftness.3 b/rtgrpblib_set_draftness.3
new file mode 100644
index 0000000..43fd83f
--- /dev/null
+++ b/rtgrpblib_set_draftness.3
@@ -0,0 +1,42 @@
+.TH RTGRPBLIB_SET_DRAFTNESS 3 LIBRIFUNKTIONSTECKENSNITTSGLYFRASTERISERINGSPROGRAMBIBLIOTEKET
+.SH NAME
+rtgrpblib_set_draftness - Reconfigure a drawing buffer with a new draftness value
+
+.SH DESCRIPTION
+.LP
+.nf
+#include <librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket.h>
+
+void rtgrpblib_set_draftness(RTGRPBLIB_RASTER *\fIraster\fP, double \fIdraftness\fP);
+.fi
+.PP
+Link with
+.IR "-lrifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket" .
+
+.SH DESCRIPTION
+The
+.BR rtgrpblib_set_draftness ()
+function changes that draftness value of drawing buffer
+.I raster
+to the value specified in the
+.I draftness
+parameter. The value must be positive, and shall not be
+unreasonably small, lest drawing functions may get stuck.
+The default value is 0.5.
+.PP
+When drawing a curve, the size of each step the library
+takes will be proportional to the draftness value, but
+will also depend on other factors. Doubling the draftness
+value with halve (disregarind overheads) the time it takes
+to draw any given curve.
+
+.SH RETURN VALUES
+None.
+
+.SH ERRORS
+None.
+
+.SH SEE ALSO
+.BR librifunktionsteckensnittsglyfrasteriseringsprogrambiblioteket (7),
+.BR rtgrpblib_create_raster (3),
+.BR rtgrpblib_fill_shapes (3)