SDB:How to Report a Font Issue
This article discusses font rendering issues of fontconfig based applications. And how to debug and report them properly.
Situation
You noticed that some fonts on you desktop aren't rendered properly and you would like to improve it for you and for all openSUSE users in future openSUSE releases.
Libraries involved
- freetype -- font rendering library (freetype home)
- fontconfig -- library for configuring and customizing font access (fontconfig home)
Procedure
Several algorithms for rendering fonts are used by freetype library. Programs using fontconfig to determine which installed font to pick for UIs or documents are configurable by config files under /etc/fonts and files or directories included from there (e. g. ~/.fonts.conf file).
Example
Try following ~/.fonts.conf
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<!-- /etc/fonts/local.conf file for local customizations -->
<fontconfig>
<match target="font">
<edit name="matrix">
<matrix>
<double>-1</double><double>0</double>
<double>0</double><double>1</double>
</matrix>
</edit>
</match>
</fontconfig>
and rerun any X application to see if this change have some effect on it.
Mandatory part
Please file a bugreport. In summary field, use: fontconfig:$family_name:$whats_wrong and replace the placeholders with their respective values. You will need to figure out which font family is badly rendered to make a useful bugreport. There is no single way to gather this information from your system. Where font dialog of affected application doesn't help, the following command can give you a clue:
where fc-debug.sh wrapper can look like
FC_DEBUG=1 $@ | egrep -A2 -e "Best score" -e "First font Pattern" | grep family: | sed 's:.*\(".*"\).*:\1:' | sort | uniq
Note: It is not true that same program in the same situation is using same font while running on other system at the same time; it depends on how is rendering library configured and of course which fonts are installed. In other words, for the same query you can get other font on different systems.
$whats_wrong can be also generic "wrongly rendered", nevertheless any detail is welcome and screenshot is always required.
Example
We have noticed, that R is rendered wrongly for some font.
We are of course interested in shortest way to expose the issue, which is
- run firefox http://en.opensuse.org/SDB:How_to_Report_a_Printing_Issue
- Ctrl+Q
for this case. With fc-debug we get
$ fc-debug.sh firefox http://en.opensuse.org/SDB:How_to_Report_a_Printing_Issue 2>/dev/null "Cantarell" "DejaVu Sans" "DejaVu Sans Mono" "Liberation Sans"
Problematic font can be then determinated by any application capable to display font you choose (i. e. have font dialog).
It is evident now that the culprit is Liberation Sans. However, rendering results depends on font sizes: this issue is hardly noticeable for 10pt. For smaller and smaller sizes it becomes more obvious.
Optional part
To help us more, you can experiment and try various algorithms for rendering font you think can be displayed better.
Note: Please leave subpixel rendering aside (patents, bugzilla precedent, how to turn on subpixel hinting).
Use following fontconfig file (e. g. as ~/.fonts.conf):
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
<match target="font">
<test name="family">
<string>FAMILY_NAME</string>
</test>
<edit name="antialias" mode="assign">
<bool>true</bool>
</edit>
<edit name="hinting" mode="assign">
<bool>true</bool>
</edit>
<edit name="autohint" mode="assign">
<bool>false</bool>
</edit>
<edit name="hintstyle" mode="assign">
<const>hintfull</const>
</edit>
</match>
</fontconfig>
with FAMILY_NAME replaced by name of problematic font.
- antialiasing can be turned on (antialiasing=true) or off (antialiasing=false), see Font rasterization
- hinting can be turned on (hinting=true) or off (hinting=false), see Font hinting
- hinting can be done either with bytecode interpreter (BCI, DejaVu hinting tutorial, autohinting=false) or with freetype's autohinter (FreeType Auto-Hinting, autohinting=true)
- hinting level is defined with hintstyle; expected values of this variable is 0 (hintnone), 1 (hintslight), 2 (hintmedium) and 3 (hintfull)
It is said that most fonts achieve best results with following values:
| font's native instructions | antialiasing | hinting | autohinter | hintstyle |
|---|---|---|---|---|
| good | true | true | false | 3 |
| incomplete or no | true | true | true | 1 |
This can be matter of taste, yes. For example, some users can like fonts rendered without antialiasing. Also, some advantage of one algorithm can be balanced by advantage of another one.
will tell you which algorithm is used for rendering font matching PATTERN. Rarely, choice of rendering algorithm(s) can depend on other entries of pattern, so family name is sometimes not enough. You can experiment with ~/fonts.conf above by combining rendering algorithms together. Don't forgot to rerun testing program whenever you change fontconfig file.
Example
Follow up of previous example. With
we get
Pattern has 31 elts (size 32)
family: "Liberation Sans"(s)
familylang: "en"(s)
style: "Regular"(s)
stylelang: "en"(s)
fullname: "Liberation Sans"(s)
fullnamelang: "en"(s)
slant: 0(i)(s)
weight: 80(i)(s)
width: 100(i)(s)
size: 12(f)(s)
pixelsize: 12.5(f)(s)
foundry: "unknown"(s)
antialias: FcTrue(w)
hintstyle: 3(i)(w)
hinting: FcTrue(w)
verticallayout: FcFalse(s)
autohint: FcFalse(w)
globaladvance: FcTrue(s)
file: "/usr/share/fonts/truetype/LiberationSans-Regular.ttf"(s)
index: 0(i)(s)
outline: FcTrue(s)
scalable: FcTrue(s)
dpi: 75(f)(s)
scale: 1(f)(s)
charset:
0000: 00000000 ffffffff ffffffff 7fffffff 00000000 ffffffff ffffffff ffffffff
0001: ffffffff ffffffff ffffffff ffffffff 00040000 00000000 00000000 fc000000
0002: 0f000000 00000000 00000000 00000000 00000000 00000000 3f0002c0 00000000
0003: 00000000 00000000 00000000 40000000 ffffd7f0 fffffffb 00007fff 00000000
0004: ffffdffe ffffffff dffeffff 00000000 00030000 00000000 00000000 00000000
001e: 00000000 00000000 00000000 00000000 0000003f 00000000 00000000 000c0000
0020: 7fbb0000 560d0047 00000010 80000000 00000000 00001098 00000000 00000000
0021: 00480020 00004044 78000000 00000000 003f0000 00000100 00000000 00000000
0022: c6268044 00000a00 00000100 00000033 00000000 00000000 00000000 00000000
0023: 00010004 00000003 00000000 00000000 00000000 00000000 00000000 00000000
0025: 11111005 10101010 ffff0000 00001fff 000f1111 14041c03 03008c10 00000040
0026: 00000000 1c000000 00000005 00000c69 00000000 00000000 00000000 00000000
00f0: 00000026 00000000 00000000 00000000 00000000 00000000 00000000 00000000
00fb: 00000006 00000000 00000000 00000000 00000000 00000000 00000000 00000000
(s)
lang: aa|af|ast|av|ay|be|bg|bi|br|bs|ca|ce|ch|co|cs|cy|da|de|el|en|eo|es|et|eu|fi|fj|fo|fr|fur|fy|gd|gl|gv|ho|hr|hu|ia|id|ie|ik|io|is|it|ki|kl|kum|la|lb|lez|lt|lv|mg|mh|mo|mt|nb|nds|nl|nn|no|nr|nso|ny|oc|om|os|pl|pt|rm|ro|ru|se|sel|sk|sl|sma|smj|smn|so|sq|sr|ss|st|sv|sw|tk|tl|tn|tr|ts|uk|uz|vo|vot|wa|wen|wo|xh|yap|zu|an|crh|csb|fil|hsb|ht|jv|kj|ku-tr|kwm|lg|li|ms|na|ng|pap-an|pap-aw|rn|rw|sc|sg|sn|su|za(s)
fontversion: 69468(i)(s)
capability: "otlayout:DFLT otlayout:cyrl otlayout:grek otlayout:latn"(s)
fontformat: "TrueType"(s)
embeddedbitmap: FcFalse(w)
decorative: FcFalse(s)
which implies that we expect better results with font's hinting instructions than with autohinter. Changing to autohinter=true and hintstyle=1 by
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>
<match target="font">
<test name="family">
<string>Liberation Sans</string>
</test>
<edit name="antialias" mode="assign">
<bool>true</bool>
</edit>
<edit name="hinting" mode="assign">
<bool>true</bool>
</edit>
<edit name="autohint" mode="assign">
<bool>true</bool>
</edit>
<edit name="hintstyle" mode="assign">
<const>hintslight</const>
</edit>
</match>
</fontconfig>
gives
