sys/man/2/ttf

   1 .TH TTF 2
   2 .SH NAME
   3 ttfopen, ttfscale, ttfclose, ttffindchar, ttfenumchar, ttfgetglyph,
   4 ttfputglyph, ttfgetcontour, ttfrender, ttfrunerender, ttfnewbitmap,
   5 ttffreebitmap, ttfblit \- TrueType renderer
   6 .SH SYNOPSIS
   7 .de PB
   8 .PP
   9 .ft L
  10 .nf
  11 ..
  12 .PB
  13 #include <u.h>
  14 #include <libc.h>
  15 #include <bio.h>
  16 #include <ttf.h>
  17 .PB
  18 struct TTBitmap {
  19         u8int *bit;
  20         int width, height, stride;
  21 };
  22 .PB
  23 struct TTGlyph {
  24         TTBitmap;
  25         int xminpx, xmaxpx, yminpx, ymaxpx, advanceWidthpx;
  26         /* + internals */
  27 };
  28 .PB
  29 struct TTFont {
  30         int ppem, ascentpx, descentpx;
  31         /* + internals */
  32 };
  33 .PB
  34 .ta +\w'\fLTTBitmap* \fP'u
  35 TTFont* ttfopen(char *filename, int size, int flags);
  36 TTFont* ttfscale(TTFont *f, int size, int flags);
  37 void    ttfclose(TTFont *f);
  38 .PB
  39 int     ttffindchar(TTFont *f, Rune r);
  40 int     ttfenumchar(TTFont *f, Rune r, Rune *rp);
  41 .PB
  42 TTGlyph*        ttfgetglyph(TTFont *f, int glyphidx, int render);
  43 void    ttfputglyph(TTGlyph *g);
  44 int     ttfgetcontour(TTGlyph *g, int idx, float **fp, int *nfp);
  45 .PB
  46 TTBitmap*       ttfrender(TTFont *f, char *s, char *e, int w, int h,
  47                         int flags, char **pp);
  48 TTBitmap*       ttfrunerender(TTFont *f, Rune *s, Rune *e, int w, int h,
  49                         int flags, Rune **pp);
  50 .PB
  51 TTBitmap*       ttfnewbitmap(int w, int h);
  52 void    ttfblit(TTBitmap *dst, int dstx, int dsty, TTBitmap *src,
  53                         int srcx, int srcy, int w, int h);
  54 void    ttffreebitmap(TTBitmap *);
  55 .SH DESCRIPTION
  56 .PP
  57 .I Libttf
  58 is a parser and renderer of TrueType fonts.
  59 Given a \fLttf\fR font file it can produce the rendered versions of characters at a given size.
  60 .PP
  61 .I Ttfopen
  62 opens the font at
  63 .I filename
  64 and initialises it for rendering at size
  65 .I size
  66 (specified in pixels per em).
  67 .I Flags
  68 is reserved for future use and should be zero.
  69 If rendering at multiple sizes is desired,
  70 .I ttfscale
  71 reopens the font at a different size (internally the size-independent data is shared).
  72 .I TTfclose
  73 closes an opened font.
  74 Each instance of a font created by
  75 .I ttfopen
  76 and
  77 .I ttfscale
  78 must be closed separately.
  79 .PP
  80 A character in a TrueType font is called a glyph.
  81 Glyphs are numbered starting from 0 and the glyph indices do not need to follow any established coding scheme.
  82 .I Ttffindchar
  83 finds the glyph number of a given rune (Unicode codepoint).
  84 If the character does not exist in the font, zero is returned.
  85 Note that, in TrueType fonts, glyph 0 conventionally contains the "glyph not found" character.
  86 .I Ttfenumchar
  87 is like
  88 .I ttffindchar
  89 but will continue searching if the character is not in the font, returning the rune number for which it found a glyph in
  90 .BR *rp .
  91 It returns character in ascending Unicode order and it can be used to enumerate the characters in a font.
  92 Zero is returned if there are no further characters.
  93 .PP
  94 .I Ttfgetglyph
  95 interprets the actual data for a glyph specified by its index
  96 .IR glyphidx .
  97 With
  98 .I render
  99 set to zero, the data is left uninterpreted; currently its only use is
 100 .I ttfgetcontour.
 101 With
 102 .I render
 103 set to one, the glyph is also rendered, i.e. a pixel representation is produced and stored in the
 104 .I TTBitmap
 105 embedded in the
 106 .I TTGlyph
 107 structure it returns.
 108 Although TrueType uses a right handed coordinate system (y increases going up), the bitmap data returns follows Plan 9 conventions (and is compatible with the
 109 .IR draw (3)
 110 mask argument).
 111 The bottom left hand corner is at position (\fIxmin\fR, \fIymin\fR) in the TrueType coordinate system.
 112 .I Ttfputglyph
 113 should be used to return
 114 .I TTGlyph
 115 structures for cleanup.
 116 .PP
 117 .I Ttfgetcontour
 118 can be used to obtain raw contour data for a glyph.
 119 Given an index
 120 .I i
 121 it returns the corresponding contour (counting from zero), storing a pointer to a list of (\fIx\fR, \fIy\fR) pairs in
 122 .BR *fp .
 123 The array is allocated with
 124 .IR malloc (2).
 125 The (always odd) number of points is stored in
 126 .BR *np .
 127 The contours correspond to closed quadratic Bézier curves and the points with odd indices are the control points.
 128 For an invalid index, zero is returned and
 129 .B *fp
 130 and
 131 .B *np
 132 are not accessed.
 133 For a valid index, the number returned is the number of contours with index ≥ \fIi\fR.
 134 .PP
 135 .I Ttfrender
 136 and
 137 .I ttfrunerender
 138 typeset a string of text (specified as UTF-8 or raw Unicode, respectively) and return a bitmap of size
 139 .I w
 140 and
 141 .IR h .
 142 It attempts to typeset text starting from
 143 .I s
 144 and up to and not including
 145 .IR e .
 146 If
 147 .I e
 148 is
 149 .BR nil ,
 150 text is typeset until a null byte is encountered.
 151 .I Flags
 152 specifies the alignment.
 153 .BR TTFLALIGN ,
 154 .BR TTFRALIGN
 155 and
 156 .B TTFCENTER
 157 specify left-aligned, right-aligned and centered text, respectively.
 158 .B TTFJUSTIFY
 159 can be or'ed with these three options to produce text where any ``wrapped'' line is justified.
 160 .PP
 161 For reasons of efficiency and simplicity,
 162 .I libttf
 163 includes its own format for 1 bpp bitmaps.
 164 In these bitmaps,
 165 0 corresponds to transparent and 1 corresponds to opaque.
 166 Otherwise, the format is identical to
 167 .B k1
 168 .IR image (6)
 169 bitmaps.
 170 .I Ttfnewbitmap
 171 and
 172 .I ttffreebitmap
 173 allocate and deallocate such bitmaps, respectively.
 174 .I TTGlyph
 175 structures can be used in place of bitmaps but must be deallocated with
 176 .IR ttfputglyph ,
 177 not
 178 .IR ttffreebitmap .
 179 .I Ttfblit
 180 copies part of one bitmap onto another.
 181 Note that bits are or'ed together \(-- blitting a transparent over an opaque pixel does not produce an transparent pixel.
 182 .SH SOURCE
 183 .B /sys/src/libttf
 184 .SH "SEE ALSO"
 185 Apple, ``TrueType™ Reference Manual''.
 186 .br
 187 Microsoft, ``OpenType® specification''.
 188 .br
 189 FreeType, source code (the only accurate source).
 190 .br
 191 .IR ttfrender (1).
 192 .SH DIAGNOSTICS
 193 Following standard conventions, routines returning pointers return
 194 .B nil
 195 on error and return an error message in
 196 .BR errstr .
 197 .SH BUGS
 198 Both ``standards'' are packages of contradictions and lies.
 199 .PP
 200 Apple Advanced Typography and Microsoft OpenType extensions are not supported; similarly non-TrueType (Postscript, Bitmap) fonts packaged as
 201 .B .ttf
 202 files are not supported.
 203 .PP
 204 The library is immature and interfaces are virtually guaranteed to change.
 205 .PP
 206 Fonts packaged as
 207 .B .ttc
 208 files are not supported.
 209 .SH HISTORY
 210 .I Libttf
 211 first appeared in 9front in June, 2018.