.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)