Add section 3 man pages

Signed-off-by: Mattias Andrée <m@maandree.se>

1 files changed, 150 insertions, 0 deletions

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 <libparsepcf.h>
+
+#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)