mirror of
https://github.com/tomolt/libschrift
synced 2025-07-26 04:24:38 -04:00
269 lines
13 KiB
HTML
269 lines
13 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta charset="utf-8"/>
|
|
<link rel="stylesheet" href="style.css" type="text/css" media="all"/>
|
|
<title>SCHRIFT(3)</title>
|
|
</head>
|
|
<body>
|
|
<table class="head">
|
|
<tr>
|
|
<td class="head-ltitle">SCHRIFT(3)</td>
|
|
<td class="head-vol">Library Functions Manual</td>
|
|
<td class="head-rtitle">SCHRIFT(3)</td>
|
|
</tr>
|
|
</table>
|
|
<div class="manual-text">
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
|
|
<code class="Nm">schrift</code>, <code class="Nm">libschrift</code> —
|
|
<div class="Nd">Lightweight TrueType font rendering library</div>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
|
|
<span class="Lb">library “libschrift”</span>
|
|
<br/>
|
|
<code class="In">#include <<a class="In">schrift.h</a>></code>
|
|
<p class="Pp"><var class="Ft">const char *</var>
|
|
<br/>
|
|
<code class="Fn">sft_version</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p>
|
|
<p class="Pp"><var class="Ft">SFT_Font *</var>
|
|
<br/>
|
|
<code class="Fn">sft_loadmem</code>(<var class="Fa" style="white-space: nowrap;">const
|
|
void *mem</var>, <var class="Fa" style="white-space: nowrap;">unsigned long
|
|
size</var>);</p>
|
|
<p class="Pp"><var class="Ft">SFT_Font *</var>
|
|
<br/>
|
|
<code class="Fn">sft_loadfile</code>(<var class="Fa" style="white-space: nowrap;">const
|
|
char *filename</var>);</p>
|
|
<p class="Pp"><var class="Ft">void</var>
|
|
<br/>
|
|
<code class="Fn">sft_freefont</code>(<var class="Fa" style="white-space: nowrap;">SFT_Font
|
|
*font</var>);</p>
|
|
<p class="Pp"><var class="Ft">int</var>
|
|
<br/>
|
|
<code class="Fn">sft_lmetrics</code>(<var class="Fa" style="white-space: nowrap;">const
|
|
struct SFT *sft</var>, <var class="Fa" style="white-space: nowrap;">struct
|
|
SFT_LMetrics *metrics</var>);</p>
|
|
<p class="Pp"><var class="Ft">int</var>
|
|
<br/>
|
|
<code class="Fn">sft_lookup</code>(<var class="Fa" style="white-space: nowrap;">const
|
|
struct SFT *sft</var>, <var class="Fa" style="white-space: nowrap;">unsigned
|
|
long codepoint</var>, <var class="Fa" style="white-space: nowrap;">SFT_Glyph
|
|
*glyph</var>);</p>
|
|
<p class="Pp"><var class="Ft">int</var>
|
|
<br/>
|
|
<code class="Fn">sft_hmetrics</code>(<var class="Fa" style="white-space: nowrap;">const
|
|
struct SFT *sft</var>,
|
|
<var class="Fa" style="white-space: nowrap;">SFT_Glyph glyph</var>,
|
|
<var class="Fa" style="white-space: nowrap;">struct SFT_HMetrics
|
|
*metrics</var>);</p>
|
|
<p class="Pp"><var class="Ft">int</var>
|
|
<br/>
|
|
<code class="Fn">sft_kerning</code>(<var class="Fa" style="white-space: nowrap;">const
|
|
struct SFT *sft</var>,
|
|
<var class="Fa" style="white-space: nowrap;">SFT_Glyph leftGlyph</var>,
|
|
<var class="Fa" style="white-space: nowrap;">SFT_Glyph rightGlyph</var>,
|
|
<var class="Fa" style="white-space: nowrap;">struct SFT_Kerning
|
|
*kerning</var>);</p>
|
|
<p class="Pp"><var class="Ft">int</var>
|
|
<br/>
|
|
<code class="Fn">sft_extents</code>(<var class="Fa" style="white-space: nowrap;">const
|
|
struct SFT *sft</var>,
|
|
<var class="Fa" style="white-space: nowrap;">SFT_Glyph glyph</var>,
|
|
<var class="Fa" style="white-space: nowrap;">struct SFT_Extents
|
|
*extents</var>);</p>
|
|
<p class="Pp"><var class="Ft">int</var>
|
|
<br/>
|
|
<code class="Fn">sft_render</code>(<var class="Fa" style="white-space: nowrap;">const
|
|
struct SFT *sft</var>,
|
|
<var class="Fa" style="white-space: nowrap;">SFT_Glyph glyph</var>,
|
|
<var class="Fa" style="white-space: nowrap;">struct SFT_Image
|
|
image</var>);</p>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
|
|
The function <code class="Fn">sft_version</code>() may be called to determine
|
|
the version of <code class="Nm">schrift</code>. Since
|
|
<code class="Nm">schrift</code> uses semantic versioning, the returned string
|
|
is of the form "MAJOR.MINOR.PATCH".
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Loading_fonts"><a class="permalink" href="#Loading_fonts">Loading
|
|
fonts</a></h2>
|
|
<code class="Fn">sft_loadfile</code>() will load a font from a given filename
|
|
(by mapping it into memory), whereas <code class="Fn">sft_loadmem</code>() can
|
|
be given an arbitrary memory address and size (in bytes). This allows loading
|
|
fonts from ZIP file streams etc.
|
|
<p class="Pp">Once a particular font is no longer needed, its memory should be
|
|
freed again by calling <code class="Fn">sft_freefont</code>(). If the font
|
|
has been loaded with <code class="Fn">sft_loadmem</code>(), the underlying
|
|
memory region will have to be freed separately.</p>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="the_SFT_structure"><a class="permalink" href="#the_SFT_structure">the
|
|
SFT structure</a></h2>
|
|
Most functions take a <var class="Vt">struct SFT</var> as their primary
|
|
argument. This is a structure to be filled out by the caller. It bundles
|
|
multiple commonly needed parameters. The fields are as follows:
|
|
<dl class="Bl-tag">
|
|
<dt><var class="Va">font</var></dt>
|
|
<dd>The font to render with</dd>
|
|
<dt><var class="Va">xScale</var></dt>
|
|
<dd>The width of one em-square in pixels</dd>
|
|
<dt><var class="Va">yScale</var></dt>
|
|
<dd>The height of one em-square in pixels</dd>
|
|
<dt><var class="Va">xOffset</var></dt>
|
|
<dd>The horizontal offset to be applied before rendering to an image (Useful
|
|
for subpixel-accurate positioning)</dd>
|
|
<dt><var class="Va">yOffset</var></dt>
|
|
<dd>The vertical offset to be applied before rendering to an image (Useful for
|
|
subpixel-accurate positioning)</dd>
|
|
<dt><var class="Va">flags</var></dt>
|
|
<dd>A bitfield of binary flags</dd>
|
|
</dl>
|
|
<p class="Pp">If the <code class="Dv">SFT_DOWNWARD_Y</code> flag is set, the Y
|
|
axis is interpreted to point downwards. Per default, it points upwards.</p>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Glyph_ids"><a class="permalink" href="#Glyph_ids">Glyph
|
|
ids</a></h2>
|
|
<code class="Nm">schrift</code> operates in terms of glyph ids (of type
|
|
<var class="Vt">SFT_Glyph</var>), which are font-specific identifiers assigned
|
|
to renderable symbols (glyphs). The way to obtain a glyph id is to call
|
|
<code class="Fn">sft_lookup</code>(). This function takes a Unicode codepoint
|
|
in <var class="Va">codepoint</var> and writes its corresponding glyph id into
|
|
the variable pointed to by <var class="Va">glyph</var>.
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Querying_metrics"><a class="permalink" href="#Querying_metrics">Querying
|
|
metrics</a></h2>
|
|
<code class="Fn">sft_lmetrics</code>() calculates the typographic metrics
|
|
neccessary for laying out multiple lines of text.
|
|
<p class="Pp">This function writes its output into the structure pointed to by
|
|
<var class="Va">metrics</var>. The fields are as follows:</p>
|
|
<dl class="Bl-tag">
|
|
<dt><var class="Va">ascender</var></dt>
|
|
<dd>The distance from the baseline to the visual top of the text</dd>
|
|
<dt><var class="Va">descender</var></dt>
|
|
<dd>The distance from the baseline to the visual bottom of the text</dd>
|
|
<dt><var class="Va">lineGap</var></dt>
|
|
<dd>The default amount of horizontal padding between consecutive lines</dd>
|
|
</dl>
|
|
<p class="Pp">When displaying multiple glyphs in a line, you have to keep track
|
|
of the pen position. <code class="Fn">sft_hmetrics</code>() tells you where
|
|
to draw the next glyph with respect to the pen position, and how to update
|
|
it after rendering the glyph.</p>
|
|
<p class="Pp">This function writes its output into the structure pointed to by
|
|
<var class="Va">metrics</var>. The fields are as follows:</p>
|
|
<dl class="Bl-tag">
|
|
<dt><var class="Va">advanceWidth</var></dt>
|
|
<dd>How much the pen position should advance to the right after rendering the
|
|
glyph</dd>
|
|
<dt><var class="Va">leftSideBearing</var></dt>
|
|
<dd>The offset that should be applied along the X axis from the pen position
|
|
to the edge of the glyph image</dd>
|
|
</dl>
|
|
<p class="Pp">Some sequences of glyphs may look awkward if they're layed out
|
|
naively. For example, the gap between the two characters "VA"
|
|
might look disproportionally large. Kerning is a way to combat this
|
|
phenomenon, by slightly moving the second character closer or further away
|
|
by a small amount. <code class="Fn">sft_kerning</code>() may be used to
|
|
retrieve kerning information for a given pair of glyph ids.</p>
|
|
<p class="Pp">This function writes its output into the structure pointed to by
|
|
<var class="Va">kerning</var>. The fields are as follows:</p>
|
|
<dl class="Bl-tag">
|
|
<dt><var class="Va">xShift</var></dt>
|
|
<dd>An amount that should be added to the pen's X position in-between the two
|
|
glyphs</dd>
|
|
<dt><var class="Va">yShift</var></dt>
|
|
<dd>An amount that should be added to the pen's Y position in-between the two
|
|
glyphs</dd>
|
|
</dl>
|
|
</section>
|
|
<section class="Ss">
|
|
<h2 class="Ss" id="Rendering_glyphs"><a class="permalink" href="#Rendering_glyphs">Rendering
|
|
glyphs</a></h2>
|
|
<code class="Fn">sft_extents</code>() computes bounding box information of a
|
|
glyph without having to render it.
|
|
<p class="Pp">This function writes its output into the structure pointed to by
|
|
<var class="Va">extents</var>. The fields are as follows:</p>
|
|
<dl class="Bl-tag">
|
|
<dt><var class="Va">yOffset</var></dt>
|
|
<dd>An offset along the Y axis relative to the pen position that should be
|
|
applied when displaying the glyph</dd>
|
|
<dt><var class="Va">minWidth</var></dt>
|
|
<dd>The minimum width that an image needs such that the glyph can be properly
|
|
rendered into it</dd>
|
|
<dt><var class="Va">minHeight</var></dt>
|
|
<dd>The minimum height that an image needs such that the glyph can be properly
|
|
rendered into it</dd>
|
|
</dl>
|
|
<p class="Pp">To actually render a glyph into a easily-displayable raster image,
|
|
use <code class="Fn">sft_render</code>().</p>
|
|
<p class="Pp">Other than most functions, <code class="Fn">sft_render</code>()
|
|
takes a structure in <var class="Va">image</var> that is to be filled out by
|
|
the caller. The fields are as follows:</p>
|
|
<dl class="Bl-tag">
|
|
<dt><var class="Va">pixels</var></dt>
|
|
<dd>A pointer to an array of bytes, width * height in size</dd>
|
|
<dt><var class="Va">width</var></dt>
|
|
<dd>The number of pixels in a row of the image</dd>
|
|
<dt><var class="Va">height</var></dt>
|
|
<dd>The number of pixels in a column of the image</dd>
|
|
</dl>
|
|
<p class="Pp">The image will be rendered into the memory provided in
|
|
<var class="Va">pixels</var>. Each byte corresponds to one pixel, with rows
|
|
of the image being directly adjacent in memory without padding between them.
|
|
Glyphs are rendered "white on black", meaning the background has a
|
|
pixel value of 0, and the foreground goes up to a value of 255. Pixel values
|
|
follow a linear color ramp, unlike conventional computer screens. That is to
|
|
say, they are <i class="Em">not gamma-corrected</i>. These properties make
|
|
it very easy to use images rendered with
|
|
<code class="Fn">sft_render</code>() as alpha masks.</p>
|
|
</section>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
|
|
VALUES</a></h1>
|
|
<code class="Fn">sft_loadmem</code>() and <code class="Fn">sft_loadfile</code>()
|
|
return <code class="Dv">NULL</code> on error.
|
|
<p class="Pp"><code class="Fn">sft_lmetrics</code>(),
|
|
<code class="Fn">sft_lookup</code>(),
|
|
<code class="Fn">sft_hmetrics</code>(),
|
|
<code class="Fn">sft_kerning</code>(),
|
|
<code class="Fn">sft_extents</code>(), and
|
|
<code class="Fn">sft_render</code>() all return 0 on success and -1 on
|
|
error.</p>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
|
|
See the source code of <b class="Sy">sftdemo</b> for a detailed example of
|
|
real-world usage of <code class="Nm">schrift</code>.
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
|
|
<span class="An">Thomas Oltmann</span>
|
|
<<a class="Mt" href="mailto:thomas.oltmann.hhg@gmail.com">thomas.oltmann.hhg@gmail.com</a>>
|
|
</section>
|
|
<section class="Sh">
|
|
<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
|
|
The only text encoding that <code class="Nm">schrift</code> understands is
|
|
Unicode.
|
|
<p class="Pp">Similarly, the only kind of font file supported right now are
|
|
TrueType (.ttf) fonts (Some OpenType fonts might work too, as OpenType is
|
|
effectively a superset of TrueType).</p>
|
|
<p class="Pp">As of v0.10.0, there is no support for right-to-left scripts
|
|
<i class="Em">yet</i>.</p>
|
|
<p class="Pp"><code class="Nm">schrift</code> currently does not implement font
|
|
hinting and probably never will.</p>
|
|
</section>
|
|
</div>
|
|
<table class="foot">
|
|
<tr>
|
|
<td class="foot-date">December 20, 2020</td>
|
|
<td class="foot-os">Void Linux</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|