aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Makefile20
-rw-r--r--README13
-rw-r--r--libparsepsf.715
-rw-r--r--libparsepsf.h2
-rw-r--r--libparsepsf.h.039
-rw-r--r--libparsepsf_destroy_font.326
l---------libparsepsf_font.31
-rw-r--r--libparsepsf_get_glyph.394
-rw-r--r--libparsepsf_parse_font.3133
l---------libparsepsf_unimap.31
l---------struct_libparsepsf_font.31
l---------struct_libparsepsf_unimap.31
12 files changed, 344 insertions, 2 deletions
diff --git a/Makefile b/Makefile
index f0f17e9..f699cc3 100644
--- a/Makefile
+++ b/Makefile
@@ -20,6 +20,17 @@ OBJ =\
HDR =\
libparsepsf.h
+MAN0 =\
+ libparsepsf.h.0
+
+MAN3 =\
+ libparsepsf_destroy_font.3\
+ libparsepsf_get_glyph.3\
+ libparsepsf_parse_font.3
+
+MAN7 =\
+ libparsepsf.7
+
all: libparsepsf.a libparsepsf.$(LIBEXT) demo
$(OBJ): $(HDR)
@@ -45,12 +56,18 @@ demo: demo.o libparsepsf.a
install: libparsepsf.a
mkdir -p -- "$(DESTDIR)$(PREFIX)/lib"
mkdir -p -- "$(DESTDIR)$(PREFIX)/include"
+ mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man0"
+ mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3"
+ mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man7"
cp -- libparsepsf.a "$(DESTDIR)$(PREFIX)/lib"
cp -- libparsepsf.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBMINOREXT)"
$(FIX_INSTALL_NAME) "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBMINOREXT)"
ln -sf -- "libparsepsf.$(LIBMINOREXT)" "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBMAJOREXT)"
ln -sf -- "libparsepsf.$(LIBMAJOREXT)" "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBEXT)"
cp -- libparsepsf.h "$(DESTDIR)$(PREFIX)/include"
+ cp -P -- $(MAN0) "$(DESTDIR)$(MANPREFIX)/man0"
+ cp -P -- $(MAN3) "$(DESTDIR)$(MANPREFIX)/man3"
+ cp -P -- $(MAN7) "$(DESTDIR)$(MANPREFIX)/man7"
uninstall:
-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libparsepsf.a"
@@ -58,6 +75,9 @@ uninstall:
-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBMAJOREXT)"
-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libparsepsf.$(LIBMINOREXT)"
-rm -f -- "$(DESTDIR)$(PREFIX)/include/libparsepsf.h"
+ -cd -- "$(DESTDIR)$(MANPREFIX)/man0" && rm -f -- $(MAN0)
+ -cd -- "$(DESTDIR)$(MANPREFIX)/man3" && rm -f -- $(MAN3)
+ -cd -- "$(DESTDIR)$(MANPREFIX)/man7" && rm -f -- $(MAN7)
clean:
-rm -f -- *.o *.lo *.su *.a *.so *.so.* demo
diff --git a/README b/README
index 96de825..f4295db 100644
--- a/README
+++ b/README
@@ -1 +1,12 @@
-libparsepsf is a C library for interpreting PSF (PC Screen Font) files.
+NAME
+ libparsepsf - Library for interpreting PSF (PC Screen Font) files.
+
+DESCRIPTION
+ libparsepsf is a C library for interpreting PSF (PC Screen Font) files.
+ It can be used to examine the contents of a font file, and look up
+ glyphs to use a for a text. It is not rendering text, instead
+ the user is given enough information to implement it's own rendering;
+ nor is the library capable of creating PSF files.
+
+SEE ALSO
+ None
diff --git a/libparsepsf.7 b/libparsepsf.7
new file mode 100644
index 0000000..32b8e66
--- /dev/null
+++ b/libparsepsf.7
@@ -0,0 +1,15 @@
+.TH LIBPARSEPSF 7 LIBPARSEPSF
+.SH NAME
+libparsepsf \- Library for interpreting PSF (PC Screen Font) files.
+.SH DESCRIPTION
+.B libparsepsf
+is a C library for interpreting PSF (PC Screen Font) files.
+It can be used to examine the contents of a font file, and look up
+glyphs to use a for a text. It is not rendering text, instead
+the user is given enough information to implement it's own rendering;
+nor is the library capable of creating PSF files.
+.SH SEE ALSO
+.BR libparsepsf.h (0),
+.BR libparsepsf_parse_font (3),
+.BR libparsepsf_get_glyph (3),
+.BR libparsepsf_destroy_font (3)
diff --git a/libparsepsf.h b/libparsepsf.h
index 74b229b..8e98789 100644
--- a/libparsepsf.h
+++ b/libparsepsf.h
@@ -60,7 +60,7 @@ struct libparsepsf_font {
/**
* Glyph trie, maps from byte sequences to glyph indices;
* you can use `libparsepsf_get_glyph` to search it
- * (enumeration has to be done manually); not that an
+ * (enumeration has to be done manually); note that an
* entry can be multiple characters wide, for example
* to deal with context dependent glyphs and grapheme
* clusters
diff --git a/libparsepsf.h.0 b/libparsepsf.h.0
new file mode 100644
index 0000000..b3193eb
--- /dev/null
+++ b/libparsepsf.h.0
@@ -0,0 +1,39 @@
+.TH LIBPARSEPSF.H 0 LIBPARSEPSF
+.SH NAME
+libparsepsf.h \- Header file for interpreting PSF (PC Screen Font) files.
+.SH SYNOPSIS
+.nf
+#include <libparsepsf.h>
+.fi
+.PP
+Link with
+.IR -lparsepsf .
+.SH DESCRIPTION
+The
+.B <libparsepsf.h>
+header defines structures and functions for interpreting PSF
+(PC Screen Font) files.
+.PP
+This header defines the following functions:
+.TP
+.BR libparsepsf_parse_font (3)
+Parse a PSF file.
+.TP
+.BR libparsepsf_get_glyph (3)
+Get glyph to use at a position in a text string.
+.TP
+.BR libparsepsf_destroy_font (3)
+Deallocate a parsed PSF file.
+.PP
+This header defines the following structures:
+.TP
+.B struct libparsepsf_font
+Structure containing all font information.
+.TP
+.B struct libparsepsf_unimap
+Node for byte-sequence-to-glyph mapping trie.
+.SH SEE ALSO
+.BR libparsepsf (7),
+.BR libparsepsf_parse_font (3),
+.BR libparsepsf_get_glyph (3),
+.BR libparsepsf_destroy_font (3)
diff --git a/libparsepsf_destroy_font.3 b/libparsepsf_destroy_font.3
new file mode 100644
index 0000000..8763e3c
--- /dev/null
+++ b/libparsepsf_destroy_font.3
@@ -0,0 +1,26 @@
+.TH LIBPARSEPSF_DESTROY_FONT 3 LIBPARSEPSF
+.SH NAME
+libparsepsf_destroy_font \- Deallocate a parsed PSF files
+.SH SYNOPSIS
+.nf
+#include <libparsepsf.h>
+
+void libparsepsf_destroy_font(struct libparsepsf_font *\fIfont\fP);
+.fi
+.PP
+Link with
+.IR -lparsepsf .
+.SH DESCRIPTION
+The
+.B libparsepsf_destroy_font
+function deallocates the contents of
+.IR *font ,
+without deallocating the memory that the pointer
+itself points to directly (only memory pointed
+to by nested pointers).
+.SH RETURN VALUE
+None.
+.SH ERRORS
+None.
+.SH SEE ALSO
+.BR libparsepsf_parse_font (3)
diff --git a/libparsepsf_font.3 b/libparsepsf_font.3
new file mode 120000
index 0000000..21a36bb
--- /dev/null
+++ b/libparsepsf_font.3
@@ -0,0 +1 @@
+struct_libparsepsf_font.3 \ No newline at end of file
diff --git a/libparsepsf_get_glyph.3 b/libparsepsf_get_glyph.3
new file mode 100644
index 0000000..bb2c481
--- /dev/null
+++ b/libparsepsf_get_glyph.3
@@ -0,0 +1,94 @@
+.TH LIBPARSEPSF_GET_GLYPH 3 LIBPARSEPSF
+.SH NAME
+libparsepsf_get_glyph \- Get glyph to use in a position in a text
+.SH SYNOPSIS
+.nf
+#include <libparsepsf.h>
+
+size_t libparsepsf_get_glyph(struct libparsepsf_font *\fIfont\fP, const char *\fIc\fP, size_t *\fIremp\fP, const char **\fInext_cp\fP);
+.fi
+.PP
+Link with
+.IR -lparsepsf .
+.SH DESCRIPTION
+The
+.B libparsepsf_get_glyph
+function gets the next glyph to print for a line of text.
+.PP
+.I font
+be a parsed font: created with
+.BR libparsepsf_parse_font (3).
+.PP
+.I c
+shall be the current position in the text, and either
+.I remp
+shall be
+.I NULL
+or
+.I *remp
+shall be the number of bytes remaining in the text.
+.PP
+Upon successful completion, the number of bytes
+read from
+.I c
+will be subtracted from
+.IR *remp
+(unless
+.I remp
+is
+.IR NULL ),
+and, unless
+.I next_cp
+is
+.I NULL,
+.I *next_cp
+will be set to
+.I &c[n]
+where
+.I n
+is the number of bytes in the byte-sequence for the
+returned glyph.
+.PP
+If and only if
+.I remp
+is
+.IR NULL ,
+the
+.B libparsepsf_get_glyph
+function will assume the text ends at the first NUL byte.
+.PP
+.I *remp
+and
+.I *next_cp
+are only updated if the function returns a non-zero value.
+.SH RETURN VALUE
+The
+.B libparsepsf_get_glyph
+function returned a glyph index, plus 1, upon successful
+completion, or 0 if the end of the text has been reached
+or if there is no glyph for the current position. On
+failure the function returns 0 and sets
+.I errno
+appropriately to indicate the error.
+.SH ERRORS
+The
+.B libparsepsf_get_glyph
+function may fail if:
+.TP
+.B EILSEQ
+If
+.I font->map
+is
+.I NULL
+and an illegal byte sequence was found.
+.SH NOTE
+A sequence of multiple characters can be rendered as a
+single glyph, therefore it is important that the entire
+text line has been loaded and there all characters on
+the line in prior positions have been mapped.
+.PP
+The
+.B libparsepsf_get_glyph
+function does not treat <newline> especially.
+.SH SEE ALSO
+.BR libparsepsf_parse_font (3)
diff --git a/libparsepsf_parse_font.3 b/libparsepsf_parse_font.3
new file mode 100644
index 0000000..7fe22b8
--- /dev/null
+++ b/libparsepsf_parse_font.3
@@ -0,0 +1,133 @@
+.TH LIBPARSEPSF_PARSE_FONT 3 LIBPARSEPSF
+.SH NAME
+libparsepsf_parse_font \- Parse the contents of a PSF file
+.SH SYNOPSIS
+.nf
+#include <libparsepsf.h>
+
+struct libparsepsf_unimap {
+ struct libparsepsf_unimap *\fInonterminal\fP[256];
+ size_t \fIterminal\fP[256];
+};
+
+struct libparsepsf_font {
+ size_t \fInum_glyphs\fP;
+ size_t \fIheight\fP;
+ size_t \fIwidth\fP;
+ uint8_t *\fIglyph_data\fP;
+ struct libparsepsf_unimap *\fImap\fP;
+};
+
+int libparsepsf_parse_font(const void *\fIdata\fP, size_t \fIsize\fP, struct libparsepsf_font *\fIfontp\fP, uint32_t *\fIunrecognised_versionp\fP);
+.fi
+.PP
+Link with
+.IR -lparsepsf .
+.SH DESCRIPTION
+The
+.B libparsepsf_parse_font
+parses the contents of a PSF (PC Screen Font) file,
+and output the information in the file, in
+.IR *fontp
+upon successful completion, which should be deallocated
+using the
+.BR libparsepsf_destroy_font (3)
+function when it is no longer needed. On failure
+.IR *fontp
+is set so that
+.BR libparsepsf_destroy_font (3)
+can be called without any side-effects.
+.PP
+.I data
+shall contain the content contents of the entire
+font file, and
+.I size
+shall be set to the number of bytes in the font file.
+.PP
+.I *unrecognised_versionp
+is normally set to 0, however, if the minor format
+version used by the font file is not recognised,
+.I *unrecognised_versionp
+will be set to that number.
+.I *unrecognised_versionp
+being set to a non-zero number, does not indicate
+failure as it is assumed that backwards-compatibility
+exists within major format versions.
+.PP
+No argument may be
+.IR NULL .
+.PP
+.I fontp->num_glyph
+will be set to the number of glyphs in the font,
+.I fontp->width
+will be set to the bit-width of each glyph in the font,
+.I fontp->height
+will be set to the bit-height of each glyph in the font,
+.I fontp->glyph_data
+will contain the glyphs in the font, and
+.I fontp->map
+will either be set to
+.I NULL
+or a trie that maps byte sequences to glyph indices.
+.PP
+If
+.I fontp->map
+is
+.IR NULL ,
+unicode character points map directly (identity mapping)
+to glyph indices; and UTF-8 the assumed encoding; otherwise
+.I fontp->map
+maps byte sequences (from an unspecified encoding, usually
+UTF-8) to glyph indices.
+.I fontp->map
+can be searched using the
+.BR libparsepsf_get_glyph (3)
+function, but enumeration must be done manually. Note that
+an entry can be multiple characters wide, for example to
+deal with context dependent glyphs and grapheme clusters.
+In each node in the trie,
+.IR nonterminal[b] ,
+for a byte
+.IR b ,
+maps either to
+.I NULL
+if there is no glyph for a continuation on the current
+byte sequence, or to a trie-node for the byte in the
+byte sequence. Regardless of the value of
+.IR nonterminal[b] ,
+.I terminal[b] ,
+may map either to 0, if there is no glyph for the current
+byte sequence, or the glyph index, plus 1, for the current
+byte sequence.
+.PP
+.I fontp->glyph_data
+is a ordered array of glyph, where is glyph is oriented in
+row-major and most-significant-bit-first order, but each
+row is also right-padded to a multiple of 8 bits, meaning
+that the bit 0x80 in the first byte for a glyph represents
+the left-most, top-most bit in the, and 0x40 in the same
+byte represents the bit directly right to it. Bit on means
+ink on, bit off means ink off. For a glyph index
+.IR i ,
+.I &fontp->glyph_data[i*(fontp->height*(fontp->width/8+(fontp->width%8>0)))]
+maps to the start of the glyph with that index.
+.SH RETURN VALUE
+The
+.B libparsepsf_parse_font
+function returns 0 upon successful completion.
+On failure, -1 is returned and
+.I errno
+is set appropriately to indicate the error.
+.SH ERRORS
+The
+.B libparsepsf_parse_font
+function may fail if:
+.TP
+.B ENOMEM
+The function failed to allocate enough memory.
+.TP
+.B EBFONT
+The font file is corrupt or unsupported.
+.SH SEE ALSO
+.BR libparsepsf_destroy_font (3),
+.BR libparsepsf_get_glyph (3)
diff --git a/libparsepsf_unimap.3 b/libparsepsf_unimap.3
new file mode 120000
index 0000000..21a36bb
--- /dev/null
+++ b/libparsepsf_unimap.3
@@ -0,0 +1 @@
+struct_libparsepsf_font.3 \ No newline at end of file
diff --git a/struct_libparsepsf_font.3 b/struct_libparsepsf_font.3
new file mode 120000
index 0000000..14403d3
--- /dev/null
+++ b/struct_libparsepsf_font.3
@@ -0,0 +1 @@
+libparsepsf_parse_font.3 \ No newline at end of file
diff --git a/struct_libparsepsf_unimap.3 b/struct_libparsepsf_unimap.3
new file mode 120000
index 0000000..21a36bb
--- /dev/null
+++ b/struct_libparsepsf_unimap.3
@@ -0,0 +1 @@
+struct_libparsepsf_font.3 \ No newline at end of file