Better Text Rendering for cairo / lua

[simotek]

Description

Introduction

I have attempted to resolve #900 by creating a new lua binding specifically for doing font rendering in Cairo using Freetype and Harfbuzz, fontconfig is also used to locate the correct fonts. I have chosen to follow the approach of the imlib2_helper binding and not expose functions from the headers of each of these libraries but rather provide simple functions that "internally" use each of these libraries.

At the time of creating this PR I have no fixed thoughts on the API other then it works for my use case and tries to balance the simple act of rendering an English string while also allowing complex options such as RTL text as requested in #75 as well as being able to center and right align text #940 and #1017. So your thoughts on the API topic would be much appreciated, once the API is finalized I will add appropriate documentation. currently this is the last major step for be before being able to move to a lua only config.

Current API Description (Happy to make changes here)

Loading a font from a file is a slow enough operation that we probably don't want to do it multiple times so I separated loading fonts and freeing memory at close into separate functions.

/* font is a string containing the name of the font to load */
/* this will be matched on a best effort basis and FontConfig will fall back to a similar font if the specified font isn't found */
FontData * cairo_text_hp_load_font(const char *font, int font_size);
void cairo_text_hp_destroy_font(FontData *font);

The next set of functions cover the "Simple" English use cases, I could have added a parameter for alignment but I was trying to keep the common Left case as simple as possible.

void cairo_text_hp_simple_show(cairo_t *cr, int x, int y, const char *text, FontData *font);
void cairo_text_hp_simple_show_center(cairo_t *cr, int x, int y, const char *text, FontData *font);
void cairo_text_hp_simple_show_right(cairo_t *cr, int x, int y, const char *text, FontData *font);

The next function is the "catch all" with the main implementation and allows tweeking of the internalization options such as text direction in Harfbuzz for people looking to use non latin languages.

/* 
 * Direction calls hb_direction_from_string example values are LTR and RTL
 *   https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-direction-from-string
 * Script is an ISO 15924 4 character string, "Zyyy" can be used for "Common" and "Zinh"
 *  for "Inherited". 
 *  https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-script-from-string
 * Language is a BCP 47 language tag. eg "en" or "en-US"
 */
void cairo_text_hp_intl_show(cairo_t *cr, int x, int y, cairo_text_alignment_t alignment, const char *text, 
                                                    FontData *font,  const char *direction, const char *script, const char *language);

Finally when doing layouting sometimes its useful to know how wide the final string will be so the following find the text width, again there is a simple latin version and an internationalized version. In the future I'll also provide a Height function which will be important for supporting vertical text.

int cairo_text_hp_simple_text_width(const char *text, FontData *font);
int cairo_text_hp_intl_text_width(const char *text, FontData *font, const char *direction, const char *script, const char *language);

Screenshot

In the following screenshot the "Cairo" text is using Cairo's built in basic text rendering, the "Conky" text is using Conky's standard text rendering and the "Freetype" strings are using this new API with Freetype and Harfbuzz rendering the text in Cairo. All these cases are just using the default settings as found on openSUSE Tumbleweed.

[netlify]

✅ Deploy Preview for conkyweb canceled.

Name	Link
🔨 Latest commit	d5d20e8
🔍 Latest deploy log	https://app.netlify.com/sites/conkyweb/deploys/643606d387ba2c0007c0b550

[brndnmtthws]

Looks great overall, just need to add documentation to https://github.com/brndnmtthws/conky/blob/main/doc/lua.yaml for the new functions.

[simotek]

Thanks for the feedback, i'll update the docs and finish of implementing the Top to Bottom features then finish up a couple of configs to use them before sending through some updates. But its good to know i'm heading in the right direction.

[moceap]

After trying this patches, bug #75 still exist!

[simotek]

After trying this patches, bug #75 still exist!

Yes that is currently to be expected, the WIP patch just had the LTR support so I could get feedback on the API, RTL is almost there I just need to finish writing the tests.

Also this change only works with the lua API, however it is the first step in my project to add a toolkit to make using the lua API much simpler. Although that is further from completion.

[simotek]

@moceap Can you confirm that the following screenshot looks ok, it should be the days of the week.

I'll probably do just a little more testing of my actual real world usecases before sending through an updated pull request

[simotek]

This one uses Noto Sans Arabic instead.

[moceap]

No it's not OK.

Letters in Arabic should be connected:

You write:

الإثنين
يوم الثلاثاء
الأربعاء
يوم الخميس
جمعة
السبت
الأحد

Look at them here in the browser, they are connected.

[simotek]

No it's not OK.

Letters in Arabic should be connected:

You write:

الإثنين يوم الثلاثاء الأربعاء يوم الخميس جمعة السبت الأحد

Look at them here in the browser, they are connected.

Thanks for the confirmation, that's what I thought i'll have to have a closer look at whats going wrong, the left to right seems to be ok.

[Caellian]

Never used HarfBuzz, but from what I picked up googling it, the way you're using it seems fine.

[moceap]

@simotek Take a look https://github.com/HOST-Oman/libraqm, It may fast the process.

[simotek]

@simotek Take a look https://github.com/HOST-Oman/libraqm, It may fast the process.

One thing I noticed at https://github.com/HOST-Oman/libraqm/blob/9d7ca9d59dba38e777bdcd096870776dab5e6e66/src/raqm.c#L1793C1-L1793C48 is that for the RTL case they seem to have hardcoded a -1 into the calculation for character position, So I might have to have a play with that later.

It seemed like hardcoding a -1 into the width of each character would solve the issue but I didn't want to just do it without seeing it documented, but the fact this other codebase is suggests its probably the right solution

[simotek]

Also if anyone has any idea what Ubuntu packages are needed to get cmake to find freetype that would be much appreciated so that I don't need to spin up a VM and test.

Should be libfreetype6-dev, see: https://askubuntu.com/questions/1347131/what-is-the-reason-of-cmake-error-when-using-freetype2-header

* CMake is crappy at locating dependencies sometimes (amongst a rather long list of other things), if you have that package installed, send the output of `apt-file list libfreetype6-dev` so we can patch the [Find script](https://cmake.org/cmake/help/latest/module/FindFreetype.html).

I swapped it and the XFT implementation to using cmake's find_package(Freetype REQUIRED), the old XFT implementation worked fine for me on openSUSE, but obviously it had issues on ubuntu

[simotek]

I think this is finally getting close and i've finally got it doing everything I need from it.

All the text in the below screenshot is using the new conky lua API including the stiff with borders and Gradients etc. The conky memory leak is unrelated and fixed in #2083

[brndnmtthws]

The code looks pretty reasonable to me. A few minor nit picks (mostly formatting related). I'm not really familiar with the implementation details or harfbuzz, so I'll trust your judgement on that.

Not related to this PR, but we should probably separate the helper header declarations from the implementation code (putting the latter into separate files).

[simotek]

@brndnmtthws sorry this has taken so long, I had to spend a while debugging where some memory leaks were in my testing implementation, i'm now happy that the C++ code is fine and it was a problem in other parts of my lua code.

I've re reviewed this and taken on all feedback so hopefully this is in an acceptable state now.