This function applies text layout to a run of text (which is specified as an array of Unicode characters) and returns an array of positioned glyphs in the correct visual order. Each positioned glyph in the array is represented by one DT_LX_GLYPH structure. This structure provides the glyph's font dependent index, its (x, y) position (in font units) and a character index to map that glyph back to the input text array.
Parameter | Description |
---|---|
layout |
Handle of the previously created layout instance. |
offset |
The index of the first character to process. |
count |
The number of characters to process. |
nr_of_chars |
The number of characters in the input array. |
chars |
A pointer to a memory buffer that holds the Unicode characters (input array). |
chars_format |
Format of the characters in the memory buffer. Can be one of the following:
|
direction |
Specifies the direction of the text run. Must be set to one of the following values:
|
glyph_arr |
The resulting array of positioned glyphs (output array). This is a user-supplied array into which the function copies positioned glyphs. All the elements in this array are of the DT_LX_GLYPH type. Each element contains information necessary to position and display the corresponding glyph and a character index to map that glyph back to the input text array. See the definition of the DT_LX_GLYPH structure for details. |
max_glyphs |
Specifies the size of the array into which the function copies positioned glyphs. |
If successful, the function returns the actual number of positioned glyphs needed to lay out the input array of Unicode characters. If not successful (e.g. an error occurs or an invalid input parameter is supplied), the function returns -1.
If the user-supplied output glyph array is not large enough to accept all the positioned glyphs (i.e. max_glyphs is less than the return value, the function copies only the first max_glyphs positioned glyphs into the output array (i.e. the array will be truncated). In this case, your application can increase the size of the output array and call this function again with the updated value for max_glyphs.
Provided that the user-supplied output glyph array is large enough, the function also appends an additional phantom glyph (glyph with the glyph_index = 0 and char_index = 0) immediately after the last output glyph to indicate the (x, y) position of the end of the text run. However, the number of glyphs returned by this function does not include this phantom glyph.
Recommended value for max_glyphs is 1.5 times the total number of characters in the input array of Unicode characters.
This function is designed to process a sequence of Unicode characters which is in a single font, script and direction. You can use the Unicode bidirectional algorithm to determine the direction of the text or give the user direct control over bidirectional text layout.
The sequence of input characters must be passed in reading or logical order.
Do not assume a simple one-to-one mapping between input characters and output glyphs. In other words, the size of the resulting glyph array can be (and with complex scripts usually is) different than the size of the input Unicode character array.
When it is necessary to map output glyphs back to the initial sequence of input characters (e.g. for cursor movement and text selection), use the returned array of character indices.