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

Philip Race philip.race at oracle.com
Tue Oct 16 06:40:48 UTC 2018 

I intend to push this with myself & Laurent as reviewers.

OK by all ?

-phil.

On 10/11/18, 12:22 PM, Phil Race wrote:
> 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
>

More information about the 2d-dev mailing list