Add section 3 man pages

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

1 files changed, 162 insertions, 0 deletions

diff --git a/libparsepcf_get_bitmaps.3 b/libparsepcf_get_bitmaps.3
new file mode 100644
index 0000000..54daed5
--- /dev/null
+++ b/libparsepcf_get_bitmaps.3
@@ -0,0 +1,162 @@
+.TH LIBPARSEPCF_GET_BITMAPS 3 LIBPARSEPCF
+.SH NAME
+libparsepcf_get_bitmaps \- Get glyph bitmaps
+
+.SH SYNOPSIS
+.nf
+#include <libparsepcf.h>
+
+#define LIBPARSEPCF_BITMAPS /* value omitted */
+
+struct libparsepcf_bitmaps {
+	size_t \fIglyph_count\fP;
+	size_t \fIbit_packing\fP;
+	size_t \fIrow_padding\fP;
+	int \fImsbyte_first\fP;
+	int \fImsbit_first\fP;
+	const uint8_t *\fIbitmap_data\fP;
+	/* fields intended for internal use omitted */
+};
+
+int libparsepcf_get_bitmaps(const void *\fIdata\fP, size_t \fIsize\fP,
+                            const struct libparsepcf_table *\fItable\fP,
+                            struct libparsepcf_bitmaps *\fImeta_out\fP);
+
+int libparsepcf_get_bitmap_offsets(const void *\fIdata\fP, size_t \fIsize\fP,
+                                   const struct libparsepcf_table *\fItable\fP,
+                                   const struct libparsepcf_bitmaps *\fImeta\fP,
+                                   size_t *\fIoffsets_out\fP,
+                                   size_t \fIfirst\fP, size_t \fIcount\fP);
+.fi
+.PP
+Link with
+.IR -lparsepcf .
+
+.SH DESCRIPTION
+Glyphs in PCF fonts are encoded as bitmaps which
+can be looked up in the table with the type
+.BR LIBPARSEPCF_BITMAPS ,
+which can be retrieved with the
+.BR libparsepcf_get_tables (3)
+function.
+.PP
+Once the
+.B LIBPARSEPCF_BITMAPS
+table has been identified, it can be passed as
+the third argument
+.RI ( table )
+to the
+.BR libparsepcf_get_bitmaps ()
+function along with the font file contents in the
+.I data
+argument and size, in bytes, of the file in the
+.I size
+argument. The
+.BR libparsepcf_get_bitmaps ()
+function will store the number of available
+glyphs in
+.IR meta_out->glyph_count ,
+which shall be used to check that all glyphs
+have a bitmap recorded. The
+.BR libparsepcf_get_bitmaps ()
+function will store information needed to decode
+the bitmap in
+.IR *meta_out .
+.PP
+Then the
+.BR libparsepcf_get_bitmap_offsets ()
+function can be used to get offset from
+.I meta_out->bitmap_data
+where the bitmap for each glyph is stored.
+The first four arguments shall be the
+same as with
+.BR libparsepcf_get_bitmaps ().
+.I first
+shall be the index of the glyph with the lowest index
+of the glyph the function shall get the bitmap offset
+for, and
+.I count
+shall be the number of consecutive glyphs
+(including the first glyph) to get this information
+for. For each queried glyph with index
+.IR i ,
+the bitmap offset will be stored in
+.IR offsets_out[i-first] .
+.PP
+The application shall ensure that
+.IR "first + count <= meta->glyph_count" .
+.PP
+Note that glyph indices are not the same as character
+codepoints. See
+.BR libparsepcf_get_encoding (3)
+for details about mapping characters to glyphs.
+.PP
+The be able to interpret a glyph's bitmap, it's ink
+metrics must also be acquired. The
+.BR libparsepcf_get_metrics (3)
+function is used to get a glyph's ink metrics. The
+ink metrics describe the boundaries of the bitmap,
+but the
+.BR libparsepcf_get_bitmaps ()
+function returns encoding information. The bitmap
+encodes the glyph row by row, from top to bottom,
+at the end of each row, padding is inserted into
+the bitmap to align the beginning of the next row
+in the bitmap. It is always padded to a number of
+two bytes, specified in
+.IR meta_out->row_padding .
+For each row, the cells are encoded from left to
+right, there are three fields in
+.I meta_out
+that affect the order of the bits. For example,
+the bits can be group in bytes, dual-byte words or
+quad-byte words. The number of bytes in each group
+is specified in
+.IR meta_out->bit_packing ,
+which is always a power of two and no greater than
+.IR meta_out->row_padding ,
+and each these units are intepreted as unsigned integers,
+that are either encoded in big endian (most significant
+byte first) or little endian (least significant
+byte first).
+.I meta_out->msbyte_first
+will either be 0 or 1. If 0, these units are encoded
+in little endian; if 1 these units are encoded in
+big endian. Once a unit as been interpreted as in
+unsigned integer, its bits can be inspected to
+determine the value of each cell the unit covers,
+the cells are order from left to right, but the
+bits either ordered from least significant to most
+significant or from most significant to least
+significant, and for each set bit the corresponding
+cell is inked and for each cleared bit the
+corresponding cell is uninked.
+.I meta_out->msbit_first
+is used to determine the bit order; it will either
+be 0 or 1. If 0, the bits are ordered from least
+significant to most significant; if 1, the bits are
+ordered from most significant to least significant.
+
+.SH RETURN VALUE
+The
+.BR libparsepcf_get_bitmaps ()
+and
+.BR libparsepcf_get_bitmap_offsets ()
+functions return 0 upon successful completion.
+On failure, -1 is returned and
+.I errno
+is set appropriately to indicate the error.
+
+.SH ERRORS
+The
+.BR libparsepcf_get_bitmaps ()
+and
+.BR libparsepcf_get_bitmap_offsets ()
+functions fail if:
+.TP
+.B EBFONT
+The font file is corrupt or unsupported.
+
+.SH SEE ALSO
+.BR libparsepcf (7),
+.BR libparsepcf_preparse_font (3)