Raqm: Raqm Reference Manual

## Raqm Raqm — A library for complex text layout |

## Functions

raqm_t * | raqm_create ()
raqm_t * | raqm_reference ()
void | raqm_destroy ()
void | raqm_clear_contents ()
bool | raqm_set_text ()
bool | raqm_set_text_utf8 ()
bool | raqm_set_text_utf16 ()
bool | raqm_set_par_direction ()
bool | raqm_set_language ()
bool | raqm_set_freetype_face ()
bool | raqm_set_freetype_face_range ()
bool | raqm_set_freetype_load_flags ()
bool | raqm_set_freetype_load_flags_range ()
bool | raqm_set_letter_spacing_range ()
bool | raqm_set_word_spacing_range ()
bool | raqm_set_invisible_glyph ()
bool | raqm_add_font_feature ()
bool | raqm_layout ()
raqm_glyph_t * | raqm_get_glyphs ()
raqm_direction_t | raqm_get_par_resolved_direction ()
raqm_direction_t | raqm_get_direction_at_index ()
bool | raqm_index_to_position ()
bool | raqm_position_to_index ()
void | raqm_version ()
bool | raqm_version_atleast ()
const char * | raqm_version_string ()
#define | RAQM_VERSION_ATLEAST()

## Types and Values

#define | RAQM_VERSION_MAJOR
#define | RAQM_VERSION_MICRO
#define | RAQM_VERSION_MINOR
#define | RAQM_VERSION_STRING
typedef | raqm_t
enum | raqm_direction_t
| raqm_glyph_t

## Includes

    #include <raqm.h>

## Description

Raqm is a lightweight text layout library with strong emphasis on supporting languages and writing systems that require complex text layout.

The main object in Raqm API is raqm_t, it stores all the states of the input text, its properties, and the output of the layout process.

To start, you create a raqm_t object, add text and font(s) to it, run the layout process, and finally query about the output. For example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    #include "raqm.h"

    int
    main (int argc, char *argv[])
    {
        const char *fontfile;
        const char *text;
        const char *direction;
        const char *language;
        int ret = 1;

        FT_Library library = NULL;
        FT_Face face = NULL;

        if (argc < 5)
        {
            printf ("Usage: %s FONT_FILE TEXT DIRECTION LANG\n", argv[0]);
            return 1;
        }

        fontfile =  argv[1];
        text = argv[2];
        direction = argv[3];
        language = argv[4];

        if (FT_Init_FreeType (&library) == 0)
        {
          if (FT_New_Face (library, fontfile, 0, &face) == 0)
          {
            if (FT_Set_Char_Size (face, face->units_per_EM, 0, 0, 0) == 0)
            {
              raqm_t *rq = raqm_create ();
              if (rq != NULL)
              {
                raqm_direction_t dir = RAQM_DIRECTION_DEFAULT;

                if (strcmp (direction, "r") == 0)
                  dir = RAQM_DIRECTION_RTL;
                else if (strcmp (direction, "l") == 0)
                  dir = RAQM_DIRECTION_LTR;

                if (raqm_set_text_utf8 (rq, text, strlen (text)) &&
                    raqm_set_freetype_face (rq, face) &&
                    raqm_set_par_direction (rq, dir) &&
                    raqm_set_language (rq, language, 0, strlen (text)) &&
                    raqm_layout (rq))
                {
                  size_t count, i;
                  raqm_glyph_t *glyphs = raqm_get_glyphs (rq, &count);

                  ret = !(glyphs != NULL || count == 0);

                  printf("glyph count: %zu\n", count);
                  for (i = 0; i < count; i++)
                  {
                      printf ("gid#%d off: (%d, %d) adv: (%d, %d) idx: %d\n",
                              glyphs[i].index,
                              glyphs[i].x_offset,
                              glyphs[i].y_offset,
                              glyphs[i].x_advance,
                              glyphs[i].y_advance,
                              glyphs[i].cluster);
                  }
                }

                raqm_destroy (rq);
              }
            }

            FT_Done_Face (face);
          }

          FT_Done_FreeType (library);
        }

        return ret;
    }

To compile this example:

    1
    cc -o test test.c `pkg-config --libs --cflags raqm`

## Functions

### raqm_create ()

    raqm_t *
    raqm_create (void);

Creates a new raqm_t with all its internal states initialized to their defaults.

#### Returns

A newly allocated raqm_t with a reference count of 1. The initial reference count should be released with `raqm_destroy()` when you are done using the raqm_t. Returns `NULL` in case of error.

Since: 0.1

### raqm_reference ()

    raqm_t *
    raqm_reference (raqm_t *rq);

Increases the reference count on `rq` by one. This prevents `rq` from being destroyed until a matching call to `raqm_destroy()` is made.

#### Parameters

rq | a raqm_t. |

#### Returns

The referenced raqm_t.

Since: 0.1

### raqm_destroy ()

    void
    raqm_destroy (raqm_t *rq);

Decreases the reference count on `rq` by one. If the result is zero, then `rq` and all associated resources are freed. See `raqm_reference()`.

#### Parameters

rq | a raqm_t. |

Since: 0.1

### raqm_clear_contents ()

    void
    raqm_clear_contents (raqm_t *rq);

Clears internal state of previously used raqm_t object, making it ready for reuse and keeping some of allocated memory to increase performance.

#### Parameters

rq | a raqm_t. |

Since: 0.9

### raqm_set_text ()

    bool
    raqm_set_text (raqm_t *rq,
                   const uint32_t *text,
                   size_t len);

Adds `text` to `rq` to be used for layout. It must be a valid UTF-32 text, any invalid characters will be replaced with U+FFFD. The text should typically represent a full paragraph, since doing the layout of chunks of text separately can give improper output.

#### Parameters

rq | a raqm_t. |
text | a UTF-32 encoded text string. |
len | the length of `text` . |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.1

### raqm_set_text_utf8 ()

    bool
    raqm_set_text_utf8 (raqm_t *rq,
                        const char *text,
                        size_t len);

Same as `raqm_set_text()`, but for text encoded in UTF-8 encoding.

#### Parameters

rq | a raqm_t. |
text | a UTF-8 encoded text string. |
len | the length of `text` in UTF-8 bytes. |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.1

### raqm_set_text_utf16 ()

    bool
    raqm_set_text_utf16 (raqm_t *rq,
                         const uint16_t *text,
                         size_t len);

Same as `raqm_set_text()`, but for text encoded in UTF-16 encoding.

#### Parameters

rq | a raqm_t. |
text | a UTF-16 encoded text string. |
len | the length of `text` in UTF-16 shorts. |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.10

### raqm_set_par_direction ()

    bool
    raqm_set_par_direction (raqm_t *rq,
                            raqm_direction_t dir);

Sets the paragraph direction, also known as block direction in CSS. For horizontal text, this controls the overall direction in the Unicode Bidirectional Algorithm, so when the text is mainly right-to-left (with or without some left-to-right) text, then the base direction should be set to RAQM_DIRECTION_RTL and vice versa.

The default is RAQM_DIRECTION_DEFAULT, which determines the paragraph direction based on the first character with strong bidi type (see rule P2 in Unicode Bidirectional Algorithm), which can be good enough for many cases but has problems when a mainly right-to-left paragraph starts with a left-to-right character and vice versa as the detected paragraph direction will be the wrong one, or when text does not contain any characters with string bidi types (e.g. only punctuation or numbers) as this will default to left-to-right paragraph direction.

For vertical, top-to-bottom text, RAQM_DIRECTION_TTB should be used. Raqm, however, provides limited vertical text support and does not handle rotated horizontal text in vertical text, instead everything is treated as vertical text.

#### Parameters

rq | a raqm_t. |
dir | the direction of the paragraph. |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.1

### raqm_set_language ()

    bool
    raqm_set_language (raqm_t *rq,
                       const char *lang,
                       size_t start,
                       size_t len);

Sets a BCP47 language code to be used for `len` -number of characters starting at `start` . The `start` and `len` are input string array indices (i.e. counting bytes in UTF-8 and scalar values in UTF-32).

This method can be used repeatedly to set different languages for different parts of the text.

#### Parameters

rq | a raqm_t. |
lang | a BCP47 language code. |
start | index of the first character that should use `face` . |
len | number of characters using `face` . |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.2

Stability Level: Unstable

### raqm_set_freetype_face ()

    bool
    raqm_set_freetype_face (raqm_t *rq,
                            FT_Face face);

Sets an FT_Face to be used for all characters in `rq` .

See also `raqm_set_freetype_face_range()`.

#### Parameters

rq | a raqm_t. |
face | an FT_Face. |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.1

### raqm_set_freetype_face_range ()

    bool
    raqm_set_freetype_face_range (raqm_t *rq,
                                  FT_Face face,
                                  size_t start,
                                  size_t len);

Sets an FT_Face to be used for `len` -number of characters staring at `start` . The `start` and `len` are input string array indices, counting elements according to the underlying encoding. `start` must always be aligned to the start of an encoded codepoint, and `len` must always end at a codepoint's final element.

This method can be used repeatedly to set different faces for different parts of the text. It is the responsibility of the client to make sure that face ranges cover the whole text, and are properly aligned.

See also `raqm_set_freetype_face()`.

#### Parameters

rq | a raqm_t. |
face | an FT_Face. |
start | index of the first character that should use `face` from the input string. |
len | number of elements using `face` . |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.1

### raqm_set_freetype_load_flags ()

    bool
    raqm_set_freetype_load_flags (raqm_t *rq,
                                  int flags);

Sets the load flags passed to FreeType when loading glyphs, should be the same flags used by the client when rendering FreeType glyphs.

#### Parameters

rq | a raqm_t. |
flags | FreeType load flags. |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.3

### raqm_set_freetype_load_flags_range ()

    bool
    raqm_set_freetype_load_flags_range (raqm_t *rq,
                                        int flags,
                                        size_t start,
                                        size_t len);

Sets the load flags passed to FreeType when loading glyphs for `len` -number of characters staring at `start` . Flags should be the same as used by the client when rendering corresponding FreeType glyphs. The `start` and `len` are input string array indices (i.e. counting bytes in UTF-8 and scalar values in UTF-32).

This method can be used repeatedly to set different flags for different parts of the text. It is the responsibility of the client to make sure that flag ranges cover the whole text.

See also `raqm_set_freetype_load_flags()`.

#### Parameters

rq | a raqm_t. |
flags | FreeType load flags. |
start | index of the first character that should use `flags` . |
len | number of characters using `flags` . |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.9

### raqm_set_letter_spacing_range ()

    bool
    raqm_set_letter_spacing_range (raqm_t *rq,
                                   int spacing,
                                   size_t start,
                                   size_t len);

Set the letter spacing or tracking for a given range, the value will be added onto the advance and offset for RTL, and the advance for other directions. Letter spacing will be applied between characters, so the last character will not have spacing applied after it. Note that not all scripts have a letter-spacing tradition, for example, Arabic does not, while Devanagari does.

This will also add “disable `liga`, `clig`, `hlig`, `dlig`, and `calt`” font features to the internal features list, so call this function after setting the font features for best spacing results.

#### Parameters

rq | a raqm_t. |
spacing | amount of spacing in Freetype Font Units (26.6 format). |
start | index of the first character that should use `spacing` . |
len | number of characters using `spacing` . |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.10

### raqm_set_word_spacing_range ()

    bool
    raqm_set_word_spacing_range (raqm_t *rq,
                                 int spacing,
                                 size_t start,
                                 size_t len);

Set the word spacing for a given range. Word spacing will only be applied to 'word separator' characters, such as 'space', 'no break space' and 'Ethiopic word separator'. The value will be added onto the advance and offset for RTL, and the advance for other directions.

#### Parameters

rq | a raqm_t. |
spacing | amount of spacing in Freetype Font Units (26.6 format). |
start | index of the first character that should use `spacing` . |
len | number of characters using `spacing` . |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.10

### raqm_set_invisible_glyph ()

    bool
    raqm_set_invisible_glyph (raqm_t *rq,
                              int gid);

Sets the glyph id to be used for invisible glyphs.

If `gid` is negative, invisible glyphs will be suppressed from the output.

If `gid` is zero, invisible glyphs will be rendered as space.

If `gid` is a positive number, it will be used for invisible glyphs.

#### Parameters

rq | a raqm_t. |
gid | glyph id to use for invisible glyphs. |

#### Returns

`true` if no errors happened, `false` otherwise.

Since: 0.6

### raqm_add_font_feature ()

    bool
    raqm_add_font_feature (raqm_t *rq,
                           const char *feature,
                           int len);

Adds a font feature to be used by the raqm_t during text layout. This is usually used to turn on optional font features that are not enabled by default, for example `dlig` or `ss01`, but can be also used to turn off default font features.

`feature` is string representing a single font feature, in the syntax understood by `hb_feature_from_string()`.

This function can be called repeatedly, new features will be appended to the end of the features list and can potentially override previous features.

#### Parameters

rq | a raqm_t. |
feature | a font feature string. | [transfer none]
len | length of `feature` , -1 for `NULL`-terminated. |

#### Returns

`true` if parsing `feature` succeeded, `false` otherwise.

Since: 0.1

### raqm_layout ()

    bool
    raqm_layout (raqm_t *rq);

Run the text layout process on `rq` . This is the main Raqm function where the Unicode Bidirectional Text algorithm will be applied to the text in `rq` , text shaping, and any other part of the layout process.

#### Parameters

rq | a raqm_t. |

#### Returns

`true` if the layout process was successful, `false` otherwise.

Since: 0.1

### raqm_get_glyphs ()

    raqm_glyph_t *
    raqm_get_glyphs (raqm_t *rq,
                     size_t *length);

Gets the final result of Raqm layout process, an array of raqm_glyph_t containing the glyph indices in the font, their positions and other possible information.

#### Parameters

rq | a raqm_t. |
length | output array length. | [out]

#### Returns

An array of raqm_glyph_t, or `NULL` in case of error. This is owned by `rq` and must not be freed.

[transfer none]

Since: 0.1

### raqm_get_par_resolved_direction ()

    raqm_direction_t
    raqm_get_par_resolved_direction (raqm_t *rq);

Gets the resolved direction of the paragraph;

#### Parameters

rq | a raqm_t. |

#### Returns

The raqm_direction_t specifying the resolved direction of text, or RAQM_DIRECTION_DEFAULT if `raqm_layout()` has not been called on `rq` .

Since: 0.8

### raqm_get_direction_at_index ()

    raqm_direction_t
    raqm_get_direction_at_index (raqm_t *rq,
                                 size_t index);

Gets the resolved direction of the character at specified index;

#### Parameters

rq | a raqm_t. |
index | character index. | [in]

#### Returns

The raqm_direction_t specifying the resolved direction of text at the specified index, or RAQM_DIRECTION_DEFAULT if `raqm_layout()` has not been called on `rq` .

Since: 0.8

### raqm_index_to_position ()

    bool
    raqm_index_to_position (raqm_t *rq,
                            size_t *index,
                            int *x,
                            int *y);

Calculates the cursor position after the character at `index` . If the character is right-to-left, then the cursor will be at the left of it, whereas if the character is left-to-right, then the cursor will be at the right of it.

#### Parameters

rq | a raqm_t. |
index | character index. | [inout]
x | output x position. | [out]
y | output y position. | [out]

#### Returns

`true` if the process was successful, `false` otherwise.

Since: 0.2

### raqm_position_to_index ()

    bool
    raqm_position_to_index (raqm_t *rq,
                            int x,
                            int y,
                            size_t *index);

Returns the `index` of the character at `x` and `y` position within text. If the position is outside the text, the last character is chosen as `index` .

#### Parameters

rq | a raqm_t. |
x | x position. |
y | y position. |
index | output character index. | [out]

#### Returns

`true` if the process was successful, `false` in case of error.

Since: 0.2

### raqm_version ()

    void
    raqm_version (unsigned int *major,
                  unsigned int *minor,
                  unsigned int *micro);

Returns library version as three integer components.

#### Parameters

major | Library major version component. | [out]
minor | Library minor version component. | [out]
micro | Library micro version component. | [out]

Since: 0.7

### raqm_version_atleast ()

    bool
    raqm_version_atleast (unsigned int major,
                          unsigned int minor,
                          unsigned int micro);

Checks if library version is less than or equal to the specified version.

#### Parameters

major | Library major version component. |
minor | Library minor version component. |
micro | Library micro version component. |

#### Returns

`true` if library version is less than or equal to the specified version, `false` otherwise.

Since: 0.7

### raqm_version_string ()

    const char *
    raqm_version_string (void);

Returns library version as a string with three components.

#### Returns

library version string.

Since: 0.7

### RAQM_VERSION_ATLEAST()

    #define             RAQM_VERSION_ATLEAST(major,minor,micro)

Checks if library version is less than or equal to the specified version.

#### Parameters

major | Library major version component. |
minor | Library minor version component. |
micro | Library micro version component. |

#### Returns

`true` if library version is less than or equal to the specified version, `false` otherwise.

Since: 0.7

## Types and Values

### RAQM_VERSION_MAJOR

    #define RAQM_VERSION_MAJOR 0

Library major version component.

Since: 0.7

### RAQM_VERSION_MICRO

    #define RAQM_VERSION_MICRO 5

Library micro version component.

Since: 0.7

### RAQM_VERSION_MINOR

    #define RAQM_VERSION_MINOR 10

Library minor version component.

Since: 0.7

### RAQM_VERSION_STRING

    #define RAQM_VERSION_STRING "0.10.5"

Library version as a string with three components.

Since: 0.7

### raqm_t

    typedef struct _raqm raqm_t;

This is the main object holding all the states of the currently processed text as well as its output.

Since: 0.1

### enum raqm_direction_t

Base paragraph direction, see `raqm_set_par_direction()`.

#### Members

RAQM_DIRECTION_DEFAULT | Detect paragraph direction automatically. |
RAQM_DIRECTION_RTL | Paragraph is mainly right-to-left text. |
RAQM_DIRECTION_LTR | Paragraph is mainly left-to-right text. |
RAQM_DIRECTION_TTB | Paragraph is mainly vertical top-to-bottom text. |

Since: 0.1

### raqm_glyph_t

    typedef struct {
        unsigned int index;
        int x_advance;
        int y_advance;
        int x_offset;
        int y_offset;
        uint32_t cluster;
        FT_Face ftface;
    } raqm_glyph_t;

The structure that holds information about output glyphs, returned from `raqm_get_glyphs()`.

#### Members

unsigned int `index`; | the index of the glyph in the font file. |
int `x_advance`; | the glyph advance width in horizontal text. |
int `y_advance`; | the glyph advance width in vertical text. |
int `x_offset`; | the horizontal movement of the glyph from the current point. |
int `y_offset`; | the vertical movement of the glyph from the current point. |
uint32_t `cluster`; | the index of the original character in the input text. |
FT_Face `ftface`; | the `FT_Face` of the glyph. |