Index

C/C++ Functions

lxLayoutApplyPlus

DT_SLONG lxLayoutApplyPlus(DT_LXLAYOUT layout, DT_SLONG offset, DT_SLONG count, DT_SLONG nr_of_chars, const DT_UBYTE* chars, DT_ID_SWORD chars_format, DT_ID_UBYTE direction, LX_GLYPH glyph_arr[], DT_SLONG max_glyphs)

Short Description: Apply text layout instance to a run of text

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.

Parameters

ParameterDescription

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:

  • 1 (LX_FORMAT_UBYTE) = indicates that the size of each character in the buffer is 1 byte. All characters have codepoints in the 0 - 255 range.

  • 2 (LX_FORMAT_UWORD_LE) = indicates that the size of each character in the buffer is 2 bytes (little endian byte ordering). All characters have codepoints in the 0 - 65,535 range.

  • -2 (LX_FORMAT_UWORD_BE) = indicates that the size of each character in the buffer is 2 bytes (big endian byte ordering). All characters have codepoints in the 0 - 65,535 range.

  • 3 (LX_FORMAT_UTRIO_LE) = indicates that the size of each character in the buffer is 3 bytes (little endian byte ordering). All characters have codepoints in the 0 - 16,777,216 range.

  • -3 (LX_FORMAT_UTRIO_BE) = indicates that the size of each character in the buffer is 3 bytes (big endian byte ordering). All characters have codepoints in the 0 - 16,777,216 range.

  • 4 (LX_FORMAT_ULONG_LE) = indicates that the size of each character in the buffer is 4 bytes (little endian byte ordering). All characters have codepoints in the 0 - 4,294,967,296 range.

  • -4 (LX_FORMAT_ULONG_BE) = indicates that the size of each character in the buffer is 4 bytes (big endian byte ordering). All characters have codepoints in the 0 - 4,294,967,296 range.

  • 102 (LX_FORMAT_UWORD) = indicates that the size of each character in the buffer is 2 bytes (CPU byte ordering). All characters have codepoints in the 0 - 65,535 range.

  • 104 (LX_FORMAT_ULONG) = indicates that the size of each character in the buffer is 4 bytes (CPU byte ordering). All characters have codepoints in the 0 - 4,294,967,296 range.

  • 124 (LX_FORMAT_UTF16) = indicates the buffer is in UTF-16 format. Each character is encoded with one or two DT_ID_UWORD code units (using CPU specific byte ordering) as per UTF-16 encoding scheme. This variable-length encoding format is capable of encoding all 1,112,064 possible Unicode characters.

direction

Specifies the direction of the text run. Must be set to one of the following values:

  • 0 (LX_DIRECTION_LTR) = left to right text
  • 1 (LX_DIRECTION_RTL) = right to left text
  • 2 (LX_DIRECTION_TTB) = top to bottom text (added in D-Type 7.5.1.2; works only with HarfBuzz-based D-Type Text Layout Extension)
  • 3 (LX_DIRECTION_BTT) = bottom to top text (added in D-Type 7.5.1.2; works only with HarfBuzz-based D-Type Text Layout Extension)

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.

Return Value

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.

Note 1

Recommended value for max_glyphs is 1.5 times the total number of characters in the input array of Unicode characters.

Comments

 

Index