Top |
raqm_t * | raqm_create () |
raqm_t * | raqm_reference () |
void | raqm_destroy () |
bool | raqm_set_text () |
bool | raqm_set_text_utf8 () |
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_add_font_feature () |
bool | raqm_layout () |
raqm_glyph_t * | raqm_get_glyphs () |
bool | raqm_index_to_position () |
bool | raqm_position_to_index () |
Raqm is a light weight 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:
#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:
cc -o test test.c `pkg-config --libs --cflags raqm`
raqm_t *
raqm_create (void
);
Creates a new raqm_t with all its internal states initialized to their defaults.
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_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.
Since 0.1
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 cairo_reference()
.
Since 0.1
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 character 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.
Since 0.1
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.
Since 0.1
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.
Since 0.1
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 staring at start
. The start
and len
are
input string array indices (i.e. counting bytes in UTF-8 and scaler values
in UTF-32).
This method can be used repeatedly to set different languages for different parts of the text.
rq |
a raqm_t. |
|
lang |
a BCP47 language code. |
|
start |
index of first character that should use |
|
len |
number of characters using |
Since 0.2
Stability Level: Unstable
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()
.
Since 0.1
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 (i.e. counting bytes in
UTF-8 and scaler values in UTF-32).
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.
See also raqm_set_freetype_face()
.
rq |
a raqm_t. |
|
face |
an FT_Face. |
|
start |
index of first character that should use |
|
len |
number of characters using |
Since 0.1
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.
This requires version of HarfBuzz that has hb_ft_font_set_load_flags()
, for
older version the flags will be ignored.
Since 0.3
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.
rq |
a raqm_t. |
|
feature |
a font feature string. |
[transfer none] |
len |
length of |
Since 0.1
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.
Since 0.1
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.
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
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.
rq |
a raqm_t. |
|
index |
character index. |
[inout] |
x |
output x position. |
[out] |
y |
output y position. |
[out] |
Since 0.2
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
.
Since 0.2
typedef struct _raqm raqm_t;
This is the main object holding all state of the currently processed text as well as its output.
Since 0.1
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()
.
the index of the glyph in the font file. |
||
the glyph advance width in horizontal text. |
||
the glyph advance width in vertical text. |
||
the horizontal movement of the glyph from the current point. |
||
the vertical movement of the glyph from the current point. |
||
the index of original character in input text. |
||
the |