From 45cc16376f79ceeb642da4a5ab5b4568b3231871 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sun, 13 Oct 2024 23:14:32 +0200 Subject: Add section 3 man pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- LIBPARSEPCF_ACCELERATORS.3 | 1 + LIBPARSEPCF_BDF_ACCELERATORS.3 | 1 + LIBPARSEPCF_BDF_ENCODINGS.3 | 1 + LIBPARSEPCF_BITMAPS.3 | 1 + LIBPARSEPCF_GLYPH_NAMES.3 | 1 + LIBPARSEPCF_INK_METRICS.3 | 1 + LIBPARSEPCF_METRICS.3 | 1 + LIBPARSEPCF_NOT_ENCODED.3 | 1 + LIBPARSEPCF_PROPERTIES.3 | 1 + LIBPARSEPCF_SWIDTHS.3 | 1 + Makefile | 51 +++++++ libparsepcf.h | 10 +- libparsepcf_destroy_preparsed_font.3 | 1 + libparsepcf_get_accelerators.3 | 161 +++++++++++++++++++++ libparsepcf_get_bitmap_offsets.3 | 1 + libparsepcf_get_bitmaps.3 | 162 +++++++++++++++++++++ libparsepcf_get_encoding.3 | 170 ++++++++++++++++++++++ libparsepcf_get_glyph_indices.3 | 1 + libparsepcf_get_glyph_name_subtable.3 | 1 + libparsepcf_get_glyph_names.3 | 111 +++++++++++++++ libparsepcf_get_metrics.3 | 150 ++++++++++++++++++++ libparsepcf_get_metrics_count.3 | 1 + libparsepcf_get_properties.3 | 180 ++++++++++++++++++++++++ libparsepcf_get_property_subtable.3 | 1 + libparsepcf_get_swidth_count.3 | 1 + libparsepcf_get_swidths.3 | 105 ++++++++++++++ libparsepcf_get_table_count.3 | 1 + libparsepcf_get_tables.3 | 101 +++++++++++++ libparsepcf_preparse_font.3 | 249 +++++++++++++++++++++++++++++++++ struct_libparsepcf_accelerators.3 | 1 + struct_libparsepcf_bitmaps.3 | 1 + struct_libparsepcf_encoding.3 | 1 + struct_libparsepcf_font.3 | 1 + struct_libparsepcf_glyph_names.3 | 1 + struct_libparsepcf_metrics.3 | 1 + struct_libparsepcf_properties.3 | 1 + struct_libparsepcf_property_subtable.3 | 1 + struct_libparsepcf_table.3 | 1 + 38 files changed, 1474 insertions(+), 3 deletions(-) create mode 120000 LIBPARSEPCF_ACCELERATORS.3 create mode 120000 LIBPARSEPCF_BDF_ACCELERATORS.3 create mode 120000 LIBPARSEPCF_BDF_ENCODINGS.3 create mode 120000 LIBPARSEPCF_BITMAPS.3 create mode 120000 LIBPARSEPCF_GLYPH_NAMES.3 create mode 120000 LIBPARSEPCF_INK_METRICS.3 create mode 120000 LIBPARSEPCF_METRICS.3 create mode 120000 LIBPARSEPCF_NOT_ENCODED.3 create mode 120000 LIBPARSEPCF_PROPERTIES.3 create mode 120000 LIBPARSEPCF_SWIDTHS.3 create mode 120000 libparsepcf_destroy_preparsed_font.3 create mode 100644 libparsepcf_get_accelerators.3 create mode 120000 libparsepcf_get_bitmap_offsets.3 create mode 100644 libparsepcf_get_bitmaps.3 create mode 100644 libparsepcf_get_encoding.3 create mode 120000 libparsepcf_get_glyph_indices.3 create mode 120000 libparsepcf_get_glyph_name_subtable.3 create mode 100644 libparsepcf_get_glyph_names.3 create mode 100644 libparsepcf_get_metrics.3 create mode 120000 libparsepcf_get_metrics_count.3 create mode 100644 libparsepcf_get_properties.3 create mode 120000 libparsepcf_get_property_subtable.3 create mode 120000 libparsepcf_get_swidth_count.3 create mode 100644 libparsepcf_get_swidths.3 create mode 120000 libparsepcf_get_table_count.3 create mode 100644 libparsepcf_get_tables.3 create mode 100644 libparsepcf_preparse_font.3 create mode 120000 struct_libparsepcf_accelerators.3 create mode 120000 struct_libparsepcf_bitmaps.3 create mode 120000 struct_libparsepcf_encoding.3 create mode 120000 struct_libparsepcf_font.3 create mode 120000 struct_libparsepcf_glyph_names.3 create mode 120000 struct_libparsepcf_metrics.3 create mode 120000 struct_libparsepcf_properties.3 create mode 120000 struct_libparsepcf_property_subtable.3 create mode 120000 struct_libparsepcf_table.3 diff --git a/LIBPARSEPCF_ACCELERATORS.3 b/LIBPARSEPCF_ACCELERATORS.3 new file mode 120000 index 0000000..373e5bb --- /dev/null +++ b/LIBPARSEPCF_ACCELERATORS.3 @@ -0,0 +1 @@ +libparsepcf_get_accelerators.3 \ No newline at end of file diff --git a/LIBPARSEPCF_BDF_ACCELERATORS.3 b/LIBPARSEPCF_BDF_ACCELERATORS.3 new file mode 120000 index 0000000..373e5bb --- /dev/null +++ b/LIBPARSEPCF_BDF_ACCELERATORS.3 @@ -0,0 +1 @@ +libparsepcf_get_accelerators.3 \ No newline at end of file diff --git a/LIBPARSEPCF_BDF_ENCODINGS.3 b/LIBPARSEPCF_BDF_ENCODINGS.3 new file mode 120000 index 0000000..2b68279 --- /dev/null +++ b/LIBPARSEPCF_BDF_ENCODINGS.3 @@ -0,0 +1 @@ +libparsepcf_get_encoding.3 \ No newline at end of file diff --git a/LIBPARSEPCF_BITMAPS.3 b/LIBPARSEPCF_BITMAPS.3 new file mode 120000 index 0000000..8f92a6f --- /dev/null +++ b/LIBPARSEPCF_BITMAPS.3 @@ -0,0 +1 @@ +libparsepcf_get_bitmaps.3 \ No newline at end of file diff --git a/LIBPARSEPCF_GLYPH_NAMES.3 b/LIBPARSEPCF_GLYPH_NAMES.3 new file mode 120000 index 0000000..1d119d1 --- /dev/null +++ b/LIBPARSEPCF_GLYPH_NAMES.3 @@ -0,0 +1 @@ +libparsepcf_get_glyph_names.3 \ No newline at end of file diff --git a/LIBPARSEPCF_INK_METRICS.3 b/LIBPARSEPCF_INK_METRICS.3 new file mode 120000 index 0000000..58b91b9 --- /dev/null +++ b/LIBPARSEPCF_INK_METRICS.3 @@ -0,0 +1 @@ +libparsepcf_get_metrics.3 \ No newline at end of file diff --git a/LIBPARSEPCF_METRICS.3 b/LIBPARSEPCF_METRICS.3 new file mode 120000 index 0000000..58b91b9 --- /dev/null +++ b/LIBPARSEPCF_METRICS.3 @@ -0,0 +1 @@ +libparsepcf_get_metrics.3 \ No newline at end of file diff --git a/LIBPARSEPCF_NOT_ENCODED.3 b/LIBPARSEPCF_NOT_ENCODED.3 new file mode 120000 index 0000000..2b68279 --- /dev/null +++ b/LIBPARSEPCF_NOT_ENCODED.3 @@ -0,0 +1 @@ +libparsepcf_get_encoding.3 \ No newline at end of file diff --git a/LIBPARSEPCF_PROPERTIES.3 b/LIBPARSEPCF_PROPERTIES.3 new file mode 120000 index 0000000..271ccf6 --- /dev/null +++ b/LIBPARSEPCF_PROPERTIES.3 @@ -0,0 +1 @@ +libparsepcf_get_properties.3 \ No newline at end of file diff --git a/LIBPARSEPCF_SWIDTHS.3 b/LIBPARSEPCF_SWIDTHS.3 new file mode 120000 index 0000000..697cd3d --- /dev/null +++ b/LIBPARSEPCF_SWIDTHS.3 @@ -0,0 +1 @@ +libparsepcf_get_swidths.3 \ No newline at end of file diff --git a/Makefile b/Makefile index cabef3f..ccd5c25 100644 --- a/Makefile +++ b/Makefile @@ -15,6 +15,9 @@ LIB_MINOR = 0 LIB_VERSION = $(LIB_MAJOR).$(LIB_MINOR) LIB_NAME = parsepcf +# Version 2.0 is ABI-backwards compatible with +# version 1.0, but not API-backwards compatible + OBJ =\ libparsepcf_destroy_preparsed_font.o\ @@ -45,6 +48,47 @@ HDR =\ libparsepcf.h\ common.h +MAN3 =\ + struct_libparsepcf_table.3\ + LIBPARSEPCF_PROPERTIES.3\ + LIBPARSEPCF_ACCELERATORS.3\ + LIBPARSEPCF_METRICS.3\ + LIBPARSEPCF_BITMAPS.3\ + LIBPARSEPCF_INK_METRICS.3\ + LIBPARSEPCF_BDF_ENCODINGS.3\ + LIBPARSEPCF_SWIDTHS.3\ + LIBPARSEPCF_GLYPH_NAMES.3\ + LIBPARSEPCF_BDF_ACCELERATORS.3\ + libparsepcf_get_table_count.3\ + libparsepcf_get_tables.3\ + struct_libparsepcf_properties.3\ + struct_libparsepcf_property_subtable.3\ + libparsepcf_get_properties.3\ + libparsepcf_get_property_subtable.3\ + struct_libparsepcf_metrics.3\ + libparsepcf_get_metrics_count.3\ + libparsepcf_get_metrics.3\ + struct_libparsepcf_glyph_names.3\ + libparsepcf_get_glyph_names.3\ + libparsepcf_get_glyph_name_subtable.3\ + struct_libparsepcf_bitmaps.3\ + int libparsepcf_get_bitmaps.3\ + int libparsepcf_get_bitmap_offsets.3\ + struct_libparsepcf_encoding.3\ + LIBPARSEPCF_NOT_ENCODED.3\ + libparsepcf_get_encoding.3\ + libparsepcf_get_glyph_indices.3\ + struct_libparsepcf_accelerators.3\ + libparsepcf_get_accelerators.3\ + libparsepcf_get_swidth_count.3\ + libparsepcf_get_swidths.3\ + struct_libparsepcf_font.3\ + libparsepcf_preparse_font.3\ + libparsepcf_destroy_preparsed_font.3 + +MAN0 = libparsepcf.h.0 +MAN7 = libparsepcf.7 + LOBJ = $(OBJ:.o=.lo) SRC = $(OBJ:.o=.c) @@ -73,12 +117,16 @@ libparsepcf.$(LIBEXT): $(LOBJ) install: libparsepcf.a libparsepcf.$(LIBEXT) 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 -- libparsepcf.a "$(DESTDIR)$(PREFIX)/lib/" cp -- libparsepcf.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libparsepcf.$(LIBMINOREXT)" $(FIX_INSTALL_NAME) "$(DESTDIR)$(PREFIX)/lib/libparsepcf.$(LIBMINOREXT)" ln -sf -- libparsepcf.$(LIBMINOREXT) "$(DESTDIR)$(PREFIX)/lib/libparsepcf.$(LIBMAJOREXT)" ln -sf -- libparsepcf.$(LIBMAJOREXT) "$(DESTDIR)$(PREFIX)/lib/libparsepcf.$(LIBEXT)" cp -- libparsepcf.h "$(DESTDIR)$(PREFIX)/include/" + cp -P -- $(MAN3) "$(DESTDIR)$(MANPREFIX)/man3/" uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libparsepcf.a" @@ -86,6 +134,9 @@ uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libparsepcf.$(LIBMINOREXT)" -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libparsepcf.$(LIBEXT)" -rm -f -- "$(DESTDIR)$(PREFIX)/include/libparsepcf.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 *.a *.lo *.su *.so *.so.* *.dll *.dylib diff --git a/libparsepcf.h b/libparsepcf.h index d9ec6dd..f5980e4 100644 --- a/libparsepcf.h +++ b/libparsepcf.h @@ -40,6 +40,8 @@ struct libparsepcf_table { /** * The size of the table + * + * Intended for internal use */ uint32_t size; @@ -48,6 +50,8 @@ struct libparsepcf_table { * * (The file is padded with NUL bytes to align * each table to a 4 byte boundary) + * + * Intended for internal use */ uint32_t offset; }; @@ -667,8 +671,8 @@ struct libparsepcf_accelerators { uint8_t constant_metrics : 1; /** - * `.constant_metrics` and, for all characters, left side bearing = 0, - * right side bearing = character width, ascent = `.font_ascent`, and + * `.constant_metrics` and, for all characters, left-side bearing = 0, + * right-side bearing = character width, ascent = `.font_ascent`, and * descent = `.font_descent` */ uint8_t terminal_font : 1; @@ -748,7 +752,7 @@ struct libparsepcf_accelerators { * * @throws EBFONT The file is not a properly formatted PCF file * - * `LIBPARSEPCF_BDF_ACCELERATORS` shall be prefered over + * `LIBPARSEPCF_BDF_ACCELERATORS` shall be preferred over * `LIBPARSEPCF_ACCELERATORS` of both tables are present. * `LIBPARSEPCF_BDF_ACCELERATORS` is more accurate and refers * only to the encoded characters in the font, whereas diff --git a/libparsepcf_destroy_preparsed_font.3 b/libparsepcf_destroy_preparsed_font.3 new file mode 120000 index 0000000..bcbba50 --- /dev/null +++ b/libparsepcf_destroy_preparsed_font.3 @@ -0,0 +1 @@ +libparsepcf_preparse_font.3 \ No newline at end of file diff --git a/libparsepcf_get_accelerators.3 b/libparsepcf_get_accelerators.3 new file mode 100644 index 0000000..a68c6f4 --- /dev/null +++ b/libparsepcf_get_accelerators.3 @@ -0,0 +1,161 @@ +.TH LIBPARSEPCF_GET_ACCELERATORS 3 LIBPARSEPCF +.SH NAME +libparsepcf_get_accelerators \- Get font information + +.SH SYNOPSIS +.nf +#include + +#define LIBPARSEPCF_ACCELERATORS /* value omitted */ +#define LIBPARSEPCF_BDF_ACCELERATORS /* value omitted */ + +struct libparsepcf_accelerators { + uint8_t \fIno_overlap\fP : 1; + uint8_t \fIconstant_metrics\fP : 1; + uint8_t \fIterminal_font\fP : 1; + uint8_t \fIconstant_width\fP : 1; + uint8_t \fIink_inside\fP : 1; + uint8_t \fIink_metrics\fP : 1; + uint8_t \fIdraw_rtl\fP : 1; + uint8_t \fIhave_ink_bounds\fP : 1; + int32_t \fIfont_ascent\fP; + int32_t \fIfont_descent\fP; + int32_t \fImax_overlap\fP; + struct libparsepcf_metrics \fImin_bounds\fP; + struct libparsepcf_metrics \fImax_bounds\fP; + struct libparsepcf_metrics \fImin_ink_bounds\fP; + struct libparsepcf_metrics \fImax_ink_bounds\fP; +}; + +int libparsepcf_get_accelerators(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + struct libparsepcf_accelerators *\fImeta_out\fP); +.fi +.PP +Link with +.IR -lparsepcf . + +.SH DESCRIPTION +A PCF font files may record overall font +information, intended for optimisations, +in the tables with the types +.B LIBPARSEPCF_ACCELERATORS +and +.B LIBPARSEPCF_BDF_ACCELERATORS +which can be retrieved with the +.BR libparsepcf_get_tables (3) +function. If both tables are present, +.B LIBPARSEPCF_BDF_ACCELERATORS +shall be preferred, it is more accurate +and only refers to the encoded characters +in the font, whereas +.B LIBPARSEPCF_ACCELERATORS +includes all glyphs (not that the fallback +glyph do not necessarily correspond to an +encoded character). +.PP +Once the +.B LIBPARSEPCF_ACCELERATORS +or +.B LIBPARSEPCF_BDF_ACCELERATORS +table has been identified, it can be passed as +the third argument +.RI ( table ) +to the +.BR libparsepcf_get_accelerators () +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_accelerators () +function will store the font information in +.IR *meta_out . +.PP +The following information will be stored in +.IR *meta_out : +.TP +.I no_overlap +If 1, then for each glyph, the layout metrics, +.IR mtx , +.I mtx.right_side_bearing - mtx.character_width +will not be greater than +.IR meta_out->min_bounds.left_side_bearing . +.TP +.I constant_width +If 1, all glyph have the same layout width. +.TP +.I constant_metrics +If 1, all glyphs have the same layout metrics. +.TP +.I terminal_font +If 1, all glyphs have the same layout metrics +and for each glyph, the layout left-side bearing is 0, +the layout right-side bearing is the layout width, +the layout ascent is +.IR meta_out->font_ascent , +and the layout descent is +.IR meta_out->font_descent . +.TP +.I ink_inside +If 1, no glyph will have ink outside the +glyph's layout box. +.TP +.I ink_metrics +If 1, at least one glyph have ink metrics +different from the layout metrics. +.TP +.I draw_rtl +If 1, the font is a right-to-left font, +if 0, the font is a left-to-right font. +.TP +.I have_ink_bounds +If 0, the function copied +.I meta_out->min_bounds +into +.I meta_out->min_ink_bounds +and +.I meta_out->max_bounds +into +.IR meta_out->max_ink_bounds . +.TP +.I font_ascent +The number of pixels the font ascend above the baseline. +.TP +.I font_descent +The number of pixels the font descend below the baseline. +.TP +.I max_overlap +The maximum horizontal overlap, in pixels, of two glyph. +.TP +.I min_bounds +The lower bounds, over each glyph, of the layout metrics. +.TP +.I max_bounds +The upper bounds, over each glyph, of the layout metrics. +.TP +.I min_ink_bounds +The lower bounds, over each glyph, of the ink metrics. +.TP +.I max_ink_bounds +The upper bounds, over each glyph, of the ink metrics. + +.SH RETURN VALUE +The +.BR libparsepcf_get_accelerators () +function returns 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_accelerators () +function fails if: +.TP +.B EBFONT +The font file is corrupt or unsupported. + +.SH SEE ALSO +.BR libparsepcf (7), +.BR libparsepcf_preparse_font (3) diff --git a/libparsepcf_get_bitmap_offsets.3 b/libparsepcf_get_bitmap_offsets.3 new file mode 120000 index 0000000..8f92a6f --- /dev/null +++ b/libparsepcf_get_bitmap_offsets.3 @@ -0,0 +1 @@ +libparsepcf_get_bitmaps.3 \ No newline at end of file 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 + +#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) diff --git a/libparsepcf_get_encoding.3 b/libparsepcf_get_encoding.3 new file mode 100644 index 0000000..428ca19 --- /dev/null +++ b/libparsepcf_get_encoding.3 @@ -0,0 +1,170 @@ +.TH LIBPARSEPCF_GET_ENCODING 3 LIBPARSEPCF +.SH NAME +libparsepcf_get_encoding \- Get glyph index + +.SH SYNOPSIS +.nf +#include + +#define LIBPARSEPCF_BDF_ENCODINGS /* value omitted */ + +#define LIBPARSEPCF_NOT_ENCODED ((size_t)0xFFFF) + +struct libparsepcf_encoding { + uint16_t \fImin_byte2\fP; + uint16_t \fImax_byte2\fP; + uint16_t \fImin_byte1\fP; + uint16_t \fImax_byte1\fP; + uint16_t \fIdefault_glyph\fP; + size_t \fIchar_count\fP; +}; + +int libparsepcf_get_encoding(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + struct libparsepcf_encoding *\fImeta_out\fP); + +int libparsepcf_get_glyph_indices(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + const struct libparsepcf_encoding *\fImeta\fP, + size_t *\fIindices_out\fP, + size_t \fIfirst\fP, size_t \fIcount\fP); +.fi +.PP +Link with +.IR -lparsepcf . + +.SH DESCRIPTION +PCF fonts file are encoded for specific for characters +sets and encodings do not encode glyphs by codepoints +but rather by how characters are encoded. To get the +appropriate glyph for a character, the +.BR libparsepcf_get_properties (3) +function must first be used to determine the encoding, +and if it does not match the expeced encoding translate +the text into the encoding used by the font (it may +also be possible to load a version of the font the +uses the expected encoding). Second, the +.BR libparsepcf_get_tables (3) +function is used to find the table with the type +.BR LIBPARSEPCF_BDF_ENCODINGS , +which is then passed into the +.BR libparsepcf_get_encoding (3) +function as it's third argument +.RI ( table ), +along with the font file contents in the +.I data +argument and size, in bytes, of the file in the +.I size +argument to get the coverage of the font, encoding +information, and the default glyph to use when the +font does not have the glyph for a character. +If the encoding uses one byte for each character, +.I meta_out->min_byte1 +and +.I meta_out->max_byte1 +are both set to 0, otherwise, the encoding uses +two bytes for each character. +The index of the default glyph will be stored in +.IR meta_out->default_glyph . +The fields +.IR meta_out->min_byte1 , +.IR meta_out->max_byte1 , +.IR meta_out->min_byte2 , +and +.I meta_out->max_byte2 +are used to translate an encoded character into +a character index which can then be mapped into +a glyph index using the +.BR libparsepcf_get_glyph_indices () +function. +.PP +When calling the +.BR libparsepcf_get_glyph_indices () +function, the first four arguments shall be +the same as passed into the +.BR libparsepcf_get_encoding () +function. +.I first +shall be the index of the character with the lowest index +of the character the function shall get the glyph index +for, and +.I count +shall be the number of consecutive characters +(including the first character) to get this information +for. For each queried character with index +.IR i , +the glyph index will be stored in +.IR indices_out[i-first] , +however if character is not encoded (does not have +a glyph), it the value +.I LIBPARSEPCF_NOT_ENCODED +will be stored instead. +.PP +The application shall ensure that +.IR "first + count <= meta->char_count" . +.PP +For single-byte encodings, the character index +is calculated by subtracting +.I meta_out->min_byte2 +from the character byte, however the application +must make sure that the value of the character +byte is at least +.I meta_out->min_byte2 +but no greater than +.IR meta_out->max_byte2 . +.PP +For dual-bute encodings, the application must +first ensure that there are two bytes available, +and ensure that the value of the first byte is +at least +.I meta_out->min_byte1 +but no greater than +.IR meta_out->max_byte1 , +and that the value of the second byte is at least +.I meta_out->min_byte2 +but no greater than +.IR meta_out->max_byte2 . +The application can then subtract +.I meta_out->min_byte1 +from the value of the first byte, and call the +difference +.IR a , +and subtract +.I meta_out->min_byte2 +from the value of the second byte, and call the +difference +.IR b . +If the application has already calculated the +font-constant value +.IR ".max_byte2 - .min_byte2 + 1" , +called +.IR k . +The character's index is than calculated by +.IR "a * k + b" . +(This is the simplest description of the +formula but it can be optimised for the +application to use one less subtract.) + +.SH RETURN VALUE +The +.BR libparsepcf_get_encoding () +and +.BR libparsepcf_get_glyph_indices () +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_encoding () +and +.BR libparsepcf_get_glyph_indices () +functions fail if: +.TP +.B EBFONT +The font file is corrupt or unsupported. + +.SH SEE ALSO +.BR libparsepcf (7), +.BR libparsepcf_preparse_font (3) diff --git a/libparsepcf_get_glyph_indices.3 b/libparsepcf_get_glyph_indices.3 new file mode 120000 index 0000000..2b68279 --- /dev/null +++ b/libparsepcf_get_glyph_indices.3 @@ -0,0 +1 @@ +libparsepcf_get_encoding.3 \ No newline at end of file diff --git a/libparsepcf_get_glyph_name_subtable.3 b/libparsepcf_get_glyph_name_subtable.3 new file mode 120000 index 0000000..1d119d1 --- /dev/null +++ b/libparsepcf_get_glyph_name_subtable.3 @@ -0,0 +1 @@ +libparsepcf_get_glyph_names.3 \ No newline at end of file diff --git a/libparsepcf_get_glyph_names.3 b/libparsepcf_get_glyph_names.3 new file mode 100644 index 0000000..d9991b1 --- /dev/null +++ b/libparsepcf_get_glyph_names.3 @@ -0,0 +1,111 @@ +.TH libparsepcf_get_glyph_names 3 LIBPARSEPCF +.SH NAME +libparsepcf_get_glyph_names \- Get glyph PostScript names + +.SH SYNOPSIS +.nf +#include + +#define LIBPARSEPCF_GLYPH_NAMES /* value omitted */ + +struct libparsepcf_glyph_names { + size_t \fIglyph_count\fP; + /* fields intended for internal use omitted */ +}; + +int libparsepcf_get_glyph_names(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + struct libparsepcf_glyph_names *\fImeta_out\fP); + +int libparsepcf_get_glyph_name_subtable(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + const struct libparsepcf_glyph_names *\fImeta\fP, + const char **\fInames_out\fP, + size_t \fIfirst\fP, size_t \fIcount\fP); +.fi +.PP +Link with +.IR -lparsepcf . + +.SH DESCRIPTION +If the PostScript glyph names are stored in +a PCF font file, they are recorded in the table +with the type +.B LIBPARSEPCF_GLYPH_NAMES +retrieved with the +.BR libparsepcf_get_tables (3) +function. +.PP +Once the +.B LIBPARSEPCF_GLYPH_NAMES +table has been identified, it can be passed as +the third argument +.RI ( table ) +to the +.BR libparsepcf_get_glyph_names () +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_glyph_names () +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 name recorded, as well as internal +information needed by the +.BR libparsepcf_get_glyph_name_subtable () +function in other fields in +.IR *meta_out . +.PP +Then the +.BR libparsepcf_get_glyph_name_subtable () +function can be used to get the PostScript names +of each glyph. The first four arguments shall be +the same as with +.BR libparsepcf_get_glyph_names (). +.I first +shall be the index of the glyph with the lowest +index of the glyph the function shall get the +name 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 PostScript name will be stored in +.IR names_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. + +.SH RETURN VALUE +The +.BR libparsepcf_get_glyph_names () +and +.BR libparsepcf_get_glyph_name_subtable () +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_glyph_names () +and +.BR libparsepcf_get_glyph_name_subtable () +functions fail if: +.TP +.B EBFONT +The font file is corrupt or unsupported. + +.SH SEE ALSO +.BR libparsepcf (7), +.BR libparsepcf_preparse_font (3) diff --git a/libparsepcf_get_metrics.3 b/libparsepcf_get_metrics.3 new file mode 100644 index 0000000..70bd623 --- /dev/null +++ b/libparsepcf_get_metrics.3 @@ -0,0 +1,150 @@ +.TH LIBPARSEPCF_GET_METRICS 3 LIBPARSEPCF +.SH NAME +libparsepcf_get_metrics \- Get glyph metrics + +.SH SYNOPSIS +.nf +#include + +#define LIBPARSEPCF_METRICS /* value omitted */ +#define LIBPARSEPCF_INK_METRICS /* value omitted */ + +struct libparsepcf_metrics { + int16_t \fIleft_side_bearing\fP; + int16_t \fIright_side_bearing\fP; + int16_t \fIcharacter_width\fP; + int16_t \fIcharacter_ascent\fP; + int16_t \fIcharacter_descent\fP; + uint16_t \fIcharacter_attributes\fP; +}; + +int libparsepcf_get_metrics_count(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + size_t *\fIcount_out\fP); + +int libparsepcf_get_metrics(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + struct libparsepcf_metrics *\fImetrics_out\fP, + size_t \fIfirst\fP, size_t \fIcount\fP); +.fi +.PP +Link with +.IR -lparsepcf . + +.SH DESCRIPTION +In PCF font files, the layout metrics for each +glyph is recorded in a type with the tape +.BR LIBPARSEPCF_METRICS , +which can be retrieved with the +.BR libparsepcf_get_tables (3) +function. The file may also contain the table +.B LIBPARSEPCF_INK_METRICS +for the ink metrics. If however no +.B LIBPARSEPCF_INK_METRICS +is present in the file, the +.B LIBPARSEPCF_METRICS +file be used for this purpose instead in +addition to layout metrics +.PP +Once the +.B LIBPARSEPCF_METRICS +or +.B LIBPARSEPCF_INK_METRICS +table has been identified, it can be passed as +the third argument +.RI ( table ) +to the +.BR libparsepcf_get_metrics_count () +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_metrics_count () +function will store the number of available +glyphs in +.IR *count_out , +which shall be used to check that all glyphs +have a metrics recorded. +.PP +Then the +.BR libparsepcf_get_metrics () +function can be used to get the glyph metrics of +each glyph. The first three arguments shall be the +same as with +.BR libparsepcf_get_metrics_count (). +.I first +shall be the index of the glyph with the lowest index +of the glyph the function shall get the metrics 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 metrics will be stored in +.IR metrics_out[i-first] . +.PP +The application shall ensure that +.IR "first + count <= *count_out" . +.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 glyph metrics consists of five fields: +.TP +.I left_side_bearing +The number of pixels right of (negative if left of) +the origin (caret position) of the leftmost ink-on +pixel in the glyph +.TP +.I right_side_bearing +The number of pixels right of (negative if left of) +the origin (caret position) of the rightmost ink-on +pixel in the glyph +.TP +.I character_width +The number of pixels the next characters origin shall +be right of the current character's origin (that is +the number of pixels the caret shall advance) +.TP +.I character_ascent +The number of pixels the character ascend above +the baseline (if non-positive, it's fully below +the baseline) +.TP +.I character_descent +The number of pixels the character descend below +the baseline (if non-positive, it's fully above +the baseline) +.PP +Along with the glyph metrics, each glyph may +also have an applications-specific attribute +store in the +.I character_attributes +field. + +.SH RETURN VALUE +The +.BR libparsepcf_get_metrics_count () +and +.BR libparsepcf_get_metrics () +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_metrics_count () +and +.BR libparsepcf_get_metrics () +functions fail if: +.TP +.B EBFONT +The font file is corrupt or unsupported. + +.SH SEE ALSO +.BR libparsepcf (7), +.BR libparsepcf_preparse_font (3) diff --git a/libparsepcf_get_metrics_count.3 b/libparsepcf_get_metrics_count.3 new file mode 120000 index 0000000..58b91b9 --- /dev/null +++ b/libparsepcf_get_metrics_count.3 @@ -0,0 +1 @@ +libparsepcf_get_metrics.3 \ No newline at end of file diff --git a/libparsepcf_get_properties.3 b/libparsepcf_get_properties.3 new file mode 100644 index 0000000..366b07f --- /dev/null +++ b/libparsepcf_get_properties.3 @@ -0,0 +1,180 @@ +.TH LIBPARSEPCF_GET_PROPERTIES 3 LIBPARSEPCF +.SH NAME +libparsepcf_get_properties \- Get font properties + +.SH SYNOPSIS +.nf +#include + +#define LIBPARSEPCF_PROPERTIES /* value omitted */ + +struct libparsepcf_properties { + size_t \fIproperty_count\fP; + /* fields intended for internal use omitted */ +}; + +struct libparsepcf_property_subtable { + const char *\fIname\fP; + int \fIis_string_property\fP; + union { + int32_t \fIsigned_value\fP; + const char *\fIstring_value\fP; + } \fIvalue\fP; +}; + +int libparsepcf_get_properties(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + struct libparsepcf_properties *\fImeta_out\fP); + +int libparsepcf_get_property_subtable(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + const struct libparsepcf_properties *\fImeta\fP, + struct libparsepcf_property_subtable *\fIprops\fP, + size_t \fIfirst\fP, size_t \fIcount\fP); +.fi +.PP +Link with +.IR -lparsepcf . + +.SH DESCRIPTION +A PCF font files should record font +properties in the table with the type +.B LIBPARSEPCF_PROPERTIES +which can be retrieved with the +.BR libparsepcf_get_tables (3) +function. +.PP +Once the +.B LIBPARSEPCF_PROPERTIES +table has been identified, it can be passed as +the third argument +.RI ( table ) +to the +.BR libparsepcf_get_properties () +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_properties () +function will store the number of available +properties in +.IR meta_out->property_count , +as well as internal information needed by the +.BR libparsepcf_get_property_subtable () +function in other fields in +.IR *meta_out . +.PP +Then the +.BR libparsepcf_get_property_subtable () +function can be used to get each font property. +The first four arguments shall be +the same as with +.BR libparsepcf_get_properties (). +.I first +shall be the index of the property with the lowest +index of the property the function shall get, and +.I count +shall be the number of consecutive properties +(including the first properties) to get. For each +queried properties with index +.IR i , +the property name will be stored in +.I props[i]->name +and the property value will be stored in +.I props[i]->value.signed_value +it it is numerical and in +.I props[i]->value.string_value +if it is a textual. In the former case +.I props[i]->is_string_property +will be set to 0 and in the latter case +.I props[i]->is_string_property +will be set to 1. +.PP +The application shall ensure that +.IR "first + count <= meta->property_count" . + +.SH RETURN VALUE +The +.BR libparsepcf_get_properties () +and +.BR libparsepcf_get_property_subtable () +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_properties () +and +.BR libparsepcf_get_property_subtable () +functions fail if: +.TP +.B EBFONT +The font file is corrupt or unsupported. + +.SH EXTENDED DESCRIPTION +For X fonts, the file will some of the properties +listing in +.IR https://www.x.org/releases/X11R7.7/doc/xorg-docs/xlfd/xlfd.html . +Particularly important fields are: +.TP +.B FAMILY_NAME +The name of the font. Note that the name is not +necessarily unique, but must be combined with other +identification properties to unique identify the +font or font family. +.TP +.B FONT +X Logical Font Descriptor. This uniquely identifies +the the font and some of its properties. +.TP +.B SLANT +The font's slant style. Common values are +\(dqR\(dq for roman, \(dqI\(dq for italic, and +\(dqO\(dq for oblique. +.TP +.B ADD_STYLE_NAME +The font's style, apart from slant style. Common +values are \(dqSerif\(dq, \(dqSans Serif\(dq, and +\(dq\(dq. +.TP +.B SPACING +The font's width-variableness, \(dqP\(dq for +proportional, \(dqM\(dq for monospaced, and +\(dqC\(dq for character-cell (monospaced font that +follows the standard typewriter character cell model). +.TP +.B AVERAGE_WIDTH +Mostly useful for character-cell types, where it +specifies the cell width in decipixels. +.TP +.B PIXEL_SIZE +The height of the font in pixels. +.TP +.B CAP_HEIGHT +The nominal height of majuscule letters in pixels. +.TP +.B X_HEIGHT +The nominal height of minuscule letters in pixels. +.TP +.B POINT_SIZE +The height of the font in decipoints. +.TP +.B RESOLUTION_X +The horizontal resolution, in dots per inch, the +font was designed for. +.TP +.B RESOLUTION_Y +The vertical resolution, in dots per inch, the +font was designed for. +.TP +.BR CHARSET_REGISTRY " and " CHARSET_ENCODING +Identifies the character encoding used by the +font, ISO10646-1 (the combination \(dqISO10646\(dq, +\(dq1\(dq) is particularly important. + +.SH SEE ALSO +.BR libparsepcf (7), +.BR libparsepcf_preparse_font (3) diff --git a/libparsepcf_get_property_subtable.3 b/libparsepcf_get_property_subtable.3 new file mode 120000 index 0000000..271ccf6 --- /dev/null +++ b/libparsepcf_get_property_subtable.3 @@ -0,0 +1 @@ +libparsepcf_get_properties.3 \ No newline at end of file diff --git a/libparsepcf_get_swidth_count.3 b/libparsepcf_get_swidth_count.3 new file mode 120000 index 0000000..697cd3d --- /dev/null +++ b/libparsepcf_get_swidth_count.3 @@ -0,0 +1 @@ +libparsepcf_get_swidths.3 \ No newline at end of file diff --git a/libparsepcf_get_swidths.3 b/libparsepcf_get_swidths.3 new file mode 100644 index 0000000..36cd7aa --- /dev/null +++ b/libparsepcf_get_swidths.3 @@ -0,0 +1,105 @@ +.TH LIBPARSEPCF_GET_SWIDTHS 3 LIBPARSEPCF +.SH NAME +libparsepcf_get_swidths \- Get em-width of glyphs + +.SH SYNOPSIS +.nf +#include + +#define LIBPARSEPCF_SWIDTHS /* value omitted */ + +int libparsepcf_get_swidth_count(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + size_t *\fIcount_out\fP); + +int libparsepcf_get_swidths(const void *\fIdata\fP, size_t \fIsize\fP, + const struct libparsepcf_table *\fItable\fP, + int32_t *\fIwidths_out\fP, + size_t \fIfirst\fP, size_t \fIcount\fP); +.fi +.PP +Link with +.IR -lparsepcf . + +.SH DESCRIPTION +If the so called scaleable widths of the glyphs +in a PCF font file is recorded in the file, they +are recorded in the table with the type +.B LIBPARSEPCF_SWIDTHS +retrieved with the +.BR libparsepcf_get_tables (3) +function. +.PP +The \(dqscaleable width\(dq of a glyph is the +width measured in a relative unit, in the case +of PCF files, milli-ems. +.PP +Once the +.B LIBPARSEPCF_SWIDTHS +table has been identified, it can be passed as +the third argument +.RI ( table ) +to the +.BR libparsepcf_get_swidth_count () +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_swidth_count () +function will store the number of available +glyphs in +.IR *count_out , +which shall be used to check that all glyphs +have a width recorded. +.PP +Then the +.BR libparsepcf_get_swidths () +function can be used to get the width, in +milli-ems, of each glyph. The first three +arguments shall be the same as with +.BR libparsepcf_get_swidth_count (). +.I first +shall be the index of the glyph with the lowest +index of the glyph the function shall get the +width 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 width will be stored in +.IR widths_out[i-first] . +.PP +The application shall ensure that +.IR "first + count <= *count_out" . +.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. + +.SH RETURN VALUE +The +.BR libparsepcf_get_swidth_count () +and +.BR libparsepcf_get_swidths () +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_swidth_count () +and +.BR libparsepcf_get_swidths () +functions fail if: +.TP +.B EBFONT +The font file is corrupt or unsupported. + +.SH SEE ALSO +.BR libparsepcf (7), +.BR libparsepcf_preparse_font (3) diff --git a/libparsepcf_get_table_count.3 b/libparsepcf_get_table_count.3 new file mode 120000 index 0000000..9a77785 --- /dev/null +++ b/libparsepcf_get_table_count.3 @@ -0,0 +1 @@ +libparsepcf_get_tables.3 \ No newline at end of file diff --git a/libparsepcf_get_tables.3 b/libparsepcf_get_tables.3 new file mode 100644 index 0000000..5bd066c --- /dev/null +++ b/libparsepcf_get_tables.3 @@ -0,0 +1,101 @@ +.TH LIBPARSEPCF_GET_TABLES 3 LIBPARSEPCF +.SH NAME +libparsepcf_get_tables \- Get font data tables + +.SH SYNOPSIS +.nf +#include + +struct libparsepcf_table { + uint32_t \fItype\fP; + /* fields intended for internal use omitted */ +}; + +int libparsepcf_get_table_count(const void *\fIdata\fP, size_t \fIsize\fP, size_t *\fIcount_out\fP); + +int libparsepcf_get_tables(const void *\fIdata\fP, size_t \fIsize\fP, + struct libparsepcf_table *\fItables_out\fP, + size_t \fIfirst\fP, size_t \fIcount\fP); +.fi +.PP +Link with +.IR -lparsepcf . + +.SH DESCRIPTION +PCF font files contain a set of tables for containing +different information about the font or its glyphs. The +.BR libparsepcf_get_table_count () +function is used to determine the number of the tables +in the file, and the +.BR libparsepcf_get_tables () +function is used to get the tables. +.PP +The +.I data +argument shall the font file content and the +.I size +argument shall be the size of the file in bytes. +.PP +The +.BR libparsepcf_get_table_count () +function will store, in +.IR *count_out , +the number of tables available in the font file. +.PP +The +.BR libparsepcf_get_table () +function will store information about tables in +.IR tables_out . +.I first +shall be the index of the table with the lowest +index of the table the function shall get the +information for, and +.I count +shall be the number of consecutive tables +(including the first table) to get the information +for. For each queried table with index +.IR i , +the table's type (what it is used for) will be +stored in +.IR tables_out[i-first].table , +.I tables_out[i-first] +will also contain additional internal information +required by the functions used to parse the function, +see the +.B SEE ALSO +section for functions used to parse individual tables +(the functions whose name include \(dq_get_\(dq)). +.PP +The application shall ensure that +.IR "first + count <= *count_out" . + +.SH RETURN VALUE +The +.BR libparsepcf_get_table_count () +and +.BR libparsepcf_get_tables () +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_table_count () +and +.BR libparsepcf_get_tables () +functions fail if: +.TP +.B EBFONT +The font file is corrupt or unsupported. + +.SH SEE ALSO +.BR libparsepcf (7), +.BR libparsepcf_preparse_font (3), +.BR libparsepcf_get_accelerators (3), +.BR libparsepcf_get_bitmaps (3), +.BR libparsepcf_get_encoding (3), +.BR libparsepcf_get_glyph_names (3), +.BR libparsepcf_get_metrics (3), +.BR libparsepcf_get_properties (3), +.BR libparsepcf_get_swidths (3) diff --git a/libparsepcf_preparse_font.3 b/libparsepcf_preparse_font.3 new file mode 100644 index 0000000..0fce166 --- /dev/null +++ b/libparsepcf_preparse_font.3 @@ -0,0 +1,249 @@ +.TH LIBPARSEPCF_PREPARSE_FONT 3 LIBPARSEPCF +.SH NAME +libparsepcf_preprase_font \- Get font data tables and metadata + +.SH SYNOPSIS +.nf +#include + +struct libparsepcf_font { + const struct libparsepcf_table *\fIprob_table\fP; + struct libparsepcf_properties \fIprops\fP; + const struct libparsepcf_table *\fIaccel_table\fP; + struct libparsepcf_accelerators \fIaccels\fP; + const struct libparsepcf_table *\fImtx_table\fP; + size_t \fImetrics\fP; + const struct libparsepcf_table *\fIinkmtx_table\fP; + size_t \fIink_metrics\fP; + const struct libparsepcf_table *\fIenc_table\fP; + struct libparsepcf_encoding \fIencoding\fP; + const struct libparsepcf_table *\fIbitmap_table\fP; + struct libparsepcf_bitmaps \fIbitmaps\fP; + const struct libparsepcf_table *\fIswidth_table\fP; + size_t \fIswidths\fP; + const struct libparsepcf_table *\fIname_table\fP; + struct libparsepcf_glyph_names \fInames\fP; + size_t \fIglyph_count\fP; + /* fields intended for internal use omitted */ +}; + +int libparsepcf_preparse_font(const void *\fIdata\fP, size_t \fIsize\fP, + struct libparsepcf_font *\fIfont_out\fP); + +int libparsepcf_destroy_preparsed_font(struct libparsepcf_font *\fIfont\fP); +.fi +.PP +Link with +.IR -lparsepcf . + +.SH DESCRIPTION +PCF font files contain a set of tables for containing +different information about the font or its glyphs. +The +.BR libparsepcf_preparse_font () +function can be used, as an alternative to the +.BR libparsepcf_get_tables (3) +function, the to locate and load the tables, making +it easy to use other functions to read the table's +subtables. +.PP +The +.I data +argument shall the font file content and the +.I size +argument shall be the size of the file in bytes. +.PP +If the font file contains a property table +.RI ( LIBPARSEPCF_PROPERTIES ) +it will be stored in +.I font_out->prob_table +and the data retrieved by the +.BR libparsepcf_get_properties (3) +function for the +.BR libparsepcf_get_property_subtable (3) +function will be stored in +.IR font_out->probs , +otherwise +.I font_out->prob_table +will be set to +.IR NULL . +.PP +If the font file contains an \(dqaccelerators\(dq +table +.RI ( LIBPARSEPCF_BDF_ACCELERATORS +(preferred) or +.I LIBPARSEPCF_ACCELERATORS +(fallback)) it will be stored in +.I font_out->accel_table +and the table will be loaded into +.IR font_out->accels , +otherwise +.I font_out->accel_table +will be set to +.IR NULL . +Be sure to check that +.I font_out->accel_table +is +.RI non- NULL +before reading +.IR font_out->accels . +.PP +The glyph layout metrics table +.RI ( LIBPARSEPCF_METRICS ), +which can be parsed using the +.BR libparsepcf_get_metrics (3) +function, will be stored in +.I font_out->mtx_table +and the number of glyph in the table +will be stored in +.IR font_out->metrics . +.PP +If the font file contains a glyph ink metrics table +.RI ( LIBPARSEPCF_INK_METRICS ), +which can be parsed using the +.BR libparsepcf_get_metrics (3) +function, will be stored in +.I font_out->inkmtx_table +and the number of glyph in the table +will be stored in +.IR font_out->ink_metrics , +otherwise +.I font_out->inkmtx_table +will be set to +.IR NULL . +.PP +The character-to-glyph table +.RI ( LIBPARSEPCF_BDF_ENCODINGS ), +which can be parsed using the +.BR libparsepcf_get_glyph_indices (3) +function, will be stored in +.I font_out->enc_table +and the data retrieved by the +.BR libparsepcf_get_encoding (3) +function for the +.BR libparsepcf_get_glyph_indices (3) +function will be stored in +.IR font_out->encoding . +.PP +If the font contains a bitmap talbe +.RI ( LIBPARSEPCF_BITMAPS ), +it will be stored in +.IR font_out->bitmap_table +and data load from the table, using the +.BR libparsepcf_get_bitmaps (3) +function will be stored +.IR font_out->bitmaps , +otherwise +.I font_out->bitmap_table +will be set to +.IR NULL . +Unless +.I font_out->bitmaps +is set to +.IR NULL , +the +.BR libparsepcf_get_bitmap_offsets (3) +function can be used to get the individual +bitmaps for each glyph. +.PP +If the font file contains a \(dqscaleable\(dq +width table +.RI ( LIBPARSEPCF_SWIDTHS ), +which can be parsed using the +.BR libparsepcf_get_swidths (3) +function, will be stored in +.I font_out->swidth_table +and the number of glyph in the table +will be stored in +.IR font_out->swidths , +otherwise +.I font_out->swidth_table +will be set to +.IR NULL . +.PP +If the font file contains a PostScript +glyph name table +.RI ( LIBPARSEPCF_GLYPH_NAMES ), +which can be parsed using the +.BR libparsepcf_get_glyph_name_subtable (3) +function, will be stored in +.I font_out->name_table +and the data retrieved by the +.BR libparsepcf_get_glyph_names (3) +function for the +.BR libparsepcf_get_glyph_name_subtable (3) +function will be stored in +.IR font_out->names . +otherwise +.I font_out->name_table +will be set to +.IR NULL . +.PP +The function will ensure that all tables report the +same number of glyphs, and the number of glyphs will +be stored in +.IR font_out->glyph_count , +but it may (if the corresponding table is found) +also be stored in +.IR font_out->metrics , +.IR font_out->ink_metrics , +.IR font_out->bitmaps.glyph_count , +.IR font_out->names.glyph_count , +and +.IR font_out->swidths . +.PP +If the font contains a property table, +.PP +Once the font is not needed anymore, the +.BR libparsepcf_destroy_preparsed_font () +function shall be used to deallocate the memory +stored in +.IR *font , +it will also reset the contents of +.IR *font . + +.SH RETURN VALUE +The +.BR libparsepcf_preparse_font () +and +.BR libparsepcf_destroy_preparsed_font () +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_preparse_font () +and +.BR libparsepcf_destroy_preparsed_font () +functions fail if: +.TP +.B EBFONT +The font file is corrupt or unsupported. + +.SH NOTES +As the layout metrics shall be used if the +font file is missing the ink metrics table, +it may be a good idea, for the application +to set +.I font_out->inkmtx_table +to +.I font_out->mtx_table +and +.I font_out->ink_metrics +to +.I font_out->metrics +if +.I font_out->inkmtx_table +is +.IR NULL . +The +.BR libparsepcf_preparse_font () +function does not automatically because +it may be useful for the application to +know whether the ink metrics and layout +metrics are identical. + +.SH SEE ALSO +.BR libparsepcf (7) diff --git a/struct_libparsepcf_accelerators.3 b/struct_libparsepcf_accelerators.3 new file mode 120000 index 0000000..373e5bb --- /dev/null +++ b/struct_libparsepcf_accelerators.3 @@ -0,0 +1 @@ +libparsepcf_get_accelerators.3 \ No newline at end of file diff --git a/struct_libparsepcf_bitmaps.3 b/struct_libparsepcf_bitmaps.3 new file mode 120000 index 0000000..8f92a6f --- /dev/null +++ b/struct_libparsepcf_bitmaps.3 @@ -0,0 +1 @@ +libparsepcf_get_bitmaps.3 \ No newline at end of file diff --git a/struct_libparsepcf_encoding.3 b/struct_libparsepcf_encoding.3 new file mode 120000 index 0000000..2b68279 --- /dev/null +++ b/struct_libparsepcf_encoding.3 @@ -0,0 +1 @@ +libparsepcf_get_encoding.3 \ No newline at end of file diff --git a/struct_libparsepcf_font.3 b/struct_libparsepcf_font.3 new file mode 120000 index 0000000..bcbba50 --- /dev/null +++ b/struct_libparsepcf_font.3 @@ -0,0 +1 @@ +libparsepcf_preparse_font.3 \ No newline at end of file diff --git a/struct_libparsepcf_glyph_names.3 b/struct_libparsepcf_glyph_names.3 new file mode 120000 index 0000000..1d119d1 --- /dev/null +++ b/struct_libparsepcf_glyph_names.3 @@ -0,0 +1 @@ +libparsepcf_get_glyph_names.3 \ No newline at end of file diff --git a/struct_libparsepcf_metrics.3 b/struct_libparsepcf_metrics.3 new file mode 120000 index 0000000..58b91b9 --- /dev/null +++ b/struct_libparsepcf_metrics.3 @@ -0,0 +1 @@ +libparsepcf_get_metrics.3 \ No newline at end of file diff --git a/struct_libparsepcf_properties.3 b/struct_libparsepcf_properties.3 new file mode 120000 index 0000000..271ccf6 --- /dev/null +++ b/struct_libparsepcf_properties.3 @@ -0,0 +1 @@ +libparsepcf_get_properties.3 \ No newline at end of file diff --git a/struct_libparsepcf_property_subtable.3 b/struct_libparsepcf_property_subtable.3 new file mode 120000 index 0000000..271ccf6 --- /dev/null +++ b/struct_libparsepcf_property_subtable.3 @@ -0,0 +1 @@ +libparsepcf_get_properties.3 \ No newline at end of file diff --git a/struct_libparsepcf_table.3 b/struct_libparsepcf_table.3 new file mode 120000 index 0000000..9a77785 --- /dev/null +++ b/struct_libparsepcf_table.3 @@ -0,0 +1 @@ +libparsepcf_get_tables.3 \ No newline at end of file -- cgit v1.2.3-70-g09d2