TTF(2)                                                     TTF(2)

     NAME
          ttfopen, ttfscale, ttfclose, ttffindchar, ttfenumchar,
          ttfgetglyph, ttfputglyph, ttfgetcontour, ttfrender,
          ttfrunerender, ttfnewbitmap, ttffreebitmap, ttfblit -
          TrueType renderer

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <bio.h>
          #include <ttf.h>

          struct TTBitmap {
               u8int *bit;
               int width, height, stride;
          };

          struct TTGlyph {
               TTBitmap;
               int xminpx, xmaxpx, yminpx, ymaxpx, advanceWidthpx;
               /* + internals */
          };

          struct TTFont {
               int ppem, ascentpx, descentpx;
               /* + internals */
          };

          TTFont*   ttfopen(char *filename, int size, int flags);
          TTFont*   ttfscale(TTFont *f, int size, int flags);
          void      ttfclose(TTFont *f);

          int       ttffindchar(TTFont *f, Rune r);
          int       ttfenumchar(TTFont *f, Rune r, Rune *rp);

          TTGlyph*  ttfgetglyph(TTFont *f, int glyphidx, int render);
          void      ttfputglyph(TTGlyph *g);
          int       ttfgetcontour(TTGlyph *g, int idx, float **fp, int *nfp);

          TTBitmap* ttfrender(TTFont *f, char *s, char *e, int w, int h,
                    int flags, char **pp);
          TTBitmap* ttfrunerender(TTFont *f, Rune *s, Rune *e, int w, int h,
                    int flags, char **pp);

          TTBitmap* ttfnewbitmap(int w, int h);
          void      ttfblit(TTBitmap *dst, int dstx, int dsty, TTBitmap *src,
                    int srcx, int srcy, int w, int h);
          void      ttffreebitmap(TTBitmap *);

     DESCRIPTION

     TTF(2)                                                     TTF(2)

          Libttf is a parser and renderer of TrueType fonts.  Given a
          ttf font file it can produce the rendered versions of char-
          acters at a given size.

          Ttfopen opens the font at filename and initialises it for
          rendering at size size (specified in pixels per em).  Flags
          is reserved for future use and should be zero.  If rendering
          at multiple sizes is desired, ttfscale reopens the font at a
          different size (internally the size-independent data is
          shared).  TTfclose closes an opened font.  Each instance of
          a font created by ttfopen and ttfscale must be closed sepa-
          rately.

          A character in a TrueType font is called a glyph.  Glyphs
          are numbered starting from 0 and the glyph indices do not
          need to follow any established coding scheme.  Ttffindchar
          finds the glyph number of a given rune (Unicode codepoint).
          If the character does not exist in the font, zero is
          returned.  Note that, in TrueType fonts, glyph 0 convention-
          ally contains the "glyph not found" character.  Ttfenumchar
          is like ttffindchar but will continue searching if the char-
          acter is not in the font, returning the rune number for
          which it found a glyph in *rp.  It returns character in
          ascending Unicode order and it can be used to enumerate the
          characters in a font.  Zero is returned if there are no fur-
          ther characters.

          Ttfgetglyph interprets the actual data for a glyph specified
          by its index glyphidx. With render set to zero, the data is
          left uninterpreted; currently its only use is ttfgetcontour.
          With render set to one, the glyph is also rendered, i.e. a
          pixel representation is produced and stored in the TTBitmap
          embedded in the TTGlyph structure it returns.  Although
          TrueType uses a right handed coordinate system (y increases
          going up), the bitmap data returns follows Plan 9 conven-
          tions (and is compatible with the draw(3) mask argument).
          The bottom left hand corner is at position (xmin, ymin) in
          the TrueType coordinate system.  Ttfputglyph should be used
          to return TTGlyph structures for cleanup.

          Ttfgetcontour can be used to obtain raw contour data for a
          glyph.  Given an index i it returns the corresponding con-
          tour (counting from zero), storing a pointer to a list of
          (x, y) pairs in *fp.  The array is allocated with malloc(2).
          The (always odd) number of points is stored in *np.  The
          contours correspond to closed quadratic Bézier curves and
          the points with odd indices are the control points.  For an
          invalid index, zero is returned and *fp and *np are not
          accessed.  For a valid index, the number returned is the
          number of contours with index ≥ i.

          Ttfrender and ttfrunerender typeset a string of text

     TTF(2)                                                     TTF(2)

          (specified as UTF-8 or raw Unicode, respectively) and return
          a bitmap of size w and h. It attempts to typeset text start-
          ing from s and up to and not including e. If e is nil, text
          is typeset until a null byte is encountered.  Flags speci-
          fies the alignment.  TTFLALIGN, TTFRALIGN and TTFCENTER
          specify left-aligned, right-aligned and centered text,
          respectively.  TTFJUSTIFY can be or'ed with these three
          options to produce text where any ``wrapped'' line is justi-
          fied.

          For reasons of efficiency and simplicity, libttf includes
          its own format for 1 bpp bitmaps.  In these bitmaps, 0 cor-
          responds to transparent and 1 corresponds to opaque.  Other-
          wise, the format is identical to k1 image(6) bitmaps.
          Ttfnewbitmap and ttffreebitmap allocate and deallocate such
          bitmaps, respectively.  TTGlyph structures can be used in
          place of bitmaps but must be deallocated with ttfputglyph,
          not ttffreebitmap. Ttfblit copies part of one bitmap onto
          another.  Note that bits are or'ed together -- blitting a
          transparent over an opaque pixel does not produce an trans-
          parent pixel.

     SOURCE
          /sys/src/libttf

     SEE ALSO
          Apple, ``TrueType™ Reference Manual''.
          Microsoft, ``OpenType® specification''.
          FreeType, source code (the only accurate source).
          ttfrender(1).

     DIAGNOSTICS
          Following standard conventions, routines returning pointers
          return nil on error and return an error message in errstr.

     BUGS
          Both ``standards'' are packages of contradictions and lies.

          Apple Advanced Typography and Microsoft OpenType extensions
          are not supported; similarly non-TrueType (Postscript, Bit-
          map) fonts packaged as .ttf files are not supported.

          The library is immature and interfaces are virtually guaran-
          teed to change.

          Fonts packaged as .ttc files are not supported.

     HISTORY
          Libttf first appeared in 9front in June, 2018.