Update copyright headers
[qt:qt.git] / doc / src / platforms / emb-fonts.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page qt-embedded-fonts.html
30
31     \title Qt for Embedded Linux Fonts
32     \ingroup qt-embedded-linux
33
34     \l {Qt for Embedded Linux} uses the
35     \l{http://freetype.sourceforge.net/freetype2/index.html}{FreeType 2}
36     font engine to produce font output. The formats supported depends on
37     the locally installed version of the FreeType library. In addition,
38     \l{Qt for Embedded Linux} supports the Qt Prerendered Font formats (\l QPF and \l QPF2):
39     light-weight non-scalable font formats specific to \l {Qt for Embedded Linux}.
40     QPF2 is the native format of \l{Qt for Embedded Linux}. QPF is the legacy
41     format used by Qt/Embedded 2.x and 3.x. Several of the formats may be rendered
42     using anti-aliasing for improved readability.
43
44     When \l{Qt for Embedded Linux} applications run, they look for fonts in
45     Qt's \c lib/fonts/ directory. \l {Qt for Embedded Linux} will automatically detect
46     prerendered fonts and TrueType fonts. For compatibility, it will also read the
47     legacy \c lib/fonts/fontdir file.
48
49     Support for other font formats can be added. To make a suggestion,
50     please create a task in our bug tracker at \l
51     {http://bugreports.qt-project.org}{http://bugreports.qt-project.org}.
52
53     \tableofcontents
54
55     \table 100%
56     \row
57     \o
58     \bold {Optimization}
59
60     The \l FreeType, \l QPF2 and \l QPF formats are features that can be
61     disabled using the
62     \l{Fine-Tuning Features in Qt}{feature definition system},
63     reducing the size of Qt and saving resources.
64
65     Note that at least one font format must be defined.
66
67     See the \l {Fine-Tuning Features in Qt} documentation for
68     details.
69
70     \o
71     \inlineimage qt-embedded-fontfeatures.png
72     \endtable
73
74     All supported fonts use the Unicode character encoding. Most fonts
75     available today do, but they usually don't contain \e all the
76     Unicode characters. A complete 16-point Unicode font uses over 1
77     MB of memory.
78
79     \target FreeType
80     \section1 FreeType Formats
81
82     The \l {http://freetype.sourceforge.net/freetype2/index.html}{FreeType 2}
83     library (and therefore \l{Qt for Embedded Linux}) can support the following font formats:
84
85     \list
86         \o TrueType (TTF)
87         \o PostScript Type1 (PFA/PFB)
88         \o Bitmap Distribution Format (BDF)
89         \o CID-keyed Type1
90         \o Compact Font Format (CFF)
91         \o OpenType fonts
92         \o SFNT-based bitmap fonts
93         \o Portable Compiled Format (PCF)
94         \o Microsoft Windows Font File Format (Windows FNT)
95         \o Portable Font Resource (PFR)
96         \o Type 42 (limited support)
97     \endlist
98
99     It is possible to add modules to the \l
100     {http://freetype.sourceforge.net/freetype2/index.html}{FreeType 2}
101     font engine to support other types of font files. For more
102     information, see the font engine's own website: \l
103     http://freetype.sourceforge.net/freetype2/index.html.
104
105     Glyphs rendered using FreeType are shared efficiently between applications,
106     reducing memory requirements and speeding up text rendering.
107
108     \omit
109     \l {Qt for Embedded Linux} will by default use the system FreeType library if it exists.
110     Otherwise it will use a copy of the FreeType library in Qt, which by default only
111     supports TrueType fonts to reduce footprint.
112     \endomit
113
114     \target QPF2
115     \section1 Qt Prerendered Font (QPF2)
116
117     The Qt Prerendered Font (QPF2) is an architecture-independent,
118     light-weight and non-scalable font format specific to \l{Qt for Embedded Linux}.
119
120     Nokia provides the cross-platform \l makeqpf tool, included in the
121     \c tools directory of both \l {Qt} and \l{Qt for Embedded Linux}, which allows
122     generation of QPF2 files from system fonts.
123
124     QPF2 supports anti-aliasing and complex writing systems, using information
125     from the corresponding TrueType font, if present on the system. The format
126     is designed to be mapped directly to memory. The same format is used to
127     share glyphs from non-prerendered fonts between applications.
128
129     \target QPF
130     \section1 Legacy Qt Prerendered Font (QPF)
131
132     Nokia provides support for the legacy QPF format for compatibility
133     reasons. QPF is based on the internal font engine data structure of Qt/Embedded
134     versions 2 and 3.
135
136     Note that the file name describes the font, for example \c helvetica_120_50.qpf
137     is 12 point Helvetica while \c helvetica_120_50i.qpf is 12 point Helvetica \e italic.
138
139     \omit
140     \section1 Memory Requirements
141
142     Taking advantage of the way the QPF format is structured, Qt for
143     Embedded Linux memory-maps the data rather than reading and parsing it.
144     This reduces RAM consumption even further.
145
146     Scalable fonts use a larger amount of memory per font, but
147     these fonts provide a memory saving if many different sizes of each
148     font are needed.
149     \endomit
150
151     \section1 The Legacy \c fontdir File
152
153     For compatibility reasons \l{Qt for Embedded Linux} supports the \c fontdir
154     file, if present. The file defines additional fonts available to the
155     application, and has the following format:
156
157     \snippet doc/src/snippets/code/doc_src_emb-fonts.qdoc 0
158
159     \table 100%
160     \header \o Field \o Description
161     \row \o \bold name
162     \o The name of the font format, e.g.,\c Helvetica, \c Times, etc.
163     \row \o \bold file
164     \o The name of the file containing the font, e.g., \c
165     helvR0810.bdf, \c verdana.ttf, etc.
166     \row \o \bold renderer
167     \o Specifies the font engine that should be used to render the
168     font, currently only the FreeType font engine (\c FT) is
169     supported.
170     \row \o \bold italic
171     \o Specifies whether the font is italic or not; the accepted
172     values are \c y or \c n.
173     \row \o \bold weight
174     \o Specifies the font's weight: \c 50 is normal, \c 75 is bold,
175     etc.
176     \row \o \bold size
177     \o Specifies the font size, i.e., point size * 10. For example, a
178     value of 120 means 12pt. A value of 0 means that the font is
179     scalable.
180     \row \o \bold flags
181     \o The following flag is supported:
182     \list
183         \o \c s: smooth (anti-aliased)
184     \endlist
185     All other flags are ignored.
186     \endtable
187 */