Skip to content

Home

Jump to bottom
Martín Dias edited this page Oct 12, 2023 · 13 revisions

Welcome to the Alexandrie wiki!

FFI bindings

This project includes FFI bindings to Cairo and FreeType that do not depend on the bindings that exist in Pharo.

Why rewriting the bindings? What's different?

  • Document Pharo code to ease a developer to link with the C API counterpart.
  • Offer direct access to the raw C API of the bound libraries. (See note below)
  • Cairo:
    • Focus on using the Cairo API smartly, avoiding redundant calls and early OO abstractions.
    • It doesn't rely on the "Surface Plugin", like Sparta-Cairo, unlike Athens-Cairo.
  • FreeType:
    • Only cover a small subset of the FreeType API that Cairo needs to draw text.
    • Support color bitmap fonts (emoji)

Additionally, we provide FFI bindings to a library that didn't had any support on Pharo yet: Harfbuzz. This library "converts a sequence of Unicode input into properly formatted and positioned glyph output—for any writing system and language." With Harfbuzz, we get access to advanced information stored in font files, such as ligatures, that Cairo and FreeType don't get.

Notes

Using these bindings, a developer should be able to follow a C tutorial and easily translate the code to Pharo.

Tip: To find how a C API function is bound in Pharo, you can copy the function name in the official documentation or the tutorial, paste it on any Pharo text editor, right click and select "Method source with it" in the context menu.

  • If there is a method with that name, then start browsing the class, senders, etc. to learn how to use it.
  • If no method contains it, then you can add it by yourself "by example": find a similar binding to another FFI call. It is often simple.

Tip: Most FFI calls in this repo have a link in the method comment to read to original documentation.

Cairo This is a good start to understand how cairo works: https://cairographics.org/tutorial/ Examples: https://cairographics.org/cookbook/ The API reference: https://cairographics.org/manual/index.html

Testing

The project counts with Test packages that pixel-compare the actual output of the render with PNGs previously exported in the 'tests/' directory of this repo. If any pixel doesn't match with the expected output, the test fails. Browse AeCanvasTest. To run such tests, the AeFilesystemResources will look into the registered Iceberg repositories for one named 'Alexandrie' (case-insensitive). This means that the test will ERROR if the repository is not registered at Iceberg. Normally the repository is registered after Metacello load. But it was not the case on the CI jobs (via smalltalk-ci), and that's why the '.ci.ston' executes a pre-install code (located in the 'scripts/' directory) that adds registers the repository explicitely.

Install

Load in a Pharo 11:

Metacello new
        baseline: 'Alexandrie';
        repository: 'github://pharo-graphics/Alexandrie/src';
        load.

Dependencies

The dynamic libraries provided by the Pharo VM satisfy the project needs in all major platforms (Mac, Linux and Windows). This is true after this release of Pharo VM. These are the versions:

  • Cairo: 1.17.4
  • FreeType: 2.12.1
  • Harfbuzz: 5.3.1

You can find the library versions by printing each of the following sentences:

AeCairoLibrary uniqueInstance versionString.
AeFTLibrary newInitialized versionString.
AeHarfbuzzLibrary uniqueInstance versionString.

Debug CI locally

  1. cd to some tmp directory
  2. git clone https://github.com/pharo-graphics/Alexandrie.git && export GITHUB_WORKSPACE="$(pwd)/Alexandrie" && ~/d/pharo/smalltalkCI/bin/smalltalkci -s Pharo64-11 Alexandrie/.ci.ston
Clone this wiki locally