From 5dd2a21919c91f560a35d5f666cc7ad67e108889 Mon Sep 17 00:00:00 2001 From: Vincent Wei Date: Mon, 11 Mar 2019 12:33:42 +0800 Subject: [PATCH] Description of Bidi APIs --- include/gdi.h | 224 +++++++++++++++++++++++++++++++++++++--- src/font/charset.c | 2 +- src/font/unicode-bidi.c | 19 ++-- src/include/bidi.h | 118 --------------------- 4 files changed, 222 insertions(+), 141 deletions(-) diff --git a/include/gdi.h b/include/gdi.h index 20a0e0c3..bccb07ab 100644 --- a/include/gdi.h +++ b/include/gdi.h @@ -7473,9 +7473,41 @@ MG_EXPORT UCharGeneralCategory GUIAPI UCharGetCategory(Uchar32 uc); /** The function determines the break property of a UNICODE character. */ MG_EXPORT UCharBreakType GUIAPI UCharGetBreakType(Uchar32 uc); -/** The function determines the bidi type of a UNICODE character. */ +/** + * \fn BidiType GUIAPI UCharGetBidiType(Uchar32 uc) + * \brief Get bidi type of a Unicode character. + * + * This function returns the bidi type of a Unicode character as defined in + * Table 3.7 Bidirectional Character Types of the + * Unicode Bidirectional Algorithm available at + * + * https://www.unicode.org/reports/tr9/#Bidirectional_Character_Types + * + * \param uc The Uchar32 character. + * + * \return The bidi type. + * + * \sa UCharGetBidiTypes, bidi_types + */ MG_EXPORT BidiType GUIAPI UCharGetBidiType(Uchar32 uc); +/** + * \fn void GUIAPI UCharGetBidiTypes(const Uchar32* ucs, int nr_ucs, + * BidiType* bds); + * \brief Get bidi types for an string of Unicode characters. + * + * This function finds the bidi types of an string of Unicode characters. + * + * \param ucs The pointer to the Uchar32 string. + * \param nr_ucs The number of Unicode characters in the string. + * \param bds The pointer to a buffer which will be used to store + * the bidi types of the characters in \a ucs. + * + * \sa UCharGetBidiType + */ +MG_EXPORT void GUIAPI UCharGetBidiTypes(const Uchar32* ucs, int nr_ucs, + BidiType* bds); + #define BIDI_BRACKET_NONE 0 #define BIDI_BRACKET_OPEN_MASK 0x80000000 #define BIDI_BRACKET_CHAR_MASK 0X7FFFFFFF @@ -7524,9 +7556,186 @@ MG_EXPORT BidiBracketType GUIAPI UCharGetBracketType(Uchar32 ch); MG_EXPORT void GUIAPI UCharGetBracketTypes(const Uchar32 *ucs, int len_ucs, const BidiType *bidi_types, BidiBracketType *bracket_types); -/** The function returns the mirror character of a UNICODE character. */ +/** + * \fn BOOL GUIAPI UCharGetMirror(Uchar32 uc, Uchar32* mirrored) + * \brief Get mirroed character. + * + * This function finds the mirrored equivalent of a Unicode character as + * defined in the file BidiMirroring.txt of the Unicode Character Database + * available at + * + * https://www.unicode.org/Public/UNIDATA/BidiMirroring.txt. + * + * \param uc The Uchar32 character. + * \param mirrored A pointer to a Uchar32 buffer to return the mirroed + * character. If the input character \a uc is a declared as a + * mirroring character in the Unicode standard and has a mirrored + * equivalent, the matching mirrored character was put in this buffer, + * otherwise the input character itself was put. + * + * \return A BOOL value indicates if the character has a mirroring equivalent + * or not. + */ MG_EXPORT BOOL GUIAPI UCharGetMirror(Uchar32 uc, Uchar32* mirrored); +/** + * \fn int GUIAPI UCharGetParagraphDir(const BidiType *bidi_types, int len) + * \brief get base paragraph direction + * + * This function finds the base direction of a single paragraph, + * as defined by rule P2 of the Unicode Bidirectional Algorithm available at + * http://www.unicode.org/reports/tr9/#P2. + * + * You typically do not need this function as + * __mg_unicode_bidi_get_paragraph_els() knows how to compute base direction + * itself, but you may need this to implement a more sophisticated paragraph + * direction handling. Note that you can pass more than a paragraph to this + * function and the direction of the first non-neutral paragraph is returned, + * which is a very good heuristic to set direction of the neutral paragraphs + * at the beginning of text. For other neutral paragraphs, you better use the + * direction of the previous paragraph. + * + * \param bidi_types the pointer to the BidiType array as returned by + * __mg_unicode_bidi_get_bidi_types() + * \param len The length of bidi_types + * + * \return Base pargraph direction. No weak paragraph direction is returned, + * only BIDI_PGDIR_LTR, BIDI_PGDIR_RTL, or BIDI_PGDIR_ON. + * + */ +MG_EXPORT int GUIAPI UCharGetParagraphDir(const BidiType *bidi_types, int len); + +/** + * \fn BidiLevel GUIAPI UCharGetParagraphEmbeddingLevels( + * const BidiType *bidi_types, + * const BidiBracketType* bracket_types, int len, + * int *base_dir, BidiLevel *embedding_levels); + * \brief Get bidi embedding levels of a paragraph. + * + * This function finds the bidi embedding levels of a single paragraph, + * as defined by the Unicode Bidirectional Algorithm available at + * + * https://www.unicode.org/reports/tr9/. + * + * This function implements rules P2 to I1 inclusive, and parts 1 to 3 of L1. + * Part 4 of L1 is implemented in __mg_unicode_bidi_reorder_line(). + * + * \param bidi_types the pointer to the BidiType array as returned by + * UCharGetBidiTypes(). + * \param bracket_types The pointer to a Uint8 which contains the + bracket types as returned by UCharGetBracketTypes() + * \param len The length of the list. + * \param base_dir requested and resolved paragraph base direction + * \param embedding_levels The pointer to a buffer which will restore + * the embedding levels + * + * \return The Maximum level found plus one, or zero if any error occurred + * (memory allocation failure most probably). + * + * \sa UCharGetBidiTypes, UCharGetBracketTypes + */ +MG_EXPORT BidiLevel GUIAPI UCharGetParagraphEmbeddingLevels( + const BidiType *bidi_types, + const BidiBracketType* bracket_types, int len, + int *base_dir, BidiLevel *embedding_levels); + +/* + * \var typedef void (*CB_REVERSE_EXTRA) (void* extra, int len, int pos) + * \brief The prototype of the user defined function to reverse an array. + * + * The function reverse an array pointed by \a extra from the position + * specified by \a pos for the length specified by \a len. + * + * \sa UCharReorderBidiLine, BIDILogAChars2VisACharsEx + */ +typedef void (*CB_REVERSE_EXTRA) (void* extra, int len, int pos); + +/** + * \fn BidiLevel GUIAPI UCharReorderBidiLine(Uint32 reorder_flags, + * const BidiType *bidi_types, int len, int off, + * int base_dir, BidiLevel *embedding_levels, + * Uchar32 *visual_str, int *map, + * void* extra, CB_REVERSE_EXTRA cb_reverse_extra) + * \brief Reorder a line of logical string to visual string. + * + * This function reorders the characters in a line of text from logical to + * final visual order. + * + * This function implements part 4 of rule L1, and rules + * L2 and L3 of the Unicode Bidirectional Algorithm available at + * + * https://www.unicode.org/reports/tr9/#Reordering_Resolved_Levels. + * + * As a side effect it also sets position maps if not NULL. + * + * You should provide the resolved paragraph direction and embedding levels as + * set by UCharGetParagraphEmbeddingLevels(). Also note that the embedding + * levels may change a bit. To be exact, the embedding level of any sequence + * of white space at the end of line is reset to the paragraph embedding level + * (That is part 4 of rule L1). + * + * Note that the bidi types and embedding levels are not reordered. + * You can reorder these (or any other) arrays using the map later. + * The user is responsible to initialize map to something sensible, + * like an identity mapping, or pass NULL if no map is needed. + * + * There is an optional part to this function, which is whether non-spacing + * marks for right-to-left parts of the text should be reordered to come after + * their base characters in the visual string or not. + * + * Most rendering engines expect this behavior, but console-based systems + * for example do not like it. This is controlled by the + * BIDI_FLAG_REORDER_NSM flag. The flag is on in BIDI_FLAGS_DEFAULT. + * + * \param reorder_flags The reorder flags. + * \param bidi_types the pointer to the BidiType array as returned by + * UCharGetBidiTypes() + * \param bracket_types The pointer to a BidiBracketType array which + * contains the bracket types as returned by UCharGetBracketTypes() + * \param len The length of the list. + * \param off The input offset of the beginning of the line in the paragraph. + * \param base_dir The resolved paragraph base direction. + * \param embedding_levels The embedding levels, as returned by + UCharGetParagraphEmbeddingLevels() + * \param visual_str The Uchar32 string will be reordered. + * \param map a map of string indices which is reordered to reflect + * where each glyph ends up. + * \param extra The pointer to the extra array to reorder; can be NULL. + * \param cb_reverse_extra The callback function to reverse the extra array. + * + * \return Maximum level found in this line plus one, or zero if any error + * occurred (memory allocation failure most probably). + * + * \sa UCharGetBidiTypes, UCharGetBracketTypes, + * UCharGetParagraphEmbeddingLevels + */ +MG_EXPORT BidiLevel GUIAPI UCharReorderBidiLine(Uint32 reorder_flags, + const BidiType *bidi_types, int len, int off, + int base_dir, BidiLevel *embedding_levels, + Uchar32 *visual_str, int *map, + void* extra, CB_REVERSE_EXTRA cb_reverse_extra); + +/** + * \fn void GUIAPI UCharShapeMirroring(const BidiLevel *els, int len, + * Uchar32 *ucs) + * \brief Do mirroring shaping + * + * This functions replaces mirroring characters on right-to-left embeddings in + * string with their mirrored equivalent as returned by UCharGetMirror(). + * + * This function implements rule L4 of the Unicode Bidirectional Algorithm + * available at http://www.unicode.org/reports/tr9/#L4. + * + * \param els input list of embedding levels, as returned by + * UCharGetParagraphEmbeddingLevels(). + * \param len The input string length. + * \param ucs The Uchar32 string to shape. + * + * \sa UCharGetParagraphEmbeddingLevels + */ +MG_EXPORT void GUIAPI UCharShapeMirroring(const BidiLevel *els, int len, + Uchar32 *ucs); + /** The function determines whether a character is alphanumeric. */ MG_EXPORT BOOL GUIAPI IsUCharAlnum(Uchar32 uc); @@ -10136,17 +10345,6 @@ MG_EXPORT int GUIAPI BIDIGetTextVisualAChars (LOGFONT* log_font, const char* text, int text_len, Achar32** achars, ACHARMAPINFO** achars_map); -/* - * \var typedef void (*CB_REVERSE_EXTRA) (void* extra, int len, int pos) - * \brief The prototype of the user defined function to reverse an array. - * - * The function reverse an array pointed by \a extra from the position - * specified by \a pos for the length specified by \a len. - * - * \sa BIDILogAChars2VisACharsEx - */ -typedef void (*CB_REVERSE_EXTRA) (void* extra, int len, int pos); - /** \fn BOOL GUIAPI BIDILogAChars2VisACharsEx (LOGFONT* log_font, * Achar32* achars, int nr_achars, int pel, * void* extra, CB_REVERSE_EXTRA cb_reverse_extra) diff --git a/src/font/charset.c b/src/font/charset.c index 11869b29..6d2590c0 100644 --- a/src/font/charset.c +++ b/src/font/charset.c @@ -3608,7 +3608,7 @@ BidiType GUIAPI UCharGetBidiType(Uchar32 uc) return linear_enum_to_bidi_type[UNIBIDI_GET_BIDI_TYPE(uc)]; } -void UCharGetBidiTypes(const Uchar32 *str, int len, BidiType *btypes) +void GUIAPI UCharGetBidiTypes(const Uchar32 *str, int len, BidiType *btypes) { register int i = len; for (; i; i--) { diff --git a/src/font/unicode-bidi.c b/src/font/unicode-bidi.c index 205fcd03..b77f5946 100644 --- a/src/font/unicode-bidi.c +++ b/src/font/unicode-bidi.c @@ -55,11 +55,12 @@ #define DEBUG #include "common.h" -#include "minigui.h" -#include "gdi.h" #ifdef _MGCHARSET_UNICODE +#include "minigui.h" +#include "gdi.h" + #include "devfont.h" #include "bidi.h" #include "unicode-bidi.h" @@ -643,7 +644,7 @@ static void print_pairing_nodes(BidiPairingNode *nodes) #define BIDI_EMBEDDING_DIRECTION(link) \ BIDI_LEVEL_TO_DIR(RL_LEVEL(link)) -int __mg_unicode_bidi_get_par_direction(const BidiType *bidi_types, const int len) +int UCharGetParagraphDir(const BidiType *bidi_types, const int len) { register int i; @@ -737,7 +738,7 @@ static void free_pairing_nodes(BidiPairingNode *nodes) } } -BidiLevel __mg_unicode_bidi_get_paragraph_els(const BidiType *bidi_types, +BidiLevel UCharGetParagraphEmbeddingLevels(const BidiType *bidi_types, const BidiBracketType *bracket_types, const int len, int *pbase_dir, BidiLevel *embedding_levels) { @@ -753,7 +754,7 @@ BidiLevel __mg_unicode_bidi_get_paragraph_els(const BidiType *bidi_types, goto out; } - _DBG_PRINTF ("in __mg_unicode_bidi_get_paragraph_els"); + _DBG_PRINTF ("in UCharGetParagraphEmbeddingLevels"); /* Determinate character types */ { @@ -1506,7 +1507,7 @@ BidiLevel __mg_unicode_bidi_get_paragraph_els(const BidiType *bidi_types, separator or paragraph separator, and 4. any sequence of whitespace characters and/or isolate formatting characters at the end of the line. - ... (to be continued in __mg_unicode_bidi_reorder_line()). */ + ... (to be continued in UCharReorderBidiLine()). */ list = new_run_list (); if (!list) goto out; q = list; @@ -1565,7 +1566,7 @@ BidiLevel __mg_unicode_bidi_get_paragraph_els(const BidiType *bidi_types, status = TRUE; out: - _DBG_PRINTF ("leaving __mg_unicode_bidi_get_paragraph_els"); + _DBG_PRINTF ("leaving UCharGetParagraphEmbeddingLevels"); if (main_run_list) free_run_list (main_run_list); @@ -1598,7 +1599,7 @@ static void index_array_reverse (int *arr, int len) } } -BidiLevel __mg_unicode_bidi_reorder_line(Uint32 flags, +BidiLevel UCharReorderBidiLine(Uint32 flags, const BidiType *bidi_types, int len, int off, int base_dir, BidiLevel *embedding_levels, Uchar32 *visual_str, int *map, @@ -1612,7 +1613,7 @@ BidiLevel __mg_unicode_bidi_reorder_line(Uint32 flags, goto out; } - _DBG_PRINTF ("in __mg_unicode_bidi_reorder_line"); + _DBG_PRINTF ("in UCharReorderBidiLine"); _DBG_PRINTF ("reset the embedding levels, 4. whitespace at the end of line"); { diff --git a/src/include/bidi.h b/src/include/bidi.h index 6f803798..b99e73dd 100644 --- a/src/include/bidi.h +++ b/src/include/bidi.h @@ -109,124 +109,6 @@ Achar32* __mg_legacy_bidi_index_reorder (const CHARSETOPS* charset_ops, Achar32* achars, int len, int* index_map, int pel); #endif -#ifdef _MGCHARSET_UNICODE - -/** - * \fn __mg_unicode_bidi_get_paragraph_dir - * \brief get base paragraph direction - * - * This function finds the base direction of a single paragraph, - * as defined by rule P2 of the Unicode Bidirectional Algorithm available at - * http://www.unicode.org/reports/tr9/#P2. - * - * You typically do not need this function as - * __mg_unicode_bidi_get_paragraph_els() knows how to compute base direction - * itself, but you may need this to implement a more sophisticated paragraph - * direction handling. Note that you can pass more than a paragraph to this - * function and the direction of the first non-neutral paragraph is returned, - * which is a very good heuristic to set direction of the neutral paragraphs - * at the beginning of text. For other neutral paragraphs, you better use the - * direction of the previous paragraph. - * - * \param bidi_types the pointer to the BidiType array as returned by - * __mg_unicode_bidi_get_bidi_types() - * \param len The length of bidi_types - * - * \return Base pargraph direction. No weak paragraph direction is returned, - * only BIDI_PGDIR_LTR, BIDI_PGDIR_RTL, or BIDI_PGDIR_ON. - * - */ -int __mg_unicode_bidi_get_paragraph_dir(const BidiType *bidi_types, int len); - -/** - * \fn __mg_unicode_bidi_get_paragraph_els - * \brief Get bidi embedding levels of a paragraph - * - * This function finds the bidi embedding levels of a single paragraph, - * as defined by the Unicode Bidirectional Algorithm available at - * http://www.unicode.org/reports/tr9/. - * - * This function implements rules P2 to I1 inclusive, and parts 1 to 3 of L1. - * Part 4 of L1 is implemented in __mg_unicode_bidi_reorder_line(). - * - * There are a few macros defined in mgbidi-bidi-types.h to work with this - * embedding levels. - * - * \param bidi_types the pointer to the BidiType array as returned by - * __mg_unicode_bidi_get_bidi_types() - * \param bracket_types The pointer to a Uint8 which contains the - bracket types as returned by UCharGetBracketTypes() - * \param len The length of the list. - * \param base_dir requested and resolved paragraph base direction - * \param embedding_levels The pointer to a buffer which will restore - * the embedding levels - * - * \return The Maximum level found plus one, or zero if any error occurred - * (memory allocation failure most probably). - */ -BidiLevel __mg_unicode_bidi_get_paragraph_els(const BidiType *bidi_types, - const BidiBracketType* bracket_types, int len, - int *base_dir, BidiLevel *embedding_levels); - -/** - * \fn __mg_unicode_bidi_reorder_line - * \brief Reorder a line of logical string to visual - * - * This function reorders the characters in a line of text from logical to - * final visual order. - * - * This function implements part 4 of rule L1, and rules - * L2 and L3 of the Unicode Bidirectional Algorithm available at - * http://www.unicode.org/reports/tr9/#Reordering_Resolved_Levels. - * - * As a side effect it also sets position maps if not NULL. - * - * You should provide the resolved paragraph direction and embedding levels as - * set by __mg_unicode_bidi_get_paragraph_els(). Also note that the embedding - * levels may change a bit. To be exact, the embedding level of any sequence - * of white space at the end of line is reset to the paragraph embedding level - * (That is part 4 of rule L1). - * - * Note that the bidi types and embedding levels are not reordered. - * You can reorder these (or any other) arrays using the map later. - * The user is responsible to initialize map to something sensible, - * like an identity mapping, or pass NULL if no map is needed. - * - * There is an optional part to this function, which is whether non-spacing - * marks for right-to-left parts of the text should be reordered to come after - * their base characters in the visual string or not. - * - * Most rendering engines expect this behavior, but console-based systems - * for example do not like it. This is controlled by the - * BIDI_FLAG_REORDER_NSM flag. The flag is on in BIDI_FLAGS_DEFAULT. - * - * \param flags The reorder flags. - * \param bidi_types the pointer to the BidiType array as returned by - * __mg_unicode_bidi_get_bidi_types() - * \param bracket_types The pointer to a BidiBracketType array which - * contains the bracket types as returned by UCharGetBracketTypes() - * \param len The length of the list. - * \param off The input offset of the beginning of the line in the paragraph. - * \param base_dir The resolved paragraph base direction. - * \param embedding_levels The embedding levels, as returned by - __mg_unicode_bidi_get_paragraph_els() - * \param visual_str The Uchar32 string will be reordered. - * \param extra The pointer to the extra array to reorder; can be NULL. - * \param cb_reverse_extra The callback function to reverse the extra array. - * \param map a map of string indices which is reordered to reflect - * where each glyph ends up. - * - * \return Maximum level found in this line plus one, or zero if any error - * occurred (memory allocation failure most probably). - */ -BidiLevel __mg_unicode_bidi_reorder_line(Uint32 flags, - const BidiType *bidi_types, int len, int off, - int base_dir, BidiLevel *embedding_levels, - Uchar32 *visual_str, int *map, - void* extra, CB_REVERSE_EXTRA cb_reverse_extra); - -#endif /* _MGCHARSET_UNICODE */ - #ifdef __cplusplus } #endif /* __cplusplus */