diff options
Diffstat (limited to 'libparsepsf.h')
| -rw-r--r-- | libparsepsf.h | 99 |
1 files changed, 98 insertions, 1 deletions
diff --git a/libparsepsf.h b/libparsepsf.h index b1984b4..d13c062 100644 --- a/libparsepsf.h +++ b/libparsepsf.h @@ -6,22 +6,119 @@ #include <stddef.h> +/** + * Glyph trie + */ struct libparsepsf_unimap { + + /** + * Mapping for next byte in a longer sequences + */ struct libparsepsf_unimap *nonterminal[256]; - size_t terminal[256]; /* index + 1, 0 if not used */ + + /** + * Unless the byte index maps to 0, mapped to value + * less 1 is the glyph index to use for the sequence + * if there is no longer sequence + */ + size_t terminal[256]; }; +/** + * Parsed PSF font structure + */ struct libparsepsf_font { + + /** + * The number of glyphs in the font + */ size_t num_glyphs; + + /** + * The bit-height of each glyph + */ size_t height; + + /** + * The bit-width of each glyph + */ size_t width; + + /** + * The glyph data + * + * Each glyph is `.height * (.width / 8 + (.width % 8 ? 1 : 0))` + * bytes large. Each glyph is right-padded to a multiple of 8 bits, + * and are oriented in row-major and most-signficant-bit-first order, + * 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. + */ uint8_t *glyph_data; + + /** + * 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 + * entry can be multiple characters wide, for example + * to deal with context dependent glyphs and grapheme + * clusters + * + * `NULL` if unicode character points map directly + * (identity mapping) to glyph indices; and UTF-8 the + * assumed encoding + */ struct libparsepsf_unimap *map; }; +/** + * Deallocate font + * + * @param font Pointer to the data to deallocate + */ void libparsepsf_destroy_font(struct libparsepsf_font *font); + +/** + * Parse a PSF font file + * + * @param data The font file content + * @param size The number of bytes in `data` + * @param fontp Output parameter for the font, should be deallocated + * using `libparsepsf_destroy_font` when no longer + * needed (only allocated on success completion) + * @param unrecognised_versionp Normally set to 0; set to 1 if the minor version in + * the font file is unrecognised (backwards-compatibility + * is assumed, so it will still be parsed as a supported + * font file) + * @return 0 on successful completion, -1 on failure + * @throws ENOMEM Failed to allocate enough memory + * @throws EBFONT Corrupt or unsupported font file + */ int libparsepsf_parse_font(const void *data, size_t size, struct libparsepsf_font *fontp, uint32_t *unrecognised_versionp); + +/** + * Get the next glyph to print for a text + * + * @param font The parsed font, created with `libparsepsf_parse_font` + * @param c The current position in the text (the text shall be + * completely loaded to guarantee multi-characters glyphs + * are properly printed) + * @param remp The number of bytes in `c`, will be updated to reflect + * the value it shall have when the function is called + * again, with `*next_cp` as `c` (that is, the number of + * bytes in the found byte sequence is subtracted); + * if `NULL`, the text ends when a NUL byte is found + * @param next_cp Output parameter for the next position in the text; + * may be `NULL` + * @return The index of the glyph, plus 1; 0 if the glyph if the + * end of the text is reached or if no glyph is found, + * or (only if `font->map` is `NULL`) if an illegal byte + * sequence was found + * @throws EILSEQ If an illegal byte sequence was found (only if + * `font->map` is `NULL`) + */ size_t libparsepsf_get_glyph(const struct libparsepsf_font *font, const char *c, size_t *remp, const char **next_cp); #endif |