diff options
Diffstat (limited to 'libparsepcf_preparse_font.3')
| -rw-r--r-- | libparsepcf_preparse_font.3 | 249 |
1 files changed, 249 insertions, 0 deletions
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 <libparsepcf.h> + +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) |