[OpenJDK 2D-Dev] Setting the FreeType LCD filter

[Phil Race]

Very well done analysis of the options and very thorough testing of the 
effects
on the different libraries/platforms.


 > There are some alternatives to setting the filter:
 >   • Bundle the FreeType library by default

Although the build makes this easy to set as an option, we decided we 
prefer to
use the platform library on Linux - and Solaris for that matter - in our 
releases.

So setting this option is going to be needed for some years to come, until
even a Linux current release like Ubuntu 18.04 is obsolete.

We can't re-use the OpenJavaFX bug ID, and surprisingly I can't find an open
bug on this for 2D. So I've submitted 
https://bugs.openjdk.java.net/browse/JDK-8212071

And I've attached John's images to the bug report and pasted his email 
in there.



-phil.


On 10/11/2018 10:56 AM, John Neffenger wrote:
> On 10/10/2018 11:15 AM, Laurent Bourgès wrote:
>> It looks awesome & promising.
>
> Thank you, Laurent, for looking into it so quickly!
>
>> PS: It is better to send plain text (long) email than sending 
>> external links (github).
>
> Thanks for the tip. Right, Web pages and repositories can be deleted, 
> so here it is, for the record ...
>
> The symptoms of the problem are the same as in the link below, but 
> they appear in AWT and Swing applications instead of JavaFX applications.
>
>   JDK-8188810: Fonts are blurry on Ubuntu 16.04 and Debian 9
>   https://bugs.openjdk.java.net/browse/JDK-8188810
>
> The description of the problem on the Java side follows.
>
> Synopsis: Reduce color fringes in FreeType subpixel rendering
>
> The text in Java applications often has severe color fringes when 
> using OpenJDK on Ubuntu and other Debian-based distributions because 
> the JDK fails to set the LCD filter. Adding two lines of code to the 
> file freetypeScaler.c fixed the problem in my tests, without any 
> regression errors for other Linux distributions. The patch is attached 
> to this message as the file freetypeScaler.diff.
>
> There are some alternatives to setting the filter:
>
>   • Bundle the FreeType library by default and always use the new 
> Harmony subpixel rendering technique. This option removes the 
> uncertainty in the library at the expense of an additional 4.6 
> megabytes to the installed size — an increase of less than one 
> percent. OpenJDK 12 even includes the latest FreeType 2.9.1, a newer 
> version than the one found on most systems.
>
>   • Wait another year and see what changes are made to FreeType, if 
> any, when the ClearType patents expire. This option, though, doesn’t 
> solve the problem that users of Ubuntu and other Debian-based 
> distributions have now.
>
> The problem originates in decisions made by the developers of 
> FreeType, Debian, Fedora, and OpenJDK concerning the Microsoft 
> ClearType patents [1].
>
>   • In 2007, FreeType 2.3.0 added a compiler configuration macro to 
> the file ftoption.h named FT_CONFIG_OPTION_SUBPIXEL_RENDERING. If 
> defined, the FreeType library includes patented ClearType techniques 
> in its subpixel rendering.
>
>     But there’s a catch. When the ClearType methods are enabled, the 
> subpixel rendering is not filtered, which results in severe color 
> fringes. Clients of the FreeType library must make an explicit call to 
> the function FT_Library_SetLcdFilter to apply color filtering. The 
> filter was disabled by default, explained one of its authors, “to 
> avoid major surprises to existing clients, including libXft and Cairo 
> which already perform some wacky color filtering on top of FreeType.”
>
>   • In 2009, Debian created a patch to FreeType 2.3.9, named 
> enable-subpixel-rendering.patch, that defines the macro and enables 
> ClearType-style rendering. The change log states, “This is considered 
> no more or less evil than the bytecode interpreter which we also 
> enable.” Ubuntu, based on Debian, applies the patch as well. Fedora 
> created the same patch in 2007, named freetype-2.3.0-enable-spr.patch, 
> but does not apply the patch by default.
>
>   • In 2017, FreeType 2.8.1 included a new subpixel rendering 
> technique, called Harmony, that is nearly identical in output to the 
> ClearType technique but uses a different algorithm, avoiding the 
> patents. FreeType now uses Harmony subpixel rendering when the 
> ClearType methods are disabled, with no need for clients to set the 
> LCD filter. (This would have been a good time for Debian to remove its 
> subpixel rendering patch.) The latest Fedora Workstation 28 runs 
> FreeType 2.8.0, which does not include Harmony.
>
>   • In 2019, the Microsoft ClearType patents expire.
>
> So now we have two variants of the FreeType library: one that requires 
> a function call to set the LCD filter in Ubuntu and other 
> distributions based on Debian, and another that doesn’t require the 
> function call in Red Hat Enterprise Linux, Oracle Linux, and other 
> distributions based on Fedora.
>
> To demonstrate the problem, I built four versions of the JDK from the 
> latest OpenJDK sources. I built a version that uses the system 
> FreeType library and another that uses the bundled FreeType library. 
> Then I changed the OpenJDK code to set the default LCD filter and 
> built the two versions again. The four builds were named:
>
>   jdk-12-system-lcdnone
>   jdk-12-system-lcddefault
>   jdk-12-bundled-lcdnone
>   jdk-12-bundled-lcddefault
>
> The system library is FreeType 2.8.1 in Ubuntu 18.04.1 LTS, which has 
> the Debian patch applied (ClearType methods enabled), while the 
> bundled library is FreeType 2.9.1 in OpenJDK 12, which uses the 
> library default (ClearType methods disabled). I wrote a simple Java 
> Swing application called FontDemo [2] that displays two text areas 
> with the Adobe Source Code Pro font [3] in TTF and OTF formats (the 
> latest non-variable download).
>
> The results are shown in the two images attached to this message:
>
>   fontdemo.png
>     Three screenshots of the FontDemo program
>
>   fontdemo-detail.png
>     Details from the screenshots scaled by 800 percent
>
> When using the Ubuntu system FreeType library, setting the LCD filter 
> is critical. The screenshots show the ClearType-style rendering 
> without setting the LCD filter, and after adding the change to set the 
> filter. The ClearType configuration macro is defined in the Ubuntu 
> build of FreeType, so the function to set the filter returns success 
> (0) when called and applies color filtering.
>
> When using the OpenJDK bundled FreeType library, setting the LCD 
> filter does nothing. The screenshots show the FreeType Harmony 
> rendering, which is the same whether or not the LCD filter is set. The 
> ClearType configuration macro is not defined in the OpenJDK build of 
> FreeType, so the function to set the filter returns 
> FT_Err_Unimplemented_Feature (7) when called and does nothing.
>
> The test system I used is a QEMU/KVM guest virtual machine running 
> Ubuntu 18.04.1 LTS (Bionic Beaver) with the details shown below. The 
> display is a 27-inch Dell UltraSharp U2717D monitor with a resolution 
> of 2560 × 1440 pixels at 109 pixels per inch.
>
> ubuntu at bionic:~$ uname -a
> Linux bionic 4.15.0-36-generic #39-Ubuntu SMP
>   Mon Sep 24 16:19:09 UTC 2018 x86_64 x86_64 x86_64 GNU/Linux
>
> ubuntu at bionic:~$ ldd --version
> ldd (Ubuntu GLIBC 2.27-3ubuntu1) 2.27
>
> ubuntu at bionic:~$ getconf GNU_LIBPTHREAD_VERSION
> NPTL 2.27
>
> ubuntu at bionic:~$ $HOME/opt/jdk-12-system-lcdnone/bin/java -version
> openjdk version "12-internal" 2019-03-19
> OpenJDK Runtime Environment (build 12-internal+0-adhoc.ubuntu.jdk)
> OpenJDK 64-Bit Server VM (build 12-internal+0-adhoc.ubuntu.jdk, mixed 
> mode)
>
> Below are the full test results using five versions of FreeType built 
> first with the ClearType methods disabled (the default) and then again 
> with them enabled. I ran all 10 libraries under OpenJDK 12, first with 
> no LCD filter and then again after adding the code to set the default 
> LCD filter.
>
> No LCD Filter
>
> 2008 FreeType 2.3.5 (libfreetype.so.6.3.16) in Ubuntu 8.04 LTS
>     ClearType Off: Grayscale, ClearType On: Mild fringes
>
> 2014 FreeType 2.5.2 (libfreetype.so.6.11.1) in Ubuntu 14.04 LTS
>     ClearType Off: Grayscale, ClearType On: Severe fringes
>
> 2016 FreeType 2.6.1 (libfreetype.so.6.12.1) in Ubuntu 16.04 LTS
>     ClearType Off: Grayscale, ClearType On: Severe fringes
>
> 2018 FreeType 2.8.1 (libfreetype.so.6.15.0) in Ubuntu 18.04 LTS
>     ClearType Off: Harmony, ClearType On: Severe fringes
>
> 2019 FreeType 2.9.1 (libfreetype.so.6.16.1) in OpenJDK 12
>     ClearType Off: Harmony, ClearType On: Severe fringes
>
> The OpenJDK does not set the FreeType LCD filter, so there are severe 
> color fringes when using a FreeType library built with the ClearType 
> methods enabled. The only reason the older FreeType 2.3.5 shows mild 
> color fringes is because it uses full hinting, so the glyphs are 
> simply too skinny to see their colors.
>
> Default LCD Filter
>
> 2008 FreeType 2.3.5 (libfreetype.so.6.3.16) in Ubuntu 8.04 LTS
>     ClearType Off: Grayscale, ClearType On: ClearType filtered
>
> 2014 FreeType 2.5.2 (libfreetype.so.6.11.1) in Ubuntu 14.04 LTS
>     ClearType Off: Grayscale, ClearType On: ClearType filtered
>
> 2016 FreeType 2.6.1 (libfreetype.so.6.12.1) in Ubuntu 16.04 LTS
>     ClearType Off: Grayscale, ClearType On: ClearType filtered
>
> 2018 FreeType 2.8.1 (libfreetype.so.6.15.0) in Ubuntu 18.04 LTS
>     ClearType Off: Harmony, ClearType On: ClearType filtered
>
> 2019 FreeType 2.9.1 (libfreetype.so.6.16.1) in OpenJDK 12
>     ClearType Off: Harmony, ClearType On: ClearType filtered
>
> After changing the OpenJDK to set the default LCD filter, there is no 
> version of the FreeType library that shows the severe color fringes. 
> Note that Fedora Workstation 28 includes FreeType 2.8.0 with the 
> ClearType methods disabled, so it displays grayscale anti-aliasing for 
> the OpenJDK whether it sets the LCD filter or not. (FreeType 2.8.0 
> does not include Harmony.)
>
> For background information on LCD filters see Section 2.2.1 [4] of The 
> Raster Tragedy at Low-Resolution, which has an interactive 
> demonstration of the filters used in ClearType (Microsoft), CoolType 
> (Adobe), FreeType (open source), and Quartz 2D (Apple). Hover your 
> mouse over each of the samples in the illustration to remove the filter.
>
> Below is the relevant section of the file ftoption.h in FreeType 2.9.1 
> bundled with OpenJDK 12, edited for formatting:
>
> java.desktop/share/native/libfreetype/include/freetype/config/ftoption.h
>
> /*
> Uncomment the line below if you want to activate LCD rendering
> technology similar to ClearType in this build of the library. This
> technology triples the resolution in the direction color subpixels.
> To mitigate color fringes inherent to this technology, you also need
> to explicitly set up LCD filtering.
>
> Note that this feature is covered by several Microsoft patents
> and should not be activated in any default build of the library.
> When this macro is not defined, FreeType offers alternative LCD
> rendering technology that produces excellent output without LCD
> filtering.
> */
> /* #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING */
>
> [1] http://david.freetype.org/cleartype-patents.html
> [2] 
> https://github.com/jgneff/openjdk-freetype/blob/master/src/org/status6/FontDemo.java
> [3] https://github.com/adobe-fonts/source-code-pro
> [4] http://rastertragedy.com/RTRCh2.htm#Sec21