Module Otfm

module Otfm: sig .. end
OpenType font decoder.

WARNING. This interface is subject to change in the future.

Otfm is an in-memory decoder for the OpenType font data format. It provides low-level access to OpenType fonts tables and functions to decode some of them.

Consult the limitations and example of use.

Note. Unless otherwise specified the strings returned are UTF-8 encoded.

v0.3.0 - homepage

References




Tags


type tag 
The type for OpenType tags.
module Tag: sig .. end
Tags.

Unicode code points

For some reason OpenType allows the (textually meaningless) surrogate code points to be mapped to glyphs. Hence we deal with Unicode code points not scalar values.

type cp = int 
The type for Unicode code points, ranges from 0x0000 to 0x10_FFFF. Any code point returned by Otfm is guaranteed to be in the range.
type cp_range = cp * cp 
The type for Unicode code point ranges. Any range (u0, u1) returned by Otfm has u0 <= u1.
val is_cp : int -> bool
is_cp i is true if i is an Unicode code point.
val pp_cp : Format.formatter -> cp -> unit
pp_cp ppf cp prints an unspecified representation of cp on ppf.

Decode


type error_ctx = [ `Offset_table | `Table of tag | `Table_directory ] 
The type for error contexts.
type error = [ `Invalid_cp of int
| `Invalid_cp_range of int * int
| `Invalid_offset of error_ctx * int
| `Invalid_postscript_name of string
| `Missing_required_table of tag
| `Unexpected_eoi of error_ctx
| `Unknown_composite_format of error_ctx * int
| `Unknown_flavour of tag
| `Unknown_loca_format of error_ctx * int
| `Unknown_version of error_ctx * int32
| `Unsupported_TTC
| `Unsupported_cmaps of (int * int * int) list
| `Unsupported_glyf_matching_points ]
The type for decoding errors.

Note. In case of `Invalid_poscript_name a string of bytes is returned.

val pp_error : Format.formatter -> [< error ] -> unit
pp_error ppf e prints an uspecified representation of e on ppf.
type src = [ `String of string ] 
The type for input sources.
type decoder 
The type for OpenType font decoders.
val decoder : [< src ] -> decoder
decoder src is a decoder decoding from src.
val decoder_src : decoder -> src
decoder_src d is d's input source.

Table decoding

These functions can be used in any order and are robust: when they return an error the decoder is back to a consistant state and can be used further. However if Otfm.flavour or Otfm.table_list returns an error you can safely assume that all other functions will. The fields are in general not documented please refer to the OpenType specification for details.

type flavour = [ `CFF | `TTF ] 
The type for OpenType flavours.
val flavour : decoder -> (flavour, error) Result.result
decode_flavour d is the flavour of the font decoded by d.
val table_list : decoder -> (tag list, error) Result.result
table_list t is the list of tables of the font decoded by d.
val table_mem : decoder -> tag -> (bool, error) Result.result
table_mem d t is true if table t is in the font decoded by d.
val table_raw : decoder -> tag -> (string option, error) Result.result
table_raw d t is the (unpadded) data of the table t as a string if the table t exists.

Convenience decodes

These functions lookup data in the right table.

val glyph_count : decoder -> (int, error) Result.result
glyph_count d is the number of glyphs in the font (bounded by 65535).
val postscript_name : decoder -> (string option, error) Result.result
poscript_name d is the PostScript name of d. Looks up and validates as mandated by the OTF standard, don't rely on Otfm.name if you really need this information.

cmap table


type glyph_id = int 
The type for glyph ids, from 0 to 65534.
type map_kind = [ `Glyph | `Glyph_range ] 
The type for map kinds.

Determines how an unicode range (u0, u1) and a glyph id gid must be interpreted in the folding function of Otfm.cmap.


val cmap : decoder ->
('a -> map_kind -> cp_range -> glyph_id -> 'a) ->
'a -> ((int * int * int) * 'a, error) Result.result
cmap d f acc folds over a mapping from unicode scalar values to glyph ids by reading the cmap table. The returned triple of integer indicates the platform id, encoding id and format of the cmap used.

Limitations. Only the format 13 (last resort font), format 12 (UCS-4) and format 4 (UCS-2) cmap table formats are supported.

If multiple tables are present, it favours 13 over 12 over 4. If multiple tables of the same format are present it takes the first one it finds.

If no supported cmap table is found the error `Unsupported_cmaps is returned with the list of platform id, encoding id, format available in the font.


glyf table


type glyf_loc 
The type for glyph locations. See Otfm.loca table.
type glyph_simple_descr = (bool * int * int) list list 
The type for simple glyph descriptions. Lists of contours, contours are list of points with a boolean indicating whether the point is on or off curve.
type glyph_composite_descr = (glyph_id * (int * int) * (float * float * float * float) option) list 
The type for glyph composites. A list of components made of a glyph id, a translation and an optional linear transform a b c d (column major).
type glyph_descr = [ `Composite of glyph_composite_descr
| `Simple of glyph_simple_descr ] * (int * int * int * int)
The type for glyph descriptions. A simple or composite descriptions with the glyph's (minx, miny, maxx, maxy)'s bounding box.
val glyf : decoder -> glyf_loc -> (glyph_descr, error) Result.result
glyf d loc is the glyph descroption located at loc by reading the glyf table. Glyph locations are obtainted via Otfm.loca.


type head = {
   head_font_revision : int32;
   head_flags : int;
   head_units_per_em : int;
   head_created : float; (*
Unix timestamp.
*)
   head_modified : float; (*
Unix timestamp.
*)
   head_xmin : int;
   head_ymin : int;
   head_xmax : int;
   head_ymax : int;
   head_mac_style : int;
   head_lowest_rec_ppem : int;
   head_index_to_loc_format : int;
}
The type for representing head tables.
val head : decoder -> (head, error) Result.result
head d is the head table.

hhea table


type hhea = {
   hhea_ascender : int;
   hhea_descender : int;
   hhea_line_gap : int;
   hhea_advance_width_max : int;
   hhea_min_left_side_bearing : int;
   hhea_min_right_side_bearing : int;
   hhea_xmax_extent : int;
   hhea_caret_slope_rise : int;
   hhea_caret_slope_run : int;
   hhea_caret_offset : int;
}
The type for hhea tables.
val hhea : decoder -> (hhea, error) Result.result
hhea d is the hhea table.

hmtx table


val hmtx : decoder ->
('a -> glyph_id -> int -> int -> 'a) ->
'a -> ('a, error) Result.result
hmtx d f acc folds over the horizontal metrics of the font by reading the hmtx table. f is applied on each entry with f acc' gid adv lsb with gid the glyph id (guaranteed to range, in order, from 0 to glyph count minus one), adv the (unsigned) advance width, and lsb the (signed) left side bearing.

name table


type lang = string 
The type for BCP 47 language tags.
val name : decoder ->
('a -> int -> lang -> string -> 'a) ->
'a -> ('a, error) Result.result
name d f acc folds over the name records of the font by reading the name table. f is applied on each name id entry with f acc' nid lang name with nid the name id, lang the language tag, and name the UTF-8 encoded name value.

Note. The module normalizes Windows language ids to lowercased BCP 47 ids. Language tags found in language tag records should be BCP 47 language tags but are not checked for conformance.

Tip. If you are looking for the postcript name use Otfm.postscript_name.

Limitations. Lookups data only in platform ids 0, 2 and 3 (Unicode, ISO and Windows) with UTF-16BE encoding and reports only the data of the first one it finds for a given name id.


OS/2 table


type os2 = {
   os2_x_avg_char_width : int;
   os2_us_weight_class : int;
   os2_us_width_class : int;
   os2_fs_type : int;
   os2_y_subscript_x_size : int;
   os2_y_subscript_y_size : int;
   os2_y_subscript_x_offset : int;
   os2_y_subscript_y_offset : int;
   os2_y_superscript_x_size : int;
   os2_y_superscript_y_size : int;
   os2_y_superscript_x_offset : int;
   os2_y_superscript_y_offset : int;
   os2_y_strikeout_size : int;
   os2_y_strikeout_position : int;
   os2_family_class : int;
   os2_panose : string; (*
10 bytes
*)
   os2_ul_unicode_range1 : int32;
   os2_ul_unicode_range2 : int32;
   os2_ul_unicode_range3 : int32;
   os2_ul_unicode_range4 : int32;
   os2_ach_vend_id : int32;
   os2_fs_selection : int;
   os2_us_first_char_index : int;
   os2_us_last_char_index : int;
   os2_s_typo_ascender : int;
   os2_s_type_descender : int;
   os2_s_typo_linegap : int;
   os2_us_win_ascent : int;
   os2_us_win_descent : int;
   os2_ul_code_page_range_1 : int32 option;
   os2_ul_code_page_range_2 : int32 option;
   os2_s_x_height : int option;
   os2_s_cap_height : int option;
   os2_us_default_char : int option;
   os2_us_break_char : int option;
   os2_us_max_context : int option;
}
The type for OS/2 tables.
val os2 : decoder -> (os2, error) Result.result
os2 d is the OS/2 table.

kern table


type kern_info = {
   kern_dir : [ `H | `V ];
   kern_kind : [ `Kern | `Min ];
   kern_cross_stream : bool;
}
The type for kerning (sub)table information.
val kern : decoder ->
('a -> kern_info -> [ `Fold | `Skip ] * 'a) ->
('a -> glyph_id -> glyph_id -> int -> 'a) ->
'a -> ('a, error) Result.result
kern d t p acc folds over the kerning tables of d by reading the kern table. t is called on each new (sub)table, the table pairs are skipped if it returns `Skip otherwise p acc' left right value is called on each kerning pair of the table. The function returns acc if there is no kern table.

Limitations. Only format 0 kerning tables are supported.


loca table


val loca : decoder ->
glyph_id -> (glyf_loc option, error) Result.result
loca d gid looks up the location of the glyph with id gid by reading the loca table. The result can be used with Otfm.glyf to lookup the glyph.

Limitations

As it stands Otfm has the following limitations. Some of these may be lifted in the future and a few of these can be overcome by pre-processing your font (e.g. extract .ttc files to .ttf, or removing hinting information to reduce the font size). See also the individual table decoding functions for other limitations.



Examples

The following code prints the postscript name of the font on stdout.

  let otf_postscript_name bytes =
    let d = Otfm.decoder (`String bytes) in
    match Otfm.postscript_name d with
    | Error e -> Format.eprintf "@[%a@]@." Otfm.pp_error e
    | Ok (Some n) -> Format.printf "%s@." n;
    | Ok None -> ()