RFC: Better Text Rendering for cairo / lua #1501

simotek · 2023-04-12T00:46:22Z

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.

Add empty files and various build options for the lua text bindings Adds requirements for Fontconfig, Freetype and Harfbuzz

netlify · 2023-04-12T00:46:29Z

✅ Deploy Preview for conkyweb canceled.

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

I thought I already removed this and squashed the commit

brndnmtthws

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

brndnmtthws · 2023-04-15T16:13:09Z

.github/workflows/build-and-test-linux.yaml

We could probably enable this in the macos build too, if you want to take a stab at that.

Once I figure out why the ubuntu builds are failing i'll have a shot at enabling it.

brndnmtthws · 2023-04-15T16:19:38Z

lua/libcairo_text_helper.h

The functions in here to be documented in conky/doc/lua.yml.

I've had a shot at doing this in a way that hopefully makes sense, for some reason i couldn't generate docs locally but that doesn't seem related to any of my changes.

If your happy with that i'll probably do similar for the imlib2 bindings that also aren't currently documented.

simotek · 2023-04-17T05:09:03Z

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 · 2023-07-04T00:31:27Z

After trying this patches, bug #75 still exist!

simotek · 2023-07-06T02:32:39Z

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 · 2023-07-20T06:03:00Z

@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 · 2023-07-20T06:23:17Z

This one uses Noto Sans Arabic instead.

moceap · 2023-08-09T14:15:17Z

No it's not OK.

Letters in Arabic should be connected:

You write:

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

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

simotek · 2023-08-10T12:18:50Z

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.

Caellian · 2023-11-04T01:19:41Z

lua/libcairo_text_helper.h

+  //alternatively you can use hb_buffer_set_unicode_funcs(buf, hb_glib_get_unicode_funcs());
+  hb_buffer_set_unicode_funcs(buf, hb_glib_get_unicode_funcs());
+  hb_buffer_set_direction(buf, text_direction); /* or LTR */
+  hb_buffer_set_script(buf, text_script); /* see hb-unicode.h */


Which text_script are you using to test out arabic? It should be "Arab" as defined in hb-common.h.

Caellian · 2023-11-04T01:24:10Z

lua/libcairo_text_helper.h

+  }
+  hb_script_t text_script = hb_script_from_string(script, -1);
+  if (text_script == HB_SCRIPT_UNKNOWN) {
+    text_script = HB_SCRIPT_COMMON;


Try setting this to HB_SCRIPT_ARABIC (string literal) instead of HB_SCRIPT_COMMON and see if it works (though it will break everything else).

Caellian · 2023-11-04T01:27:06Z

lua/libcairo_text_helper.h

+  //alternatively you can use hb_buffer_set_unicode_funcs(buf, hb_glib_get_unicode_funcs());
+  hb_buffer_set_unicode_funcs(buf, hb_glib_get_unicode_funcs());
+  hb_buffer_set_direction(buf, text_direction); /* or LTR */
+  hb_buffer_set_script(buf, text_script); /* see hb-unicode.h */


This should be hb-common.h as well. Just pointing it out (so it's easier for others to pick up), not that these comments will affect anything.

Caellian · 2023-11-04T01:35:17Z

lua/libcairo_text_helper.h

+    text_script = HB_SCRIPT_COMMON;
+  }
+
+  hb_language_t text_language = hb_language_from_string (language, -1);


Is the language set to "ar"?

Yep, the full setting was {font_family="Noto Sans Arabic", font_size=16, align=CAIRO_TEXT_ALIGN_LEFT, font_direction="RTL", font_script="HB_SCRIPT_ARABIC", font_language="ar"}

Caellian · 2023-11-04T02:09:25Z

lua/libcairo_text_helper.h

+  hb_buffer_destroy(buf);
+}
+
+void cairo_text_hp_simple_show(cairo_t *cr, int x, int y, const char *text, FontData *font)


Note that there's no need for these cairo_text_hp_simple_show_* convenience functions. toluapp supports default values and harfbuzz can infer defaults too.

You can make all of the properties optional by:

adding a call to hb_buffer_guess_segment_properties (hb_buffer); in cairo_text_hp_intl_show after specified properties are set.

setting argument order to be: language (because it's inferred from system (least smart)), script (inferred from buffer contents), direction (inferred from script)

as documented here

that order would minimize the need for supplying well inferred values to set the one without a good default

specifying argument defaults to be nullptr/NULL in the header

e.g. const char *direction = NULL

and not calling hb_*_from_string if the value is null (i.e. empty string).

In the same line of reasoning I'd position cairo alignment argument after the font argument and set it to default to CAIRO_TEXT_ALIGN_LEFT.

Also, the binding function should be able to load and cache a font. The cache can leak memory (no need to call free) as it would be weird to manage such things from a lua script and fonts will likely be needed for each draw call.

So the signature of cairo_text_hp_intl_show in .pkg would finally look like: void cairo_text_hp_intl_show(cairo_t *cr, int x, int y, const char *text, const char *font = NULL, int font_size = 12, cairo_text_alignment_t alignment = CAIRO_TEXT_ALIGN_LEFT, const char *language = NULL, const char *script = NULL, const char *direction = NULL).

Sorry I didn't see this until now, I'll certainly swap to the idea of default arguments that seems much better. Leaking fonts seems reasonable to me as well so i'm happy to just add a cache.

I am implementing most of this, with the exception of language which i'm going to default to english if not explicitly set. The reason being if I create a config / script for conky and want to distribute it, I don't want it to start breaking in random ways because other people are using a different language. Also much of conky's outputs such as process names CPU percentages etc work best in English. In this case if you are doing something that requires an explicit language you'll need to set it as well.

moceap · 2023-12-04T02:33:40Z

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

simotek · 2023-12-08T00:31:30Z

@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

Add empty files and various build options for the lua text bindings Adds requirements for Fontconfig, Freetype and Harfbuzz

This should go into its own PR but right now I need it for my system to work.

This replaces the old approach of using a series of function declarations.

For some reason RTL positioning is wrong, it seems somewhat based on font size 1/10th font size seems to get closer to correct so run with that for now, i'll continue investigating a proper fix.

netlify · 2024-02-15T01:53:47Z

✅ Deploy Preview for conkyweb canceled.

Name	Link
🔨 Latest commit	`e5482ca`
🔍 Latest deploy log	https://app.netlify.com/sites/conkyweb/deploys/65e670c2e2e84d00089e6d00

simotek · 2024-02-15T02:01:26Z

So far I've done all the interface changes, other then caching fonts, which is next on my list.

As for the RTL codepaths, subtracting 1/10th of the font size seems to get much closer then -1 especially for larger font sizes. Its not perfect for all fonts at all sizes though, but is significantly better, i'll follow this up with upstream closer

@moceap I presume this screenshot is getting much closer. At this point I have no idea if the text is actual words.

simotek · 2024-02-15T02:29:10Z

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.

Fonts are now cached in C, given the number of fonts and sizes I expect people will use, this implementation seems simpler then implementing hashmaps or attempting to do bindings in C++

This reverts commit 5036cc4. Fixed better upstream now

On my machine i'm using it with lua5.3 and I see packages for 5.4 as well.

Caellian

Some inputs on tables in docs.

Caellian · 2024-03-18T23:05:54Z

doc/lua.yaml

+      | script              | A string containing a ISO 15924 script tag.                                          |
+      |                     | Default value: auto-detect from text                                                 |
+      | direction           | A string representing text direction eg `LTR`, `RTL` or `TTB`                        |
+      |                     | Default value: auto-detect from text otherwise `LTR`                                 |                                                               |


Extra pipe (|) at the end.

Caellian · 2024-03-18T23:12:59Z

doc/lua.yaml

+      | script              | A string containing a ISO 15924 script tag.                                          |
+      |                     | Default value: auto-detect from text                                                 |
+      | direction           | A string representing text direction eg `LTR`, `RTL` or `TTB`                        |
+      |                     | Default value: auto-detect from text otherwise `LTR`                                 |


Instead of putting default value into the next row, it might be better to put it in the same cell and use <br/> so that it looks like this:

Argument Description

language A string containing a BCP 47 language tag.
Default value: en

Caellian · 2024-03-18T23:26:32Z

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.

simotek and others added 3 commits April 11, 2023 21:35

lua text: Supporting infra

2a0db1d

Add empty files and various build options for the lua text bindings Adds requirements for Fontconfig, Freetype and Harfbuzz

lua text: initial implementation.

79b81a6

Add the ability to center and right align text.

24706e8

github-actions bot added appimage Issue or PR that's related to AppImage changes gh-actions Issue or PR that suggest changing GitHub actions sources PR modifies project sources labels Apr 12, 2023

lua text: Remove test code

d5d20e8

I thought I already removed this and squashed the commit

simotek mentioned this pull request Apr 12, 2023

Significantly Expanding Polycore. philer/polycore#12

Open

brndnmtthws requested changes Apr 15, 2023

View reviewed changes

Caellian reviewed Nov 4, 2023

View reviewed changes

simotek and others added 9 commits February 14, 2024 10:19

lua text: Supporting infra

b625e93

Add empty files and various build options for the lua text bindings Adds requirements for Fontconfig, Freetype and Harfbuzz

lua text: initial implementation.

4077ad5

Commit the WIP so I can merge it

00b2ec0

Fix for brndnmtthws#1698

5036cc4

This should go into its own PR but right now I need it for my system to work.

Fix comment hb-unicode.h should be hb-common.h

488b450

Swap to using optional parameters

b0063e5

This replaces the old approach of using a series of function declarations.

Add Hack for RTL positioning

945ce1f

For some reason RTL positioning is wrong, it seems somewhat based on font size 1/10th font size seems to get closer to correct so run with that for now, i'll continue investigating a proper fix.

Remove Top to Bottom Fixme's they are fixed

dc7c0e0

Merge branch 'lua-text-helper2' into lua-text-helper3

ca1be94

Some general cleanup post merge

47c45af

simotek added 4 commits February 15, 2024 12:37

Attempt to fix workflows by adding freetype dep

7553faf

Probably actually need freetype6

2c74058

Try again, I don't understand Ubuntu

7e2a662

Try something from google

ac50fa7

simotek added 4 commits February 22, 2024 10:14

lua-text: Move to caching fonts in C

ba71b73

Fonts are now cached in C, given the number of fonts and sizes I expect people will use, this implementation seems simpler then implementing hashmaps or attempting to do bindings in C++

Revert "Fix for brndnmtthws#1698"

8f34c9d

This reverts commit 5036cc4. Fixed better upstream now

docs: tolua++ now works with more then lua5.1

9ba643c

On my machine i'm using it with lua5.3 and I see packages for 5.4 as well.

lua-text: Add docs.

f4f7462

github-actions bot added the documentation Issue or PR that suggests documentation improvements label Feb 22, 2024

lua-text: Fix build with

e5482ca

Caellian reviewed Mar 18, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC: Better Text Rendering for cairo / lua #1501

RFC: Better Text Rendering for cairo / lua #1501

simotek commented Apr 12, 2023 •

edited

netlify bot commented Apr 12, 2023 •

edited

brndnmtthws left a comment

brndnmtthws Apr 15, 2023

simotek Feb 22, 2024

brndnmtthws Apr 15, 2023

simotek Feb 22, 2024

simotek commented Apr 17, 2023

moceap commented Jul 4, 2023

simotek commented Jul 6, 2023

simotek commented Jul 20, 2023

simotek commented Jul 20, 2023

moceap commented Aug 9, 2023

simotek commented Aug 10, 2023

Caellian left a comment

Caellian Nov 4, 2023 •

edited

Caellian Nov 4, 2023

Caellian Nov 4, 2023

Caellian Nov 4, 2023

simotek Dec 8, 2023 •

edited

Caellian Nov 4, 2023 •

edited

Caellian Nov 4, 2023

Caellian Nov 4, 2023

simotek Dec 8, 2023

simotek Feb 14, 2024

moceap commented Dec 4, 2023

simotek commented Dec 8, 2023

netlify bot commented Feb 15, 2024 •

edited

simotek commented Feb 15, 2024

simotek commented Feb 15, 2024

Caellian left a comment

Caellian Mar 18, 2024

Caellian Mar 18, 2024

Caellian commented Mar 18, 2024

RFC: Better Text Rendering for cairo / lua #1501

Are you sure you want to change the base?

RFC: Better Text Rendering for cairo / lua #1501

Conversation

simotek commented Apr 12, 2023 • edited

Description

Introduction

Current API Description (Happy to make changes here)

Screenshot

netlify bot commented Apr 12, 2023 • edited

✅ Deploy Preview for conkyweb canceled.

brndnmtthws left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

simotek commented Apr 17, 2023

moceap commented Jul 4, 2023

simotek commented Jul 6, 2023

simotek commented Jul 20, 2023

simotek commented Jul 20, 2023

moceap commented Aug 9, 2023

simotek commented Aug 10, 2023

Caellian left a comment

Choose a reason for hiding this comment

Caellian Nov 4, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

simotek Dec 8, 2023 • edited

Choose a reason for hiding this comment

Caellian Nov 4, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

moceap commented Dec 4, 2023

simotek commented Dec 8, 2023

netlify bot commented Feb 15, 2024 • edited

✅ Deploy Preview for conkyweb canceled.

simotek commented Feb 15, 2024

simotek commented Feb 15, 2024

Caellian left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Caellian commented Mar 18, 2024

simotek commented Apr 12, 2023 •

edited

netlify bot commented Apr 12, 2023 •

edited

Caellian Nov 4, 2023 •

edited

simotek Dec 8, 2023 •

edited

Caellian Nov 4, 2023 •

edited

netlify bot commented Feb 15, 2024 •

edited