diff options
| -rw-r--r-- | Makefile | 20 | ||||
| -rw-r--r-- | README | 13 | ||||
| -rw-r--r-- | libparsepsf.7 | 15 | ||||
| -rw-r--r-- | libparsepsf.h | 2 | ||||
| -rw-r--r-- | libparsepsf.h.0 | 39 | ||||
| -rw-r--r-- | libparsepsf_destroy_font.3 | 26 | ||||
| l--------- | libparsepsf_font.3 | 1 | ||||
| -rw-r--r-- | libparsepsf_get_glyph.3 | 94 | ||||
| -rw-r--r-- | libparsepsf_parse_font.3 | 133 | ||||
| l--------- | libparsepsf_unimap.3 | 1 | ||||
| l--------- | struct_libparsepsf_font.3 | 1 | ||||
| l--------- | struct_libparsepsf_unimap.3 | 1 |
12 files changed, 344 insertions, 2 deletions
@@ -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 @@ -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 |